Configuration

Shannon can run without a configuration file, but configuration enables authenticated testing, scope guidance, rules of engagement, optional security code analysis, report filtering, and SARIF output.

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

npx mode resolves credentials from:

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

Source-build mode resolves credentials from:

Environment variables, such as export ANTHROPIC_API_KEY=...
./.env

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

Create a configuration file

Copy and modify the example configuration:

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

Run with the -c flag:

npx (recommended)
Build from source

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

./shannon start -u https://example.com -r /path/to/repo -c ./my-app-config.yaml

Basic configuration structure

# Describe your target environment.
description: "Next.js e-commerce app on PostgreSQL. Local dev environment; .env files contain local-only credentials."

# Every scan runs all five vulnerability classes.

# Security code analysis (opt-in). `enabled` is its only setting.
# agentic_sast:
#   enabled: "true"

# 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"

# Report options applied when assembling the final report.
# report:
#   min_severity: low
#   min_confidence: low
#   guidance: |
#     Drop findings about missing security headers and rate-limit gaps.
#   sarif: "false"

Security code analysis

Every scan runs all five analysis classes: Injection, Cross-Site Scripting, Authentication, Authorization, and Server-Side Request Forgery. The class set is fixed and has no configuration selector.

Security code analysis is opt-in, through the agentic_sast block:

agentic_sast:
  enabled: "true"

enabled is the only setting. Omitting the block, or setting enabled: "false", turns it off. Either way, all five vulnerability classes still run.

It reads the repository for vulnerabilities before the pentest and passes what it finds into the exploitation phase, where it is reconciled with the pentest’s own candidates. A code-analysis candidate is never reported on its own: like every other candidate, an exploitation agent must demonstrate it first. It adds model time and cost. If it fails, the pentest continues without its findings and the scan finishes as partial.

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

The optional report block controls the final report. min_severity drops findings below a severity in every run. min_confidence applies only to analysis-only runs (exploit: "false"), because exploited findings are already proven. guidance tells the report agent which topics to drop. sarif writes a SARIF 2.1.0 log (report.sarif) next to the PDF report. It is on by default for exploit runs; set sarif: "false" to opt out.

Every finding carries a severity, but it means something different in each mode. An exploitative run measures severity from what the exploit demonstrated. An analysis-only run assesses it from the class of flaw and the impact it would have, and adds a confidence rating, since nothing was proven. Setting min_confidence on an exploitative run is ignored, and Shannon logs a warning naming the threshold to use instead.

SARIF output

Each finding becomes one SARIF result, filed under a rule per vulnerability class (shannon/injection, shannon/xss, shannon/auth, shannon/authz, shannon/ssrf, and shannon/miscellaneous for findings outside those classes) and tagged with its OWASP Top Ten 2025 category. Results are anchored to the code location the analysis phase recorded, falling back to the HTTP entry point when the finding names no file. Severity maps onto SARIF’s three levels: critical and high become error, medium becomes warning, and everything else becomes note.

The log is written only for exploitative runs, and sarif is ignored when exploit is "false". If the SARIF log cannot be written, the JSON and Markdown reports are still produced and the scan finishes as partial.

Subscription plans

Shannon can run on a ChatGPT Plus or Pro (Codex) subscription or an xAI (Grok) subscription with SHANNON_USE_PI_AUTH=1. Claude Code subscriptions are supported only on version 1.9.0. See AI Providers.