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:
allowing you to conduct AuthN outside of the scanner (e.g., by using your existing login scripts)
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 scancommand is an overlay example, meaning:app.applicationId,app.env, andapp.hostare derived from stackhawk.ymlthe rest of the configs are derived from stackhawk-auth-external-token.yml
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.