1. stackhawk/stackhawk@1.0.5

stackhawk/stackhawk@1.0.5

Partner
Sections
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.
Created: April 15, 2020Version Published: January 14, 2022Releases: 10
Org Usage:
< 25

Orb Quick Start Guide

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.

Usage Examples

hawkscan-local

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

hawkscan-remote

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

Jobs

hawkscan-local

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

Show job Source
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

hawkscan-remote

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.

Show job Source
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

Orb Source

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
Developer Updates
Get tips to optimize your builds
Or join our research panel and give feedback
By submitting this form, you are agreeing to ourTerms of UseandPrivacy Policy.