May I see some ID?

To the unaware, nothing says you don’t belong quite like a 400 level Unauthorized or Forbidden error message. To the maleficent, however, these messages reveal a potential hidden treasure trove of data available for exploitation. Given the typical web application undergoes an average of 13,279 attacks each month, (source | Contrast Security) security testing is critical for ensuring only the right users have access to the right information.

When implementing security testing and vulnerability scanning, it is important to test all paths, including the authenticated routes. Only scanning public routes will give an incomplete picture of your web application’s security posture and cause you to miss the majority of vulnerabilities, which are often hidden behind a credentialed login.

As covered in our Onboarding Series, StackHawk supports the following types of automated authentication for security testing:

Credential TypeHTTP Content TypeAuthorization Type
Username/Passwordapplication/x-www-form-urlencodedBearer Token
Username/Passwordapplication/jsonBearer Token
Username/Passwordapplication/jsonCustom Token
ExternalN/AQuery Param
ExternalN/ABearer Token

The rest of this article will focus on configuring StackHawk’s scanner, HawkScan, using Username/Password + Cookie Authorization, commonly implemented with form-based authentication.

Configuring HawkScan

Let’s assume you’ve implemented the following paths for your application. [public route] [public route] [public route] [protected route] [protected route] [protected route]

Basic HawkScan Configuration (Public Routes):

First, we’ll begin with a basic configuration for HawkScan, which will only find the publicly available routes /home, /login/, and /comments. While only a partial picture of your application, this is still a great place to start to ensure the scanner is working as expected and able to find your environment.

    applicationId: kkAAAKAW-kAWW-kkAA-WWwW-kAAkkAAAAwWW
    env: Development
    host: http://localhost:8020

Authenticated Configuration (Public + Protected Routes)

To enable HawkScan to find and test the protected routes you need to define the expected experience of an authenticated user. For example, what elements of your web application indicate that a user’s state is logged-in vs. logged-out? Additionally, it’s important to know where a user would navigate to login to your application, what pages are accessible after a login has been validated, and what would indicate success or failure. These elements are easily found using existing developer tools within your browser.

Developer Tools HTML Form Element
Cookie Names
Cookie Names
Test Path & Success Criteria
Test Path & Success Criteria

Now that we’ve understood the experience of an authenticated user, we can use the information we’ve found to configuration our stackhawk.yml file.

    applicationId: kkAAAKAW-kAWW-kkAA-WWwW-kAAkkAAAAwWW
    env: Pre-Production
    host: <http://localhost:8020>
    antiCsrfParam: csrfToken
        loggedInIndicator: "\\\\QLog out\\\\E"
        loggedOutIndicator: "\\\\Qlogin-form\\\\E"
            type: FORM
            loginPagePath: /admin/login/
            loginPath: /admin/login/
            usernameField: username
            passwordField: password
            scanUsername: ${SCAN_USERNAME} # env variable
            scanPassword: ${SCAN_PASSWORD} # env variable
                - name: next
                - val: "/admin/"
                - "csrftoken"
				- "sessionid"
            path: /admin/
			type: HEADER
            success: ".*200.*"

Configuration Definitions:

  • applicationId: Unique ID for organizing your scan results by app or microservice in the StackHawk Platform.
  • env: The name of your staging environment, corresponding to your application in the StackHawk platform.
  • host: The url of the application to scan.
  • antiCsrfParam: The name of your CSRF security parameter used in any application form inputs.
  • loggedInIndicator: When this regex pattern is present in the HTTP response (header or body), it signifies the user is logged-in. EX: logout link
  • loggedOutIndicator: When this regex pattern is present in the HTTP response (header or body), it signifies the user is logged out. EX: login link
  • loginPathPage: The path to your login form, if applicable. This is an optional path but is often required if the POST to the loginPath requires an anti-csrf token to be passed as part of the POST.
  • loginPath: Your login route to POST credentials for a user in the application.
  • otherParams: Parameters required by your login payload in addition to login credentials.
  • testPath: The path to a protected route in your application that requires authorization. Example: /mysettings.
  • scanUsername & scanPassword: Credential values to be passed into the form’s usernameField and passwordField via environment variables or secret store.

Running the Scan

All that’s left to do is run the scan. If you haven’t already, make sure you complete the following checklist to see successful scan results:

  • Install Docker
  • Create a stackhawk.yml file in the root directory of your application
  • Create an application at and add the application id to the top of your YAML file.
  • Ensure the “host” value in your YAML file points to a running application
  • Complete the YAML configuration following the steps outlined above
  • Create and API Key within your StackHawk profile settings
  • Run the following docker command:
docker run --rm -v $(pwd):/hawk:rw -it \
  -e API_KEY=hawk.xxxxxxxxxxxxxxxxxxxx.xxxxxxxxxxxxxxxxxxxx \

Check out our HawkDocs page for more information and additional configuration options.


You don’t have to be afraid of those Unauthorized or Forbidden error messages anymore! If you’re using HawkScan and see one of those messages, you now know how to fix the issue. Using those handy developer tools to better understand your authentication workflows and double-check your configuration file will put you on the path to successful scans and a more secure web application environment.