Asynchronous HTTPS API
This feature is only available for bucketAV for Amazon S3!
The asynchronous HTTPS API can be used to submit scan jobs to bucketAV via HTTPS. The asynchronous API invokes (HTTP(S) POST request) a callback URL that you specify to send the scan result to your system once available.
Are you interested in a synchronous API? Learn more.
API definition (#)
All requests must be authenticated using a Bearer token. Pass the bearer token via an Authorization
header. E.g., Authorization: Bearer secret
. You configure the allowed tokens via the ApiKeys configuration parameter.
POST /api/v1/scan/async/download (#)
Download a file from a remote location (HTTP/HTTPS), scan the file, and post the scan result to your callback URL.
The request body is JSON formatted with these properties:
download_url
(string): URL to download and scan via HTTP(S) GET.download_headers
: (object, optional): Headers to send when downloading the file (requires version >= 2.2.1 of this Add-On; requires bucketAV powered by ClamAV® version >= 2.17.0 or bucketAV powered by Sophos® version >= 2.8.0).callback_url
(string): URL to receive the scan result via HTTPS POST.callback_headers
: (object, optional): Headers to send when invoking the callback (requires version >= 2.2.1 of this Add-On; Content-Type and Content-Length are always added and can not be changed; requires bucketAV powered by ClamAV® version >= 2.17.0 or bucketAV powered by Sophos® version >= 2.8.0).trace_id
(string, optional): ID allowing you to trace the scan request with a custom ID.custom_data
(string, optional): Custom data that bucketAV passes through-maximum of 16 KB in UTF-8.
The response status code is 204
.
Example:
curl \
-vvv \
-X POST \
-H 'Authorization: Bearer secret' \
-H 'Content-Type: application/json' \
-d '{"download_url": "https://download.yourcompany.com/path/to/file.pdf", "callback_url": "https://api.yourcompany.com/bucketav/callback"}' \
'https://.../api/v1/scan/async/download'
POST /api/v1/scan/async/s3 (#)
Download a file from S3, scan the file, and post the scan result to your callback URL.
The request body is JSON formatted with these properties:
bucket
(string): The bucket name.key
(string): The object key.version
(string, optional): If versioning is turned on, the object version.callback_url
(string): URL to receive the scan result via HTTPS POST.trace_id
(string, optional): ID allowing you to trace the scan request with a custom ID.custom_data
(string, optional): Custom data that bucketAV passes through-maximum of 16 KB in UTF-8.
The response status code is 204
.
Example:
curl \
-vvv \
-X POST \
-H 'Authorization: Bearer secret' \
-H 'Content-Type: application/json' \
-d '{"bucket": "you-bucket", "key": "path/to/file.pdf", "callback_url": "https://api.yourcompany.com/bucketav/callback"}' \
'https://.../api/v1/scan/async/s3'
GET /api/v1/test (#)
Check if API key is valid.
The response status code is 204
.
Example:
curl \
-vvv \
-X GET \
-H 'Authorization: Bearer secret' \
'https://.../api/v1/test'
Callback URL (#)
The callback URL is called by bucketAV via an HTTPS POST request with a JSON payload with these properties:
status
(string (clean
,infected
,no
)): The scan result.finding
(string, optional): For infected files, the type of virus/malware that was detected.size
(number): The file size in bytes.download_time
(number): Time to download the file in seconds.scan_time
(number): Time to scan the file in seconds.download_url
(string): The downloaded URL.trace_id
(string, optional): ID to trace custom scan jobs.custom_data
(string, optional): Custom data defined when submitting a custom scan job.
Setup (#)
Requires bucketAV for Amazon S3 powered by ClamAV® version >= 2.14.0, or bucketAV for Amazon S3 powered by Sophos® version >= 2.4.0.
To update to the latest version, follow the Update Guide.
Install Add-On (requires a running bucketAV installation)
- Set the Stack name to
bucketav-api
. - Set the BucketAVStackName parameter to the stack name of bucketAV (if you followed the docs, the name is
bucketav
). - Set the ApiKeys parameter and add at least one secret value that clients use to authenticate requests using Bearer Authentication.
- Select I acknowledge that AWS CloudFormation might create IAM resources.
- Click on the Create stack button to save.
- Wait for the stack to reach status
CREATE_COMPLETE
. - Click on the Outputs tab to get the ApiEndpoint.
CloudFormation snippet (#)
# [...]
Resources:
# [...]
Api:
Type: 'AWS::CloudFormation::Stack'
Properties:
Parameters:
BucketAVStackName: 'bucketav' # if you followed the docs, the name is bucketav
ApiKeys: 'secret1,secret2' # TODO replace API keys
TemplateURL: 'https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/api/v2.5.0/bucketav-add-on-api.yaml'
Terraform snippet (#)
resource "aws_cloudformation_stack" "bucketav_add_on_api" {
name = "bucketav-api"
template_url = "https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/api/v2.5.0/bucketav-add-on-api.yaml"
capabilities = ["CAPABILITY_IAM"]
parameters = {
BucketAVStackName = "bucketav" # if you followed the docs, the name is bucketav
ApiKeys = "secret1,secret2" # TODO replace API keys
}
}
Update (#)
- To update this Add-On to version v2.5.0, go to the AWS CloudFormation Management Console.
- Double-check the region at the top right.
- Search for
bucketav-api
, otherwise search for the name you specified. - Select the stack and click on Update.
- Select Replace current template and set the Amazon S3 URL to
https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/api/v2.5.0/bucketav-add-on-api.yaml
Copy - Click on Next.
- Scroll to the bottom of the page and click on Next.
- Scroll to the bottom of the page and click on Next.
- Scroll to the bottom of the page, enable I acknowledge that AWS CloudFormation might create IAM resources, and click on Update stack.
- While the update runs, the stack status is UPDATE_IN_PROGRES. Reload the table from time to time and …
- … wait until the CloudFormation stack status switches to UPDATE_COMPLETE.
Architecture (#)
The following AWS services are used:
- IAM User to create presigned S3 URLs used for
POST /api/v1/scan/async/s3
. - Lambda Function to implement the API.
- API Gateway to run the HTTPS API.
- CloudWatch Alarms to monitor the used AWS services.
- CloudWatch Logs to store logs.
Release Notes (#)
Subscribe to our Atom feed or newsletter to stay up-to-date! We also publish a machine-readable JSON file.
v2.5.0
Changes:
- Support custom domain with Amazon Route53 and AWS Certificate Manager
Release date:2024-08-01
Template: https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/api/v2.5.0/bucketav-add-on-api.yaml
v2.4.1
Changes:
- Bug fixes
Release date:2024-07-09
Template: https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/api/v2.4.1/bucketav-add-on-api.yaml
v2.4.0
Changes:
- Added test endpoint GET /api/v1/test
Release date:2024-04-17
Template: https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/api/v2.4.0/bucketav-add-on-api.yaml
v2.3.0
Changes:
- Update Lambda runtime to Node.js 20
Release date:2024-02-14
Template: https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/api/v2.3.0/bucketav-add-on-api.yaml
v2.2.1
Changes:
- Hide ApiKeys parameter values
Release date:2024-01-17
Template: https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/api/v2.2.1/bucketav-add-on-api.yaml
v2.2.0
Changes:
- Support custom headers for custom downloads
- Add Service Discovery
Release date:2023-12-07
Template: https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/api/v2.2.0/bucketav-add-on-api.yaml
v2.1.0
Changes:
- Update Lambda runtime to Node.js 18
Release date:2023-09-01
Template: https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/api/v2.1.0/bucketav-add-on-api.yaml
v2.0.2
Changes:
- Extend presigned URL expiry to 12 hours
Release date:2023-07-14
Template: https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/api/v2.0.2/bucketav-add-on-api.yaml
v2.0.1
Changes:
- Add ApiEndpoint output
Release date:2023-07-13
Template: https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/api/v2.0.1/bucketav-add-on-api.yaml
v2.0.0
Changes:
- Initial release
Release date:2023-06-28
Template: https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/api/v2.0.0/bucketav-add-on-api.yaml