# How to Configure TOTP/2FA Authentication for Testing Applications in Shannon

> Configure TOTP 2FA for testing applications in Shannon. Easily set up two-factor authentication with base-32 secrets and automated code generation for browser automation.

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

---

**Shannon enables automated testing of two-factor authentication by accepting a Base-32 TOTP secret in YAML configuration and automatically generating time-based verification codes during browser automation flows.**

Shannon (KeygraphHQ/shannon) is an open-source penetration testing framework that automates web application authentication workflows. When testing applications protected by TOTP/2FA authentication, Shannon eliminates manual code entry by deriving fresh 6-digit codes from a pre-configured secret, allowing seamless automated login sequences.

## Understanding Shannon's TOTP Configuration Schema

Shannon validates all authentication parameters against a strict JSON Schema defined in **[`configs/config-schema.json`](https://github.com/KeygraphHQ/shannon/blob/main/configs/config-schema.json)**. The schema explicitly defines the `totp_secret` field as a string property within the `authentication.credentials` object, ensuring type safety during configuration parsing.

According to the schema definition at lines 38-42, the `totp_secret` accepts a Base-32 encoded string representing the shared secret typically displayed as a QR code during 2FA enrollment. This secret remains static while Shannon generates dynamic codes from it at runtime.

## Step-by-Step TOTP Setup

### 1. Add the TOTP Secret to Your Configuration

Locate the Base-32 secret provided by your application’s 2FA setup (often shown as "Manual entry" text alongside the QR code). Add this to your Shannon configuration file under `authentication.credentials`:

```yaml
authentication:
  credentials:
    username: "testuser@example.com"
    password: "SecurePass123!"
    totp_secret: "JBSWY3DPEHPK3PXP"  # Base-32 encoded secret

```

Shannon validates this secret immediately upon loading the configuration, ensuring it contains only valid Base-32 characters (A-Z, 2-7) before any browser automation begins.

### 2. Reference the TOTP Code in Login Flows

Shannon uses placeholder substitution to inject TOTP codes into browser automation instructions. In your `login_flow` array, reference the generated code using the **`$totp`** placeholder:

```yaml
authentication:
  login_flow:
    - "Type $username into the email input field"
    - "Type $password into the password field"
    - "Click the 'Sign In' button"
    - "Wait for the 2FA code input field to appear"
    - "Type $totp into the verification code field"
    - "Click the 'Verify' button"

```

During execution, **[`src/prompts/prompt-manager.ts`](https://github.com/KeygraphHQ/shannon/blob/main/src/prompts/prompt-manager.ts)** (lines 71-88) handles the replacement logic. The `$totp` placeholder expands to a human-readable description in natural language prompts, while the raw secret remains available for code generation via the internal template system using `{{totp_secret}}`.

## How Shannon Generates TOTP Codes at Runtime

When the browser automation reaches the 2FA verification step, Shannon invokes the **`generate_totp`** MCP (Model Context Protocol) tool to produce a fresh 6-digit code synchronized with the current time.

### TOTP Generation Process

The generation workflow implemented in **[`mcp-server/src/tools/generate-totp.ts`](https://github.com/KeygraphHQ/shannon/blob/main/mcp-server/src/tools/generate-totp.ts)** follows these steps:

1. **Input Validation**: The tool validates that the provided secret conforms to Base-32 encoding standards (lines 25-31). Invalid characters or malformed strings trigger immediate errors before cryptographic operations begin.

2. **RFC 6238 Algorithm Execution**: The core `generateTOTP` function (lines 68-72) implements the standard time-based one-time password algorithm:
   - Calculates the current time step (30-second intervals)
   - Generates an HMAC-SHA1 hash of the secret and time step
   - Truncates the result to a 6-digit decimal code

3. **Result Delivery**: The tool returns a structured response (lines 85-98) containing:
   - `totpCode`: The 6-digit verification code
   - `timestamp`: ISO 8601 generation time
   - `expiresIn`: Seconds remaining until code expiration

### Secret Validation Safety Checks

Before any TOTP generation occurs, **[`mcp-server/src/validation/totp-validator.ts`](https://github.com/KeygraphHQ/shannon/blob/main/mcp-server/src/validation/totp-validator.ts)** (lines 48-73) performs rigorous validation:

- **Character Set Verification**: Ensures the secret contains only valid Base-32 characters (A-Z, 2-7)
- **Length Validation**: Verifies the decoded secret meets minimum length requirements
- **Decoding Test**: Attempts actual Base-32 decoding to catch padding errors or corruption

Invalid secrets raise descriptive errors that abort the authentication flow immediately, preventing wasted automation cycles on impossible configurations.

## Complete Configuration Example

Here is a production-ready configuration demonstrating TOTP/2FA authentication for testing applications with Shannon:

```yaml

# Shannon configuration for 2FA-enabled application testing

target:
  name: "SecureApp Production"
  base_url: "https://app.secureexample.com"

authentication:
  login_type: form
  login_url: "https://app.secureexample.com/login"
  
  credentials:
    username: "pentest@example.com"
    password: "{{ env.VAULT_PASSWORD }}"  # Injected from environment

    totp_secret: "JBSWY3DPEHPK3PXP"      # Base-32 secret from 2FA setup

  
  login_flow:
    - "Navigate to $login_url"
    - "Type $username into the username input field"
    - "Type $password into the password input field"
    - "Click the 'Login' button"
    - "Wait for the TOTP input field to be visible"
    - "Type $totp into the 'Authentication Code' field"
    - "Click the 'Verify' button"
  
  success_condition:
    type: url_contains
    value: "/dashboard"

scanning:
  depth: standard
  max_duration: 3600

```

This configuration leverages the `$totp` placeholder to trigger automatic code generation while keeping the actual `totp_secret` secure in the credentials object.

## Summary

- **Shannon supports automated TOTP/2FA authentication** through YAML configuration, eliminating manual code entry during penetration testing workflows.
- **Configuration requires a Base-32 encoded `totp_secret`** added to `authentication.credentials`, validated against the schema in [`configs/config-schema.json`](https://github.com/KeygraphHQ/shannon/blob/main/configs/config-schema.json).
- **Use the `$totp` placeholder** in login flow instructions to trigger automatic code generation, processed by [`src/prompts/prompt-manager.ts`](https://github.com/KeygraphHQ/shannon/blob/main/src/prompts/prompt-manager.ts).
- **Runtime generation** occurs via the `generate_totp` MCP tool in [`mcp-server/src/tools/generate-totp.ts`](https://github.com/KeygraphHQ/shannon/blob/main/mcp-server/src/tools/generate-totp.ts), implementing RFC 6238 with strict Base-32 validation from [`mcp-server/src/validation/totp-validator.ts`](https://github.com/KeygraphHQ/shannon/blob/main/mcp-server/src/validation/totp-validator.ts).
- **Security safeguards** include immediate validation of secret format and character set before any cryptographic operations execute.

## Frequently Asked Questions

### What TOTP algorithms does Shannon support?

Shannon implements the standard **RFC 6238** TOTP algorithm using HMAC-SHA1 with a 30-second time step, compatible with Google Authenticator, Authy, and other standard authenticator applications. The implementation in [`mcp-server/src/tools/generate-totp.ts`](https://github.com/KeygraphHQ/shannon/blob/main/mcp-server/src/tools/generate-totp.ts) generates 6-digit codes by default, matching the de facto standard for most web applications.

### How does Shannon handle invalid TOTP secrets?

Shannon validates TOTP secrets before attempting code generation. The validator in [`mcp-server/src/validation/totp-validator.ts`](https://github.com/KeygraphHQ/shannon/blob/main/mcp-server/src/validation/totp-validator.ts) checks that the secret contains only valid Base-32 characters (A-Z and 2-7), verifies proper length, and attempts actual decoding to catch padding errors. If validation fails, Shannon raises an immediate error that halts the authentication flow, preventing wasted automation cycles on malformed configurations.

### Can I use Shannon with multiple 2FA methods simultaneously?

Currently, Shannon supports one TOTP secret per authentication configuration. If your application supports multiple 2FA methods (SMS, TOTP, hardware keys), configure Shannon to use the TOTP method by providing the `totp_secret` in `authentication.credentials`. The `$totp` placeholder in your login flow will then trigger automatic code generation for that specific TOTP method during the browser automation sequence.

### Where is the TOTP secret stored during test execution?

The TOTP secret resides in the `authentication.credentials.totp_secret` field of your YAML configuration file. Shannon processes this secret in memory during execution, using it to generate time-based codes via the MCP tool mechanism. The secret is never echoed in natural language prompts—[`src/prompts/prompt-manager.ts`](https://github.com/KeygraphHQ/shannon/blob/main/src/prompts/prompt-manager.ts) replaces `$totp` with a generic description while injecting the raw secret only into internal templates via `{{totp_secret}}` for code generation purposes.