AWS Code Services

Overview

AWS has a number of tools to aid in software development, including CodeBuild to build, test, and deploy software, and CodePipeline to sequence actions, including CodeBuild jobs. In this article we will create a simple CodeBuild project to scan an API that has already been deployed to our development environment.

Secure Your API Key

When you signed up on StackHawk, you created an API key. To keep it a secret, copy it to AWS Parameter Store as a SecureString, and name it /hawk/api/key1. We will extract that secret as an environment variable, HAWK_API_KEY, in CodeBuild so that HawkScan can use it.

Configure Codebuild

At the base directory of your code repository, add a buildspec.yml file to configure your CodeBuild job to install and run HawkScan. Notice the env.parameter-store section, which extracts your SecureString, /hawk/api/key1, into the build-time environment variable HAWK_API_KEY.

version: 0.2

env:
  parameter-store:
    HAWK_API_KEY: /hawk/api/key1
  # Optional: pin a version (6.0.0 or later). Leave it unset to install the latest release.
  # variables:
  #   HAWK_INSTALL_VERSION: "6.6.0"

phases:
  install:
    commands:
      - curl -fsSL https://download.stackhawk.com/hawk/install.sh | sh
      - export PATH="$HOME/.hawk/bin:$PATH"
  build:
    commands:
      - hawk --api-key="${HAWK_API_KEY}" --no-color scan

The install phase installs the hawk CLI with the hawk CLI install script, which downloads the latest HawkScan release and checks its checksum. The script doesn’t change the PATH, so the next command adds its install directory, ~/.hawk/bin. CodeBuild runs every command in a version: 0.2 buildspec in the same shell, so the build phase can then run hawk. The --no-color flag keeps the scan output readable in the CodeBuild logs.

Docker Alternative

If you’d rather run HawkScan as a Docker container, enable privileged mode on your CodeBuild project and replace the install and build phases with:

phases:
  build:
    commands:
      - |
        docker run -v $(pwd):/hawk:rw -t \
        -e API_KEY="${HAWK_API_KEY}" \
        -e NO_COLOR=true \
        stackhawk/hawkscan

Configure HawkScan

At the base directory of your code repository, create a stackhawk.yml appropriate for scanning your application. For our example, we will create a minimal config pointing to our Development environment API endpoint. Just replace the host entry with your test endpoint, and replace applicationId with your App ID from StackHawk.

app:
  applicationId: xxXXXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX
  host: http://example.com
  env: Development

hawk:
  startupTimeoutMinutes: 1
  spider:
    base: false

Run It

Check those two files into source control, and then configure a CodeBuild job to use that repository as its primary source. Start the build, and tail the logs in the CodeBuild console. You should see your scan initiate, run, and print a summary of results. Also, check your account at StackHawk to review your scan details!