Synchronous HTTPS API
This feature is only available for bucketAV for Amazon S3!
The synchronous HTTPS API can be used to submit scan jobs to bucketAV via HTTPS. The synchronous API returns the scan result in the HTTP response.
Are you interested in an asynchronous API? Learn more.
API definition
Authentication
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/sync/download
Download a file from a remote location (HTTP/HTTPS), scan the file, and return the scan result.
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.
The response status code is 200
, and the body is JSON formatted 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, optional): The file size in bytes.
Example
curl \
-X POST \
-H 'Authorization: Bearer secret' \
-H 'Content-Type: application/json' \
-d '{"download_url": "https://download.yourcompany.com/path/to/file.pdf"}' \
'https://.../api/v1/scan/sync/download'
{"status":"clean","size":2903045}
POST /api/v1/scan/sync/binary
Upload a file, scan the file, and return the scan result.
The request body contains the binary data (application/octet-stream
).
The response status code is 200
, and the body is JSON formatted 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, optional): The file size in bytes.
Example
curl \
-X POST \
-H 'Authorization: Bearer secret' \
-H 'Content-Type: application/octet-stream' \
-d '@path/to/file' \
https://.../api/v1/scan/sync/binary
{"status":"clean","size":73928372}
POST /api/v1/scan/sync/form
Upload a file, scan the file, and return the scan result.
The request body is multipart/form-data
formatted and contains one file.
The response status code is 200
, and the body is JSON formatted 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, optional): The file size in bytes.
Example
curl \
-H 'Authorization: Bearer secret' \
-F file=@path/to/file \
https://.../api/v1/scan/sync/form
{"status":"clean","size":73928372}
POST /api/v1/scan/sync/s3
Download a file from S3, scan the file, and return the scan result.
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.
The response status code is 200
, and the body is JSON formatted 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, optional): The file size in bytes.
Example
curl \
-X POST \
-H 'Authorization: Bearer secret' \
-H 'Content-Type: application/json' \
-d '{"bucket": "you-bucket", "key": "path/to/file.pdf"}' \
'https://.../api/v1/scan/sync/s3'
{"status":"clean","size":105255200}
Setup
The synchronous HTTPS API depends on the following:
- A running bucketAV installation.
- An EC2 Key Pair (can be the same as for your bucketAV installation).
- A Route 53 public hosted zone or a Certificate Manager public certificate.
Please select the same engine as in your running bucketAV installation.
Install Add-On (requires a running bucketAV installation)
- Set the Stack name to
bucketav-api-sync
. - Set the BucketAVStackName parameter to the stack name of bucketAV (if you followed the docs, the name is
bucketav
). - Set the KeyName parameter to an EC2 Key Pair name.
- Set the ApiKeys parameter and add at least one secret value that clients use to authenticate requests using Bearer Authentication.
- The DnsConfiguration parameter controls if the DNS and TLS configuration should happen automatically in Route 53 (recommended) or manually.
AUTO_ROUTE_53
: Set the HostedZoneId parameter to a Route 53 public hosted zone ID and the DomainName parameter to the DNS name you want to use to reach your HTTPS API.MANUAL
: Set the CertificateArn parameter to an ACM public certificate ARN.
- 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
. - Depending on the DnsConfiguration parameter:
AUTO_ROUTE_53
: You are done.MANUAL
: Click on the Outputs tab to get the LoadBalancerDnsName. In Route 53, create a record:- Set Record name to match with the domain name in your ACM public certificate.
- Set Record type to A.
- Enable Alias.
- Set Route traffic to Alias to Application and Classical Load Balancer and…
- …select the regin where bucketAV is installed in and…
- …select the load balancer that includes the value from the LoadBalancerDnsName output.
- Click Create records.
Install Add-On (requires a running bucketAV installation)
- Set the Stack name to
bucketav-api-sync
. - Set the BucketAVStackName parameter to the stack name of bucketAV (if you followed the docs, the name is
bucketav
). - Set the KeyName parameter to an EC2 Key Pair name.
- Set the ApiKeys parameter and add at least one secret value that clients use to authenticate requests using Bearer Authentication.
- The DnsConfiguration parameter controls if the DNS and TLS configuration should happen automatically in Route 53 (recommended) or manually.
AUTO_ROUTE_53
: Set the HostedZoneId parameter to a Route 53 public hosted zone ID and the DomainName parameter to the DNS name you want to use to reach your HTTPS API.MANUAL
: Set the CertificateArn parameter to an ACM public certificate ARN.
- 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
. - Depending on the DnsConfiguration parameter:
AUTO_ROUTE_53
: You are done.MANUAL
: Click on the Outputs tab to get the LoadBalancerDnsName. In Route 53, create a record:- Set Record name to match with the domain name in your ACM public certificate.
- Set Record type to A.
- Enable Alias.
- Set Route traffic to Alias to Application and Classical Load Balancer and…
- …select the regin where bucketAV is installed in and…
- …select the load balancer that includes the value from the LoadBalancerDnsName output.
- Click Create records.
CloudFormation snippet
# [...]
Resources:
# [...]
ApiSync:
Type: 'AWS::CloudFormation::Stack'
Properties:
Parameters:
BucketAVStackName: 'bucketav' # if you followed the docs, the name is bucketav
KeyName: 'YOUR_EC2_KEY_NAME' # TODO replace key name (see https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html)
ApiKeys: 'secret1,secret2' # TODO replace API keys
DnsConfiguration: 'AUTO_ROUTE_53'
HostedZoneId: 'Z12345678ABCDEFGHIJKL' # TODO replace hosted zone id
DomainName: 'bucketav-api.mycompany.com' # TODO replace domain name
TemplateURL: 'https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/api-sync/v2.9.0/bucketav-add-on-api-sync-sophos-dedicated-public-vpc.yaml'
Resources:
# [...]
ApiSync:
Type: 'AWS::CloudFormation::Stack'
Properties:
Parameters:
BucketAVStackName: 'bucketav' # if you followed the docs, the name is bucketav
KeyName: 'YOUR_EC2_KEY_NAME' # TODO replace key name (see https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html)
ApiKeys: 'secret1,secret2' # TODO replace API keys
DnsConfiguration: 'AUTO_ROUTE_53'
HostedZoneId: 'Z12345678ABCDEFGHIJKL' # TODO replace hosted zone id
DomainName: 'bucketav-api.mycompany.com' # TODO replace domain name
TemplateURL: 'https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/api-sync/v2.9.0/bucketav-add-on-api-sync-clamav-dedicated-public-vpc.yaml'
Terraform snippet
resource "aws_cloudformation_stack" "bucketav_add_on_api_sync" {
name = "bucketav-api-sync"
template_url = "https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/api-sync/v2.9.0/bucketav-add-on-api-sync-sophos-dedicated-public-vpc.yaml"
capabilities = ["CAPABILITY_IAM"]
parameters = {
BucketAVStackName = "bucketav" # if you followed the docs, the name is bucketav
KeyName = "YOUR_EC2_KEY_NAME" # TODO replace key name (see https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html)
ApiKeys = "secret1,secret2" # TODO replace API keys
DnsConfiguration = "AUTO_ROUTE_53"
HostedZoneId = "Z12345678ABCDEFGHIJKL" # TODO replace hosted zone id
DomainName = "bucketav-api.mycompany.com" # TODO replace domain name
}
}
resource "aws_cloudformation_stack" "bucketav_add_on_api_sync" {
name = "bucketav-api-sync"
template_url = "https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/api-sync/v2.9.0/bucketav-add-on-api-sync-clamav-dedicated-public-vpc.yaml"
capabilities = ["CAPABILITY_IAM"]
parameters = {
BucketAVStackName = "bucketav" # if you followed the docs, the name is bucketav
KeyName = "YOUR_EC2_KEY_NAME" # TODO replace key name (see https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html)
ApiKeys = "secret1,secret2" # TODO replace API keys
DnsConfiguration = "AUTO_ROUTE_53"
HostedZoneId = "Z12345678ABCDEFGHIJKL" # TODO replace hosted zone id
DomainName = "bucketav-api.mycompany.com" # TODO replace domain name
}
}
Update
- To update this Add-On to version v2.9.0, go to the AWS CloudFormation Management Console.
- Double-check the region at the top right.
- Search for
bucketav-api-sync
, 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-sync/v2.9.0/bucketav-add-on-api-sync-sophos-dedicated-public-vpc.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.
- To update this Add-On to version v2.9.0, go to the AWS CloudFormation Management Console.
- Double-check the region at the top right.
- Search for
bucketav-api-sync
, 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-sync/v2.9.0/bucketav-add-on-api-sync-clamav-dedicated-public-vpc.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:
- VPC (see Dedicated public VPC Network topology).
- IAM Roles (see IAM).
- Application Load Balancer to distribute incoming HTTPS requests to workers.
- EC2 Auto Scaling Group with scaling rules to run and scale the fleet of workers.
- CloudWatch Dashboard to visualize the health of the system.
- CloudWatch Alarms to monitor the used AWS services.
- CloudWatch Logs to store logs.
Pricing examples
Assuming a workload of 3.000 GB / month (File size: ~5MB; File types: pdf, png, jpeg, mp3, xlsx, docx, pptx, key, zip, tar.gz; File content: real-world files, not generated) running two m5.large EC2 instances:
bucketAV powered by Sophos® | bucketAV powered by ClamAV® | |
---|---|---|
bucketAV Software Cost | $673.00/month | $202.12/month |
AWS infrastructure | $73.00/month | $202.12/month |
Please send us an email for a custom cost estimation!
Limitations
- Maximum file size is 200 MB.
- The request timeout is 60 seconds.
- The number of concurrent requests per worker is limited:
Maximum number of concurrent requests | |
---|---|
bucketAV powered by ClamAV® | 4 |
bucketAV powered by Sophos® | Number of vCPUs * 8 |
Assuming the default instance type of m5.large
:
Maximum number of concurrent requests | |
---|---|
bucketAV powered by ClamAV® | 4 |
bucketAV powered by Sophos® | 16 |
Release Notes
Subscribe to our Atom feed or newsletter to stay up-to-date! We also publish a machine-readable JSON file.
v2.9.0
Changes:
- Support new region ap-southeast-5 (ClamAV only)
- Reserved Concurrent Execution for Lambda functions
- Improved rolling update
- Bug fixes
- Amazon Linux 2023 security updates (ClamAV only)
- Amazon Linux 2 security updates (Sophos only)
Release date:2024-11-19
Templates:
- powered by Sophos:
- Dedicated public VPC (recommended):
https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/api-sync/v2.9.0/bucketav-add-on-api-sync-sophos-dedicated-public-vpc.yaml
- Dedicated public VPC (recommended):
- powered by ClamAV:
- Dedicated public VPC (recommended):
https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/api-sync/v2.9.0/bucketav-add-on-api-sync-clamav-dedicated-public-vpc.yaml
- Dedicated public VPC (recommended):
v2.8.0
Changes:
- Update to Amazon Linux 2023 (ClamAV only)
- Update to ClamAV 1.4 (ClamAV only)
- Support for RAR files (ClamAV only)
- Bug fixes
- Amazon Linux 2 security updates (Sophos only)
Release date:2024-09-24
Templates:
- powered by Sophos:
- Dedicated public VPC (recommended):
https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/api-sync/v2.8.0/bucketav-add-on-api-sync-sophos-dedicated-public-vpc.yaml
- Dedicated public VPC (recommended):
- powered by ClamAV:
- Dedicated public VPC (recommended):
https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/api-sync/v2.8.0/bucketav-add-on-api-sync-clamav-dedicated-public-vpc.yaml
- Dedicated public VPC (recommended):
v2.7.1
Changes:
- Bug fixes
- Amazon Linux 2 security updates
Release date:2024-08-13
Templates:
- powered by Sophos:
- Dedicated public VPC (recommended):
https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/api-sync/v2.7.1/bucketav-add-on-api-sync-sophos-dedicated-public-vpc.yaml
- Dedicated public VPC (recommended):
- powered by ClamAV:
- Dedicated public VPC (recommended):
https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/api-sync/v2.7.1/bucketav-add-on-api-sync-clamav-dedicated-public-vpc.yaml
- Dedicated public VPC (recommended):
v2.7.0
Changes:
- Bug fixes
- Amazon Linux 2 security updates
Release date:2024-08-05
Templates:
- powered by Sophos:
- Dedicated public VPC (recommended):
https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/api-sync/v2.7.0/bucketav-add-on-api-sync-sophos-dedicated-public-vpc.yaml
- Dedicated public VPC (recommended):
- powered by ClamAV:
- Dedicated public VPC (recommended):
https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/api-sync/v2.7.0/bucketav-add-on-api-sync-clamav-dedicated-public-vpc.yaml
- Dedicated public VPC (recommended):
v2.6.0
Changes:
- Support Sophos Live Protection cloud lookups (disabled by default)
- Amazon Linux 2 security updates
Release date:2024-06-25
Templates:
- powered by Sophos:
- Dedicated public VPC (recommended):
https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/api-sync/v2.6.0/bucketav-add-on-api-sync-sophos-dedicated-public-vpc.yaml
- Dedicated public VPC (recommended):
- powered by ClamAV:
- Dedicated public VPC (recommended):
https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/api-sync/v2.6.0/bucketav-add-on-api-sync-clamav-dedicated-public-vpc.yaml
- Dedicated public VPC (recommended):
v2.5.0
Changes:
- Bug fixes
- Amazon Linux 2 security updates
Release date:2024-05-08
Templates:
- powered by Sophos:
- Dedicated public VPC (recommended):
https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/api-sync/v2.5.0/bucketav-add-on-api-sync-sophos-dedicated-public-vpc.yaml
- Dedicated public VPC (recommended):
- powered by ClamAV:
- Dedicated public VPC (recommended):
https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/api-sync/v2.5.0/bucketav-add-on-api-sync-clamav-dedicated-public-vpc.yaml
- Dedicated public VPC (recommended):
v2.4.0
Changes:
- Bug fixes
- Amazon Linux 2 security updates
Release date:2024-04-11
Templates:
- powered by Sophos:
- Dedicated public VPC (recommended):
https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/api-sync/v2.4.0/bucketav-add-on-api-sync-sophos-dedicated-public-vpc.yaml
- Dedicated public VPC (recommended):
- powered by ClamAV:
- Dedicated public VPC (recommended):
https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/api-sync/v2.4.0/bucketav-add-on-api-sync-clamav-dedicated-public-vpc.yaml
- Dedicated public VPC (recommended):
v2.3.0
Changes:
- Bug fixes
- Amazon Linux 2 security updates
Release date:2024-03-21
Templates:
- powered by Sophos:
- Dedicated public VPC (recommended):
https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/api-sync/v2.3.0/bucketav-add-on-api-sync-sophos-dedicated-public-vpc.yaml
- Dedicated public VPC (recommended):
- powered by ClamAV:
- Dedicated public VPC (recommended):
https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/api-sync/v2.3.0/bucketav-add-on-api-sync-clamav-dedicated-public-vpc.yaml
- Dedicated public VPC (recommended):
v2.2.0
Changes:
- Bug fixes
- Amazon Linux 2 security updates
Release date:2024-03-14
Templates:
- powered by Sophos:
- Dedicated public VPC (recommended):
https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/api-sync/v2.2.0/bucketav-add-on-api-sync-sophos-dedicated-public-vpc.yaml
- Dedicated public VPC (recommended):
- powered by ClamAV:
- Dedicated public VPC (recommended):
https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/api-sync/v2.2.0/bucketav-add-on-api-sync-clamav-dedicated-public-vpc.yaml
- Dedicated public VPC (recommended):
v2.1.0
Changes:
- Bug fixes
- Amazon Linux 2 security updates
Release date:2024-02-14
Templates:
- powered by Sophos:
- Dedicated public VPC (recommended):
https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/api-sync/v2.1.0/bucketav-add-on-api-sync-sophos-dedicated-public-vpc.yaml
- Dedicated public VPC (recommended):
- powered by ClamAV:
- Dedicated public VPC (recommended):
https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/api-sync/v2.1.0/bucketav-add-on-api-sync-clamav-dedicated-public-vpc.yaml
- Dedicated public VPC (recommended):
v2.0.2
Changes:
- Only route known paths to EC2 instances
Release date:2024-01-17
Templates:
- powered by Sophos:
- Dedicated public VPC (recommended):
https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/api-sync/v2.0.2/bucketav-add-on-api-sync-sophos-dedicated-public-vpc.yaml
- Dedicated public VPC (recommended):
- powered by ClamAV:
- Dedicated public VPC (recommended):
https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/api-sync/v2.0.2/bucketav-add-on-api-sync-clamav-dedicated-public-vpc.yaml
- Dedicated public VPC (recommended):
v2.0.1
Changes:
- Hide ApiKeys parameter values
Release date:2024-01-17
Templates:
- powered by Sophos:
- Dedicated public VPC (recommended):
https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/api-sync/v2.0.1/bucketav-add-on-api-sync-sophos-dedicated-public-vpc.yaml
- Dedicated public VPC (recommended):
- powered by ClamAV:
- Dedicated public VPC (recommended):
https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/api-sync/v2.0.1/bucketav-add-on-api-sync-clamav-dedicated-public-vpc.yaml
- Dedicated public VPC (recommended):
v2.0.0
Changes:
- Initial release
Release date:2024-01-17
Templates:
- powered by Sophos:
- Dedicated public VPC (recommended):
https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/api-sync/v2.0.0/bucketav-add-on-api-sync-sophos-dedicated-public-vpc.yaml
- Dedicated public VPC (recommended):
- powered by ClamAV:
- Dedicated public VPC (recommended):
https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/api-sync/v2.0.0/bucketav-add-on-api-sync-clamav-dedicated-public-vpc.yaml
- Dedicated public VPC (recommended):