Overview
Standard Configuration
HawkScan's usernamePassword configuration includes a JSON type option which submits credentials to the target application as a JSON blob.
Basic example (AuthN)
In this example, we use the JSON POST approach to submit credentials via a simple JSON payload:
usernamePassword:
type: JSON
loginPath: /login
usernameField: email
passwordField: password
scanUsername: ${EMAIL} # e.g., "test@test.com"
scanPassword: ${PASSWORD} # e.g., "changeme"
This configuration will result in a POST to the /login url relative to your configured app.host url (e.g., https://localhost:3000/login) which contains the following JSON payload:
{"email": "test@test.com","password": "changeme"}
otherParams example (AuthN)
otherParams can also be added which add additional key/value pairs within this JSON payload.
For example:
usernamePassword:
type: JSON
loginPath: /login
usernameField: email
passwordField: password
scanUsername: ${EMAIL} # e.g., "test@test.com"
scanPassword: ${PASSWORD} # e.g., "changeme"
otherParams:
- name: rememberMe
val: 'true'
Which results in this payload:
{"rememberMe": "true","email": "test@test.com","password": "changeme"}
Issue
Suppose, however, that your application instead required a different JSON payload.
For instance, credentials nested under a "user" section:
{
"user": {
"email": "test@test.com",
"password": "changeme"
}
}
In this scenario, the usernamePassword configuration cannot account for the encapsulating "user" section of the JSON payload.
Solution: Use an Auth Script
To authenticate using custom JSON payloads, you'll need to use an authentication script rather than usernamePassword configuration.
Luckily, an example script is available in our Hawkscan Examples repository, where authentication and session script examples are available to help you authenticate to applications using numerous authentication methods.
Specifically, the Custom JSON Payloads script can be used to generate a custom JSON string using credentials and parameters that you specify.
Calling the Auth Script in stackhawk.yml
Once your script is in place, you'll need to point HawkScan to it using the authentication.script and hawkAddOn.scripts configs.
Example configs snippets:
Call the script and populate fields from environment variables that were passed to HawkScan:
authentication:
script:
name: auth_custom_json_payload.js
credentials:
email: "${SCAN_USERNAME}"
password: "${SCAN_PASSWORD}"
parameters:
login_url: "${API_LOGIN_URL}
Managing Authorization (AuthZ)
Tell HawkScan what to do with the token extracted by the script:
tokenAuthorization:
tokenType: Bearer
type: HEADER
value: Authorization
tokenExtraction:
type: TOKEN_PATH
value: token
The above tells the scanner to 1) look for a token named 'token' in the response body from the application and 2) send it to the application going forward as an Authorization header containing "Bearer <tokenvalue>".
Defining the scripts in stackhawk.yml
Define the auth script in hawkAddOn.scripts:
hawkAddOn:
scripts:
- name: auth_custom_json_payload.js
path: scripts
type: authentication
language: JAVASCRIPT
Note: The scanner looks for authentication scripts in an authentication subdirectory; in the above, path indicates that the script is at the relative path scripts/authentication/auth_custom_json_payload.js, and that stackhawk.yml is in the the directory directly above the scripts subdirectory directory.
Additional Information
Custom JSON Payload Script Demo
Scanning the javaspringvulny application using the custom json payload script and tokenAuthorization:
Overview: Authentication Scripts
For a general introduction to the topic of authentication scripts, see Using custom authentication scripts with HawkScan.