ClamAV (Anti-Virus) as a REST application on AWS ECS

Source: Dev.to

Abstract

This project provides an AWS CDK solution for automated virus scanning of S3 objects using ClamAV. By running the ClamAV daemon (clamd) as a containerized REST API on AWS ECS Fargate, it eliminates the 15‑30 second cold‑start delay typical of Lambda‑based implementations, delivering near‑instant scan results.

The architecture uses a hybrid approach:

• ECS Fargate hosts a persistent ClamAV daemon service.
• Lambda functions process S3 events, invoke the ClamAV REST API, and publish results to SNS topics.

Infrastructure as Code with AWS CDK

Core Infrastructure

• VPC – Multi‑AZ with public, private‑isolated, and private‑with‑egress subnets.
• ECS Fargate Cluster – Runs the ClamAV REST API containers (optionally on Fargate Spot for cost savings).
• Network Load Balancer (NLB) – Internal load balancer that routes traffic to the ClamAV API containers.
• S3 Gateway Endpoint – Enables private‑subnet access to S3 without a NAT gateway.

Application Components

ClamAV REST API on ECS Fargate

• Container stack – Based on python:3.14-bookworm with clamav, clamav-daemon, nginx, uwsgi, Flask, and supervisor.
• API endpoints
  • GET / – Health check (returns OK).
  • POST /scan_file – Accepts a JSON payload containing an S3 bucket and key, performs a scan via the pre‑loaded daemon, and returns the result.

Result Notification System

• SNS Topics
  • clamav-clean-topic – Notifications for clean files.
  • clamav-infected-topic – Notifications for infected files.
• Message format

{
  "input_bucket": "bucket-name",
  "input_key": "path/to/file.pdf",
  "status": "CLEAN" | "INFECTED",
  "message": "Scanning bucket-name/path/to/file.pdf\n"
}

• SQS Dead‑Letter Queue – Captures failed scan operations for retry or manual inspection.

Prerequisites

• AWS account with appropriate permissions.
• AWS CDK CLI installed (npm install -g aws-cdk).
• Node.js 16+ and pnpm package manager.
• Docker (for building container images).
• AWS CLI configured with credentials.

Installation and Deployment

# Clone the repository
git clone https://github.com/vumdao/cdk-clamav-rest-api-on-aws-ecs.git
cd cdk-clamav-rest-api-on-aws-ecs

# Install dependencies
pnpm install

# Deploy the stack
pnpm run deploy

Build and Push Docker Image to ECR

During CDK deployment the image is built and pushed automatically, but you can do it manually:

# Navigate to the Dockerfile directory
cd src/lib/constructs/s3-serverless-clamscan/clamd-api

# Build the Docker image
docker build -t simflexcloud/clamav-api .

# Authenticate Docker to your ECR registry (replace <account-id> and <region>)
aws ecr get-login-password --region <region> | \
docker login --username AWS --password-stdin <account-id>.dkr.ecr.<region>.amazonaws.com

# Tag the image for ECR
docker tag simflexcloud/clamav-api:latest \
<account-id>.dkr.ecr.<region>.amazonaws.com/simflexcloud/clamav-api:latest

# Push the image to ECR
docker push <account-id>.dkr.ecr.<region>.amazonaws.com/simflexcloud/clamav-api:latest

Expected CDK output

✅  S3ClamAvStack
Outputs:
S3ClamAvStack.EcsClusterProviderclamav-apiEndpoint = nlb-xxxx.elb..amazonaws.com:5000

Testing the Solution

1. Upload a clean file to the monitored S3 bucket and verify that a message appears on clamav-clean-topic.
2. Upload the EICAR test virus (a harmless test string) and confirm that an INFECTED notification is sent to clamav-infected-topic.

You can subscribe an SQS queue, Lambda function, or email endpoint to the SNS topics to observe the messages.

Cleanup Stack

When the demo is no longer needed, destroy all resources:

pnpm run destroy

Conclusion

By offloading ClamAV scanning to a persistent daemon running on ECS Fargate, this solution removes the cold‑start penalty of Lambda‑based scanners while retaining the scalability and operational simplicity of serverless workflows. The combination of AWS managed services (ECS Fargate, Lambda, S3, SNS, SQS) with the open‑source ClamAV engine delivers a production‑ready, cost‑effective virus‑scanning pipeline.