ON THIS PAGE

Additional Examples

The authentication and authorization configurations are defined separately to support a variety of web application needs. Below is an example representing the full spectrum of authentication configurations supported by StackHawk.

You might not need all of these configurations for your situation. Consult the Configuration docs for in-depth explanations.

stackhawk.yml

app:
  applicationId: xxXXXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX
  env: Test
  host: http://localhost:3000
  # How should the scanner authenticate to your application when performing a scan.
  authentication:
    # A value to look for on the page which helps confirm the scan is logged in
    loggedInIndicator: "\\QLog out\\E"
    # A value to look for on the page which helps confirm the scan is logged out
    loggedOutIndicator: "\\QLog in\\E"
    # A username/password based authentication scheme
    usernamePassword:
      # The Content-Type expected by the loginPath FORM = application/x-www-form-urlencoded
      type: FORM
      # The path to POST username/password credentials.
      loginPath: /login
      # The path that will return the html form of your login form.
      # This is optional and the response should contain the csrf token if applicable.
      loginPagePath: /login.jsp
      # The path to POST username/password credentials to.
      usernameField: session[email]
      # The name of the password field
      passwordField: session[password]
      # The value of the username field
      scanUsername: "example-1@railstutorial.org"
      # The value of the password field
      scanPassword: ${SCAN_PASSWORD:changeme}
      # Extra fields and their values to be included in the POST data to loginPath
      # in addition to the username/password.
      otherParams:
      - name: utf8
        val: "✓"
      - name: "session[remember_me]"
        val: "0"
    # Cookie based authorization. If you application maintains its session state on the server
    # a common way to identify the user is via a cookie that is sent back with the authentication.
    # This method supports managing the lifecycle of the cookie.
    cookieAuthorization:
      # The name of the cookie(s) that will be maintained for authenticated requests.
      cookieNames:
      - "_toy_app_session"
    # The testPath configuration is used to confirm scanning as an authenticated user is configured successfully.
    testPath:
      # The type is either HEADER or BODY and informs the success or fail regex of what part of the response to match against.
      type: HEADER
      # A path to validate that authentication was successful. This path should be only accessible to authenticated users.
      path: /profile
      # Fail criteria regex pattern.
      # A successful match indicates that the response from the path specified was not successful
      fail: ".*302.*Location.*/login.*"
      # Success criteria regex pattern.
      # A successful match indicates that the response from the path specified was successful
      success: ".*200.*"
    # If your authentication state is not maintained server side via a Cookie
    # the tokenExtraction describes how to extract the token from the supplied credential type
    # like usernamePassword in this case. The token extracted will be the value used by tokenAuthorization
    # for access to authenticated routes.
    tokenExtraction:
      # The type of extraction. In this case we're expecting the authorization token
      # To be in the JSON payload response from the authentication step.
      type: TOKEN_PATH
      # The location of the token in the json payload. eg: {"token": "myauthtoken", ...}
      value: "token"
    # Token based authorization. If your app doesn't use cookies to maintain session/authorization state then
    # you'll likely need to pass the token on every request to the authenticated routes of your application.
    tokenAuthorization:
      # The method by which the token will be passed to your application.
      # In this case a header is expected
      type: HEADER
      # The name of the header that the token will be passed with requests authenticated routes.
      value: Authorization
      # The token type when using the Authorization header as is being used here.
      # Bearer is the most common value but custom names like "JWT" or "token" are sometimes required.
      tokenType: Bearer   

Need More? Example stackhawk.yml files demonstrating different combinations of authentication and authorization are available at HawkScan Examples.