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

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. 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:

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:

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 (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 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 (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:

# 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.
• Use the $totp placeholder in login flow instructions to trigger automatic code generation, processed by src/prompts/prompt-manager.ts.
• Runtime generation occurs via the generate_totp MCP tool in mcp-server/src/tools/generate-totp.ts, implementing RFC 6238 with strict Base-32 validation from 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 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 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 replaces $totp with a generic description while injecting the raw secret only into internal templates via {{totp_secret}} for code generation purposes.

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