Login Start Free Trial Login Start Free Trial
 

HawkScan and CircleCI: First Steps

CircleCI

You can run HawkScan in CircleCI in one of two ways:

  • quickly and easily with the StackHawk Orb (hawkscan-remote or hawkscan-local)
  • in as granular and custom a fashion as you wish through CircleCI’s Machine Executor configuration

In either case, the first two steps are:

  1. Add a code repository as a CircleCI Project
  2. Secure your API key as an environment variable in your CircleCI Project

Create your CircleCI Project

If you haven’t already, set up your code repository as a CircleCI Project. From the CircleCI app, click ADD PROJECTS from the left pane, and select your code repository.

Secure Your API Key

When you signed up on StackHawk, you created an API key. To keep it a secret, copy it to the Environment Variables for your project. From within your CircleCI Project View, click on Project Settings icon (⚙️) at the top right of your browser, and then select Environment Variables from the left pane. Add your StackHawk API key as a variable called HAWK_API_KEY.

HawkScan and CircleCI: The StackHawk Orb

With the StackHawk Orb, it’s easy to integrate HawkScan into your CircleCI pipeline. The basic steps are:

  1. Add your code repository as a CircleCI Project (see above)
  2. Secure your API key as an environment variable in your CircleCI Project (see above)
  3. Configure your CircleCI job by adding a .circleci/config.yml file to your project repository
  4. Configure HawkScan with a stackhawk.yml file

Configure Your CircleCI Job

At the base directory of your code repository, add a .circleci/config.yml file to configure your CircleCI project to run the HawkScan orb. An example is provided below.

.circleci/config.yml

orbs:
  stackhawk: stackhawk/stackhawk@x.y.z

version: 2.1

workflows:
  scan-remote:
    jobs:
      - stackhawk/hawkscan-remote:
          configuration-files: stackhawk.yml
          host: 'http://example.com'

In this configuration, we define a single workflow, scan-remote, which runs the stackhawk orb job, hawkscan-remote. The job starts its own container and checks out your code, including the HawkScan configuration described below. Then HawkScan runs from within the container and sends your scan results back to the StackHawk platform. The StackHawk API key is automatically pulled from the environment variable, HAWK_API_KEY.

Configure HawkScan

At the base directory of your code repository, create a stackhawk.yml appropriate for scanning your application. Create a minimal config pointing to your Development environment API endpoint.

stackhawk.yml

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

hawk:
  startupTimeoutMinutes: 1
  spider:
    base: false

Replace the host entry with your test endpoint, and replace applicationId with your App ID from StackHawk.

Run It

Check those two files into source control, and head over to the CircleCI app console to watch your job run. The text output from the job results in CircleCI will contain a link to your scan results in the StackHawk app.

Local Scanning

The StackHawk orb has a second job option called hawkscan-local, which runs on a machine instance rather than a container. This job accepts a list of steps as a parameter, which allows you to optionally stand up local services on the CircleCI build machine before running the scan.

As an example, the following CircleCI and StackHawk configurations will stand up an nginx Docker container, and scan it.

.circleci/config.yml

orbs:
  stackhawk: stackhawk/stackhawk@x.y.z

version: 2.1

workflows:
  scan-local:
    jobs:
      - stackhawk/hawkscan-local:
          docker-network: scan_net
          steps:
            - run:
                name: Create scan_net Network
                command: docker network create scan_net
            - run:
                name: 'Run Local Test Instance, nginx_test, on the scan_net Network'
                command: docker run --rm -d --network scan_net --name nginx_test nginx

stackhawk.yml

app:
  applicationId: xxXXXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX
  host: http://nginx_test
  env: Development

hawk:
  startupTimeoutMinutes: 1
  spider:
    base: false

HawkScan and CircleCI: Machine Executor Configuration

Configure Your CircleCI Job with the Machine Executor

The Machine Executor allows you to install multiple dependencies needed by your applications and associated tests on the underlying linux VM. You can then install and run the HawkScan CLI on the same VM within your workflow.

This workflow is convenient when adding complex tasks such as Custom Scan Discovery into your CircleCI workflow.

In this Node.js example, we configure config.yml to install the latest version of the HawkScan CLI and update the PATH variable of the runner to reflect the installation.

Additional dependencies such as node packages can be installed in the same workflow, which then launches the application under test and initiates a scan.

.circleci/config.yml

version: 2.1
orbs:
  node: circleci/node@4.7
jobs:
  build-and-test:
    machine: # executor type
      image: ubuntu-2004:202010-01 
    steps:
      - checkout
      - run:
          command: |
            echo 'export HAWK_VERSION=$(curl -o- https://api.stackhawk.com/hawkscan/version)' >> "$BASH_ENV"
            echo 'export PATH="hawk-${HAWK_VERSION}:${PATH}"' >> "$BASH_ENV"
      - run: curl -v https://download.stackhawk.com/hawk/cli/hawk-"${HAWK_VERSION}".zip -o hawk.zip
      - run: unzip hawk.zip
      - run: npm install
      - run: nohup npm run start &
      - run: hawk --api-key="${HAWK_API_KEY}" scan stackhawk.yml

workflows:
  sample:
    jobs:
      - build-and-test

Configure HawkScan

At the base directory of your code repository, create a stackhawk.yml appropriate for scanning your application. Create a configuration pointing to your Development environment API endpoint.

In the following example, we add the app.waitForAppTarget configuration, which prompts the scanner to wait for the target application to come up before initiating a scan (retry every second for 5 minutes, then terminate the scanner if the application is still not online).

stackhawk.yml

app:
  applicationId: xxXXXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX
  env: Development
  host: http://localhost:3000
  waitForAppTarget:
    path: /
    pollDelay: 1000
    waitTimeoutMillis: 300000

Run It

Check those two files into source control, and head over to the CircleCI app console to watch your job run. The text output from the job results in CircleCI will contain a link to your scan results in the StackHawk app.

Bonus Feature: Adding Commit Hash and Branch

If you’re using the Machine Executor approach, you can decorate your scans with commit hash and branch details by leveraging the tags configuration in stackhawk.yml.

Specifically, you can pass the built-in CircleCI variables CIRCLE_SHA1 and CIRCLE_BRANCH to the scanner, which will associate their values with your scan results and display them in the HawkScan platform.

To do this, simply:

  1. update the hawk scan command in config.yml to pass those variables to the scanner as environment variables
  2. configure the associated tags in stackhawk.yml

hawk scan example

Add the CircleCI variables into the hawk scan command using the --env option:

hawk --api-key="${HAWK_API_KEY}" scan --env CIRCLE_SHA1="$CIRCLE_SHA1" --env CIRCLE_BRANCH="$CIRCLE_BRANCH" stackhawk.yml

tag example

Ingest the commit and branch variables that were passed to the scanner into the scan data using the tags configuration:

stackhawk.yml

app:
  applicationId: xxXXXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX
  env: Development
  host: http://localhost:3000
tags:
  - name: _STACKHAWK_GIT_COMMIT_SHA
    value: ${CIRCLE_SHA1}
  - name: _STACKHAWK_GIT_BRANCH
    value: ${CIRCLE_BRANCH}

Note: This commit and branch tagging functionality is a subset of the Pull Request Checks feature of StackHawk’s GitHub integration.

If you’re using GitHub Actions in addition to CircleCI, see the Pull Request Checks instructions to add Commit Statuses and Pull Request comments to your PR’s!