Use CircleCI version 2.1 at the top of your .circleci/config.yml file.
1
version: 2.1
Add the orbs
stanza below your version, invoking the orb:
1
2
orbs:
stackhawk: stackhawk/stackhawk@1.0.5
Use stackhawk
elements in your existing workflows and jobs.
Opt-in to use of uncertified orbs on your organization’s Security settings page.
In this example, run Nginx as a Docker container and scan it within the CircleCI build environment. Run the `stackhawk/hawkscan-local` job with the parameter `docker-network: scan_net` to tell HawkScan to run on the Docker named network, `scan_net`. Provide the parameter `steps` to do the following before the scan runs: 1) Create a named Docker bridge network, `scan_net` 2) Run an Nginx container on that network with the name `nginx_test` The HawkScan configuration is read from our source repository as `./stackhawk.yml`. In that file, the test subject is defined as `app.host=http://nginx_test`.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
version: '2.1'
orbs:
stackhawk: stackhawk/stackhawk@x.y
workflows:
scan-local:
jobs:
- stackhawk/hawkscan-local:
docker-network: scan_net
steps:
- run:
command: docker network create scan_net
name: Create scan_net Network
- run:
command: >-
docker run --rm --detach --network scan_net --name nginx_test
nginx
name: Run Local Test Instance, nginx_test, on the scan_net Network
In this example, run a scan against a remote target host defined in `stackhawk.yml` at the base of the source repository. Run stackhawk/hawkscan-remote with the configuration-files parameter, `stackhawk.yml stackhawk-circleci.yml`. This tells HawkScan to use the `stackhawk.yml` configuration file found at the base of the source repository, and to overlay it with configurations in `stackhawk-circleci.yml`. Finally, add the host parameter, `http://example.com`. This adds a HOST environment variable to the HawkScan container which may be interpolated in the `stackhawk.yml` configuration file.
1
2
3
4
5
6
7
8
9
version: '2.1'
orbs:
stackhawk: stackhawk/stackhawk@x.y
workflows:
scan-remote:
jobs:
- stackhawk/hawkscan-remote:
configuration-files: stackhawk.yml stackhawk-circleci.yml
host: http://example.com
Run a scan of a local integration environment. This job runs on a VM and runs hawkscan from a Docker container on that VM. You may provide a series of steps that result in a service running either natively on localhost, or as a Docker container on a named Docker bridge network, such as `scan_net`. If you have an integration environment running in a remote environment, you should use the stackhawk/hawkscan-remote job instead. It's faster without the VM overhead. This job requires a StackHawk API key to be stored as HAWK_API_KEY (default).
PARAMETER | DESCRIPTION | REQUIRED | DEFAULT | TYPE |
---|---|---|---|---|
api-key | Your StackHawk API key. Store your key as an environment variable in CircleCI and pass the name of the variable here.
| No | HAWK_API_KEY | env_var_name |
app-id | Pass a value to the HawkScan runtime environment variable, APP_ID. You can use this environment variable in your HawkScan configuration file to dynamically set `app.applicationId`, or any other parameter.
| No | '' | string |
auth-token | Pass a value to the HawkScan runtime environment variable, AUTH_TOKEN. You can use this environment variable in your HawkScan configuration file to dynamically set `app.authentication.external.value`, or any other parameter.
| No | '' | string |
color | Set to `true` if you want HawkScan to output in color. Color output may appear garbled in job output screens.
| No | false | boolean |
configuration-files | A list of HawkScan configuration files to load. Defaults to `stackhawk.yml`. To overlay multiple configuration files, separate them with spaces, e.g. `stackhawk1.yml stackhawk2.yml stackhawk3.yml`.
| No | stackhawk.yml | string |
docker-image | The HawkScan container to download. Change this only if recommended by StackHawk Support.
| No | stackhawk/hawkscan:latest | string |
docker-network | Optional Docker named bridge network on which to run the HawkScan container, such as `scan-net`. Defaults to the Docker default bridge named `bridge`.
| No | bridge | string |
env | Pass a value to the HawkScan runtime environment variable, ENV. You can use this environment variable in your HawkScan configuration file to dynamically set `app.env`, or any other parameter.
| No | '' | string |
host | Pass a value to the HawkScan runtime environment variable, HOST. You can use this environment variable in your HawkScan configuration file to dynamically set `app.host`, or any other parameter.
| No | '' | string |
password | Pass a value to the HawkScan runtime environment variable, PASSWORD. You can use this environment variable in your HawkScan configuration file to dynamically set `app.authentication.usernamePassword.scanPassword`, or any other parameter.
| No | '' | string |
steps | Any steps you wish to run before starting the scan. This should include starting a service or Docker container that is to be the target of the scan.
| Yes | - | steps |
username | Pass a value to the HawkScan runtime environment variable, USERNAME. You can use this environment variable in your HawkScan configuration file to dynamically set `app.authentication.usernamePassword.scanUsername`, or any other parameter.
| No | '' | string |
This is the fastest way to run a scan of a known remote host. This job requires a StackHawk API key to be stored as HAWK_API_KEY (default). If you want to stand up a simple integration test locally, in the CircleCI build environment, you should use the stackhawk/hawkscan-local job instead.
PARAMETER | DESCRIPTION | REQUIRED | DEFAULT | TYPE |
---|---|---|---|---|
api-key | Your StackHawk API key. Store your key as an environment variable in CircleCI and pass the name of the variable here.
| No | HAWK_API_KEY | env_var_name |
app-id | Pass a value to the HawkScan runtime environment variable, APP_ID. You can use this environment variable in your HawkScan configuration file to dynamically set `app.applicationId`, or any other parameter.
| No | '' | string |
auth-token | Pass a value to the HawkScan runtime environment variable, AUTH_TOKEN. You can use this environment variable in your HawkScan configuration file to dynamically set `app.authentication.external.value`, or any other parameter.
| No | '' | string |
color | Set to `true` if you want HawkScan to output in color. Color output may appear garbled in job output screens.
| No | false | boolean |
configuration-files | A list of HawkScan configuration files to load. Defaults to `stackhawk.yml`. To overlay multiple configuration files, separate them with spaces, e.g. `stackhawk1.yml stackhawk2.yml stackhawk3.yml`.
| No | stackhawk.yml | string |
docker-image | The HawkScan container to download. Change this only if recommended by StackHawk Support.
| No | stackhawk/hawkscan:latest | string |
env | Pass a value to the HawkScan runtime environment variable, ENV. You can use this environment variable in your HawkScan configuration file to dynamically set `app.env`, or any other parameter.
| No | '' | string |
host | Pass a value to the HawkScan runtime environment variable, HOST. You can use this environment variable in your HawkScan configuration file to dynamically set `app.host`, or any other parameter.
| No | '' | string |
password | Pass a value to the HawkScan runtime environment variable, PASSWORD. You can use this environment variable in your HawkScan configuration file to dynamically set `app.authentication.usernamePassword.scanPassword`, or any other parameter.
| No | '' | string |
resource-class | Override the default `resource_class` (medium). See https://circleci.com/docs/2.0/configuration-reference/#resourceclass .
| No | medium | string |
username | Pass a value to the HawkScan runtime environment variable, USERNAME. You can use this environment variable in your HawkScan configuration file to dynamically set `app.authentication.usernamePassword.scanUsername`, or any other parameter.
| No | '' | string |
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
# This code is licensed from CircleCI to the user under the MIT license.
# See here for details: https://circleci.com/developer/orbs/licensing
version: 2.1
description: |
Automate dynamic application security testing in your pipeline. StackHawk makes it simple for developers to find, triage, and fix application security bugs. Scan your application for AppSec bugs in the code your team wrote, triage and fix with provided documentation, and automate in your pipeline to prevent future bugs from hitting prod.
display:
home_url: https://stackhawk.com
source_url: https://github.com/stackhawk/stackhawk-orb
jobs:
hawkscan-local:
description: |
Run a scan of a local integration environment. This job runs on a VM and runs hawkscan from a Docker container on
that VM. You may provide a series of steps that result in a service running either natively on localhost, or as a
Docker container on a named Docker bridge network, such as `scan_net`.
If you have an integration environment running in a remote environment, you should use the stackhawk/hawkscan-remote
job instead. It's faster without the VM overhead.
This job requires a StackHawk API key to be stored as HAWK_API_KEY (default).
machine: true
parameters:
api-key:
default: HAWK_API_KEY
description: |
Your StackHawk API key. Store your key as an environment variable in CircleCI and pass the name of the variable here.
type: env_var_name
app-id:
default: ""
description: |
Pass a value to the HawkScan runtime environment variable, APP_ID. You can use this environment variable in your HawkScan configuration file to dynamically set `app.applicationId`, or any other parameter.
type: string
auth-token:
default: ""
description: |
Pass a value to the HawkScan runtime environment variable, AUTH_TOKEN. You can use this environment variable in your HawkScan configuration file to dynamically set `app.authentication.external.value`, or any other parameter.
type: string
color:
default: false
description: |
Set to `true` if you want HawkScan to output in color. Color output may appear garbled in job output screens.
type: boolean
configuration-files:
default: stackhawk.yml
description: |
A list of HawkScan configuration files to load. Defaults to `stackhawk.yml`. To overlay multiple configuration files, separate them with spaces, e.g. `stackhawk1.yml stackhawk2.yml stackhawk3.yml`.
type: string
docker-image:
default: stackhawk/hawkscan:latest
description: |
The HawkScan container to download. Change this only if recommended by StackHawk Support.
type: string
docker-network:
default: bridge
description: |
Optional Docker named bridge network on which to run the HawkScan container, such as `scan-net`. Defaults to the Docker default bridge named `bridge`.
type: string
env:
default: ""
description: |
Pass a value to the HawkScan runtime environment variable, ENV. You can use this environment variable in your HawkScan configuration file to dynamically set `app.env`, or any other parameter.
type: string
host:
default: ""
description: |
Pass a value to the HawkScan runtime environment variable, HOST. You can use this environment variable in your HawkScan configuration file to dynamically set `app.host`, or any other parameter.
type: string
password:
default: ""
description: |
Pass a value to the HawkScan runtime environment variable, PASSWORD. You can use this environment variable in your HawkScan configuration file to dynamically set `app.authentication.usernamePassword.scanPassword`, or any other parameter.
type: string
steps:
description: |
Any steps you wish to run before starting the scan. This should include starting a service or Docker container that is to be the target of the scan.
type: steps
username:
default: ""
description: |
Pass a value to the HawkScan runtime environment variable, USERNAME. You can use this environment variable in your HawkScan configuration file to dynamically set `app.authentication.usernamePassword.scanUsername`, or any other parameter.
type: string
steps:
- checkout
- steps: <<parameters.steps>>
- run:
command: |
docker run --network <<parameters.docker-network>> --volume $(pwd):/hawk --tty --env API_KEY="${<<parameters.api-key>>}" --env NO_COLOR="<<parameters.color>>" <<#parameters.app-id>>--env APP_ID="<<parameters.app-id>>"<</parameters.app-id>> <<#parameters.host>>--env HOST="<<parameters.host>>"<</parameters.host>> <<#parameters.env>>--env ENV="<<parameters.env>>"<</parameters.env>> <<#parameters.username>>--env USERNAME="<<parameters.username>>"<</parameters.username>> <<#parameters.password>>--env PASSWORD="<<parameters.password>>"<</parameters.password>> <<#parameters.auth-token>>--env AUTH_TOKEN="<<parameters.auth-token>>"<</parameters.auth-token>> <<parameters.docker-image>> <<parameters.configuration-files>>
name: Run HawkScan
hawkscan-remote:
description: |
This is the fastest way to run a scan of a known remote host.
This job requires a StackHawk API key to be stored as HAWK_API_KEY (default).
If you want to stand up a simple integration test locally, in the CircleCI build environment, you should use the
stackhawk/hawkscan-local job instead.
docker:
- image: <<parameters.docker-image>>
environment:
REPO_DIR: /home/zap/hawk
parameters:
api-key:
default: HAWK_API_KEY
description: |
Your StackHawk API key. Store your key as an environment variable in CircleCI and pass the name of the variable here.
type: env_var_name
app-id:
default: ""
description: |
Pass a value to the HawkScan runtime environment variable, APP_ID. You can use this environment variable in your HawkScan configuration file to dynamically set `app.applicationId`, or any other parameter.
type: string
auth-token:
default: ""
description: |
Pass a value to the HawkScan runtime environment variable, AUTH_TOKEN. You can use this environment variable in your HawkScan configuration file to dynamically set `app.authentication.external.value`, or any other parameter.
type: string
color:
default: false
description: |
Set to `true` if you want HawkScan to output in color. Color output may appear garbled in job output screens.
type: boolean
configuration-files:
default: stackhawk.yml
description: |
A list of HawkScan configuration files to load. Defaults to `stackhawk.yml`. To overlay multiple configuration files, separate them with spaces, e.g. `stackhawk1.yml stackhawk2.yml stackhawk3.yml`.
type: string
docker-image:
default: stackhawk/hawkscan:latest
description: |
The HawkScan container to download. Change this only if recommended by StackHawk Support.
type: string
env:
default: ""
description: |
Pass a value to the HawkScan runtime environment variable, ENV. You can use this environment variable in your HawkScan configuration file to dynamically set `app.env`, or any other parameter.
type: string
host:
default: ""
description: |
Pass a value to the HawkScan runtime environment variable, HOST. You can use this environment variable in your HawkScan configuration file to dynamically set `app.host`, or any other parameter.
type: string
password:
default: ""
description: |
Pass a value to the HawkScan runtime environment variable, PASSWORD. You can use this environment variable in your HawkScan configuration file to dynamically set `app.authentication.usernamePassword.scanPassword`, or any other parameter.
type: string
resource-class:
default: medium
description: |
Override the default `resource_class` (medium). See https://circleci.com/docs/2.0/configuration-reference/#resourceclass .
type: string
username:
default: ""
description: |
Pass a value to the HawkScan runtime environment variable, USERNAME. You can use this environment variable in your HawkScan configuration file to dynamically set `app.authentication.usernamePassword.scanUsername`, or any other parameter.
type: string
resource_class: <<parameters.resource-class>>
steps:
- checkout
- run:
command: |
echo 'export API_KEY=${<<parameters.api-key>>}' >> ${BASH_ENV}
echo 'export NO_COLOR=<<parameters.color>>' >> ${BASH_ENV}
<<#parameters.app-id>>echo 'export APP_ID=<<parameters.app-id>>' >> ${BASH_ENV}<</parameters.app-id>>
<<#parameters.host>>echo 'export HOST=<<parameters.host>>' >> ${BASH_ENV}<</parameters.host>>
<<#parameters.env>>echo 'export ENV=<<parameters.env>>' >> ${BASH_ENV}<</parameters.env>>
<<#parameters.username>>echo 'export USERNAME=<<parameters.username>>' >> ${BASH_ENV}<</parameters.username>>
<<#parameters.password>>echo 'export PASSWORD=<<parameters.password>>' >> ${BASH_ENV}<</parameters.password>>
<<#parameters.auth-token>>echo 'export AUTH_TOKEN=<<parameters.auth-token>>' >> ${BASH_ENV}<</parameters.auth-token>>
source ${BASH_ENV}
shawk <<parameters.configuration-files>>
name: HawkScan
working_directory: /home/zap/hawk
examples:
hawkscan-local:
description: |
In this example, run Nginx as a Docker container and scan it within the CircleCI build environment.
Run the `stackhawk/hawkscan-local` job with the parameter `docker-network: scan_net` to tell HawkScan to run on
the Docker named network, `scan_net`.
Provide the parameter `steps` to do the following before the scan runs:
1) Create a named Docker bridge network, `scan_net`
2) Run an Nginx container on that network with the name `nginx_test`
The HawkScan configuration is read from our source repository as `./stackhawk.yml`. In that file, the test
subject is defined as `app.host=http://nginx_test`.
usage:
version: "2.1"
orbs:
stackhawk: stackhawk/stackhawk@x.y
workflows:
scan-local:
jobs:
- stackhawk/hawkscan-local:
docker-network: scan_net
steps:
- run:
command: docker network create scan_net
name: Create scan_net Network
- run:
command: docker run --rm --detach --network scan_net --name nginx_test nginx
name: Run Local Test Instance, nginx_test, on the scan_net Network
hawkscan-remote:
description: |
In this example, run a scan against a remote target host defined in `stackhawk.yml` at the base of the source
repository.
Run stackhawk/hawkscan-remote with the configuration-files parameter, `stackhawk.yml stackhawk-circleci.yml`. This
tells HawkScan to use the `stackhawk.yml` configuration file found at the base of the source repository, and to
overlay it with configurations in `stackhawk-circleci.yml`.
Finally, add the host parameter, `http://example.com`. This adds a HOST environment variable to the HawkScan container
which may be interpolated in the `stackhawk.yml` configuration file.
usage:
version: "2.1"
orbs:
stackhawk: stackhawk/stackhawk@x.y
workflows:
scan-remote:
jobs:
- stackhawk/hawkscan-remote:
configuration-files: stackhawk.yml stackhawk-circleci.yml
host: http://example.com