Asynchronous HTTPS API

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 powered by ClamAV® version >= 2.14.0 or bucketAV 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.

For a custom domain name, please check out the AWS documentation.

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.4.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.4.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 (#)

Which version am I using?

To update this Add-On to version v2.4.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.4.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.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

Need more help?

Write us, and we'll get back to you as soon as we can.

Send us an email