Synchronous HTTPS API

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 (#)

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.

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.

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.4.0/bucketav-add-on-api-sync-sophos-dedicated-public-vpc.yaml' # TODO use this for bucketAV powered by Sophos®...
      #TemplateURL: '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' # ...or this for bucketAV powered by ClamAV®.

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.4.0/bucketav-add-on-api-sync-sophos-dedicated-public-vpc.yaml" # TODO use this for bucketAV powered by Sophos®...
  #template_url = "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" # ...or this for bucketAV powered by ClamAV®.
  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 (#)

Which version am I using?

1. To update this Add-On to version v2.4.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:
   • bucketAV powered by Sophos®: 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 Copy
   • bucketAV powered by ClamAV®: 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 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:

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

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:

Assuming the default instance type of m5.large:

Release Notes (#)

Subscribe to our Atom feed or newsletter to stay up-to-date! We also publish a machine-readable JSON file.

v2.4.0

Changes:

• Bug fixes
• Amazon Linux 2 security updates

Release date:2024-04-11

Templates:

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

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

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

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

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

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

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