HTTPS API

Our HTTPS API can be used to submit scan jobs to bucketAV via HTTPS.

At the moment, we support async jobs only. For async scan jobs, the scan result is provided by an HTTP(S) POST request to your callback URL.

If you are interested in a sync API, please email us your use case!

API definition

All requests must be authenticated using a Bearer token. Pass the bearer token via an Authorization header. E.g., Authorization: Bearer secret.

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.

Request body is JSON formatted with these properties:

• download_url (string): URL to download and scan via HTTP(S) GET.
• 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.

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.

Request body is JSON formatted with these properties:

• bucket (string): The bucket name.
• key (string): The object key.
• version (string, optional): The object version if versioning is turned on.
• 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.

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'

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

1. Set the Stack name to bucketav-api.
2. Set the BucketAVStackName parameter to the stack name of bucketAV (if you followed the docs, the name is bucketav).
3. Set the ApiKeys parameter and add at least one secret value that clients use to authenticate requests using Bearer Authentication.
4. Select I acknowledge that AWS CloudFormation might create IAM resources.
5. Click on the Create stack button to save.
6. Wait for the stack to reach status CREATE_COMPLETE.
7. Click on the Outputs tab to get the ApiEndpoint.

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

Terraform

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.1.0/bucketav-add-on-api.yaml"
  capabilities = ["CAPABILITY_IAM"]
  parameters = {
    BucketAVStackName = "bucketav" # if you followed the docs, the name is `bucketav`
    ApiKeys= "secret" # TODO replace API key
  }
}

Update

Which version am I using?

1. To update this add-on to version v2.1.0, go to the AWS CloudFormation Management Console.
2. Double-check the region at the top right.
3. Search for bucketav-api, otherwise search for the name you specified.
4. Select the stack and click on Update.
5. Select Replace current template and set the Amazon S3 URL to https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/api/v2.1.0/bucketav-add-on-api.yaml Copy
6. Click on Next.
7. Scroll to the bottom of the page and click on Next.
8. Scroll to the bottom of the page and click on Next.
9. Scroll to the bottom of the page, enable I acknowledge that AWS CloudFormation might create IAM resources, and click on Update stack.
10. While the update runs, the stack status is UPDATE_IN_PROGRES. Reload the table from time to time and …
11. … 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.
• CloudWatch Alarms to monitor the used AWS services.
• API Gateway to run the HTTPS API.