---
title: "CircleCI"
description: "Configure StackHawk security testing in your CircleCI pipeline with step-by-step instructions for automated vulnerability scanning."
url: https://docs.stackhawk.com/integrations/ci-cd/circleci/
---

# CircleCI

![CircleCI](https://docs.stackhawk.com/images/integrations/logos/circleci.svg)

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

- install the `hawk` CLI with the hawk CLI [install script](https://docs.stackhawk.com/stackhawk-cli/#install-with-a-script) in your own job, which works with the Docker and Machine executors and lets you run any other steps you need in the same job
- use the [StackHawk Orb](https://circleci.com/orbs/registry/orb/stackhawk/stackhawk) (`hawkscan_remote` or `hawkscan_local`), which runs the HawkScan Docker image for you

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 Install Script

## Configure Your CircleCI Job

At the base directory of your code repository, add a `.circleci/config.yml` file that installs the `hawk` CLI and runs a scan. An example is provided below.

```yaml title=".circleci/config.yml"
version: 2.1

jobs:
  hawkscan:
    docker:
      - image: cimg/base:stable
    steps:
      - checkout
      - run:
          name: Install HawkScan
          command: |
            # Optional: pin a version (6.0.0 or later). Leave it unset to install the latest release.
            # export HAWK_INSTALL_VERSION=6.6.0
            curl -fsSL https://download.stackhawk.com/hawk/install.sh | sh
            echo 'export PATH="$HOME/.hawk/bin:$PATH"' >> "$BASH_ENV"
      - run:
          name: Run HawkScan
          command: hawk --api-key="${HAWK_API_KEY}" scan stackhawk.yml

workflows:
  scan-remote:
    jobs:
      - hawkscan
```

In this configuration, the `hawkscan` job checks out your code, including the HawkScan configuration described below, and installs the latest HawkScan release with the install script. The script checks the download’s checksum and installs `hawk` to `~/.hawk/bin`. It doesn’t change the PATH, and each CircleCI `run` step starts a new shell, so the job appends the PATH change to `$BASH_ENV`, which CircleCI loads at the start of every later step. The second step runs the scan with the API key from the environment variable, `HAWK_API_KEY`, and sends your scan results to the StackHawk platform.

To run the same HawkScan version every time, uncomment the `HAWK_INSTALL_VERSION` line.

## 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.

```yaml title="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 with the Machine Executor

The [Machine Executor](https://circleci.com/docs/executor-intro/#linux-vm) 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](https://docs.stackhawk.com/stackhawk-cli/) on the same VM within your workflow.

This workflow is convenient when adding complex tasks such as [Custom Scan Discovery](https://docs.stackhawk.com/hawkscan/scan-discovery/custom/) 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.

```yaml title=".circleci/config.yml"
version: 2.1
orbs:
  node: circleci/node@4.7
jobs:
  build-and-test:
    machine: # executor type
      image: ubuntu-2204:current
    steps:
      - checkout
      - run:
          name: Install HawkScan
          command: |
            curl -fsSL https://download.stackhawk.com/hawk/install.sh | sh
            echo 'export PATH="$HOME/.hawk/bin:$PATH"' >> "$BASH_ENV"
      - run: npm install
      - run: nohup npm run start &
      - run: hawk --api-key="${HAWK_API_KEY}" scan stackhawk.yml

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

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).

```yaml title="stackhawk.yml"
app:
  applicationId: xxXXXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX
  env: Development
  host: http://localhost:3000
  waitForAppTarget:
    path: /
    pollDelay: 1000
    waitTimeoutMillis: 300000
```

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 run the `hawk` CLI in your own job, 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:

```yaml title="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](https://docs.stackhawk.com/integrations/workflows/github/github-pr-checks/) feature of StackHawk’s GitHub integration.

If you’re using GitHub Actions in addition to CircleCI, see the [Pull Request Checks instructions](https://docs.stackhawk.com/integrations/workflows/github/github-pr-checks/#usage) to add Commit Statuses and Pull Request comments to your PRs!

# Alternative: The StackHawk Orb

> **Warning:** Orb v2.0.0 includes breaking changes
>
> StackHawk Orb **v2.0.0** renames its jobs and parameters to `snake_case` (for example, `hawkscan-local` → `hawkscan_local` and `app-id` → `app_id`) as part of an upgrade to CircleCI’s orb build tooling. If you are upgrading from a `1.x` release, review the [migration guide](https://github.com/stackhawk/stackhawk-orb/blob/master/MIGRATION.md) before bumping the version.

The [StackHawk Orb](https://circleci.com/orbs/registry/orb/stackhawk/stackhawk) packages HawkScan as ready-made CircleCI jobs. The orb’s jobs run the `stackhawk/hawkscan` Docker image rather than the `hawk` CLI. 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 with the Orb

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.

```yaml title=".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 above. 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`.

Use the same `stackhawk.yml` described [above](#configure-hawkscan).

## Local Scanning with the Orb

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.

```yaml title=".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
```

```yaml title="stackhawk.yml"
app:
  applicationId: xxXXXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX
  host: http://nginx_test
  env: Development

hawk:
  startupTimeoutMinutes: 1
  spider:
    base: false
```