Modern web applications, especially single-page applications, are often built upon APIs that serve data to more than just HTML-based web browsers. These applications do not rely on web forms for authentication. Instead, a common approach is to create an API route that accepts a
POST request with a JSON payload containing the user’s credentials. The server will then return an authorization token as part of the JSON response. After the initial login, the API expects only the token to be sent on all subsequent requests to protected routes.
Stackhawk’s scanner, HawkScan, supports this scenario by default. Here we will focus on how to define both the username and password fields, values, and payload type for HawkScan. We’ll also add a
tokenExtraction section for obtaining the value of the token from the JSON response and a
tokenAuthorization section for using the token on all subsequent API calls.
Note: This API is designed to be intentionally minimal for authentication testing purposes only. It is not meant to showcase scan results.
You should have the following software installed on your computer.
Docker: (download from docker.com)
Python 3: (
[brew](http://<https://brew.sh/>) install pythonon MacOS)
jq: (‘brew install jq’ on MacOS)
Clone and run hawkling-api
Clone the hawkling-api repository and install the project dependencies outlined in the README.md file.
In your terminal, navigate to the
hawklingAPI/hawlingAPI/ directory that contains the
manage.py file and run the application.
Visit http://localhost:8000/ in your browser and verify you can access the home path.
The hawkling-api contains 3 paths:
kaakaww/. The first two routes are publicly available, meaning all the content at each path is freely accessible. The third route,
kaakaww/, requires a Bearer token in order to display the greeting message.
If you try to access
kaakaww/ without a token, you’ll receive a message asking for credentials. While the message says “credentials,” what it really means is an “Authentication token was not provided.”.
First, obtain your access token by POSTing credentials to
A successful post should return a response similar to the following
Next use the value of the
access token to make a request to
A request with a valid token will yield a friendly greeting
Configure and Run HawkScan
To scan the application, you’ll need to add the
stackhawk.yml file to your project directory. Filling out the file is as simple as describing the process we just stepped through using cURL.
Most often, when a user interacting with your application will innately understand whether they’re logged-in or logged-out based on context clues. To enable HawkScan to simulate scanning your application as an authorized user, we need to specifically define those clues.
In this case, when I made a request to
kaakaww/ without a Bearer token, I noticed the response contained the word “detail”. Likewise, when I made a request to
kaakaww/ with a Bearer token, the response changed to include the word “message.” Consequently, “detail” becomes my
loggedOutIndicator, and “message” becomes my
Knowing that the hawkling-api accepts
POST requests and expects a JSON payload, we specify the data expected with,
type: JSON, and define the
login/. Next, we need to tell the scanner the names of the credential fields (
passwordField) to be defined in the JSON payload. Lastly, we’ll specify the actual values of the
scanPassword. Simply put, these fields recreate our cURL command to
Following the POST request to
login/, the API returns a token in the response.
TOKEN_PATH tells the scanner we’re expecting the token to be located in a JSON payload and
value defines the name of the token to be extracted.
After the scanner has extracted the token, it needs to understand how to use it for making subsequent calls to other API routes.
tokenType all describe how the scanner should use the token, similar to the cURL command we previously made to
Once the token is obtained,
path tells HawkScan which route to use to verify authentication is working before running a scan and
success gives the scanner an indicator that the request to
path was successful.
Now that you’ve added the
stackhawk.yml file to your project directory, replace the value of
applicationId for the corresponding value in the StackHawk web platform.
Lastly, in your terminal, navigate to the directory where you saved the
stackhawk.yml file and run the docker command to initiate the scanner!
cURL is a great way to orient yourself around your applications. As you become more familiar with how your applications work, configuring HawkScan quickly becomes a walk in the park. If you need more help configuring HawkScanyou can always reach out to email@example.com. We’re more than happy to help get you up and running!
Adding security testing for authenticated app routes to your development processes ensures complete visibility into any vulnerabilities your application has before they’re found in production by the wrong crowd. If you’d like more information on how to move HawkScan from your local environment to your build pipeline, learn how to use StackHawk with Travis CI and Docker-Compose!