How Shannon Handles Authentication Flows for Form-Based Login, SSO, and API Authentication

Shannon treats authentication as a first-class configuration element, using a declarative YAML block and modular prompt templates to automatically generate Playwright MCP commands for form-based, SSO, or API authentication flows.

The KeygraphHQ/shannon repository implements a pipeline-driven penetration testing framework where authentication is woven into every phase of the assessment. Rather than hardcoding login logic, Shannon uses a template-based interpolation system that converts high-level YAML configurations into concrete browser automation steps or API calls.

Authentication Configuration in Shannon

Defining Login Types and Credentials

Shannon accepts authentication parameters through a dedicated authentication block in the user-supplied YAML configuration file. The system supports four distinct login types defined in src/types/config.ts: form, sso, api, and basic.

authentication:
  login_type: form
  login_url: https://app.example.com/login
  credentials:
    username: alice
    password: s3cr3t!
    totp_secret: JBSWY3DPEHPK3PXP
  login_flow:
    - "await page.type('#email', $username)"
    - "await page.type('#pass', $password)"
    - "await page.click('button[type=submit]')"
    - "await page.waitForNavigation()"
  success_condition:
    type: url_contains
    value: /dashboard

The YAML parser in src/config-parser.ts (line 344) normalizes the login_type value to lowercase to ensure consistent matching against the template sections.

The Authentication Schema

The TypeScript interfaces in src/types/config.ts enforce the structure of the authentication object. This schema validation ensures that required fields like login_url and credentials are present while making totp_secret and custom login_flow steps optional.

How Shannon Builds Login Instructions

Template Processing with buildLoginInstructions()

When a phase-specific prompt is loaded, the prompt-manager in src/prompts/prompt-manager.ts invokes the buildLoginInstructions() function (lines 24-92) to construct the authentication guidance. This process follows a strict pipeline:

1. Load the base template from prompts/shared/login-instructions.txt
2. Extract marked sections using <!-- BEGIN:FORM -->, <!-- BEGIN:SSO -->, and <!-- BEGIN:API --> delimiters
3. Select the appropriate section based on authentication.login_type?.toUpperCase()
4. Insert the custom login flow by joining the login_flow array with newlines
5. Substitute credential placeholders ($username, $password, $totp) with actual values from the credentials object

Placeholder Substitution and TOTP Handling

The template system performs variable interpolation to convert abstract instructions into concrete values. When a totp_secret is provided, the manager injects instructions to call the generate_totp MCP tool using the provided secret. This allows Shannon to handle time-based one-time passwords (TOTP) automatically during the authentication sequence.

Executing Authentication Flows

Form-Based Login Implementation

For form type authentication, Shannon generates Playwright MCP commands that execute the steps defined in the login_flow array. The claude-executor in src/ai/claude-executor.ts and the output formatter in src/utils/output-formatter.ts dispatch these calls to the Playwright agents defined in src/constants.ts (playwright-agent1 through playwright-agent5).

The generated commands follow this pattern:

mcp__playwright__browser_navigate {"url":"https://app.example.com/login"}
mcp__playwright__browser_type {"selector":"#email","text":"alice"}
mcp__playwright__browser_type {"selector":"#pass","text":"s3cr3t!"}
mcp__playwright__browser_click {"selector":"button[type=submit]"}
mcp__playwright__browser_wait_for {"event":"load"}

SSO and API Authentication Patterns

For SSO flows, the login-instructions.txt template contains specialized guidance for navigating third-party identity providers. The same substitution pipeline applies, allowing users to define custom steps for handling OAuth redirects or SAML assertions.

For API authentication, Shannon does not generate browser automation steps. Instead, the API section of the template (which users can customize) supports direct HTTP calls. The configuration accepts a login_url that points to an API endpoint, and the login_flow can contain instructions for POSTing JSON payloads with substituted credentials.

Verification and Error Handling

After executing the login sequence, Shannon validates the session against the success_condition defined in the configuration. The VERIFICATION section in login-instructions.txt supports multiple verification types:

• URL contains: Checks if the current URL contains a specific path
• Element exists: Verifies the presence of a dashboard element
• Cookie present: Validates session cookies

If verification fails, the system retries the authentication once, logs the failure details, and aborts the task to prevent unauthenticated scanning. This ensures that downstream agents in src/phases/pre-recon.ts (lines 87-98) only operate with validated sessions.

Summary

• Shannon implements authentication as a declarative YAML configuration with support for form-based, SSO, API, and basic authentication types.
• The buildLoginInstructions() function in src/prompts/prompt-manager.ts processes templates from prompts/shared/login-instructions.txt to generate context-specific login guidance.
• Placeholder substitution converts $username, $password, and $totp variables into actual credentials, with automatic TOTP generation support.
• Playwright MCP agents execute the generated browser automation steps, while API authentication uses customizable HTTP request templates.
• Success conditions and retry logic ensure that only validated sessions proceed to downstream penetration testing phases.

Frequently Asked Questions

How does Shannon handle TOTP and multi-factor authentication in login flows?

Shannon supports TOTP through the totp_secret field in the authentication credentials. When provided, the buildLoginInstructions() function injects instructions to call the generate_totp MCP tool using the provided secret. The generated code is then substituted into the $totp placeholder within the login flow steps, allowing Shannon to automatically handle time-based one-time passwords during form-based authentication.

Can Shannon authenticate against REST APIs instead of browser-based forms?

Yes, Shannon supports API authentication through the login_type: api configuration option. While the stock template in prompts/shared/login-instructions.txt provides a placeholder for API flows, users can extend the template with a custom <!-- BEGIN:API --> block to define direct HTTP POST requests to authentication endpoints. The same substitution pipeline applies credentials to JSON payloads, making it possible to authenticate against REST APIs without browser automation.

What happens if the authentication flow fails during a pentest?

Shannon implements verification and retry logic to handle authentication failures. After executing the login steps, the system checks the success_condition (such as URL containment or element presence) defined in the configuration. If verification fails, Shannon retries the authentication once, logs the failure details, and aborts the task to prevent unauthenticated scanning. This ensures downstream agents only operate with validated sessions.

Where are authentication credentials stored and how are they secured?

Authentication credentials are supplied through the user-provided YAML configuration file and parsed by src/config-parser.ts. The credentials exist in memory during the prompt interpolation phase in src/prompts/prompt-manager.ts, where they are substituted into templates before being sent to the AI executor. Users should follow standard security practices by restricting file permissions on configuration files, avoiding committed secrets in version control, and using environment variable substitution where supported by the YAML parser.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}