Guides

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:

  1. A running bucketAV installation.
  2. An EC2 Key Pair (can be the same as for your bucketAV installation).
  3. 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)

  1. Set the Stack name to bucketav-api-sync.
  2. Set the BucketAVStackName parameter to the stack name of bucketAV (if you followed the docs, the name is bucketav).
  3. Set the KeyName parameter to an EC2 Key Pair name.
  4. Set the ApiKeys parameter and add at least one secret value that clients use to authenticate requests using Bearer Authentication.
  5. 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.
  6. Select I acknowledge that AWS CloudFormation might create IAM resources.
  7. Click on the Create stack button to save.
  8. Wait for the stack to reach status CREATE_COMPLETE.
  9. 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:
      1. Set Record name to match with the domain name in your ACM public certificate.
      2. Set Record type to A.
      3. Enable Alias.
      4. Set Route traffic to Alias to Application and Classical Load Balancer and…
      5. …select the regin where bucketAV is installed in and…
      6. …select the load balancer that includes the value from the LoadBalancerDnsName output.
      7. Click Create records.

Install Add-On (requires a running bucketAV installation)

  1. Set the Stack name to bucketav-api-sync.
  2. Set the BucketAVStackName parameter to the stack name of bucketAV (if you followed the docs, the name is bucketav).
  3. Set the KeyName parameter to an EC2 Key Pair name.
  4. Set the ApiKeys parameter and add at least one secret value that clients use to authenticate requests using Bearer Authentication.
  5. 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.
  6. Select I acknowledge that AWS CloudFormation might create IAM resources.
  7. Click on the Create stack button to save.
  8. Wait for the stack to reach status CREATE_COMPLETE.
  9. 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:
      1. Set Record name to match with the domain name in your ACM public certificate.
      2. Set Record type to A.
      3. Enable Alias.
      4. Set Route traffic to Alias to Application and Classical Load Balancer and…
      5. …select the regin where bucketAV is installed in and…
      6. …select the load balancer that includes the value from the LoadBalancerDnsName output.
      7. Click Create records.
Not available. Please contact us if you have a use case for it!
Not available. Please contact us if you have a use case for it!

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.10.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.10.0/bucketav-add-on-api-sync-clamav-dedicated-public-vpc.yaml'
Not available. Please contact us if you have a use case for it!
Not available. Please contact us if you have a use case for it!

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.10.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.10.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
  }
}
Not available. Please contact us if you have a use case for it!
Not available. Please contact us if you have a use case for it!

Update

Which version am I using?

  1. To update this Add-On to version v2.10.0, go to the AWS CloudFormation Management Console.
  2. Double-check the region at the top right.
  3. Search for bucketav-api-sync, 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-sync/v2.10.0/bucketav-add-on-api-sync-sophos-dedicated-public-vpc.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.
  1. To update this Add-On to version v2.10.0, go to the AWS CloudFormation Management Console.
  2. Double-check the region at the top right.
  3. Search for bucketav-api-sync, 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-sync/v2.10.0/bucketav-add-on-api-sync-clamav-dedicated-public-vpc.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.
Not available. Please contact us if you have a use case for it!
Not available. Please contact us if you have a use case for it!

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.10.0

Changes:

  • Update to Amazon Linux 2023 (Sophps only)
  • Bug fixes
  • Amazon Linux 2023 security updates (ClamAV only)

Release date:2024-12-18

Templates:

  • powered by Sophos:
    • Dedicated public VPC (recommended): https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/api-sync/v2.10.0/bucketav-add-on-api-sync-sophos-dedicated-public-vpc.yaml
  • powered by ClamAV:
    • Dedicated public VPC (recommended): https://bucketav-add-ons.s3.eu-west-1.amazonaws.com/api-sync/v2.10.0/bucketav-add-on-api-sync-clamav-dedicated-public-vpc.yaml

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
  • 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

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
  • 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

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
  • 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

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
  • 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

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
  • 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

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
  • 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

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
  • 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

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
  • 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

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
  • 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

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
  • 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

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
  • 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

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
  • 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

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
  • 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
Not available. Please contact us if you have a use case for it!

Need more help?

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

Send us an email