Skip to main content

Serverless architecture to virus scan objects in Amazon S3.

Project description

cdk-serverless-clamscan

npm version PyPI version

An aws-cdk construct that uses ClamAV® to scan newly uploaded objects to Amazon S3 for viruses. The construct provides a flexible interface for a system to act based on the results of a ClamAV virus scan. Check out this blogpost for a guided walkthrough.

Overview

Pre-Requisites

Docker: The ClamAV Lambda functions utilizes a container image that is built locally using docker bundling

Examples

This project uses projen and thus all the constructs follow language specific standards and naming patterns. For more information on how to translate the following examples into your desired language read the CDK guide on Translating TypeScript AWS CDK code to other languages

Example 1. (Default destinations with rule target)

typescript

import { RuleTargetInput } from 'aws-cdk-lib/aws-events';
import { SnsTopic } from 'aws-cdk-lib/aws-events-targets';
import { Bucket } from 'aws-cdk-lib/aws-s3';
import { Topic } from 'aws-cdk-lib/aws-sns';
import { Stack, StackProps } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { ServerlessClamscan } from 'cdk-serverless-clamscan';

export class CdkTestStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    const bucket_1 = new Bucket(this, 'rBucket1');
    const bucket_2 = new Bucket(this, 'rBucket2');
    const bucketList = [bucket_1, bucket_2];
    const sc = new ServerlessClamscan(this, 'rClamscan', {
      buckets: bucketList,
    });
    const bucket_3 = new Bucket(this, 'rBucket3');
    sc.addSourceBucket(bucket_3);
    const infectedTopic = new Topic(this, 'rInfectedTopic');
    sc.infectedRule?.addTarget(
      new SnsTopic(infectedTopic, {
        message: RuleTargetInput.fromEventPath(
          '$.detail.responsePayload.message',
        ),
      }),
    );
  }
}

python

from aws_cdk import (
  Stack,
  aws_events as events,
  aws_events_targets as events_targets,
  aws_s3 as s3,
  aws_sns as sns
)
from cdk_serverless_clamscan import ServerlessClamscan
from constructs import Construct

class CdkTestStack(Stack):

  def __init__(self, scope: Construct, construct_id: str, **kwargs) -> None:
    super().__init__(scope, construct_id, **kwargs)

    bucket_1 = s3.Bucket(self, "rBucket1")
    bucket_2 = s3.Bucket(self, "rBucket2")
    bucketList = [ bucket_1, bucket_2 ]
    sc = ServerlessClamscan(self, "rClamScan",
      buckets=bucketList,
    )
    bucket_3 = s3.Bucket(self, "rBucket3")
    sc.add_source_bucket(bucket_3)
    infected_topic = sns.Topic(self, "rInfectedTopic")
    if sc.infected_rule != None:
      sc.infected_rule.add_target(
        events_targets.SnsTopic(
          infected_topic,
          message=events.RuleTargetInput.from_event_path('$.detail.responsePayload.message'),
        )
      )

Example 2. (Bring your own destinations)

typescript

import {
  SqsDestination,
  EventBridgeDestination,
} from 'aws-cdk-lib/aws-lambda-destinations';
import { Bucket } from 'aws-cdk-lib/aws-s3';
import { Queue } from 'aws-cdk-lib/aws-sqs';
import { Stack, StackProps } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { ServerlessClamscan } from 'cdk-serverless-clamscan';

export class CdkTestStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    const bucket_1 = new Bucket(this, 'rBucket1');
    const bucket_2 = new Bucket(this, 'rBucket2');
    const bucketList = [bucket_1, bucket_2];
    const queue = new Queue(this, 'rQueue');
    const sc = new ServerlessClamscan(this, 'default', {
      buckets: bucketList,
      onResult: new EventBridgeDestination(),
      onError: new SqsDestination(queue),
    });
    const bucket_3 = new Bucket(this, 'rBucket3');
    sc.addSourceBucket(bucket_3);
  }
}

python

from aws_cdk import (
  Stack,
  aws_lambda_destinations as lambda_destinations,
  aws_s3 as s3,
  aws_sqs as sqs
)
from cdk_serverless_clamscan import ServerlessClamscan
from constructs import Construct

class CdkTestStack(Stack):

  def __init__(self, scope: Construct, construct_id: str, **kwargs) -> None:
    super().__init__(scope, construct_id, **kwargs)

    bucket_1 = s3.Bucket(self, "rBucket1")
    bucket_2 = s3.Bucket(self, "rBucket2")
    bucketList = [ bucket_1, bucket_2 ]
    queue = sqs.Queue(self, "rQueue")
    sc = ServerlessClamscan(self, "rClamScan",
      buckets=bucketList,
      on_result=lambda_destinations.EventBridgeDestination(),
      on_error=lambda_destinations.SqsDestination(queue),
    )
    bucket_3 = s3.Bucket(self, "rBucket3")
    sc.add_source_bucket(bucket_3)

Operation and Maintenance

When ClamAV publishes updates to the scanner you will see “Your ClamAV installation is OUTDATED” in your scan results. While the construct creates a system to keep the database definitions up to date, you must update the scanner to detect all the latest Viruses.

Update the docker images of the Lambda functions with the latest version of ClamAV by re-running cdk deploy.

Optionally Skip Files

In certain situations, you may have files which are already scanned and you wish to omit them from ClamAV scanning. In that case, simply tag the s3 object with "scan-status": "N/A" and the file will be automatically skipped.

Example 1. (Upload file to skip)

python/boto

boto3.client('s3').upload_file(
    Filename=file_path,
    Bucket=bucket_name,
    Key=object_key,
    ExtraArgs={'Tagging': 'scan-status=N/A'}
)

typscript/aws-sdk

const params = {
  Bucket: bucketName,
  Key: objectKey,
  Body: fileContent,
  Tagging: 'scan-status=N/A',
};
const command = new PutObjectCommand(params);
const response = await (new S3Client()).send(command);

API Reference

See API.md.

Contributing

See CONTRIBUTING for more information.

License

This project is licensed under the Apache-2.0 License.

Project details


Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

cdk_serverless_clamscan-2.11.80.tar.gz (160.4 kB view details)

Uploaded Source

Built Distribution

cdk_serverless_clamscan-2.11.80-py3-none-any.whl (158.7 kB view details)

Uploaded Python 3

File details

Details for the file cdk_serverless_clamscan-2.11.80.tar.gz.

File metadata

File hashes

Hashes for cdk_serverless_clamscan-2.11.80.tar.gz
Algorithm Hash digest
SHA256 2d487964a40e9ac6853c02d6eec1a20772e9f6abad517052b27c5e3065006583
MD5 4bf22b30fd862b930a40caad89fb8fce
BLAKE2b-256 b466e5cca6b0620fc0179acc19dfe93f445b9bbde68f3a03363de0581ac4f325

See more details on using hashes here.

File details

Details for the file cdk_serverless_clamscan-2.11.80-py3-none-any.whl.

File metadata

File hashes

Hashes for cdk_serverless_clamscan-2.11.80-py3-none-any.whl
Algorithm Hash digest
SHA256 179ac315bbeb2853523754f96209c4aea51bd50fdcf4fdffaac5f6fa62ab5970
MD5 1e67cbbebefb11e4ec4f7d3415137649
BLAKE2b-256 b94a6d6308ef936bb46a4e671d934bd805b82b6d8732a795f8fcd95377e06198

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page