Skip to content
Enterprise Pricing Contact
Schedule a Technical Demo

Configuration

Shannon can run without a configuration file, but configuration enables authenticated testing, scope guidance, rules of engagement, report filtering, and rate-limit tuning.

For the full field-by-field reference, see the Configuration Schema. For login flows specifically, see Authenticated Testing.

Credential precedence

Section titled “Credential precedence”

npx mode resolves credentials from:

  1. Environment variables
  2. ~/.shannon/config.toml, created by npx @keygraph/shannon setup

Environment variables always win, so you can override saved config for a single session without editing files.

Create a configuration file

Section titled “Create a configuration file”

Copy and modify the example configuration:

Terminal window
cp configs/example-config.yaml ./my-app-config.yaml

Run with the -c flag:

Terminal window
npx @keygraph/shannon start -u https://example.com -r /path/to/repo -c ./my-app-config.yaml

Basic configuration structure

Section titled “Basic configuration structure”
# Describe your target environment.
description: "Next.js e-commerce app on PostgreSQL. Local dev environment; .env files contain local-only credentials."


# Limit which vulnerability classes run end-to-end.
# vuln_classes: [injection, xss, auth, authz, ssrf]


# Skip the exploitation phase.
# exploit: "false"


# Free-form rules of engagement.
# rules_of_engagement: |
#   - No password brute-force; cap login attempts at 5 per account.
#   - Throttle to under 5 requests per second per endpoint; back off 60s on any 429.
#   - Use placeholders like [order_id] in deliverables; no real data values.


authentication:
  login_type: form
  login_url: "https://your-app.com/login"
  credentials:
    username: "test@example.com"
    password: "yourpassword"
    totp_secret: "LB2E2RX7XFHSTGCK"


    # Optional mailbox credentials for magic-link or email-OTP flows.
    # email_login:
    #   address: "inbox@example.com"
    #   password: "mailbox-password"
    #   totp_secret: "JBSWY3DPEHPK3PXP"


  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:
  avoid:
    - description: "AI should avoid testing logout functionality"
      type: url_path
      value: "/logout"


    # code_path values are repo-relative file paths or globs.
    # - description: "Out-of-scope vendored libraries"
    #   type: code_path
    #   value: "src/vendor/**"


  focus:
    - description: "AI should emphasize testing API endpoints"
      type: url_path
      value: "/api"


# Filters applied by the report agent when assembling the final report.
# report:
#   min_severity: low
#   min_confidence: low
#   guidance: |
#     Drop findings about missing security headers and rate-limit gaps.

Scope rules

Section titled “Scope rules”

The rules block guides where Shannon spends effort. avoid rules keep Shannon away from paths or code, and focus rules emphasize areas you care about.

Supported rule types include url_path, subdomain, domain, method, header, parameter, and code_path. code_path values are repo-relative file paths or globs.

Report filters

Section titled “Report filters”

The optional report block controls what the report agent includes when assembling the final report. Set min_severity and min_confidence thresholds, and use guidance to describe categories of findings to drop.

Adaptive thinking

Section titled “Adaptive thinking”

Claude decides when and how deeply to reason on Opus 4.6, 4.7, and 4.8. This is enabled by default whenever a tier resolves to one of these models.

npx @keygraph/shannon setup prompts you during the wizard.

Subscription plan rate limits

Section titled “Subscription plan rate limits”

Anthropic subscription plans reset usage on a rolling 5-hour window. The default retry strategy may exhaust retries before the window resets. Add this to your config:

pipeline:
  retry_preset: subscription
  max_concurrent_pipelines: 2

max_concurrent_pipelines controls how many vulnerability pipelines run simultaneously. Supported values are 1 to 5, with a default of 5. Lower values reduce burst API usage but increase wall-clock time.