Overview
API Keys can be used in various ways when authenticating with applications.
To conduct an Authenticated Scan of an application which uses an API Key as part of its authentication regime, you can leverage one (or both) of the following sections of stackhawk.yml:
inject the API Key as a token; send it as a defined header in a POST or GET to a login endpoint
add a header containing the API Key to every request to the application (typically used in conjunction when a separate login mechanism is in place but the API Key header is also needed)
Procedure
Configure app.authentication (and, in some cases, hawkAddOn.replacer) according to your application's use of the API Key and other login mechanisms.
Scenario 1: Ingest the API Key into HawkScan as a Token; send it as a Header
In this example:
the application expects that an X-API-KEY header and associated API Key value be passed to the application
HawkScan ingests the API Key value via an environmental variable passed as app.authentication.external.value in an external token configuration block
HawkScan sends the ingested API Key as an X-API-KEY header (app.authentication.tokenAuthorization.value is customizable)
HawkScan tests whether authentication succeeded by sending a GET to a protected endpoint (
/mysettings) of the application
Associated YAML:
app:
authentication:
loggedInIndicator: ".*2[0-9][0-9].*OK.*|.*3[0-9][0-9].*"
loggedOutIndicator: ".*4[0-9][0-9].*Unauthorized.*"
external:
type: TOKEN
value: ${API-KEY}
tokenAuthorization:
type: HEADER
value: X-API-KEY
testPath:
path: /mysettings
success: ".*200.*"
requestMethod: GET
Notes:
The above example assumes that the application expects to receive a header named X-API-KEY with a value consisting of the contents of the API-KEY variable (with no prefix to that value). To prefix the value of API-KEY, populate tokenAuthorization.tokenType with a prefix value).
See Inject Cookies and Tokens for additional examples should the above example not match your application's authentication regime.
Scenario 2: Send API Key as a Header on every request to the application
In this scenario, the application expects the API Key to be sent as a Header on every request the scanner makes to the application, but the initial login mechanism involves something else besides the API Key (e.g., passing a username / password credentials via form or json payload in order to obtain a cookie or token).
In other words, the app.authentication section is already in use in order to accomplish the initial login, but the application still needs the API Key to be sent in addition.
In this scenario, configure hawkAddOn.replacer with the API Key information in order to send it on each request.
Example configurations:
Example 1: headername: headervalue
hawkAddOn:
replacer:
rules:
- matchString: "apikey"
replacement: "abc123"
replaceOnly: false
End result: apikey: abc123
Example 2: Encapsulated
If instead your API Key needs to be encapsulated in a different header name (e.g., an Authorization header), you can nest it like so:
hawkAddOn:
replacer:
rules:
- matchString: "Authorization"
replacement: "apikey: abc123"
replaceOnly: false
End result: Authorization: apikey: abc123
Additional Information
For applications which use the API Key value as part of a Basic Auth mechanism, see How to configure HawkScan to authenticate to applications using Basic Auth. Essentially:
the API Key becomes the basis for either the username or password value used by Basic Auth
that API Key needs to be base64 encoded as part of the Basic Auth standard
either an encoded version can be passed to ${API_KEY} using the example above (with tokenAuthorization.value=Authorization and tokenAuthorization.tokenType=Basic) or the replacer configuration documented in the Basic Auth article can be used
For a Deep Dive into authenticated scanning with HawkScan, see this recording of our Technical Workshop on Authenticated Security Testing: