This repo contains example stackhawk.yml configuration files for HawkScan by StackHawk. For more information read the documentation.
Most modern web applications require some kind of authentication to access the routes of the application. Below is a list of example configurations demonstrating the different combinations of authentication and authorization supported by StackHawk. Each file contains inline comments on the various settings.
| Credential Type | HTTP Content-Type | Authorization Type | Example Config |
|---|---|---|---|
| Username/Password | application/x-www-form-urlencoded |
Cookie | stackhawk-auth-form-cookie.yml |
| Username/Password | application/x-www-form-urlencoded |
Bearer Token | stackhawk-auth-form-token.yml |
| Username/Password | application/json |
Bearer Token | stackhawk-auth-json-token.yml |
| Username/Password | application/json |
Custom Token | stackhawk-auth-json-token-custom1.yml |
| External | N/A | Query Param | stackhawk-auth-external-token.yml |
| External | N/A | Bearer Token | stackhawk-auth-external-token.yml |
For more information see the related documentation Authenticated Scanning
Custom authentication and session management scripts can be used to handle complex authentication and authorization scenarios. If a preconfigured authentication and/or authorization style doesn't meet your needs you can replace either with a custom script.
HawkScan supports writing custom scripts in JavaScript and Kotlin via ZAP scripting support. If you can't find an example in this repository you're encouraged to check out the ZAP community scripts repository for more examples.
To use authentication scripts in HawkScan you'll need to
- Create script files with functions defined to match the interface of the script type.
- Add your script to the hawkAddons.scripts configuration section.
- Add the authentication.script and/or authentication.sessionScript configuration sections.
The stackhawk-auth-scripts-token-for-cookie.yml file is an example of using a custom authentication and session script together. The example authentication script, token-for-cookie.kts, and session management script, token-and-cookie.kts, are examples of using an external token to request a cookie for use in session management.
To get started scripting, copy and rename the templates defined for authentication and session management into your project.
When using authentication scripts in hawkscan you'll need to place the scripts in folder structure denoting their type with the location of the script directory relative to the stackhawk.yml file.
my-webapp/
stackhawk.yml
scripts/
authentication/
my-auth-script.kts
session/
my-session-script.kts
...Your stackhawk.yml file should include the scripts in hawkAddOn.scripts.
...
hawkAddOn:
scripts:
- name: my-auth-script.kts
type: authentication
path: scripts
- name: my-session-script.kts
type: session
path: scriptsThis will load your scripts into the scanner for use as authentication or session management.
Lastly you'll need to specify the scripts as the method for authentication and/or session management in your stackhawk.yml
authentication:
script:
name: my-auth-script.kts
credentials:
myToken: ${MY_TOKEN:something-secret}
sessionScript:
name: my-session-script.ktsOnce you've created your scripts and configured stackhawk.yml to use them, you can run the stackhawk/hawkscan docker image
as you normally would. HawkScan's normal authentication checks will use your scripts and will return success or errors if they've worked or not.
If your authentication script is failing, and/or not producing the expected results, you can run the stackhawk/hawkscan docker image like so to get the logs from the scanner.
docker run -e API_KEY=$HAWK_API_KEY --rm --name hawkscan --entrypoint=bash -v $(pwd):/hawk -it stackhawk/hawkscan -c 'shawk; cat zap.out'As mentioned in the troubleshooting docs, you can add logging to your scripts to track down issues.
import org.apache.log4j.LogManager
val logger = LogManager.getLogger("my-script")