With the StackHawk Orb, it’s easy to integrate HawkScan into your CircleCI pipeline. The basic steps are:
- Add your code repository as a CircleCI Project
- Secure your API key as an environment variable in your CircleCI Project
- Configure your CircleCI job by adding a
.circleci/config.ymlfile to your project repository
- Configure HawkScan with a
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.
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
At the base directory of your code repository, add a
.circleci/config.yml file to configure your CircleCI project to run HawkScan. An example is provided below.
orbs: stackhawk: email@example.com 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,
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.
app: applicationId: xxXXXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX host: http://example.com env: Development hawk: startupTimeoutMinutes: 1 spider: base: false
host entry with your test endpoint, and replace
applicationId with your App ID from StackHawk.
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.
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.
orbs: stackhawk: firstname.lastname@example.org 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 --detach --network scan_net --name nginx_test nginx
app: applicationId: xxXXXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX host: http://nginx_test env: Development hawk: startupTimeoutMinutes: 1 spider: base: false