Skip to main content
All CollectionsAuthenticated Scanning
Authenticating HawkScan to applications using token injection
Authenticating HawkScan to applications using token injection

Passing externally-obtained authorization (AuthZ) tokens to HawkScan at runtime

Anthony Stinn avatar
Written by Anthony Stinn
Updated over a week ago

Overview

HawkScan's usernamePassword configuration accommodates several variants of authentication with minimal configuration overhead.

Some scenarios, however, may require a more customized means of passing credentials (AuthN) and obtaining the resulting authorization (AuthZ) mechanism.

HawkScan's app.authentication.external configuration supports these custom scenarios by:

  1. allowing you to conduct AuthN outside of the scanner (e.g., by using your existing login scripts)

  2. injecting the resulting authorization mechanism to the scanner at runtime

For instance, you may have an existing python script which obtains a JWT Token from an external authorization service; with the external injection configuration, you can run that script and pass the resulting token directly to the command that launches HawkScan.


Procedure

Step 1: Determine the AuthN mechanism

How are does the target application validate the client's identity and then provide that client with authorization?

Some possibilities:

  • receive credentials from clients via JSON; supply a JWT token upon successful login

  • receive a form-encoded POST from a login form; provide a cookie upon

  • redirect login requests to a 3rd party OAuth provider (e.g., Auth0); accept tokens provided by that provider

Step 2: Determine the AuthZ mechanism

Going forward, we'll assume that your application returns a JWT Token in the response payload. For instance:

{"username":"user","token":"tokenvalue"}

In practice, you could also have:

  • tokens returned in an Authorization header (Authorization: token: tokenvalue)

  • cookies (as configured in app.authentication.cookieAuthorization)

  • tokens and cookies (in which case, configure the cookies in app.sessionTokens)

Step 3: Write an AuthN script which obtains the token

Utilize shell scripts or programs that you already use to perform a login; determine how to extract the resulting AuthZ mechanism (e.g., as an environment variable of the shell that then launches HawkScan).

Example:

The javaspringvulny application includes an example login script, login-auth.sh, that obtains a JWT token and then extracts that token from the response payload:

#!/usr/bin/env bash

# Fetch a JWT token from JavaSpringVulny using the JSON signin endpoint
RESPONSE=$( curl --request POST 'https://localhost:9000/api/jwt/auth/signin' \
--header 'Content-Type: application/json' \
--data-raw '{"password": "password", "username": "user"}' \
--silent --insecure )

# Extract the JWT token from the JSON response
echo $RESPONSE | jq '.token' -r

Step 4: Run the script; pass the token

In this example, we populate the AUTH_TOKEN variable with a JWT token using the script above and then pass it to the HawkScan CLI command to run a scan.

YAML Configuration:

From the stackhawk-auth-external-token.yml example (note the external section):

app:
env: ${APP_ENV:JWT Bearer Token}
openApiConf:
path: /openapi
authentication:
external:
type: TOKEN
value: ${AUTH_TOKEN}
tokenAuthorization:
type: HEADER
value: Authorization
tokenType: Bearer
testPath:
path: /api/jwt/items/search/
success: ".*200.*"
loggedInIndicator: "\\QSign Out\\E"
loggedOutIndicator: ".*Location:.*/login.*"

Commands:

Obtain the token:

dan@Dans-MacBook-Pro stackhawk.d % export AUTH_TOKEN=$(../scripts/json-auth.sh); echo $AUTH_TOKEN                                             
[TOKEN_VALUE_REDACTED]

Run the scan:

hawk scan -e USERNAME=user -e PASSWORD=password -e AUTH_TOKEN stackhawk.yml stackhawk-auth-external-token.yml

Notes:

  • The above hawk scan command is an overlay example, meaning:

  • set app.testPath to a path that can only be visited when the token is included in the request (in the above, as a header containing Authorization: Bearer: <tokenvalue>)

  • the above could also be combined into a single script that obtains the token and runs the CLI (see below)

Combined script:

#!/usr/bin/env zsh

jwt_token=$( curl --request POST 'https://localhost:9000/api/jwt/auth/signin' \
--header 'Content-Type: application/json' \
--data-raw '{"password": "password", "username": "user"}' \
--silent --insecure | jq -r '.token' )

source /Users/dan/.hawk/hawk.rc #initialize hawk CLI with SHAWK_API_KEY from local config file

hawk scan -e AUTH_TOKEN=${jwt_token} stackhawk.yml stackhawk-auth-external-jwt.yml


Additional Information

External token injection demo

Scanning the javaspringvulny application using the external configuration to inject a JWT Token:

Token formatting alternatives

Not all applications expect to receive the token as a Bearer token in an Authorization header. For alternative tokenAuthorization configurations, see Token authorization examples in HawkScan.

Note: when using the external configuration to inject a token, there's no need to configure tokenExtraction -- that job has already been handled by the external configuration.

Cookie injection

Perhaps your application uses cookies instead of a token. In this scenario, you can simply inject the cookie instead.

Did this answer your question?