HawkScan Authenticated Scanning C… | StackHawk Documentation

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

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

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.

Session Verification

Indicators answer “am I still logged in?” by regex-matching every response HawkScan receives. sessionVerification answers it directly instead, by re-sending your app.authentication.testPath at a fixed cadence and checking the same matcher that verified your login at startup. When a check fails, HawkScan re-authenticates and carries on scanning.

Session verification is opt-in. Adding the sessionVerification block turns it on — with fields or without — and leaving it out keeps the indicator behavior described above, unchanged.

app:
  authentication:
    testPath:
      path: /api/user/me
      success: ".*200 OK.*"
    sessionVerification:
      pollFrequency: 15
      activeScanPollFrequency: 5
      maxUnauthenticatedRequestPercent: 5

Option	Default	Description
`pollFrequency`	`15`	Requests between session checks while crawling. A longer interval costs latency: a session that dies mid-scan goes unnoticed for at most this many requests, and each of those reaches only what an anonymous user can see.
`activeScanPollFrequency`	`5`	Requests between session checks while actively attacking. Tighter than the crawl cadence, because the two phases do not carry equal risk — a request sent unauthenticated during an attack is a missed finding, while a URL missed while crawling is usually found again on a later pass.
`maxUnauthenticatedRequestPercent`	`5`	The share of checks that may report the session gone before HawkScan calls the scan’s coverage suspect and warns at the end of the run.
`disabled`	`false`	Turns session verification off explicitly.

Both test-path styles work: an HTTP testPath, and a gRPC one via testPath.grpcTestMethod. testPath.type (HEADER or BODY) is honored, so a mid-scan check matches exactly the way your startup check does.

Coverage warnings

If more than maxUnauthenticatedRequestPercent of checks come back unauthenticated, HawkScan finishes the scan with a warning naming the share observed and the threshold it crossed. Treat it as a reason to distrust a clean result: a scan that lost its session partway through reports only what an anonymous user could reach, which looks identical to an application with nothing to find.

Turning verification off

Setting disabled: true requires that you also set loggedInIndicator or loggedOutIndicator. With neither, HawkScan falls back to a default logged-in pattern of .*, which matches every response — the scan concludes it is authenticated for its whole run, never re-authenticates, and quietly reports an anonymous user’s view of your application. HawkScan refuses that configuration up front rather than letting you find it in a thin result.

Authenticated Scanning

Authentication Details

Login Authentication Type (AuthN)