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

• Amazon S3
• Cloudflare R2

CloudFormation snippet

• Amazon S3
• Cloudflare R2

# [...]
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.6.0/bucketav-add-on-api.yaml'

Terraform snippet

• Amazon S3
• Cloudflare R2

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.6.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?

• Amazon S3
• Cloudflare R2

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

• Amazon S3
• Cloudflare R2