Skip to main content
Shannon uses YAML configuration files to customize penetration testing behavior, authentication settings, and pipeline execution. Configuration files are placed in the ./configs/ directory.

​
Quick Start

Copy the example configuration and modify it for your application: 
cp configs/example-config.yaml 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 File Structure

Configuration files support three main sections: 
authentication:
  # Login and credential settings
  login_type: form
  login_url: "https://example.com/login"
  credentials:
    username: "[email protected]"
    password: "yourpassword"
  login_flow:
    - "Type $username into the email field"
    - "Click the 'Sign In' button"
  success_condition:
    type: url_contains
    value: "/dashboard"

rules:
  # Testing behavior customization
  avoid:
    - description: "Skip logout functionality"
      type: path
      url_path: "/logout"
  focus:
    - description: "Prioritize API endpoints"
      type: path
      url_path: "/api"

pipeline:
  # Execution settings for rate limits
  retry_preset: subscription
  max_concurrent_pipelines: 2

​
Authentication Section

Configure how Shannon authenticates to your application. See the Authentication Guide for detailed examples.
​
authentication.login_type
string
required
Type of authentication mechanismOptions:
  • form - Standard login form
  • sso - Single sign-on (Google, OAuth)
  • api - API token authentication
  • basic - HTTP Basic Auth
​
authentication.login_url
string
required
URL for the login page or endpoint
login_url: "https://example.com/login"
​
authentication.credentials
object
required
Login credentials for the test account
​
authentication.login_flow
array
required
Step-by-step natural language instructions for login (1-20 steps)Use $username, $password, and $totp variables:
login_flow:
  - "Type $username into the email field"
  - "Type $password into the password field"
  - "Click the 'Sign In' button"
​
authentication.success_condition
object
required
Condition that indicates successful authentication

​
Rules Section

Define testing behavior with avoid and focus rules to control where Shannon tests.
​
rules.avoid
array
Areas to skip during testing (max 50 rules)
avoid:
  - description: "Skip logout functionality"
    type: path
    url_path: "/logout"
  
  - description: "No DELETE operations on user API"
    type: path
    url_path: "/api/v1/users/*"
​
rules.focus
array
Areas to prioritize during testing (max 50 rules)
focus:
  - description: "Prioritize API endpoints"
    type: path
    url_path: "/api"
  
  - description: "Focus on beta admin panel"
    type: subdomain
    url_path: "beta-admin"

​
Rule Properties

Each rule in avoid or focus arrays has these properties:
​
description
string
required
Human-readable description (1-200 characters)
​
type
string
required
Rule matching typeOptions:
  • path - Match URL path patterns
  • subdomain - Match subdomains
  • domain - Match domains
  • method - Match HTTP methods
  • header - Match HTTP headers
  • parameter - Match query/body parameters
​
url_path
string
required
Pattern or value to match (1-1000 characters)Supports wildcards with *:
url_path: "/api/v1/users/*"

​
Pipeline Section

Control retry behavior and concurrency for rate limit management.
​
pipeline.retry_preset
string
Retry strategy presetOptions:
  • default - Standard retry (30min max backoff)
  • subscription - Extended retry for Anthropic subscription plans (6h max backoff, 100 retries)
pipeline:
  retry_preset: subscription
​
pipeline.max_concurrent_pipelines
string
Number of vulnerability pipelines to run simultaneously (1-5, default: 5)Lower values reduce API usage spikes but increase total runtime:
pipeline:
  max_concurrent_pipelines: 2
Subscription Plan Rate LimitsAnthropic subscription plans reset usage on a rolling 5-hour window. If you hit rate limits, use:
pipeline:
  retry_preset: subscription          # Extends max backoff to 6h
  max_concurrent_pipelines: 2         # Reduces burst API usage
This configuration allows Shannon to wait for the rate limit window to reset automatically.

​
Schema Validation

All configuration files are validated against the JSON schema at configs/config-schema.json. Invalid configurations will fail with detailed error messages during startup.

​
Common Validation Errors

ERROR: Configuration validation failed
- authentication.credentials is required
Ensure all required fields are present in your configuration.
ERROR: authentication.login_type must be one of: form, sso, api, basic
Check that enum values match exactly (case-sensitive).
ERROR: authentication.credentials.username must be 1-255 characters
Verify that all string fields meet length requirements.

​
Environment Variables

Some settings are configured via environment variables in .env rather than YAML. See:

Authentication

Setup login flows and 2FA

Cloud Providers

AWS Bedrock and Google Vertex AI

Build docs developers (and LLMs) love

Get started for freeTalk to us