Virus and Malware Scan API (Self-hosted on AWS)

Installation (#)

In case you need any help installing attachmentAV API, please let us know. Write in via hello@attachmentav.com.

Deploying the attachmentAV API to your AWS account is simple and takes about 15 minutes.

First, open attachmentAV Virus and Malware Scan API in the AWS Marketplace. Then, click the View purchase options button.

Next, subscribe to the product by clicking the Accept Terms button.

It takes a while until AWS processes the subscription. Continue by clicking the Continue to Configuration button.

Now, it is time to decide which fulfillment option to choose.

• Dedicated Public VPC (recommended) deploys a separate VPC in your AWS account. The VPC is pre-configured for attachmentAV API and ensures to isolate the workload from other workloads in the same account. This option deploys an Internet-facing API and uses firewall rules as well as an authentication token to secure the workload.
• Exsisting VPC allows you to deploy the attachmentAV API into an existing VPC. There are two main reasons for choosing this option: a) you want to deploy an internal API, or b) you have very specific networking requirements to fulfill security governance standards.

Besides the fulfillment option, choose the latest software version and the AWS region where you would like to deploy the solution.

Continue by clicking the Continue to Launch button.

Next, ensure that the action Launch CloudFormation is selected and continue by pressing the Launch button. Doing so redirects you to the AWS Management Console and opens the CloudFormation service.

We use CloudFormation to deploy our solution consisting of the following building blocks to your AWS account with ease: VPC, Elastic Load Balacner, Auto Scaling Group, EC2 instances, IAM roles, CloudWatch alarms and dashboards, and more.

To start the creation of a CloudFormation stack, keep the defaults and click the Next button.

Now, it is time to configure the attachmentAV API for your needs. The following parameters are mandatory:

• ApiKeys: API keys for authenticating client requests using Bearer Authentication. Separate API keys with a comma (e.g., key1,key2).
• KeyName: Name of the EC2 key pair to log in via SSH (username: ec2-user).
• ApiIngressCidrIp: Ingress rule allows HTTP(S) access from this IP address range (e.g., access from anywhere: 0.0.0.0/0, from single public IP address 91.45.138.21/32).

attachmentAV API supports two types of DNS and certificate configuration. Choose by selecting one of the following options for the DnsConfiguration parameter.

• AUTO_ROUTE_53 - Automatically configure DNS and the certificate. Works for Internet-facing API endpoints only.
• MANUAL - Configure DNS and the certificate manually. Works for both Internet-facing and internal API endpoints.

When selecting AUTO_ROUTE_53 the following additional parameters are required:

• HostedZoneId: Route 53 public hosted zone ID.
• DomainName: Domain name added to Route 53 public hosted zone and Certificate Manager public certificate.

Alternatively, if you choose MANUAL the following additional parameters are required:

• CertificateArn: ACM public certificate ARN (required if DnsConfiguration:=MANUAL).

After you have configured all the parameters, click the Next button.

In the next step, scroll to the bottom …

… and check the I acknowledge that AWS CloudFormation might create IAM resource box. Then, press the Next button.

Next, review the configuration of the CloudFormation stack and click the Submit button at the bottom of the page.

It will take about five minutes until the CloudFormation stack reaches the state CREATE_COMPLETE.

Lucky you, if you selected AUTO_ROUTE_53 as DnsConfiguration: you are done! The attachmentAV API is reachable under the DNS name you configured with the DomainName parameter.

In case you selected MANUAL as DnsConfiguration you need to find out the DNS name of the load balancer next. Select the Outputs tab of the CloudFormation stack. There you will find an output named LoadBalancerDnsName, which is attach-LoadB-cxSBVufhtM5S-39311217.eu-west-1.elb.amazonaws.com in our example. Ensure to create a CNAME record pointing to the value of LoadBalancerDnsName. The attachmentAV API is reachable under the DNS name of the CNAME you created.

API definition (#)

Accessing the API requires an API key. Pass the API key via a Authorization HTTP header.

The following snippet shows the HTTP header. Ensure to replace <API_KEY> with one of the API keys that you configured for the parameter ApiKeys when creating the CloudFormation stack.

Authorization: Bearer <API_KEY>

The following examples assume that you replace attachmentav.yourcompany.com with the actual domain name of your attachmentAV API installation.

POST /v1/scan/sync/download (#)

Download a file from a remote location (HTTP/HTTPS), scan the file, and return the scan result.

Maximum file size is limited by volume size only. The request timeout is 60 seconds.

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 XXX' \
  -H 'Content-Type: application/json' \
  -d '{"download_url": "https://download.yourcompany.com/path/to/file.pdf"}' \
  'https://attachmentav.yourcompany.com/v1/scan/sync/download'

{"status":"clean","size":2903045}

POST /v1/scan/sync/binary (#)

Upload a file, scan the file, and return the scan result.

Maximum file size is 200 MB. The request timeout is 60 seconds.

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 XXX' \
  -H 'Content-Type: application/octet-stream' \
  -d '@path/to/file' \
  https://attachmentav.yourcompany.com/v1/scan/sync/binary

{"status":"clean","size":73928372}

POST /v1/scan/sync/form (#)

Upload a file, scan the file, and return the scan result.

Maximum file size is 200 MB. The request timeout is 60 seconds.

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 XXX' \
  -F file=@path/to/file \
  https://attachmentav.yourcompany.com/v1/scan/sync/form

{"status":"clean","size":73928372}

POST /v1/scan/sync/s3 (#)

Download a file from S3, scan the file, and return the scan result. A bucket policy is required to grant attachmentAV access to the S3 objects.

Maximum file size only limited by the volume size. The request timeout is 60 seconds.

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 XXX' \
  -H 'Content-Type: application/json' \
  -d '{"bucket": "you-bucket", "key": "path/to/file.pdf"}' \
  'https://attachmentav.yourcompany.com/v1/scan/sync/s3'

{"status":"clean","size":105255200}

IAM roles (#)

attachmentAV deploys two IAM roles:

• ScanIAMRole: Allow Scan Fleet EC2 instances to scan objects. See ScanIAMRole.
• FlowLogRole: Required for VPC Flow Logs.
• AutoScalingGroupCalculatorRole: Allows Lambda function to create a CloudWatch log group and write log messages.

ScanIAMRole (#)

The Scan Fleet EC2 instances have access to the following AWS APIs:

• S3 access to read, delete (optional), tag (optional), and list objects and versions (can be restricted to S3 buckets/objects via the config parameters S3BucketRestriction and S3ObjectRestriction).
• KMS access to decrypt S3 objects (can be restricted to KMS keys via the config parameter KMSKeyRestriction).
• CloudWatch access to publish custom metrics under attachmentav namespace.
• CloudWatch access to publish logs to the internal log group.
• EC2 Auto Scaling access to handle lifecycle hooks.
• Marketplace Metering Service access to report usage.
• Systems Manager Session Manager access configuration parameter SystemsManagerAccess is set to true.

You can add additional permissions via the configuration parameter ManagedPolicyArns.