Initial implementation

.bandit.yml

@@ -10,4 +10,4 @@ tests:
 # - B102
 
 skips:
-# - B101 # skip "assert used" check since assertions are required in pytests
+  - B101  # skip "assert used" check since assertions are required in pytests

.github/dependabot.yml

@@ -19,6 +19,8 @@ updates:
       - dependency-name: actions/setup-python
       - dependency-name: hashicorp/setup-terraform
       - dependency-name: mxschmitt/action-tmate
+      # Managed by cisagov/skeleton-aws-lambda-python
+      # - dependency-name: actions/upload-artifact
 
   - package-ecosystem: "pip"
     directory: "/"

.github/workflows/build.yml

@@ -9,6 +9,7 @@ on:
 
 env:
   CURL_CACHE_DIR: ~/.cache/curl
+  DEFAULT_ARTIFACT_NAME: lambda_build.zip
   PIP_CACHE_DIR: ~/.cache/pip
   PRE_COMMIT_CACHE_DIR: ~/.cache/pre-commit
   RUN_TMATE: ${{ secrets.RUN_TMATE }}
@@ -98,3 +99,71 @@ jobs:
       - name: Setup tmate debug session
         uses: mxschmitt/action-tmate@v3
         if: env.RUN_TMATE
+  test:
+    runs-on: ubuntu-latest
+    needs: lint
+    steps:
+      - id: setup-env
+        uses: cisagov/setup-env-github-action@develop
+      - uses: actions/checkout@v3
+      - id: setup-python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.10"
+      - uses: actions/cache@v3
+        env:
+          BASE_CACHE_KEY: "${{ github.job }}-${{ runner.os }}-\
+            py${{ steps.setup-python.outputs.python-version }}-"
+        with:
+          path: |
+            ${{ env.PIP_CACHE_DIR }}
+          key: "${{ env.BASE_CACHE_KEY }}\
+            ${{ hashFiles('**/requirements-test.txt') }}-\
+            ${{ hashFiles('**/requirements.txt') }}"
+          restore-keys: |
+            ${{ env.BASE_CACHE_KEY }}
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install --upgrade --requirement requirements-test.txt
+      - name: Run tests
+        env:
+          GITHUB_RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: pytest
+      - name: Setup tmate debug session
+        uses: mxschmitt/action-tmate@v3
+        if: env.RUN_TMATE
+  build:
+    runs-on: ubuntu-latest
+    needs:
+      - lint
+      - test
+    strategy:
+      matrix:
+        # Python runtime versions supported by AWS
+        python-version:
+          - "3.7"
+          - "3.8"
+          - "3.9"
+    steps:
+      - uses: actions/checkout@v3
+      - name: Get the short SHA for the commit being used
+        run: |
+          echo "GH_SHORT_SHA=${GITHUB_SHA::7}" >> $GITHUB_ENV
+      - name: Build the base Lambda Docker image
+        run: |
+          docker compose build \
+            --build-arg PY_VERSION=${{ matrix.python-version }} \
+            build_deployment_package
+      - name: Generate the Lambda deployment package
+        run: docker compose up build_deployment_package
+      - name: Upload the generated Lambda deployment package as an artifact
+        uses: actions/upload-artifact@v3
+        with:
+          name: "${{ github.event.repository.name }}-\
+            py${{ matrix.python-version }}-\
+            ${{ env.GH_SHORT_SHA }}"
+          path: "${{ env.DEFAULT_ARTIFACT_NAME }}"
+      - name: Setup tmate debug session
+        uses: mxschmitt/action-tmate@v3
+        if: env.RUN_TMATE

.github/workflows/codeql-analysis.yml

@@ -0,0 +1,67 @@
+---
+# For most projects, this workflow file will not need changing; you simply need
+# to commit it to your repository.
+#
+# You may wish to alter this file to override the set of languages analyzed,
+# or to provide custom queries or build logic.
+name: "CodeQL"
+
+on:
+  push:
+    # Dependabot triggered push events have read-only access, but uploading code
+    # scanning requires write access.
+    branches-ignore:
+      - dependabot/**
+  pull_request:
+    # The branches below must be a subset of the branches above
+    branches:
+      - develop
+  schedule:
+    - cron: '0 14 * * 6'
+
+jobs:
+  analyze:
+    name: Analyze
+    runs-on: ubuntu-latest
+    permissions:
+      # required for all workflows
+      security-events: write
+    strategy:
+      fail-fast: false
+      matrix:
+        # Override automatic language detection by changing the below list
+        # Supported options are go, javascript, csharp, python, cpp, and java
+        language:
+          - python
+        # Learn more...
+        # https://docs.github.com/en/github/finding-security-vulnerabilities-and-errors-in-your-code/configuring-code-scanning#overriding-automatic-language-detection
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+
+      # Initializes the CodeQL tools for scanning.
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v2
+        with:
+          languages: ${{ matrix.language }}
+
+      # Autobuild attempts to build any compiled languages (C/C++, C#, or
+      # Java). If this step fails, then you should remove it and run the build
+      # manually (see below).
+      - name: Autobuild
+        uses: github/codeql-action/autobuild@v2
+
+      # ℹ️ Command-line programs to run using the OS shell.
+      # 📚 https://git.io/JvXDl
+
+      # ✏️ If the Autobuild fails above, remove it and uncomment the following
+      #    three lines and modify them (or add more) to build your code if your
+      #    project uses a compiled language
+
+      # - run: |
+      #     make bootstrap
+      #     make release
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v2

.gitignore

@@ -2,6 +2,9 @@
 # Files already tracked by Git are not affected.
 # See: https://git-scm.com/docs/gitignore
 
+## Project Specific ##
+lambda_build.zip
+
 ## Python ##
 __pycache__
 .mypy_cache

.isort.cfg

@@ -6,5 +6,7 @@ import_heading_stdlib=Standard Python Libraries
 import_heading_thirdparty=Third-Party Libraries
 import_heading_firstparty=cisagov Libraries
 
+known_first_party=example
+
 # Run isort under the black profile to align with our other Python linting
 profile=black

.pre-commit-config.yaml

@@ -81,12 +81,22 @@ repos:
       - id: shell-lint
 
   # Python hooks
+  # Run bandit on the tests directory with a custom configuration
   - repo: https://github.com/PyCQA/bandit
     rev: 1.7.4
     hooks:
       - id: bandit
+        name: bandit (tests directory)
+        files: tests
         args:
           - --config=.bandit.yml
+  # Run bandit on everything but the tests directory
+  - repo: https://github.com/PyCQA/bandit
+    rev: 1.7.4
+    hooks:
+      - id: bandit
+        name: bandit (everything but the tests directory)
+        exclude: tests
   - repo: https://github.com/psf/black
     rev: 22.10.0
     hooks:

Dockerfile

@@ -0,0 +1,57 @@
+ARG PY_VERSION=3.9
+
+FROM amazon/aws-lambda-python:$PY_VERSION as install-stage
+
+# Declare it a second time so it's brought into this scope.
+ARG PY_VERSION=3.9
+
+# Install the Python packages necessary to install the Lambda dependencies.
+RUN python3 -m pip install --no-cache-dir \
+    pip \
+    setuptools \
+    wheel \
+  # This version of pipenv is the minimum version to allow passing arguments
+  # to pip with the --extra-pip-args option.
+  && python3 -m pip install --no-cache-dir "pipenv>=2022.9.8"
+
+WORKDIR /tmp
+
+# Copy in the dependency files.
+COPY src/py$PY_VERSION/ .
+
+# Install the Lambda dependencies.
+#
+# The --extra-pip-args option is used to pass necessary arguments to the
+# underlying pip calls.
+RUN pipenv sync --system --extra-pip-args="--no-cache-dir --target ${LAMBDA_TASK_ROOT}"
+
+FROM amazon/aws-lambda-python:$PY_VERSION as build-stage
+
+###
+# For a list of pre-defined annotation keys and value types see:
+# https://github.com/opencontainers/image-spec/blob/master/annotations.md
+###
+# github@cisa.dhs.gov is a very generic email distribution, and it is
+# unlikely that anyone on that distribution is familiar with the
+# particulars of your repository.  It is therefore *strongly*
+# suggested that you use an email address here that is specific to the
+# person or group that maintains this repository; for example:
+# LABEL org.opencontainers.image.authors="vm-fusion-dev-group@trio.dhs.gov"
+LABEL org.opencontainers.image.authors="github@cisa.dhs.gov"
+LABEL org.opencontainers.image.vendor="Cybersecurity and Infrastructure Security Agency"
+
+# Declare it a third time so it's brought into this scope.
+ARG PY_VERSION=3.9
+
+# This must be present in the image to generate a deployment artifact.
+ENV BUILD_PY_VERSION=$PY_VERSION
+
+COPY --from=install-stage ${LAMBDA_TASK_ROOT} ${LAMBDA_TASK_ROOT}
+
+WORKDIR ${LAMBDA_TASK_ROOT}
+
+# Copy in the handler.
+COPY src/lambda_handler.py .
+
+# Ensure our handler is invoked when the image is used.
+CMD ["lambda_handler.handler"]

README.md

@@ -3,14 +3,74 @@
 [![GitHub Build Status](https://github.com/cisagov/skeleton-aws-lambda-python/workflows/build/badge.svg)](https://github.com/cisagov/skeleton-aws-lambda-python/actions)
 
 This is a generic skeleton project that can be used to quickly get a
-new [cisagov](https://github.com/cisagov) GitHub project started.
-This skeleton project contains [licensing information](LICENSE), as
+new [cisagov](https://github.com/cisagov) GitHub
+[AWS Lambda](https://aws.amazon.com/lambda/) project using the Python runtimes
+started. This skeleton project contains [licensing information](LICENSE), as
 well as [pre-commit hooks](https://pre-commit.com) and
 [GitHub Actions](https://github.com/features/actions) configurations
 appropriate for the major languages that we use.
 
-In many cases you will instead want to use one of the more specific
-skeleton projects derived from this one.
+## Building the base Lambda image ##
+
+The base Lambda image can be built with the following command:
+
+```console
+docker compose build
+```
+
+This base image is used both to build a deployment package and to run the
+Lambda locally.
+
+## Building a deployment package ##
+
+You can build a deployment zip file to use when creating a new AWS Lambda
+function with the following command:
+
+```console
+docker compose up build_deployment_package
+```
+
+This will output the deployment zip file in the root directory.
+
+## Running the Lambda locally ##
+
+The configuration in this repository allows you run the Lambda locally for
+testing as long as you do not need explicit permissions for other AWS
+services. This can be done with the following command:
+
+```console
+docker compose up --detach run_lambda_locally
+```
+
+You can then invoke the Lambda using the following:
+
+```console
+ curl -XPOST "http://localhost:9000/2015-03-31/functions/function/invocations" -d '{}'
+```
+
+The `{}` in the command is the invocation event payload to send to the Lambda
+and would be the value given as the `event` argument to the handler.
+
+Once you are finished you can stop the detached container with the following command:
+
+```console
+docker compose down
+```
+
+## How to update Python dependencies ##
+
+The Python dependencies are maintained using a [Pipenv](https://github.com/pypa/pipenv)
+configuration for each supported Python version. Changes to requirements
+should be made to the respective `src/py<Python version>/Pipfile`. More
+information about the `Pipfile` format can be found [here](https://pipenv.pypa.io/en/latest/basics/#example-pipfile-pipfile-lock).
+The accompanying `Pipfile.lock` files contain the specific dependency versions
+that will be installed. These files can be updated like so (using the Python
+3.9 configuration as an example):
+
+```console
+cd src/py3.9
+pipenv lock
+```
 
 ## New Repositories from a Skeleton ##
 

bump_version.sh

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+
+# bump_version.sh (show|major|minor|patch|prerelease|build)
+
+set -o nounset
+set -o errexit
+set -o pipefail
+
+VERSION_FILE=src/version.txt
+
+HELP_INFORMATION="bump_version.sh (show|major|minor|patch|prerelease|build|finalize)"
+
+old_version=$(sed -n "s/^__version__ = \"\(.*\)\"$/\1/p" $VERSION_FILE)
+# Comment out periods so they are interpreted as periods and don't
+# just match any character
+old_version_regex=${old_version//\./\\\.}
+
+if [ $# -ne 1 ]; then
+  echo "$HELP_INFORMATION"
+else
+  case $1 in
+    major | minor | patch | prerelease | build)
+      new_version=$(python -c "import semver; print(semver.bump_$1('$old_version'))")
+      echo Changing version from "$old_version" to "$new_version"
+      # A temp file is used to provide compatability with macOS development
+      # as a result of macOS using the BSD version of sed
+      tmp_file=/tmp/version.$$
+      sed "s/$old_version_regex/$new_version/" $VERSION_FILE > $tmp_file
+      mv $tmp_file $VERSION_FILE
+      git add $VERSION_FILE
+      git commit -m"Bump version from $old_version to $new_version"
+      git push
+      ;;
+    finalize)
+      new_version=$(python -c "import semver; print(semver.finalize_version('$old_version'))")
+      echo Changing version from "$old_version" to "$new_version"
+      # A temp file is used to provide compatability with macOS development
+      # as a result of macOS using the BSD version of sed
+      tmp_file=/tmp/version.$$
+      sed "s/$old_version_regex/$new_version/" $VERSION_FILE > $tmp_file
+      mv $tmp_file $VERSION_FILE
+      git add $VERSION_FILE
+      git commit -m"Finalize version from $old_version to $new_version"
+      git push
+      ;;
+    show)
+      echo "$old_version"
+      ;;
+    *)
+      echo "$HELP_INFORMATION"
+      ;;
+  esac
+fi