Authenticated Scanning

Most web applications will have specific pages that are only accessible to authenticated users. To effectively scan for vulnerabilities it is important to test all paths, including the authenticated routes.

HawkScan can support several styles of authentication. This includes traditional form-based username/password, http cookies, or several third party OAuth providers.

Getting Started

To set up Authenticated Scanning you will need to know the following 4 pieces of information about your application:

  • Login Authentication Type (AuthN)

    The first step needed to set up Authenticated Scanning is your application’s Authentication Type (AuthN). HawkScan supports two types for AuthN. This could be a form (with a username and password) or an external supplied authorization token. External authorization can come from services like Auth0, Amazon Cognito, Google, and Azure.

    The simplest example is a username and password form.

    Learn more about Form Based Authentication setup

    Another form is through an API key or external auth provider.

    Learn more about Token Injection Authentication setup

  • Session Authorization Type (AuthZ)

    The second step of information needed is how HawkScan should maintain authorization (AuthZ) throughout the scan. This can be done via a cookieAuthorization or tokenAuthorization configuration. HawkScan also supports custom authentication scripts for more complex setups.

    Cookie Authorization:

    Upon verification the server returns a new cookie to the requesting client. The cookie is used to track your session on the server with the expectation that subsequent requests send the cookie back via the Set-Cookie response header. This allows the server to track requests and maintain the session.

    Bearer Token Authorization:

    Many modern web application backends are APIs that serve data to more than just html based web browsers.

    A common approach for authentication in this scenario is to create an API route that accepts a user’s credentials via a POST request of JSON data with the request returning an Authorization token as part of the JSON response payload.

    Once the Authorization token is obtained, it is then passed by the client as an Authorization header on all subsequent requests to protected routes. This method of authorization is commonly referred to as bearer token authorization.

    This approach is common for single page applications that use modern javascript frameworks like Angular, React, Vue.js, and others.

    Custom Scripting:

    Custom authentication and session management scripts can be used to handle complex authentication and authorization scenarios. If a preconfigured authentication and/or authorization style doesn’t meet your needs you can replace either with a custom script.

    HawkScan supports writing custom scripts in JavaScript and Kotlin via Zap scripting support. Visit our GitHub Repo to get started.

  • Login Test Path

    The third piece of information is a means of testing for successful authentication.

    A testPath configuration may also be provided to verify HawkScan authenticated its session correctly before scanning the application. The testPath configuration also provides requestMethod and requestBody options to support alternate HTTP request verbs, such as POST or PUT. The default action is GET.

  • Logged In/Out Indicators

    The fourth and final piece relates to some data points that can tell HawkScan if it is logged in our out.

    Throughout the scan, HawkScan will check to see if it is still logged in by the loggedInIndicator and loggedOutIndicator. These are regex strings to match against http responses from pages in the web application. This could be a “Log Out”/”Sign Out” button a user would see if logged in.

Based on your application you will pair a yml snippet of your authentication type with a snippet of how your authentication maintains credentials. The authentication and authorization configurations are defined separately to support a variety of web application needs.

Setup Authenticated Scanning in the StackHawk UI

Setting up Authenticated Scanning for your application will be highly dependent on the tech stack your team uses. Your stackhawk.yml file will need to be edited to match your application’s specific needs. StackHawk has created the Authenticated Scanning modal to get you started.

Launching the Authenticated Scanning Guide

StackHawk has an Authenticated Scanning template builder to help get you started.

While on the Applications page, locate the desired Environment you would like to set up Authenticated Scanning for. On the Environment card, click the kabob menu in the top right corner. Select: “Setup Authenticated Scanning” to get started.

Setup Authenticated Scanning from Application menus

Step 1: App Details

In this step, the helper needs information about your application’s authentication to best recommend a starting point.

Open the Authentication (AuthN) dropdown and select the choice that best matches your application’s authentication.

AuthN Selection Dropdown

Injecting Token/Cookie

Sometimes authentication is not performed with just a username and password. For example, API key access or third-party authentication services like OAuth require custom tokens.

To support this type of authentication, HawkScan supports externally supplying an authorization token with the authentication.external configuration.

The external supplied authorization token can be used in conjunction with either a token or a cookie to maintain the session. If you would like to supply authorization externally, select “Inject Cookie” or “Inject Token” depending on how your application maintains the session.

Learn more about Injecting Cookies/Tokens

Form Username/Password

Select “Form with HTTP Parameters” or “Form with API Call / JSON Payload” if you would like to give HawkScan user credentials to use on a login page. You can either pull credentials in at run time or add them into your YAML file directly.

While the most basic form of authentication to set up, HawkScan needs to know what type of form is being used and what to capture after login to maintain the session (AuthZ).

After selecting your login form’s type, select how to maintain the session in the Authorization dropdown.

Note: If your Tokens or Cookies have a short life span, it is recommended you create a custom script for your authentication. View examples in GitHub, or contact support for help.

Learn more about Form Authentication

AuthZ Dropdown Selection

Step 2: Getting Your YAML Template

After giving the helper information about your application, a YAML snippet will be given and (if applicable) a link to download premade authentication scripts.

Scripts:

If you are using a 3rd party tool with a grant type that has premade scripts available, you will see a link to GitHub above your YAML Snippet. Add the Auth Script folder next to your stackhawk.yml and make adjustments as needed.

If you have decided to write your own scripts, refer to our GitHub repo.

YAML Snippet:

Copy and paste this snippet into your stackhawk.yml.

Based on the comments in your YAML snippet, edit and update your YAML file.

No matter what type of Authorization/Authentication your app is using, HawkScan requires testPath, loggedInIndicator and loggedOutIndicator.

If you are unsure of how to update your YAML file, contact support.

Auth Setup YAML Snippet

Step 3: Run a Scan!

Depending on how you set up your authentication, your run command may look different, however for most cases the run command is the same as before.

If you are using a script and/or put login credentials into your stackhawk.yml, the run command is the same as before setting up authentication.

If you are injecting a cookie, token, and/or login credentials at runtime, your run command will look different based on the environment variables you used in your configuration. Refer to the page on Running HawkScan and be prepared with the specific environment variables you used.

Detailed Configuration

All available authentication configuration properties and values are explained in depth in the Authentication subsection of the Configuration docs.