Authentication

Shannon supports multiple authentication methods to test applications with various login mechanisms. Configure authentication in your YAML config file to enable authenticated testing.

Authentication Methods

Shannon supports four authentication types:

Form Login

Standard HTML login forms with username/password

SSO / OAuth

Single sign-on with Google, GitHub, etc.

API Authentication

Token-based authentication via API endpoints

Basic Auth

HTTP Basic Authentication

The most common authentication type for web applications.

authentication:
  login_type: form
  login_url: "https://example.com/login"
  credentials:
    username: "[email protected]"
    password: "testpassword"
  
  login_flow:
    - "Type $username into the email field"
    - "Type $password into the password field"
    - "Click the 'Sign In' button"
  
  success_condition:
    type: url_contains
    value: "/dashboard"

Provide natural language steps for the AI to follow. Use these variables:

$username - Replaced with credentials.username
$password - Replaced with credentials.password
$totp - Replaced with current TOTP code (if totp_secret provided)

Best Practices:

Be specific about field names (e.g., “email field” not “first field”)
Include wait steps if pages load between actions
Describe buttons by their visible text (e.g., “Click ‘Sign In’ button”)
Keep steps concise (max 500 characters per step)
Use 1-20 steps total

Success Conditions

Define how Shannon knows authentication succeeded:

URL Contains
URL Equals
Element Present
Text Contains

Check if URL contains a substring (most common):

success_condition:
  type: url_contains
  value: "/dashboard"

Check for exact URL match:

success_condition:
  type: url_equals_exactly
  value: "https://example.com/app/home"

Check for DOM element (use CSS selector):

success_condition:
  type: element_present
  value: "[data-testid='user-menu']"

Check for text on page:

success_condition:
  type: text_contains
  value: "Welcome back"

For applications using single sign-on providers like Google, GitHub, or custom OAuth.

authentication:
  login_type: sso
  login_url: "https://example.com/login"
  credentials:
    username: "[email protected]"
    password: "testpassword"
  
  login_flow:
    - "Click the 'Sign in with Google' button"
    - "Wait for the Google login page to load"
    - "Type $username into the email field"
    - "Click 'Next'"
    - "Wait for password page"
    - "Type $password into the password field"
    - "Click 'Next'"
    - "Wait for redirect back to the application"
  
  success_condition:
    type: url_contains
    value: "/dashboard"

SSO with 2FAIf your SSO provider uses 2FA, add totp_secret to credentials and include the TOTP step in your login flow:

login_flow:
  - "Click 'Sign in with Google'"
  - "Type $username into the email field"
  - "Click 'Next'"
  - "Type $password into the password field"
  - "Click 'Next'"
  - "Enter $totp in the verification code field"  # 2FA step
  - "Click 'Verify'"

API Authentication

For applications using token-based authentication via API endpoints.

authentication:
  login_type: api
  login_url: "https://api.example.com/auth/login"
  credentials:
    username: "[email protected]"
    password: "testpassword"
  
  login_flow:
    - "Send POST request to $login_url with JSON body: {\"email\": \"$username\", \"password\": \"$password\"}"
    - "Extract the 'token' field from the response"
    - "Store the token for subsequent requests"
  
  success_condition:
    type: text_contains
    value: '"token"'

API Authentication SupportAPI authentication is supported but relies on the AI agent’s ability to construct and send HTTP requests. For complex API flows, form-based or SSO authentication may be more reliable.

Basic Authentication

For applications using HTTP Basic Auth.

authentication:
  login_type: basic
  login_url: "https://example.com/"
  credentials:
    username: "admin"
    password: "secretpassword"
  
  login_flow:
    - "Use HTTP Basic Authentication with username and password"
  
  success_condition:
    type: url_contains
    value: "/"

TOTP 2FA Setup

Shannon automatically generates time-based one-time passwords (TOTP) for two-factor authentication when you provide a totp_secret.

Getting Your TOTP Secret

The TOTP secret is the Base32-encoded shared secret used to generate 6-digit codes. Here’s how to find it:

Enable 2FA on Test Account

Set up two-factor authentication on your test account as you normally would.

Reveal the Secret Key

Most apps show a QR code and a “manual entry” or “secret key” option. Click to reveal the secret.Example secret: JBSWY3DPEHPK3PXP

Add to Config

Copy the secret and add it to your configuration:

credentials:
  username: "[email protected]"
  password: "testpassword"
  totp_secret: "JBSWY3DPEHPK3PXP"

Update Login Flow

Add TOTP step to your login flow:

login_flow:
  - "Type $username into the email field"
  - "Type $password into the password field"
  - "Click 'Sign In'"
  - "Enter $totp in the verification code field"
  - "Click 'Verify'"

TOTP Format

totp_secret

string

Base32-encoded TOTP secret (case insensitive)Valid characters: A-Z, 2-7, and = for paddingExample: JBSWY3DPEHPK3PXP

Common TOTP issues

Invalid secret format

ERROR: totp_secret must match pattern ^[A-Za-z2-7]+=*$

Ensure your secret only contains Base32 characters (A-Z, 2-7, =).Wrong code generated

Check that the secret is copied correctly (no spaces)
Verify system time is synchronized (TOTP is time-based)
Some apps use 8-digit codes instead of 6-digit (not currently supported)

Credentials Management

Security Best Practices

Use test accounts only - Never use production credentials
Limit permissions - Test accounts should have minimal privileges
Rotate regularly - Change test account passwords periodically
Secure config files - Add configs/*.yaml to .gitignore
Environment variables - For CI/CD, inject credentials at runtime

Environment Variable Substitution

Avoid hardcoding credentials by using environment variables:

authentication:
  credentials:
    username: "${TEST_USERNAME}"
    password: "${TEST_PASSWORD}"
    totp_secret: "${TEST_TOTP_SECRET}"

Set in your .env file:

TEST_USERNAME=[email protected]
TEST_PASSWORD=testpassword
TEST_TOTP_SECRET=JBSWY3DPEHPK3PXP

Provider Credentials

For AI provider authentication (Anthropic, AWS Bedrock, Google Vertex AI), configure in .env:

Anthropic API
Claude Code OAuth
AWS Bedrock
Google Vertex AI

.env

ANTHROPIC_API_KEY=your-api-key-here
CLAUDE_CODE_MAX_OUTPUT_TOKENS=64000

Get your API key from Anthropic Console.

.env

CLAUDE_CODE_OAUTH_TOKEN=your-oauth-token-here
CLAUDE_CODE_MAX_OUTPUT_TOKENS=64000

.env

CLAUDE_CODE_USE_BEDROCK=1
AWS_REGION=us-east-1
AWS_BEARER_TOKEN_BEDROCK=your-bearer-token

ANTHROPIC_SMALL_MODEL=us.anthropic.claude-haiku-4-5-20251001-v1:0
ANTHROPIC_MEDIUM_MODEL=us.anthropic.claude-sonnet-4-6
ANTHROPIC_LARGE_MODEL=us.anthropic.claude-opus-4-6

See Cloud Providers Guide for setup.

.env

CLAUDE_CODE_USE_VERTEX=1
CLOUD_ML_REGION=us-east5
ANTHROPIC_VERTEX_PROJECT_ID=your-gcp-project-id
GOOGLE_APPLICATION_CREDENTIALS=./credentials/gcp-sa-key.json

ANTHROPIC_SMALL_MODEL=claude-haiku-4-5@20251001
ANTHROPIC_MEDIUM_MODEL=claude-sonnet-4-6
ANTHROPIC_LARGE_MODEL=claude-opus-4-6

See Cloud Providers Guide for setup.

Testing Authentication

Verify your authentication configuration before running a full pentest:

Create Test Config

cp configs/example-config.yaml configs/test-auth.yaml
# Edit with your credentials and login flow

Run Pre-Recon Only

Shannon’s reconnaissance phase includes authentication testing:

./shannon start URL=https://example.com REPO=repo-name CONFIG=./configs/test-auth.yaml

Check Logs

Monitor logs for authentication success/failure:

./shannon logs ID=example-com_shannon-1234567890

Look for messages like:

✅ “Authentication successful”
❌ “Authentication failed: element not found”
❌ “Authentication timed out”

Troubleshooting

Authentication timeout

Cause: Login flow steps took too long or page didn’t load.Solutions:

Add explicit wait steps between actions
Increase timeouts in login flow instructions
Simplify login flow (remove unnecessary steps)
Check that URLs are correct

Element not found

Cause: Field or button selectors in login flow don’t match actual page elements.Solutions:

Use exact button text from the page
Be specific about field labels (“email field” not “first field”)
Verify login URL loads the correct page
Check for dynamic content that loads after page render

Success condition never met

Cause: Success condition doesn’t match post-login state.Solutions:

Verify URL/element/text after manual login
Try different condition types (url_contains vs element_present)
Check for redirects that change the final URL
Ensure success condition is unique to logged-in state

TOTP codes rejected

Cause: TOTP secret is incorrect or time synchronization issue.Solutions:

Verify secret is copied correctly (no spaces/newlines)
Check system time is accurate (TOTP requires sync)
Regenerate TOTP secret from app settings
Test secret with an authenticator app first

Configuration

Complete YAML configuration reference

Cloud Providers

AWS Bedrock and Google Vertex AI setup

Get Started

Core Concepts

Guides

CLI Reference

Authentication Methods

Form Login

SSO / OAuth

API Authentication

Basic Auth

Success Conditions

API Authentication

Basic Authentication

TOTP 2FA Setup

Getting Your TOTP Secret

TOTP Format

Credentials Management

Environment Variable Substitution

Provider Credentials

Testing Authentication

Troubleshooting

Configuration

Cloud Providers

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

CLI Reference

​Authentication Methods

Form Login

SSO / OAuth

API Authentication

Basic Auth

​Form Login

​Login Flow Instructions

​Success Conditions

​SSO / OAuth Login

​API Authentication

​Basic Authentication

​TOTP 2FA Setup

​Getting Your TOTP Secret

​TOTP Format

​Credentials Management

​Environment Variable Substitution

​Provider Credentials

​Testing Authentication

​Troubleshooting

​Related Resources

Configuration

Cloud Providers

Build docs developers (and LLMs) love

Authentication Methods

Form Login

Login Flow Instructions

Success Conditions

SSO / OAuth Login

API Authentication

Basic Authentication

TOTP 2FA Setup

Getting Your TOTP Secret

TOTP Format

Credentials Management

Environment Variable Substitution

Provider Credentials

Testing Authentication

Troubleshooting

Related Resources