Scan Authenticated Routes

Setting up Authenticated Scanning for your application depends on the tech stack your team uses. You must configure your stackhawk.yml file based on the type of authentication and authorization your application uses and in some instances include an authentication script.

The StackHawk Platform includes an Authenticated Scanning template builder to guide you through the process of updating your stackhawk.yml file and selecting an appropriate sample authentication script depending on your application’s authentication and authorization methods.

This getting started guide walks you through using the Authenticated Scanning template builder to set up authenticated scanning for your application. If you would prefer configuring your stackhawk.yml file and selecting an appropriate authenication script manually, see Authenticated Scanning for more in-depth explanation.

Before You Begin

To correctly configure your stackhawk.yml file, you need to know the following about your application:

• Login Authentication Type (AuthN)
• Session Authorization Type (AuthZ)
• Login Test Path
• Log in/out Indicators

See Authentication Details for more information about each of these items.

Launch the Template Builder

The Authenticated Scanning template builder is part of the StackHawk Platform and guides you through the process of updating your stackhawk.yml file and selecting an appropriate sample authentication script depending on your application’s authentication and authorization methods.

To access the Authenticated Scanning template builder:

1. Log in to your StackHawk account.
2. On the Applications page, find the application/environment you would like to set up authenticated scanning for.
3. Click the environment options menu icon ( ) on the environment card for your application and select Setup Authenticated Scanning.

Select Auth Method

The first step in the Authenticated Scanning template builder is to select your Authentication Method(AuthN). The template builder separates the different supported options into the following authentication types:

• 3rd party/OAuth: Most modern applications leaverage OAuth SaaS products to manage login credentials and security. HawkScan supports scripting to automate the grant type. The best grant types to automate with scripting are “Client Credential” and “Resource Owner” flows.

  See Third-party/OAuth for more information on configuring HawkScan for third-party OAuth authentication.

• Inject Cookie or Token: Another way to authenticate that HawkScan supports is externally supplying an authorization token which can be used in conjunction with either a token or a cookie to maintain the session.

  See Inject Cookie or Token for more information on configuring HawkScan for inject cookie or token authentication.

• Form with Username + Password: A common way to authenticate to a web application is by POSTing a username and password which can be verified by your server. Upon verification the server returns a cookie or token to the requesting client.

  See Form with Username + Password for more information on configuring HawkScan for form with username + password authentication.

Once you select the option that represents your application’s authentication method, you either need to select the grant type if you are using a 3rd Party OAuth option, or select the authorization method.

Select 3rd Party/OAauth Provider

If you are using 3rd Party OAuth as your authentication method, the Authenticated Scanning template builder includes the following 3rd Party OAuth providers:

• Auth0
• Okta
• Keycloak
• Firebase

Once you select one of the 3rd Party OAuth providers, you need to select the grant type.

If you do not see your OAuth provider listed, select Other Service, enter the name of your service, and the Authorization Method (AuthZ).

Grant Types Suitable for CI/CD

After you choose one of the supported 3rd Party OAuth providers, you need to select the grant type. The grant type you use will determine if your authentication flow can be automated with scripting. The best grant types to automate with scripting are Client Credential and Resource Owner flows.

• Client Credential Flow: With machine-to-machine (M2M) applications, such as CLIs, daemons, or services running on your back-end, the system authenticates and authorizes the app rather than a user.
• Resource Owner Password Flow: Highly-trusted applications can use the Resource Owner Password Flow, which requests that users provide credentials (username and password), typically using an interactive form.

StackHawk provides sample authentication scripts for the following grant types that you can include in a CI/CD workflow:

• Auth0
  • Client Credential Flow
    • Sample authentication script
    • Sample stackhawk.yml file
  • Resource Owner Password Flow
    • Sample authentication script
    • Sample stackhawk.yml file
• Okta
  • Client Credential Flow
    • Sample authentication script
    • Sample stackhawk.yml file
  • Resource Owner Password Flow
    • Sample authentication script
    • Sample stackhawk.yml file
• Keycloak
  • Client Credential Flow
    • Sample authentication script.
    • Sample stackhawk.yml file.

NOTE: If you do not see your grant type listed, see Other Grant Types.

After you select one of the grant types with authentication scripts, the Authenticated Scanning template builder provides links to the sample authentication scripts in a GitHub repo. Update and add these scripts to your application’s project in an ‘authentication’ folder. Place this folder in a ‘scripts’ folder, located in the same directory as your stackhawk.yml file.

Additionally, the Authenticated Scanning template builder provides a YAML snippet that you must update with your application’s unique data and then include in your stackhawk.yml file.

Learn more about Authentication with 3rd Party Authentication Providers

Other Grant Types

After you choose one of supported 3rd Party OAuth providers, select the grant type. The grant type you use will determine if your authentication flow can be automated with scripting. Some grant types cannot be automated and are not suitable for CI/CD. These grant types often require human intervention during the flow. For example, when a user is asked to open an app/click a button to verify it is them as they are logging in. These flows are often referred to as “Authorization Code” and “Device Authorization” flows/grants. To run HawkScan with one of these grant types, you must manually get a JWT Token from the service and inject it at run time. See Inject Token for instructions.

The following grant types are not suitable for CI/CD workflows and need manual intervention:

• Auth0
  • Authorization Code Flow
  • Implicit Flow with Form Post
• Okta
  • Authorization Code Flow
  • Authorization Code with PKCE
  • Implicit Flow with Form Post
  • SAML 2.0 Assertion Flow
• Keycloak
  • Authorization Code Flow
  • Implicit Flow with Form Post
  • Device Authorization Grant
• Firebase
  • Federated Identity Provider Integration
  • Phone Number Authentication
  • Custom Auth System Integration
  • Anonymous Authentication

You can configure these grant types to work with HawkScan by updating your stackhawk.yml file with the YAML snippet provided by the Authenticated Scanning template builder, after updating it with your application’s unique data.

Learn more about Authentication with 3rd Party Authentication Providers

Select Auth Method

After you have selected your authentication method, you need to select an authorization method if you are using one of the following authentication methods:

• a 3rd Party OAuth provider we do not list (Other Service)
• Form with HTTP Parameters
• Form with API call/JSON Payload

The Authenticated Scanning template builder offers the following options for Authorization Method (AuthZ):

• Create a Script: Custom authentication and session management scripts can be used to handle complex authentication and authorization scenarios. HawkScan supports writing custom scripts in JavaScript and Kotlin. See Authentication and session management scripts for more information.
• Inject a Cookie: Injecting a cookie for maintaining the session is rare. In most cases, it is better to use traditional form authentication form authentication with a cookie. See Injecting a Cookie for more information.
• Inject a Token: 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. See Inject Cookie or Token for more information.

Once you have selected your authentication and authorization methods, the Authenticated Scanning template builder presents a YAML snippet and in some instances a link to an authentication script. You need to add this YAML snippet to your stackhawk.yml configuration file.

Add YAML Snippet to Config

HawkScan uses the stackhawk.yml configuration file to run scans based on your application’s unique set up. If you do not have a stackhawk.yml file already, see Configuration to set up a basic configuration.

Then copy and paste the YAML snippet the Authenticated Scanning template builder generated into your stackhawk.yml file. 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 the following parameters:

• testPath
• loggedInIndicator
• loggedOutIndicator

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 Running HawkScan and be prepared with the specific environment variables you used.

Config Reference

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