MLPAB-2117 - Update documentation (#396)

.github/workflows/lambda-zip-release.yml

@@ -16,8 +16,8 @@ jobs:
         uses: actions/create-release@v1
         id: create_release
         with:
-          draft: false
-          prerelease: true
+          draft: ${{ github.ref != 'refs/heads/main' }}
+          prerelease: ${{ github.ref != 'refs/heads/main' }}
           release_name: ${{ inputs.tag }}
           tag_name: ${{ inputs.tag }}
         env:

README.md

@@ -1,2 +1,21 @@
 # opg-s3-antivirus
-Development repository: Managed by opg-org-infra & Terraform
+
+opg-s3-antivirus is a lambda function that scans files uploaded to an S3 bucket for viruses. It uses the ClamAV antivirus engine to scan files.
+
+The lambda function is triggered by put object events in the S3 bucket.
+
+Once scanned, the function adds a tag `virus-scan-status` to the object in S3 with the result of the scan, either `ok` or `infected`.
+
+## Antivirus Scan Function
+
+You can find examples of how to use the scan lambda function in [docs/examples.md](docs/examples.md).
+
+The zip version of the scan lamdba function and it's layer are base on the al2023 runtime, and the x86_64 architecture.
+
+## Antivirus Definitions Update Function
+
+The update function is an image based lambda function that updates the ClamAV definitions.
+
+## Contact
+
+Should you wish to talk to others about using this service, you can find help in the #ss-opg-s3-antivirus slack channel.

docs/example-scripts/pull-av-scan-zip-packages.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+# Bash script to pull S3 Antivirus Scan Zip Packages for Lambda
+# Ensures that aws-vault and a profile for management that allows
+# ssm get-parameter are present before running.
+
+set -e
+
+key="/opg-s3-antivirus/zip-version-main"
+value=$(aws-vault exec management-operator -- aws ssm get-parameter --name "$key" --query 'Parameter.Value' --output text 2>/dev/null || true)
+echo "Using $key: $value"
+
+echo "Pulling Antivirus lambda and Layer version: $value"
+wget -q -O ./region/modules/s3_antivirus/lambda_layer.zip https://github.com/ministryofjustice/opg-s3-antivirus/releases/download/"$value"/lambda_layer-amd64.zip
+wget -q -O ./region/modules/s3_antivirus/lambda_layer.zip.sha256sum https://github.com/ministryofjustice/opg-s3-antivirus/releases/download/"$value"/lambda_layer-amd64.zip.sha256sum
+(cd ./region/modules/s3_antivirus/ && sha256sum -c "lambda_layer.zip.sha256sum")
+wget -q -O ./region/modules/s3_antivirus/myFunction.zip https://github.com/ministryofjustice/opg-s3-antivirus/releases/download/"$value"/myFunction-amd64.zip
+wget -q -O ./region/modules/s3_antivirus/myFunction.zip.sha256sum https://github.com/ministryofjustice/opg-s3-antivirus/releases/download/"$value"/myFunction-amd64.zip.sha256sum
+(cd ./region/modules/s3_antivirus/ && sha256sum -c "myFunction.zip.sha256sum")

docs/examples.md

@@ -0,0 +1,124 @@
+# Examples
+
+Here are some useful code snippets to help you get started with the S3 Antivirus Scanner Lambda Function.
+
+## Fetching a version tag of the Lambda Function Zip and Lambda Layer Package
+
+The workflow for this repository writes a version tag to the SSM Parameter Store. This can be used to fetch the version of the Lambda Function Zip and Lambda Layer Package. The parameter is in the management account in the eu-west-1 region.
+
+```shell
+key="/opg-s3-antivirus/zip-version-main"
+value=$(aws ssm get-parameter --name "$key" --query 'Parameter.Value' --output text 2>/dev/null || true)
+echo "Using $key: $value"
+
+```
+
+When working locally you can use the script in [./example-scripts/pull-av-scan-zip-package-version.sh](./example-scripts/pull-av-scan-zip-packages.sh) to fetch the version tag using something like envrc.
+
+```shell
+
+## Fetching a version of the Lambda Function Zip and Lambda Layer Package
+
+```shell
+wget -O myFunction.zip https://github.com/ministryofjustice/opg-s3-antivirus/releases/download/v0.594.0/myFunction-amd64.zip
+wget -O myFunction.zip.sha256sum https://github.com/ministryofjustice/opg-s3-antivirus/releases/download/v0.594.0/myFunction-amd64.zip.sha256sum
+sha256sum -c "myFunction.zip.sha256sum"
+wget -O lambda_layer.zip https://github.com/ministryofjustice/opg-s3-antivirus/releases/download/v0.594.0/lambda_layer-amd64.zip
+wget -O lambda_layer.zip.sha256sum https://github.com/ministryofjustice/opg-s3-antivirus/releases/download/v0.594.0/lambda_layer-amd64.zip.sha256sum
+sha256sum -c "lambda_layer.zip.sha256sum"
+```
+
+## Deploying the zip package to AWS Lambda with Terraform
+
+```hcl
+resource "aws_lambda_layer_version" "lambda_layer" {
+  filename                 = "${path.module}/lambda_layer.zip"
+  layer_name               = "clamav"
+  description              = "ClamAV Antivirus Layer"
+  source_code_hash         = filebase64sha256("${path.module}/lambda_layer.zip")
+  compatible_architectures = ["x86_64"]
+  compatible_runtimes      = ["provided.al2023"]
+  provider                 = aws.region
+}
+
+resource "aws_lambda_function" "zip_lambda_function" {
+  function_name    = "zip-s3-antivirus"
+  description      = "Function to scan S3 objects for viruses"
+  filename         = "${path.module}/myFunction.zip"
+  handler          = "bootstrap"
+  source_code_hash = filebase64sha256("${path.module}/myFunction.zip")
+
+  architectures = ["x86_64"]
+  runtime       = "provided.al2023"
+  timeout       = 300
+  memory_size   = 4096
+  publish       = true
+
+  layers = [
+    aws_lambda_layer_version.lambda_layer.arn
+  ]
+
+  role = var.lambda_task_role.arn
+
+  tracing_config {
+    mode = "Active"
+  }
+
+  logging_config {
+    log_group  = var.aws_cloudwatch_log_group.name
+    log_format = "JSON"
+  }
+
+  dynamic "environment" {
+    for_each = length(keys(var.environment_variables)) == 0 ? [] : [true]
+    content {
+      variables = var.environment_variables
+    }
+  }
+  provider = aws.region
+}
+```
+
+## Deploying the image to AWS Lambda with Terraform
+
+```hcl
+data "aws_ecr_repository" "s3_antivirus" {
+  name     = "s3-antivirus"
+  provider = aws.management
+}
+
+data "aws_ecr_image" "s3_antivirus" {
+  repository_name = data.aws_ecr_repository.s3_antivirus.name
+  image_tag       = "latest"
+  provider        = aws.management
+}
+
+resource "aws_lambda_function" "lambda_function" {
+  function_name = "s3-antivirus"
+  description   = "Function to scan S3 objects for viruses"
+  image_uri     = "${data.aws_ecr_repository.s3_antivirus.repository_url}@${data.aws_ecr_image.s3_antivirus.image_digest}"
+  package_type  = "Image"
+  role          = var.lambda_task_role.arn
+  timeout       = 300
+  memory_size   = 4096
+  publish       = true
+
+  tracing_config {
+    mode = "Active"
+  }
+
+  logging_config {
+    log_group  = var.aws_cloudwatch_log_group.name
+    log_format = "JSON"
+  }
+
+  dynamic "environment" {
+    for_each = length(keys(var.environment_variables)) == 0 ? [] : [true]
+    content {
+      variables = var.environment_variables
+    }
+  }
+  provider = aws.region
+}
+
+```

docs/pull_request_template.md

@@ -0,0 +1,13 @@
+# Purpose
+
+Briefly describe the purpose of the change, and/or link to the JIRA ticket for context
+
+Fixes: (Ticket Reference)
+
+## Approach
+
+Explain how your code addresses the purpose of the change
+
+## Learning
+
+Any tips and tricks, blog posts or tools which helped you. Plus anything notable you've discovered about the Modernising LPA service