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.
- 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.
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
- To update this add-on to version v2.1.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.1.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.
- CloudWatch Alarms to monitor the used AWS services.
- API Gateway to run the HTTPS API.