Authenticated Scanning

Why Authenticated Scanning Matters

Most applications hide their valuable functionality behind login screens. Without authentication, security scanners can only test public routes, missing the critical parts of your application where the most dangerous vulnerabilities often lurk. StackHawk’s authenticated scanning capabilities allow HawkScan to:

• Access protected routes and functionality
• Test authorization boundaries between different user roles
• Discover vulnerabilities in authenticated API endpoints
• Provide comprehensive security coverage of your application

Getting Started with Authentication

Setting up authenticated scanning requires configuring HawkScan to handle your application’s specific authentication mechanism. This guide will help you:

• Identify your authentication type - Determine how your application handles login
• Configure your stackhawk.yml file - Add the necessary authentication parameters
• Run your first authenticated scan - Verify complete access to protected routes

Understanding Your Authentication Method

Before configuring HawkScan, you need to understand how your application handles authentication. Most applications fall into one of these categories:

Authentication Type	Common Examples	Best For
Form-based Authentication	Traditional username/password login forms	Applications with simple login pages
OAuth/3rd Party	Auth0, Okta, Keycloak, Firebase	Modern applications using identity providers
Token-based Authentication	JWT, Bearer tokens	APIs and single-page applications
Cookie-based Authentication	Session cookies	Traditional web applications

See Authenticated Scanning for detailed configuration options.

Configuration Steps

1. Gather Required Information

For all authentication types, you’ll need:

• Login Test Path: A protected page that requires authentication
• Logged In Indicator: Text or pattern that confirms successful login
• Logged Out Indicator: Text or pattern that indicates no authentication

2. Configure Your Authentication Type

Add the appropriate section to your stackhawk.yml file based on your authentication method:

Form-based Authentication

app:
  authentication:
    loggedInIndicator: "Welcome, User" # Text that appears when logged in
    loggedOutIndicator: "Login" # Text that appears when logged out
    testPath: /dashboard # A path that requires authentication
    usernamePassword:
      type: FORM
      username: ${HAWK_USERNAME} # Set as environment variable
      password: ${HAWK_PASSWORD} # Set as environment variable
      loginPath: /login
      submitSelector: "button[type='submit']" # CSS selector for login button
      usernameSelector: "#username" # CSS selector for username field
      passwordSelector: "#password" # CSS selector for password field

OAuth/3rd Party Authentication

For OAuth providers like Auth0, Okta, or Keycloak, use the native oauth configuration:

app:
  authentication:
    loggedInIndicator: "HTTP/[0-9]+.[0-9]+\\s+([2-3][0-9][0-9])"
    loggedOutIndicator: "HTTP/[0-9]+.[0-9]+\\s+(4[0-9][0-9])"
    oauth:
      parameters:
        tokenEndpoint: https://${YOUR_DOMAIN}/oauth/token
        grantType: client_credentials
      credentials:
        clientId: ${YOUR_CLIENT_ID}
        clientSecret: ${YOUR_CLIENT_SECRET}
    tokenExtraction:
      type: TOKEN_PATH
      value: access_token
    tokenAuthorization:
      type: HEADER
      value: Authorization
      tokenType: Bearer
    testPath:
      path: /api/private
      success: '.*200.*'

See 3rd Party OAuth for provider-specific examples.

Token Injection

app:
  authentication:
    loggedInIndicator: "User Profile" # Text indicating successful login
    loggedOutIndicator: "Unauthorized" # Text indicating no authentication
    testPath: /api/profile # Protected path to verify authentication
    external:
      headers:
        - name: "Authorization"
          value: "Bearer ${API_TOKEN}"

Running Your Authenticated Scan

Once configured, run HawkScan with your authentication settings:

# For configurations with environment variables
hawk scan --env-file .env 

# For basic configurations without environment variables
hawk scan

Verifying Authentication Success

After running your scan, check for these indicators of successful authentication:

• HawkScan logs should show successful login and authentication
• The scan results should include protected routes
• The “Coverage” tab in the StackHawk Platform should show authenticated pages

Troubleshooting Authentication

If your authentication isn’t working:

• Check the HawkScan logs for specific authentication errors
• Verify your login indicators are unique and reliable
• Ensure your authentication credentials are correct
• Test your login flow manually to confirm it works as expected

Next Steps

• Authenticated Scanning Reference - Detailed configuration options for all authentication types
• 3rd Party OAuth Guide - Provider-specific examples for Auth0, Okta, Keycloak, and Firebase
• Example Configurations - Sample scripts and YAML configs on GitHub