Skip to main content
Shannon can run without a configuration file, but creating one enables authenticated testing, two-factor authentication support, and customized analysis scoping. Configuration files use YAML format and are validated against a JSON schema to ensure correctness.

​
When You Need Configuration

You should create a configuration file when:
  • Authenticated Testing: Your application requires login (form-based, SSO, API, or basic auth)
  • Two-Factor Authentication: Your application uses TOTP/2FA for login
  • Test Scoping: You want to define specific areas to focus on or avoid during testing
  • Rate Limit Management: You’re on an Anthropic subscription plan with rolling 5-hour rate limit windows
  • Concurrency Control: You want to reduce concurrent pipeline execution to manage API usage

​
Configuration File Location

Configuration files must be placed in the ./configs/ directory at the Shannon project root. This directory is automatically mounted into the Docker container. 
# Copy the example configuration
cp configs/example-config.yaml configs/my-app-config.yaml

# Edit your configuration
vim configs/my-app-config.yaml

# Run Shannon with your configuration
./shannon start URL=https://example.com REPO=repo-name CONFIG=./configs/my-app-config.yaml

​
Configuration Structure

A Shannon configuration file can contain three main sections:

​
Authentication Section

Defines how Shannon should authenticate with your application: 
authentication:
  login_type: form  # form, sso, api, or basic
  login_url: "https://example.com/login"
  credentials:
    username: "[email protected]"
    password: "testpassword"
    totp_secret: "LB2E2RX7XFHSTGCK"  # Optional for 2FA
  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"

​
Rules Section

Defines testing boundaries and priorities: 
rules:
  avoid:
    - description: "Do not test logout functionality"
      type: path
      url_path: "/logout"
  focus:
    - description: "Prioritize API testing"
      type: path
      url_path: "/api"

​
Pipeline Section

Controls retry behavior and concurrency: 
pipeline:
  retry_preset: subscription  # default or subscription
  max_concurrent_pipelines: 2  # 1-5, default: 5

​
Minimal Configuration

You can include only the sections you need. For example, a minimal authenticated testing configuration: 
authentication:
  login_type: form
  login_url: "https://example.com/login"
  credentials:
    username: "[email protected]"
    password: "testpassword"
  success_condition:
    type: url_contains
    value: "/dashboard"

​
Schema Validation

All configuration files are validated against configs/config-schema.json. If validation fails, Shannon will display detailed error messages indicating:
  • Missing required fields
  • Invalid types or values
  • Malformed patterns
  • Security violations
The schema enforces:
  • Maximum file size of 1MB
  • Safe YAML parsing (no code execution)
  • Security checks for dangerous patterns
  • Type validation for all fields
  • Conflict detection between rules

​
Next Steps

Authentication

Configure login, credentials, and 2FA

YAML Config Reference

Complete configuration options reference

Retry Strategies

Handle rate limits and subscription plans

Pipeline Settings

Control concurrency and testing mode

Build docs developers (and LLMs) love

Get started for freeTalk to us