Login Start Free Trial Login Start Free Trial
 

Authenticated Scanning

Most web applications have pages that are only accessible to authenticated users. To effectively scan for vulnerabilities, you must test all paths, including the authenticated routes.

HawkScan uses the stackhawk.yml configuration file to run scans based on your application’s unique setup. To test authenticated routes, configure stackhawk.yml with your application’s authentication flow details.

Authentication Details

To set up Authenticated Scanning, configure your stackhawk.yml file with the following information about your application:

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

Login Authentication Type (AuthN)

The first piece of information you need to set up Authenticated Scanning is your application’s Authentication Type (AuthN).

HawkScan supports the following authentication types:

  • Third-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.

Session Authorization Type (AuthZ)

The second piece of information you need to set up Authenticated Scanning is how HawkScan should maintain authorization (AuthZ) throughout the scan.

Session Authorization can be configured in one of the following ways:

  • Cookie Authorization (cookieAuthorization)
  • Bearer Token Authorization (tokenAuthorization)
  • Custom Authentication Script (script)

The first type of authorization HawkScan supports is cookie authorization. Cookie authorization is when 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 with the Set-Cookie response header. This cookie allows the server to track requests and maintain the session.

See Cookie Authorization for more information on configuring HawkScan for cookie authorization.

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 with 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.

See Bearer Token Authorization for more information on configuring HawkScan for bearer token authorization.

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 with scripting support. Visit our GitHub Repo to get started.

See Custom Authentication Script (script) for more information on configuring HawkScan for custom scripting authorization.

Login Test Path

The third piece of information you need to set up Authenticated Scanning is a means of testing for successful authentication.

You must provide a testPath configuration to verify HawkScan authenticated its session correctly before scanning the application. The testPath configuration includes the requestMethod and requestBody options to support alternate HTTP request verbs, such as POST or PUT. The default action is GET.

For more information on testpath configuration see app.authentication.testPath

Logged In/Out Indicators

The fourth and final piece of information you need to set up Authenticated Scanning relates to some data points that can tell HawkScan if it is logged in or out.

Throughout the scan, HawkScan will check to see if it is still logged in by the loggedInIndicator and loggedOutIndicator, found in your stackhawk.yml file under app.authentication. These are regex strings used to match against the following two main patterns:

  • Text in an HTML response body from pages in the web application. For example, these responses could be a “Log out/Sign out” button a user would see if logged in.
  • HTTP response codes, commonly used when scanning APIs. For example, HTTP.*4[0-9][0-9](\\s*)Unauthorized.* for loggedInIndicator and HTTP.*2[0-9][0-9]\\s*O[kK](\\s*)|HTTP.*3[0-9][0-9].* for loggedOutIndicator.