Forms with Username and Passwords

Overview

HTTP authentication is a form of authentication where a server will issue a challenge to a client request and the client will provides a user’s credentials in the header of the request.

The authentication section of the stackhawk.yml will have 4 parts:

Logged in/out indicators
- How HawkScan checks it is logged in throughout the scan.
Auth(N)
- Your form type and login credentials.
Auth(Z)
- How you maintain the session. Either a Cookie or Token.
Test Path
- How HawkScan sees if it successfully logged in

Make sure your file has all 4 of these parts filled out.

YAML by HTTP Type

NTLM Authentication:

stackhawk.yml

app:
  applicationId: kkAAAKAW-kAWW-kkAA-WWwW-kAAkkAAAAwWW
  env: Test
  host: ${APP_HOST:http://localhost:3000}
  antiCsrfParam: __RequestVerificationToken
  authentication:
    # Paths that HawkScan checks to see if it is still logged in during the scan
    loggedInIndicator: "HTTP.*2[0-9][0-9]\\s*O[kK](\\s*)|HTTP.*3[0-9][0-9].*" # Change me
    loggedOutIndicator: "HTTP.*4[0-9][0-9](\\s*)Unauthorized.*" # Change me
    # Auth(N) HTTP Authentication
    usernamePassword:
      type: HTTP
      loginPath: /login # Page behind NTLM Authentication
      usernameField: user # Field name for the account username/email
      passwordField: password # Field name for the password
      scanUsername: ${SCAN_USERNAME} # Inject variable at runtime or place your username here
      scanPassword: ${SCAN_PASSWORD} # Inject variable at runtime or place your password here  
      realm: "My Realm"  # The realm protection space for your ntlm authentication
    # (REQUIRED) Add your Auth(Z) here. Either Cookie or Token
    tokenAuthorization:
      type: HEADER
      value: Authorization
      tokenType: NTLM
    #A path that can only be seen when successfully logged in. HawkScan will check this path to see if log in was successfull
    testPath:
      path: /mysettings # Change me
      success: ".*200.*"
      requestMethod: GET

Basic Authentication:

Basic authentication is very simlar to NTLM authentication with the token type for the Authorization is specified as Basic

stackhawk.yml

    # (REQUIRED) Add your Auth(Z) here. Either Cookie or Token
    tokenAuthorization:
      type: HEADER
      value: Authorization
      tokenType: BASIC

YAML Sections in Detail

Giving HawkScan HTTP Credentials

HawkScan best practices is using environment variable runtime overrides. This is the most secure way to keep valid credentials to your application secret. These can be pulled in from your run command or a stored secret in your pipeline.

stackhawk.yml

app:
  applicationId: xxXXXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX
  env: Test
  host: ${APP_HOST:http://localhost:3000}
  authentication:
    usernamePassword:
      scanUsername: ${SCAN_USERNAME}
      scanPassword: ${SCAN_PASSWORD}

Maintaining the Session

For HTTP authentication, the authorization is stored in the Authorization Header. The tokenType will determine what type of auth it is, e.g. Basic or in this example NTLM.

Tokens:

stackhawk.yml

app:
  applicationId: xxXXXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX
  env: Test
  host: ${APP_HOST:http://localhost:3000}
  authentication:
    tokenAuthorization:
      type: HEADER
      value: Authorization
      tokenType: NTLM

Logged In/Out Indicators

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 requests in the web application.

A .loggedInIndicator could be a “Log Out” or ”Sign Out” button a user would see if logged in. An example of a .loggedOutIndicator would be a “Log In” button on the sign in page. These can also leverage http status codes from the response.

stackhawk.yml

app:
  applicationId: xxXXXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX
  env: Test
  host: ${APP_HOST:http://localhost:3000}
  authentication:
    loggedInIndicator: "HTTP.*2[0-9][0-9]\\s*O[kK](\\s*)|HTTP.*3[0-9][0-9].*"
    loggedOutIndicator: "HTTP.*4[0-9][0-9](\\s*)Unauthorized.*"

Example NTLM Authentication

NTLM authentication is a multi legged authentication. The flow in the browser would be as such:

A user will visit a page and be challenged with providing a username and password.
The browser will store a hashed version of the password.
The browser will request to be connected to the server.
The server will respond with a nonce.
The browser then sends back the nonce encrypted with the user’s password hash for NTLMv1. NTLMV2 uses username and timestamp as well.

Detailed Configuration

You would want a stackhawk.yml configuration like this.

stackhawk.yml

app:
  applicationId: xxXXXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX
  env: Test
  host: ${APP_HOST:http://localhost:3000}
  authentication:
    loggedInIndicator: "HTTP.*2[0-9][0-9]\\s*O[kK](\\s*)|HTTP.*3[0-9][0-9].*"
    loggedOutIndicator: "HTTP.*4[0-9][0-9](\\s*)Unauthorized.*"
    usernamePassword:
      type: HTTP
      loginPath: /
      usernameField: email
      passwordField: password
      scanUsername: ${SCAN_USERNAME}
      scanPassword: ${SCAN_PASSWORD}
    tokenAuthorization:
      type: HEADER
      value: Authorization
      tokenType: NTLM
    testPath:
      path: /mysettings
      success: ".*200.*"

The authentication request/response would then look something like.

Auth Request

GET / HTTP/1.1
Host: localhost:3000
Authorization: NTLM TlRMTVNTUAABAAAABoIIAAAAAAAAAAAAAAAAAAAAAAA=
Accept: */*

Challenge Response

HTTP/1.1 401 Unauthorized
Content-Type: text/html; charset=us-ascii
Server: Microsoft-HTTPAPI/2.0
WWW-Authenticate: NTLM TlRMTVNTUAACAAAADgAOADgAAAAGgooCCkHJ30o9RUcAAAAAAAAAAJAAkABGAAAACgBdWAAAAA9XSU5ERVYyMzAyRVZBTAIAHABXAEkATgBEAEUAVgAyADMAMAAyAEUAVgBBAEwAAQAcAFcASQBOAEQARQBWADIAMwAwADIARQBWAEEATAAEABwAVwBpAG4ARABlAHYAMgAzADAAMgBFAHYAYQBsAAMAHABXAGkAbgBEAGUAdgAyADMAMAAyAEUAdgBhAGwABwAIAIHxrhL+ctkBAAAAAA==

Authorized Request to `/mysettings`

GET / HTTP/1.1
Host: localhost:3000
Authorization: NTLM TlRMTVNTUAADAAAAGAAYAEAAAADAAMAAWAAAAAAAAAAYAQAABAAEABgBAAALAAsAHAEAAAAAAAAAAAAABoKKAk7QHf/4L8gXYkLkwTHVZ0nCgylcRISB+pANx6y5cDJDdh//qgd4ltYBAQAAAAAAAADdZBL+ctkBwoMpXESEgfoAAAAAAgAcAFcASQBOAEQARQBWADIAMwAwADIARQBWAEEATAABABwAVwBJAE4ARABFAFYAMgAzADAAMgBFAFYAQQBMAAQAHABXAGkAbgBEAGUAdgAyADMAMAAyAEUAdgBhAGwAAwAcAFcAaQBuAEQAZQB2ADIAMwAwADIARQB2AGEAbAAHAAgAgfGuEv5y2QEAAAAAAAAAAHVzZXJXT1JLU1RBVElPTg==
Accept: */*

Authorized Response

HTTP/1.1 200 OK
Transfer-Encoding: chunked
Content-Type: text/html; charset=utf-8
Server: Microsoft-IIS/10.0
Persistent-Auth: true

Requests to protected routes like /mysettings will have the Authorization header added to each request. With the type header describing the token being as a request header, the value being the name of the header Authorization, and tokenType : NTLM prepended to the token.

Example Basic Authentication

Basic authentication is much more simple and just includes a base64 hash of the username:password in each request.

Detailed Configuration

You would want a stackhawk.yml configuration like this.

stackhawk.yml

app:
  applicationId: xxXXXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX
  env: Test
  host: ${APP_HOST:http://localhost:3000}
  authentication:
    loggedInIndicator: "HTTP.*2[0-9][0-9]\\s*O[kK](\\s*)|HTTP.*3[0-9][0-9].*"
    loggedOutIndicator: "HTTP.*4[0-9][0-9](\\s*)Unauthorized.*"
    usernamePassword:
      type: HTTP
      loginPath: /
      usernameField: email
      passwordField: password
      scanUsername: ${SCAN_USERNAME}
      scanPassword: ${SCAN_PASSWORD}
    tokenAuthorization:
      type: HEADER
      value: Authorization
      tokenType: Basic
    testPath:
      path: /mysettings
      success: ".*200.*"

The authentication request/response would then look something like:

Auth Request

GET / HTTP/1.1
Host: localhost:3000
Authorization: BASIC dXNlcjpwYXNzd29yZA==
Accept: */*

See Authenticating HawkScan to applications using Basic Auth for additional details.

Forms with Username and Passwords

Overview

YAML by HTTP Type

NTLM Authentication:

Basic Authentication:

YAML Sections in Detail

Giving HawkScan HTTP Credentials

Maintaining the Session

Example NTLM Authentication

Detailed Configuration

Auth Request

Challenge Response

Authorized Request to /mysettings

Authorized Response

Example Basic Authentication

Detailed Configuration

Auth Request

Authorized Request to `/mysettings`