HawkScan and CircleCI
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.yml
file to your project repository - Configure HawkScan with a
stackhawk.yml
file
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
.
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 HawkScan. 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.
BONUS: 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