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

> Explore how Shannon simplifies authentication flows for form-based login, SSO, and API authentication using declarative YAML and modular prompt templates for automated Playwright commands.

- Repository: [KeygraphHQ/shannon](https://github.com/keygraphhq/shannon)
- Tags: deep-dive
- Published: 2026-02-16

---

**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`](https://github.com/KeygraphHQ/shannon/blob/main/src/types/config.ts): `form`, `sso`, `api`, and `basic`.

```yaml
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`](https://github.com/KeygraphHQ/shannon/blob/main/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`](https://github.com/KeygraphHQ/shannon/blob/main/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`](https://github.com/KeygraphHQ/shannon/blob/main/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`](https://github.com/KeygraphHQ/shannon/blob/main/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`](https://github.com/KeygraphHQ/shannon/blob/main/src/ai/claude-executor.ts) and the output formatter in [`src/utils/output-formatter.ts`](https://github.com/KeygraphHQ/shannon/blob/main/src/utils/output-formatter.ts) dispatch these calls to the Playwright agents defined in [`src/constants.ts`](https://github.com/KeygraphHQ/shannon/blob/main/src/constants.ts) (`playwright-agent1` through `playwright-agent5`).

The generated commands follow this pattern:

```typescript
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`](https://github.com/KeygraphHQ/shannon/blob/main/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`](https://github.com/KeygraphHQ/shannon/blob/main/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`](https://github.com/KeygraphHQ/shannon/blob/main/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`](https://github.com/KeygraphHQ/shannon/blob/main/src/prompts/prompt-manager.ts) processes templates from [`prompts/shared/login-instructions.txt`](https://github.com/KeygraphHQ/shannon/blob/main/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`](https://github.com/KeygraphHQ/shannon/blob/main/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`](https://github.com/KeygraphHQ/shannon/blob/main/src/config-parser.ts). The credentials exist in memory during the prompt interpolation phase in [`src/prompts/prompt-manager.ts`](https://github.com/KeygraphHQ/shannon/blob/main/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.