This is the abridged developer documentation for Shannon # Overview > Install, configure, and run Shannon, Keygraph's open-source AI pentester, and see how it relates to the Keygraph platform. Shannon is Keygraph’s open-source AI pentester for web applications and APIs (AGPL-3.0). It reads your source code, runs real exploits against the running app, and reports only the findings it can prove. Keygraph’s commercial editions, Keygraph Pro and Keygraph Enterprise, are powered by an enhanced, enterprise-grade version of the Shannon engine. Authorized use only Shannon actively executes exploits. Run it only against applications you own or have explicit written authorization to test, and never against production systems. See [Safety and limitations](/docs/explanations/safety/). ## Start here [Section titled “Start here”](#start-here) * **[Quick Start](/docs/tutorials/quick-start/)**: run your first pentest with `npx @keygraph/shannon` or a build from source, then open the report. * **[AI providers](/docs/how-to/ai-providers/)**: set `SHANNON_AI_MODEL` and bring your own key for Anthropic, OpenAI, xAI, AWS Bedrock, a gateway, or a local model. * **[CLI commands](/docs/reference/cli/)**: `start`, `scans`, `logs`, `status`, and every `start` flag. ## Tutorials [Section titled “Tutorials”](#tutorials) Learning-oriented lessons that take you from zero to a working result. [All tutorials](/docs/tutorials/). * **[Quick Start](/docs/tutorials/quick-start/)**: install, run, and read your first proof-of-exploit report. * **[Run Shannon in CI](/docs/how-to/ci-cd/)**: the official GitHub Action and GitLab CI/CD component run pull-request, release, and scheduled pentests. ## How-to guides [Section titled “How-to guides”](#how-to-guides) Task-oriented recipes for people who know the basics. [All how-to guides](/docs/how-to/). * **[Build from source and CLI](/docs/how-to/source-build/)**: run Shannon from a local clone. * **[Configuration](/docs/how-to/configuration/)**: scope a scan, set rules of engagement, and filter the report. * **[Authenticated testing](/docs/how-to/authenticated-testing/)**: describe a login flow so Shannon can test behind authentication. * **[AI providers](/docs/how-to/ai-providers/)**: providers, models, gateways, and local models. * **[Platforms and networking](/docs/how-to/platforms/)**: Windows, Linux, and macOS, and reaching a local target. * **[Workspaces and resuming](/docs/how-to/workspaces/)**: resume an interrupted run without repeating completed work. * **[CI/CD integrations](/docs/how-to/ci-cd/)**: the GitHub Action and GitLab component, requirements, and severity gates. ## Reference [Section titled “Reference”](#reference) Exact facts for lookup. [All reference](/docs/reference/). * **[CLI commands](/docs/reference/cli/)**: commands, `start` flags, and monitoring. * **[Environment variables](/docs/reference/environment-variables/)**: every variable Shannon reads. * **[Configuration schema](/docs/reference/configuration-schema/)**: the config file field by field. ## Explanations [Section titled “Explanations”](#explanations) Background on how Shannon works and why. [All explanations](/docs/explanations/). * **[Introduction](/docs/explanations/introduction/)**: what Shannon is and how a scan runs. * **[Editions](/docs/explanations/editions/)**: Shannon Open Source compared with the Keygraph platform. * **[Keygraph platform](/docs/explanations/keygraph-platform/)**: the commercial platform for continuous pentesting. * **[Coverage](/docs/explanations/coverage-roadmap/)**: what Shannon tests today. * **[Safety and limitations](/docs/explanations/safety/)**: authorized use, side effects, and cost. * **[Community and support](/docs/explanations/community/)**: license, Discord, and reporting issues. * **[FAQ](/docs/explanations/faq/)**: common questions about self-hosting, BYOK, SARIF, and local models. ## For AI agents [Section titled “For AI agents”](#for-ai-agents) These docs are also published as plain Markdown: [llms.txt](/docs/llms.txt) (index), [llms-full.txt](/docs/llms-full.txt) (every page), and [llms-small.txt](/docs/llms-small.txt) (condensed). The Keygraph site overview is at [keygraph.io/llms.txt](https://keygraph.io/llms.txt). # Shannon Explanations > Understanding-oriented background on how Keygraph works and why. Explanations are **understanding-oriented**: they illuminate concepts, architecture, and the reasoning behind design choices. They give context, not steps. To actually do something, see [How-to guides](/docs/how-to/) or [Tutorials](/docs/tutorials/). ## Available explanations [Section titled “Available explanations”](#available-explanations) * **[Introduction](/docs/explanations/introduction/)**: what Shannon is, why it exists, and how a scan works, stage by stage. * **[Editions](/docs/explanations/editions/)**: how Shannon Open Source compares to the commercial Keygraph platform. * **[Safety and limitations](/docs/explanations/safety/)**: authorized-use requirements, mutative effects, cost, and model caveats. * **[Coverage](/docs/explanations/coverage-roadmap/)**: current vulnerability coverage, the proof-by-exploitation philosophy, and the OWASP WSTG matrix. * **[Keygraph platform](/docs/explanations/keygraph-platform/)**: the continuous pentesting platform that runs an enhanced build of Shannon. * **[Community and support](/docs/explanations/community/)**: license, office hours, Discord, acknowledgements, and where to report issues. * **[FAQ](/docs/explanations/faq/)**: self-hosting, BYOK, SARIF, providers, local models, scan duration, and resuming. ## Coming soon [Section titled “Coming soon”](#coming-soon) * **How Keygraph proves exploitability**: the shape of the work, from hypothesis to attack to artifact to verdict. * **The Code Property Graph**: how source-aware analysis maps your application. * **Whitebox vs. blackbox**: code-aware exploitation vs. zero-code-access pentesting. * **The verdict layer**: adjudicating exploitable vs. confirmed non-exploitable. * **Architecture and data handling**: in-perimeter, stateless, bring-your-own-keys, read-only by default. # Community & Support > License, community office hours, Discord, acknowledgements, and where to report issues. ## License [Section titled “License”](#license) Shannon Open Source is licensed under the [GNU Affero General Public License v3.0](https://github.com/KeygraphHQ/shannon/blob/main/LICENSE). Commercial and enterprise licensing is available for organizations that need different license terms, commercial support, private redistribution, managed-service use, or broader deployment options. This includes the [Keygraph platform](/docs/explanations/keygraph-platform/). For commercial licensing, contact . ## Community office hours [Section titled “Community office hours”](#community-office-hours) Community office hours are available for hands-on help with bugs, deployments, and configuration questions. * **US/EU:** Thursday, 10:00 AM PT * **Asia:** Thursday, 2:00 PM IST * [Book a slot](https://cal.com/george-flores-keygraph/shannon-community-office-hours) ## Discord [Section titled “Discord”](#discord) [Join Discord](https://discord.gg/keygraph-community) to ask questions, share feedback, and connect with other Shannon users. ## Issues and feature requests [Section titled “Issues and feature requests”](#issues-and-feature-requests) At this time, Keygraph is not accepting external code contributions. Issues are welcome for bug reports and feature requests: * [Report bugs](https://github.com/KeygraphHQ/shannon/issues) * [Suggest features](https://github.com/KeygraphHQ/shannon/discussions) ## Stay connected [Section titled “Stay connected”](#stay-connected) * [Keygraph website](https://keygraph.io) * [Twitter/X: @KeygraphHQ](https://twitter.com/KeygraphHQ) * [LinkedIn: Keygraph](https://linkedin.com/company/keygraph) ## Acknowledgements [Section titled “Acknowledgements”](#acknowledgements) Shannon builds on [Pi](https://github.com/earendil-works/pi), the open-source agent harness that runs its agents, [Playwright CLI](https://github.com/microsoft/playwright-cli), and [Mantis](https://github.com/google/mantis). Thanks to their maintainers. See [THIRD\_PARTY\_NOTICES.md](https://github.com/KeygraphHQ/shannon/blob/main/THIRD_PARTY_NOTICES.md) for licensing and attribution details. ## For AI agents [Section titled “For AI agents”](#for-ai-agents) Shannon’s repository includes machine-readable maps for LLMs and AI agents: [llms.txt](https://github.com/KeygraphHQ/shannon/blob/main/llms.txt) for a concise repository map, and [llms-full.txt](https://github.com/KeygraphHQ/shannon/blob/main/llms-full.txt) for the README and docs combined into one file. # Coverage > Shannon's current vulnerability coverage and reporting philosophy. Shannon focuses on exploitable findings that can be validated against a running application. ## Current coverage [Section titled “Current coverage”](#current-coverage) * Broken Authentication * Broken Authorization * Injection * Cross-Site Scripting * Server-Side Request Forgery Shannon 3.0 also runs a sixth exploit agent for findings that fall outside these five classes (reported as Miscellaneous), and each SARIF result is tagged with its OWASP Top Ten 2025 category. ## Reporting philosophy [Section titled “Reporting philosophy”](#reporting-philosophy) Shannon follows a proof-by-exploitation model. Findings that cannot be demonstrated with a working proof of concept are not included in the final report. This reduces speculative noise, but it also means Shannon does not aim to report every possible security issue in a repository. It does not report on issues it cannot actively exploit, such as vulnerable third-party libraries, weak encryption algorithms, insecure configurations, and broad policy or static-analysis findings. Shannon 3.0 can also run optional security code analysis, but only findings it can exploit enter the pentest report. Broader static-analysis coverage is the focus of Agentic SAST on the [Keygraph platform](/docs/explanations/keygraph-platform/). ## OWASP WSTG coverage [Section titled “OWASP WSTG coverage”](#owasp-wstg-coverage) This is the full [OWASP Web Security Testing Guide](https://owasp.org/www-project-web-security-testing-guide/) checklist. A **Yes** marks controls Shannon reliably addresses. In practice detection often reaches beyond the marked rows, so the table understates coverage rather than overstating it. This table mirrors [`COVERAGE.md`](https://github.com/KeygraphHQ/shannon/blob/main/COVERAGE.md) in the repository. | Test ID | Test Name | Covered | | ------------- | --------------------------------------------------------- | :-----: | | **WSTG-INFO** | **Information Gathering** | | | WSTG-INFO-01 | Search Engine Discovery for Information Leakage | | | WSTG-INFO-02 | Fingerprint Web Server | Yes | | WSTG-INFO-03 | Review Webserver Metafiles for Information Leakage | | | WSTG-INFO-04 | Enumerate Applications on Webserver | | | WSTG-INFO-05 | Review Webpage Content for Information Leakage | | | WSTG-INFO-06 | Identify Application Entry Points | Yes | | WSTG-INFO-07 | Map Execution Paths Through Application | Yes | | WSTG-INFO-08 | Fingerprint Web Application Framework | Yes | | WSTG-INFO-09 | Fingerprint Web Application | Yes | | WSTG-INFO-10 | Map Application Architecture | Yes | | **WSTG-CONF** | **Configuration and Deploy Management** | | | WSTG-CONF-01 | Test Network Infrastructure Configuration | Yes | | WSTG-CONF-02 | Test Application Platform Configuration | | | WSTG-CONF-03 | Test File Extensions Handling for Sensitive Information | | | WSTG-CONF-04 | Review Old Backup and Unreferenced Files | | | WSTG-CONF-05 | Enumerate Infrastructure and Application Admin Interfaces | | | WSTG-CONF-06 | Test HTTP Methods | | | WSTG-CONF-07 | Test HTTP Strict Transport Security | | | WSTG-CONF-08 | Test RIA Cross Domain Policy | | | WSTG-CONF-09 | Test File Permission | | | WSTG-CONF-10 | Test for Subdomain Takeover | Yes | | WSTG-CONF-11 | Test Cloud Storage | | | WSTG-CONF-12 | Testing for Content Security Policy | | | WSTG-CONF-13 | Test Path Confusion | | | WSTG-CONF-14 | Test Other HTTP Security Header Misconfigurations | | | **WSTG-IDNT** | **Identity Management** | | | WSTG-IDNT-01 | Test Role Definitions | Yes | | WSTG-IDNT-02 | Test User Registration Process | Yes | | WSTG-IDNT-03 | Test Account Provisioning Process | Yes | | WSTG-IDNT-04 | Account Enumeration and Guessable User Account | Yes | | WSTG-IDNT-05 | Weak or Unenforced Username Policy | Yes | | **WSTG-ATHN** | **Authentication** | | | WSTG-ATHN-01 | Credentials Transported over an Encrypted Channel | Yes | | WSTG-ATHN-02 | Default Credentials | Yes | | WSTG-ATHN-03 | Weak Lock Out Mechanism | Yes | | WSTG-ATHN-04 | Bypassing Authentication Schema | Yes | | WSTG-ATHN-05 | Vulnerable Remember Password | | | WSTG-ATHN-06 | Browser Cache Weakness | | | WSTG-ATHN-07 | Weak Password Policy | Yes | | WSTG-ATHN-08 | Weak Security Question Answer | Yes | | WSTG-ATHN-09 | Weak Password Change or Reset Functionalities | Yes | | WSTG-ATHN-10 | Weaker Authentication in Alternative Channel | Yes | | WSTG-ATHN-11 | Multi-Factor Authentication (MFA) | Yes | | **WSTG-ATHZ** | **Authorization** | | | WSTG-ATHZ-01 | Directory Traversal File Include | Yes | | WSTG-ATHZ-02 | Bypassing Authorization Schema | Yes | | WSTG-ATHZ-03 | Privilege Escalation | Yes | | WSTG-ATHZ-04 | Insecure Direct Object References | Yes | | WSTG-ATHZ-05 | OAuth Weaknesses | Yes | | **WSTG-SESS** | **Session Management** | | | WSTG-SESS-01 | Session Management Schema | Yes | | WSTG-SESS-02 | Cookies Attributes | Yes | | WSTG-SESS-03 | Session Fixation | Yes | | WSTG-SESS-04 | Exposed Session Variables | | | WSTG-SESS-05 | Cross Site Request Forgery | Yes | | WSTG-SESS-06 | Logout Functionality | Yes | | WSTG-SESS-07 | Session Timeout | Yes | | WSTG-SESS-08 | Session Puzzling | | | WSTG-SESS-09 | Session Hijacking | | | WSTG-SESS-10 | JSON Web Tokens | Yes | | WSTG-SESS-11 | Concurrent Sessions | | | **WSTG-INPV** | **Input Validation** | | | WSTG-INPV-01 | Reflected Cross Site Scripting | Yes | | WSTG-INPV-02 | Stored Cross Site Scripting | Yes | | WSTG-INPV-03 | HTTP Verb Tampering | | | WSTG-INPV-04 | HTTP Parameter Pollution | | | WSTG-INPV-05 | SQL Injection | Yes | | WSTG-INPV-06 | LDAP Injection | | | WSTG-INPV-07 | XML Injection | | | WSTG-INPV-08 | SSI Injection | | | WSTG-INPV-09 | XPath Injection | | | WSTG-INPV-10 | IMAP SMTP Injection | | | WSTG-INPV-11 | Code Injection | Yes | | WSTG-INPV-12 | Command Injection | Yes | | WSTG-INPV-13 | Format String Injection | | | WSTG-INPV-14 | Incubated Vulnerabilities | | | WSTG-INPV-15 | HTTP Splitting Smuggling | | | WSTG-INPV-16 | HTTP Incoming Requests | | | WSTG-INPV-17 | Host Header Injection | | | WSTG-INPV-18 | Server-Side Template Injection | Yes | | WSTG-INPV-19 | Server-Side Request Forgery | Yes | | WSTG-INPV-20 | Mass Assignment | | | **WSTG-ERRH** | **Error Handling** | | | WSTG-ERRH-01 | Improper Error Handling | | | WSTG-ERRH-02 | Stack Traces | | | **WSTG-CRYP** | **Cryptography** | | | WSTG-CRYP-01 | Weak Transport Layer Security | Yes | | WSTG-CRYP-02 | Padding Oracle | | | WSTG-CRYP-03 | Sensitive Information Sent Via Unencrypted Channels | Yes | | WSTG-CRYP-04 | Weak Encryption | | | **WSTG-BUSL** | **Business Logic** | | | WSTG-BUSL-01 | Test Business Logic Data Validation | | | WSTG-BUSL-02 | Test Ability to Forge Requests | | | WSTG-BUSL-03 | Test Integrity Checks | | | WSTG-BUSL-04 | Test for Process Timing | | | WSTG-BUSL-05 | Test Number of Times a Function Can Be Used Limits | | | WSTG-BUSL-06 | Test Circumvention of Work Flows | | | WSTG-BUSL-07 | Test Defenses Against Application Misuse | | | WSTG-BUSL-08 | Test Upload of Unexpected File Types | | | WSTG-BUSL-09 | Test Upload of Malicious Files | | | WSTG-BUSL-10 | Test Payment Functionality | | | **WSTG-CLNT** | **Client-side** | | | WSTG-CLNT-01 | DOM Based Cross Site Scripting | Yes | | WSTG-CLNT-02 | JavaScript Execution | Yes | | WSTG-CLNT-03 | HTML Injection | Yes | | WSTG-CLNT-04 | Client-Side URL Redirect | Yes | | WSTG-CLNT-05 | CSS Injection | | | WSTG-CLNT-06 | Client-Side Resource Manipulation | | | WSTG-CLNT-07 | Test Cross Origin Resource Sharing | | | WSTG-CLNT-08 | Cross Site Flashing | | | WSTG-CLNT-09 | Clickjacking | | | WSTG-CLNT-10 | Testing WebSockets | | | WSTG-CLNT-11 | Test Web Messaging | | | WSTG-CLNT-12 | Test Browser Storage | Yes | | WSTG-CLNT-13 | Cross Site Script Inclusion | Yes | | WSTG-CLNT-14 | Reverse Tabnabbing | | | **WSTG-APIT** | **API** | | | WSTG-APIT-01 | API Reconnaissance | Yes | | WSTG-APIT-02 | API Broken Object Level Authorization | Yes | | WSTG-APIT-99 | Testing GraphQL | Yes | ## Beyond Shannon Open Source [Section titled “Beyond Shannon Open Source”](#beyond-shannon-open-source) For organizations that need broader static and organizational coverage, the [Keygraph platform](/docs/explanations/keygraph-platform/) adds Code Property Graph SAST, SCA with reachability, secrets scanning, black-box and grey-box testing, finding management, remediation, and verification. # Editions > How Shannon Open Source compares to the commercial Keygraph platform. **Shannon** is the open-source pentester you run yourself. **Keygraph Pro** and **Keygraph Enterprise** are powered by an enhanced, enterprise-grade version of the Shannon engine, running continuously across many teams and repositories. ## Shannon Open Source [Section titled “Shannon Open Source”](#shannon-open-source) Shannon Open Source is a complete autonomous pentester, not a trial edition. It is well suited to individual developers and small teams running focused security tests locally or in CI/CD. It reads your source, maps routes and data flows, runs real attacks against a live target, and writes PDF, Markdown, JSON, and SARIF reports. It runs locally, in CI, or air-gapped with your own model. ## Keygraph platform [Section titled “Keygraph platform”](#keygraph-platform) The Keygraph platform is for organizations that need a shared platform for continuous pentesting and AppSec across many teams, repositories, and environments. It centralizes deeper analysis, vulnerability management, remediation, verification, governance, and reporting so teams do not have to assemble and maintain those workflows themselves. Both editions are BYOK. Keygraph never receives your source and never proxies model traffic, open source or commercial. ## Side-by-side comparison [Section titled “Side-by-side comparison”](#side-by-side-comparison) | | Shannon Open Source | Keygraph platform | | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Best for | Developers and teams running repository-level pentests locally or in CI | Security organizations running continuous AppSec across many teams and repositories | | Code analysis | Agent pass over architecture, entry points, and data flows to seed the pentest, plus optional multi-stage security code analysis, sized to finish inside a CI run | Persistent code property graph plus a long-running analysis harness with interprocedural taint, sanitizer modeling, cross-repo context, exploit chains, and multi-pass review | | Pentesting | On-demand, source-aware white-box pentesting with optional authenticated testing, focused on injection, XSS, SSRF, broken authentication, and broken authorization, with proof by exploitation | The enterprise-grade Shannon engine, run continuously, with grey-box and black-box targets and business-logic invariant testing | | SCA and secrets | Not included | SCA with reachability and secrets scanning, including repository history | | Findings | Per-run PDF, Markdown, JSON, and SARIF 2.1.0, with SARIF upload to GitHub code scanning | One record per vulnerability per repository across scans and scanners, plus ownership, SLAs, dashboards, and audit evidence | | Fixes and verification | Fix manually from the report, then re-run the scan to verify | Fix pull requests for a developer to review and apply, verified by re-analysis and exploit replay without a full rescan | | CI/CD and source control | [GitHub Action and GitLab CI/CD component](/docs/how-to/ci-cd/) for pull-request, release, and scheduled runs, with gates on `status: exploited` | GitHub, GitLab, Azure DevOps, and Bitbucket with organization-wide policy and centrally managed integrations | | Deployment and models | Runs locally or on a CI runner with BYOK to any Anthropic- or OpenAI-compatible endpoint or local model | Deployed in your AWS, GCP, Azure, or on-premises environment, including fully air-gapped. Model requests go directly to the provider, private endpoint, gateway, or local model you configure | | Governance, license, support | AGPL-3.0, community support | SSO, SCIM, RBAC, and audit logs, plus a commercial license, enterprise support, and SOC 2 Type II | ## Learn more [Section titled “Learn more”](#learn-more) Read the [Keygraph platform overview](/docs/explanations/keygraph-platform/), visit the [Keygraph website](https://keygraph.io), book a [demo](https://cal.com/team/keygraph/keygraph-technical-demo), or contact . # FAQ > Common questions about self-hosting, BYOK, SARIF, AI providers, local models, and how Shannon exploits. ## Can I self-host Shannon? [Section titled “Can I self-host Shannon?”](#can-i-self-host-shannon) Yes. Shannon Open Source runs inside your infrastructure in an ephemeral worker container. It mounts the repository read-only and writes results to a local workspace. Keygraph never receives your source code and never proxies your model traffic. Your model requests go straight to the provider or endpoint you configure, and they carry source and application context with them. Point Shannon at a locally hosted endpoint and that traffic stays inside your environment too. ## Does Shannon support bring your own key (BYOK)? [Section titled “Does Shannon support bring your own key (BYOK)?”](#does-shannon-support-bring-your-own-key-byok) Yes, always. You provide the LLM credentials Shannon uses to run a pentest, in every deployment, open source and commercial. Keygraph never proxies your model traffic. ## Does Shannon output SARIF? [Section titled “Does Shannon output SARIF?”](#does-shannon-output-sarif) Yes. Shannon emits SARIF 2.1.0, the OASIS standard format for static analysis results, alongside structured JSON. Any SARIF consumer reads it: code scanning services, vulnerability management platforms, security dashboards, and CI/CD pipelines. It is written by default on exploit-mode scans. To opt out, set `report.sarif` to `"false"` in your configuration file. See [SARIF output](/docs/how-to/configuration/#sarif-output). ## Which AI providers does Shannon support? [Section titled “Which AI providers does Shannon support?”](#which-ai-providers-does-shannon-support) Anthropic, OpenAI, xAI, and AWS Bedrock are built in and configured directly by provider ID. Beyond those, Shannon runs on any provider in the Pi harness catalogue, named the same `:` way. Any provider can be pointed at a proxy or LLM gateway through a [custom base URL](/docs/how-to/ai-providers/#custom-base-url), which overrides only the endpoint and keeps that provider’s API dialect. A model the catalogue does not carry, such as one a router or gateway serves under its own ID, or a self-hosted model, is described in a [custom model configuration](/docs/how-to/ai-providers/#custom-model-configuration) file and passed with `--models-config`. Shannon uses a single model setting throughout a pentest. ## Can I run Shannon on a local or self-hosted model? [Section titled “Can I run Shannon on a local or self-hosted model?”](#can-i-run-shannon-on-a-local-or-self-hosted-model) Yes. Shannon works with local models served through Ollama, vLLM, or LM Studio, which expose an OpenAI-compatible endpoint, as well as routers such as OpenRouter and LLM gateways such as LiteLLM. Most self-hosted models are not in the harness catalogue, so describe them in a custom model configuration file passed with `--models-config`. Capability varies. A model that does not follow Shannon’s instructions or tool-use constraints reliably will produce weaker pentests than a frontier model, so take this path only if you know how your chosen model behaves. See [Local and self-hosted models](/docs/how-to/ai-providers/#local-and-self-hosted-models). ## Does Shannon actually exploit vulnerabilities, or just scan? [Section titled “Does Shannon actually exploit vulnerabilities, or just scan?”](#does-shannon-actually-exploit-vulnerabilities-or-just-scan) Shannon executes real exploits. It reports a finding only when it has produced a working proof-of-concept, and discards hypotheses it cannot prove. It is a pentester, not a passive scanner, so run it only against systems you are authorized to test, and never against production. See [Safety & Limitations](/docs/explanations/safety/). ## How long does a scan take? [Section titled “How long does a scan take?”](#how-long-does-a-scan-take) A full run typically takes a few hours, and longer on large repositories, slower models, or with [security code analysis](/docs/how-to/configuration/#security-code-analysis) enabled. Check progress with `status`, or tail the log with `logs`. See [Monitor progress](/docs/tutorials/quick-start/#monitor-progress). ## Can I resume a scan that was interrupted? [Section titled “Can I resume a scan that was interrupted?”](#can-i-resume-a-scan-that-was-interrupted) Yes. Re-run `start` with the same URL and the same `-w` workspace name, and Shannon skips the agents that already completed. Use `scans` to find the name of an auto-named workspace. See [Workspaces & Resuming](/docs/how-to/workspaces/). # Introduction to Shannon > What Shannon is, why it exists, and how it approaches security testing. Shannon is an autonomous AI pentester developed by [Keygraph](https://keygraph.io). It performs white-box security testing of web applications and their underlying APIs by combining source-code analysis with live exploitation. Shannon analyzes your web application’s source code to identify potential attack vectors, then uses browser automation and command-line tools to execute real exploits against the running application and its APIs. Only vulnerabilities with a working proof-of-concept are included in the final report. **Shannon**, documented here, is the open-source pentester you run yourself. Keygraph’s commercial editions, [Keygraph Pro and Keygraph Enterprise](https://keygraph.io/pricing), are powered by an enhanced, enterprise-grade version of the Shannon engine. See [Editions](/docs/explanations/editions/) for how they compare. ## Why Shannon exists [Section titled “Why Shannon exists”](#why-shannon-exists) Thanks to tools like Claude Code and Cursor, your team ships code non-stop. Most teams still pentest once a year. Between tests, vulnerabilities can ship to production and sit there unnoticed. Shannon closes that gap by providing on-demand, automated penetration testing that can run against every build or release. ### Not a replacement for human pentesters [Section titled “Not a replacement for human pentesters”](#not-a-replacement-for-human-pentesters) Shannon is built to work alongside expert pentesters and red teamers, not replace them. Great pentesters understand the business, chain attacks in ways nobody anticipated, and bring judgment that current models can’t match. Shannon solves a different problem: there is far more software to test than security teams have time to cover. It shifts pentesting left into the software development lifecycle, so you can run exploitation-backed tests against staging environments and releases at the cadence they ship, and save expert human time for the risks that need someone who knows the organization. ### Why “Shannon”? [Section titled “Why “Shannon”?”](#why-shannon) It’s named after Claude Shannon, the father of information theory. Pentesting is an information problem: every probe reduces uncertainty about a system’s state, and the best tools maximize the signal gained from every request. ## How Shannon works [Section titled “How Shannon works”](#how-shannon-works) Shannon combines multi-stage security code analysis with live reconnaissance and exploitation. Each scan flows through six stages: 1. **Recon and vulnerability analysis** explore the running application, tie runtime behavior back to the source, and run specialized agents for Injection, XSS, SSRF, Authentication, and Authorization. 2. **Security code analysis** (optional, `agentic_sast`) runs alongside them, mapping architecture, trust boundaries, data flows, and high-risk assets. 3. **Finding reconciliation** merges both streams, removes duplicates, and builds one exploitation queue. 4. **Exploitation agents**, including a sixth agent for findings outside the five classes, attempt real proof-of-concept attacks. 5. **Validation** discards every candidate Shannon cannot demonstrate. 6. **Reporting** produces PDF and Markdown reports with the evidence attached, plus JSON and SARIF. ``` flowchart TD S["Source code"] --> A["1 · Recon + vulnerability analysis
Injection · XSS · SSRF · Auth · Authz"] S --> B["2 · Security code analysis
optional"] A -- "pentest candidates" --> C["3 · Finding reconciliation
merge + deduplicate"] B -- "code-analysis candidates" --> C C --> P4 APP["Running application"] --> P4 subgraph P4 ["4 · Exploitation"] X1["Exploit · Injection"] X2["Exploit · XSS"] X3["Exploit · SSRF"] X4["Exploit · Auth"] X5["Exploit · Authz"] X6["Exploit · Misc"] end P4 --> V{"5 · Validation"} V -- "exploit demonstrated" --> R["6 · Reporting
PDF · Markdown · JSON · SARIF"] V -- "not demonstrated" --> D["Discarded"] ``` Shannon's scan workflow Only live-validated vulnerabilities become Shannon pentest findings or count toward CI/CD severity gates. Each scan runs in an ephemeral Docker container with its own isolated workspace, so runs never share state. ### What you see while it runs [Section titled “What you see while it runs”](#what-you-see-while-it-runs) `shannon status` shows each scan’s progress as a phase list: **Authentication** (login validation, shown as skipped when no login is configured), **Pre-Recon**, **Recon**, **Vulnerability Analysis**, **Exploitation**, and **Reporting**. Security code analysis and finding reconciliation appear as detail rows under the phase they feed. ## Key capabilities [Section titled “Key capabilities”](#key-capabilities) * **Proof-by-exploitation reports**: validated findings with reproducible proof-of-concept steps instead of speculative warnings. * **White-box attack planning**: source-code analysis guides dynamic testing toward realistic attack paths. * **Autonomous execution**: reconnaissance, vulnerability analysis, exploitation, and report generation launch from a single command. * **Authenticated testing**: configuration files can describe login flows (including TOTP and email-based login), test credentials, focus areas, and rules of engagement. * **OWASP-focused coverage**: targets exploitable Injection, XSS, SSRF, Broken Authentication, and Broken Authorization issues. * **Resumable workspaces**: resume interrupted runs without re-running completed agents. * **Live terminal experience**: simplifies scan setup and shows agent progress and results without exposing orchestration logs. * **Native CI/CD integrations**: the official [GitHub Action (`KeygraphHQ/shannon-action@v1`) and GitLab CI/CD component](/docs/how-to/ci-cd/) run pull-request, release, and scheduled pentests, and can fail a pipeline only on exploited findings at or above a severity you set. * **Multi-format reports**: PDF and Markdown reports plus JSON and SARIF 2.1.0 (SARIF on by default for exploit runs). * **Provider-agnostic and BYOK**: Anthropic, OpenAI, xAI, AWS Bedrock, compatible gateways, and [local models](/docs/how-to/ai-providers/#local-and-self-hosted-models) served through Ollama, vLLM, or LM Studio. * **Private by design**: runs in your infrastructure, stores results locally, and sends model requests directly to your chosen endpoint. A local endpoint keeps data inside your environment. * **Security code analysis**: optional multi-stage code analysis that feeds exploitation candidates into the pentest. ## Shannon in action [Section titled “Shannon in action”](#shannon-in-action) These reports are from Shannon Open Source 3.0 scans of Photoview 2.4.0, an open-source, self-hosted photo management application. Keygraph ran Shannon against it with three models and published the reports and SARIF logs. | Model | Token cost | Verified findings | Report | | ----------------- | ---------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | DeepSeek v4 Flash | $6.10 | 18 | [PDF](https://github.com/KeygraphHQ/shannon/blob/main/benchmark/photoview-deepseek-v4-flash.pdf) · [SARIF](https://github.com/KeygraphHQ/shannon/blob/main/benchmark/photoview-deepseek-v4-flash.sarif) | | Grok 4.6 | $35.07 | 10 | [PDF](https://github.com/KeygraphHQ/shannon/blob/main/benchmark/photoview-grok-4-6.pdf) · [SARIF](https://github.com/KeygraphHQ/shannon/blob/main/benchmark/photoview-grok-4-6.sarif) | | Claude Opus 5 | $115 | 23 (plus 1 false positive) | [PDF](https://github.com/KeygraphHQ/shannon/blob/main/benchmark/photoview-opus-5.pdf) · [SARIF](https://github.com/KeygraphHQ/shannon/blob/main/benchmark/photoview-opus-5.sarif) | All three runs found the critical pre-auth SQL injection (CVSS 9.8) that Photoview later patched, and the Opus 5 run caught 6 of the 7 vulnerabilities Photoview patched after 2.4.0. Every model caught the most urgent issue, while stronger models caught more of the subtler, higher-severity ones, which supports running a lower-cost model for frequent scans and a frontier model for periodic deeper assessments. Token cost is what a run consumed on a model key, not a product price. The reports and SARIF logs are in the [benchmark folder on GitHub](https://github.com/KeygraphHQ/shannon/tree/main/benchmark). Older sample reports, produced by the pre-3.0 engine against intentionally vulnerable applications: | Target | Summary | | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | [OWASP Juice Shop](https://github.com/KeygraphHQ/shannon/blob/main/sample-reports/shannon-report-juice-shop.md) | 20+ vulnerabilities, including authentication bypass, SQL injection, IDOR, and SSRF. | | [c{api}tal API](https://github.com/KeygraphHQ/shannon/blob/main/sample-reports/shannon-report-capital-api.md) | \~15 critical and high-severity API findings, including command injection, auth bypass, and mass assignment. | | [OWASP crAPI](https://github.com/KeygraphHQ/shannon/blob/main/sample-reports/shannon-report-crapi.md) | 15+ critical and high-severity findings across JWT, injection, SSRF, and API authorization paths. | ## Before you begin [Section titled “Before you begin”](#before-you-begin) Shannon actively executes exploits. Run it only against applications and environments you own or have explicit written authorization to test, and never against production systems. Read [Safety & Limitations](/docs/explanations/safety/) before your first run. ## Next steps [Section titled “Next steps”](#next-steps) Continue to the [Quick Start](/docs/tutorials/quick-start/) to run your first pentest. # Keygraph Platform > Keygraph Pro and Enterprise, continuous pentesting and AppSec powered by an enhanced, enterprise-grade version of the Shannon engine. Shannon is an open-source pentester. It reads your source, maps routes and data flows, runs real attacks against a live target, and writes PDF and SARIF reports. It runs locally, in CI, or air-gapped with your own model. Shannon Open Source is a complete pentester, not a trial edition. Keygraph Pro and Enterprise are built on an enhanced, enterprise-grade version of the Shannon engine. They run continuously across hundreds of repositories and add what a security team needs around it: audit-depth static analysis on a parsed code graph, business-logic testing, SCA and secrets scanning, one deduplicated record per vulnerability across scans and scanners, fix pull requests, fix verification, and SSO, RBAC, and audit logs. They are for security teams that own vulnerability management across many engineering teams and need one place to triage, assign, fix, and verify. Both editions are BYOK. Keygraph never receives your source and never proxies model traffic, open source or commercial. Shannon Open Source runs from your machine or CI runner. The Keygraph platform deploys inside your cloud or data center, including fully air-gapped. For a side-by-side table, see [Editions](/docs/explanations/editions/). ## How it fits your pipeline [Section titled “How it fits your pipeline”](#how-it-fits-your-pipeline) 1. Scans run on pull requests, releases, and a schedule against repositories in GitHub, GitLab, Azure DevOps, or Bitbucket. 2. Pipelines gate on exploited severity. A code-analysis hypothesis never fails a build. 3. Findings from every scanner and every run land as one record per vulnerability per repository, with an owner and an SLA. The same finding across ten runs is one record, not ten alerts. 4. From a finding, Keygraph opens a fix pull request into your normal review flow, for a developer to review and apply. 5. Verification confirms the fix against the changed code and the original exploit. No full rescan is required. ## What is different technically [Section titled “What is different technically”](#what-is-different-technically) ### Static analysis on a code property graph [Section titled “Static analysis on a code property graph”](#static-analysis-on-a-code-property-graph) Shannon Open Source’s code analysis is sized to finish inside a CI run: agents read the repository, map the attack surface, and hand candidates to the pentester. The Keygraph platform is built for depth instead. It first parses each repository into a persistent code property graph, then runs an analysis harness adapted to query the graph rather than read files. The harness decomposes the application into risk, taint-flow, framework, and specialist tasks, and supports audit workflows that run longer than typical CI job windows. On the graph, it performs: * Interprocedural taint tracking across functions, files, fields, containers, and framework request lifecycles. * Source, sink, and sanitizer modeling that records where validation, encoding, or authorization changes a path. * Cross-repository modeling of services, entry points, and trust boundaries. * Semantic deduplication of variants of the same defect, and exploit-chain analysis for combinations with higher impact than any single issue. * Multiple review passes per candidate, checking each claim against the graph and the available deployment and configuration context. Candidates that cannot be substantiated are not reported. ### Business-logic invariants [Section titled “Business-logic invariants”](#business-logic-invariants) Shannon Open Source focuses on injection, XSS, SSRF, and broken authentication and authorization. The Keygraph platform adds testing for bugs that do not fit a vulnerability class: it derives invariants the application is supposed to hold (tenant isolation, workflow ordering, approval limits, balance conservation, state transitions) and tests them against the running application. ### Proof by exploitation [Section titled “Proof by exploitation”](#proof-by-exploitation) The pentesting engine is an enhanced, enterprise-grade version of the Shannon engine, built on the same methodology and the same rule: a pentest finding requires a working exploit. No exploit, no finding. Pro and Enterprise store the exploit and replay it later to verify the fix. SCA prioritizes vulnerable dependencies that application code actually reaches. Secrets scanning covers current source and repository history. ## Findings [Section titled “Findings”](#findings) Shannon Open Source hands you a report per scan. The Keygraph platform deduplicates across runs and across scanners, deterministically and semantically, into one record per vulnerability per repository. Each record carries evidence, source location, severity, scan history, status, owner, resolution, and last-verified state. Workflows cover assignment, triage, false-positive and risk-acceptance decisions, and SLA policies with escalation and aging. Dashboards report open risk, coverage, new versus resolved, SLA compliance, and MTTR, exportable as evidence for customers and auditors. Findings still require human review. The platform’s extra review passes reduce weakly supported findings, but they do not eliminate them. ### Fix and verify [Section titled “Fix and verify”](#fix-and-verify) From a finding, Keygraph opens a pull request with a proposed fix scoped to that finding. A developer reviews and applies it through your normal review flow. Keygraph never commits to a protected branch. Verification re-analyzes the changed code and, for pentest findings, replays the original exploit against the patched target. The verdict comes from deterministic checks plus a review pass, without rerunning the full scan. ## Deployment and access control [Section titled “Deployment and access control”](#deployment-and-access-control) The Keygraph platform deploys entirely inside your AWS, GCP, Azure, or on-premises environment, including networks with no internet egress. There is no Keygraph-operated control plane. Customer-hosted services and stored platform data remain inside your environment for the life of the deployment. Model access is BYOK and bring-your-own-model. Route workloads to Anthropic, OpenAI, xAI, or Bedrock, a private cloud endpoint, your own gateway such as LiteLLM with your routing and policy applied, or local models on vLLM or Ollama. Model requests go directly to the endpoint you configure. A local model supports a fully disconnected deployment. Access control: SAML/OIDC SSO, SCIM, roles with repository-scoped visibility (RBAC, plus attribute and relationship rules where needed), a full audit log, and scoped API keys. Keygraph maintains a SOC 2 Type II audit. The report is available to customers under NDA. ## Talk to Keygraph [Section titled “Talk to Keygraph”](#talk-to-keygraph) Visit [keygraph.io](https://keygraph.io), book a [demo](https://cal.com/team/keygraph/keygraph-technical-demo), or email . # Safety & Limitations > Authorized-use requirements, non-production guidance, mutative effects, cost, and model caveats. Read this before running Shannon in a new environment. Shannon executes real exploits Shannon is not a passive scanner. Its exploitation agents can create users, submit forms, mutate application state, trigger outbound requests, and otherwise affect the target system. ## Authorized use only [Section titled “Authorized use only”](#authorized-use-only) Shannon is designed for legitimate security auditing. You must have explicit written authorization from the owner of the target system before running Shannon. Unauthorized scanning or exploitation of systems you do not own is illegal. Keygraph is not responsible for misuse of Shannon. ## Do not run on production [Section titled “Do not run on production”](#do-not-run-on-production) Shannon’s exploitation agents actively execute attacks to confirm vulnerabilities. This can mutate application state and data. Do not run Shannon against production systems. Use sandboxed, staging, or local development environments where data integrity is not a concern. For maximum isolation, run Shannon inside a disposable virtual machine. Potential mutative effects include: * Creating new users * Modifying or deleting data * Compromising test accounts * Triggering unintended side effects from injection attacks * Generating unexpected outbound traffic * Writing exploit artifacts to reports or deliverables ## LLM and automation caveats [Section titled “LLM and automation caveats”](#llm-and-automation-caveats) * **Verification is required.** Shannon uses a proof-by-exploitation methodology, but final reports can still contain weakly supported or incorrect details. Human review is essential. * **Model support.** Shannon is provider-agnostic. Anthropic, OpenAI, xAI, and AWS Bedrock are built in, and any other provider in the Pi harness catalogue, compatible LLM gateways, and local models served by Ollama, vLLM, or LM Studio also work (see [AI Providers](/docs/how-to/ai-providers/)). Results vary by model. A model that does not follow Shannon’s instructions or tool-use constraints reliably may produce incomplete, inaccurate, or unstable runs. * **Prompt injection risk.** Do not point Shannon at untrusted or adversarial codebases. AI-powered tools that read source code can be influenced by malicious repository content. ## Scope of analysis [Section titled “Scope of analysis”](#scope-of-analysis) Shannon currently targets exploitable vulnerabilities in these classes: * Broken Authentication * Broken Authorization * Injection * Cross-Site Scripting * Server-Side Request Forgery Shannon’s proof-by-exploitation model means it does not report issues it cannot actively exploit, such as many vulnerable-dependency, insecure-configuration, or broad-policy findings. For broader coverage, the [Keygraph platform](/docs/explanations/keygraph-platform/) adds black-box and white-box agentic pentesting, graph-based static analysis, SCA reachability, secrets detection, business logic testing, remediation workflows, SLA tracking, and reporting dashboards. ## Cost and performance [Section titled “Cost and performance”](#cost-and-performance) A full test run typically takes a few hours. LLM API costs vary by model pricing, target complexity, selected provider, and concurrency. Enabling security code analysis adds model time and cost. If you use subscription-based model access, see [Subscriptions](/docs/how-to/ai-providers/#subscriptions) in AI Providers for the supported plans. # Shannon How-to Guides > Task-focused recipes for operating Keygraph and Shannon. How-to guides are **task-oriented**: each one solves a single real problem for someone who already knows the basics. No teaching narrative, just the steps. New to Keygraph? Start with [Tutorials](/docs/tutorials/). ## Available guides [Section titled “Available guides”](#available-guides) * **[Build from source and CLI](/docs/how-to/source-build/)**: run Shannon from a local clone, with the common commands and output paths. * **[Configuration](/docs/how-to/configuration/)**: scope a scan, set rules of engagement, turn on security code analysis, and filter the report. * **[Authenticated testing](/docs/how-to/authenticated-testing/)**: describe a login flow so Shannon can test behind authentication. * **[AI providers](/docs/how-to/ai-providers/)**: bring your own model key for Anthropic, OpenAI, xAI, AWS Bedrock, any Pi-catalogue provider, a custom LLM gateway, or a local model. * **[Platforms and networking](/docs/how-to/platforms/)**: run on Windows, Linux, or macOS, and reach a local target from the worker. * **[Workspaces and resuming](/docs/how-to/workspaces/)**: resume an interrupted run without repeating completed work. * **[CI/CD integrations](/docs/how-to/ci-cd/)**: run pull-request, release, and scheduled pentests with the GitHub Action or GitLab component, and gate on exploited findings. ## Coming soon [Section titled “Coming soon”](#coming-soon) * **Run an on-demand blackbox pentest** against a deployed application. * **Self-host Keygraph** in your own AWS, GCP, or Azure, or fully air-gapped. * **Triage findings with the verdict layer**: exploitable vs. confirmed non-exploitable. * **Tune SCA reachability** so only exploitable CVEs surface. * **Review a remediation PR**: apply a verified, reviewable patch. * **Export compliance evidence** and sync findings to Jira. * **Set up SSO (SAML 2.0 / OIDC) and SCIM** provisioning. # AI Providers > Configure Anthropic, OpenAI, xAI, AWS Bedrock, any Pi-catalogue provider, a custom LLM gateway, or a local model. Shannon is provider-agnostic, and you always bring your own key. One setting, `SHANNON_AI_MODEL=:`, picks the provider and model for the whole scan. Anthropic, OpenAI, xAI, and AWS Bedrock are built in. Any other provider in the Pi harness catalogue works with a single API key, a custom base URL routes any provider through a proxy or LLM gateway, and local models served by Ollama, vLLM, or LM Studio run through a custom model configuration. The default model is `anthropic:claude-sonnet-4-6`. Keygraph never proxies your model traffic. Each provider can be configured through the interactive `setup` wizard (`npx` mode) or by supplying environment variables directly. In source-build mode, the same variables can live in a `.env` file. Pick a tab. Your choice is remembered across the site. ## Choosing a model [Section titled “Choosing a model”](#choosing-a-model) One model runs the entire scan. Set `SHANNON_AI_MODEL=:`. If it is unset, Shannon uses `anthropic:claude-sonnet-4-6`. Suggested model IDs (the setup wizard offers these, best first): | Provider | Suggested model IDs | | ---------------- | ---------------------------------------------------------------- | | `anthropic` | `claude-sonnet-4-6`, `claude-opus-4-8` | | `openai` | `gpt-5.6-sol`, `gpt-5.5` | | `xai` | `grok-4.6`, `grok-4.5` | | `amazon-bedrock` | `us.anthropic.claude-sonnet-4-6`, `us.anthropic.claude-opus-4-8` | The wizard also takes a typed model ID, and `SHANNON_AI_MODEL` accepts any model in the provider’s catalogue. The older `ANTHROPIC_SMALL_MODEL`, `ANTHROPIC_MEDIUM_MODEL`, and `ANTHROPIC_LARGE_MODEL` variables no longer do anything. Shannon refreshes the model catalogue over the network at scan start, so a newly released model on a catalogue provider resolves without upgrading Shannon. The refresh is bounded and falls back to the built-in catalogue if it times out. ## Cyber safeguards (do this before your first scan) [Section titled “Cyber safeguards (do this before your first scan)”](#cyber-safeguards-do-this-before-your-first-scan) Anthropic and OpenAI both apply real-time safeguards to security workloads, and a Shannon scan is one. If a safeguard engages mid-run, the model can refuse and the scan stops partway through rather than at the start. Review each vendor’s guidance and complete the verification or enrollment they ask of legitimate security testers before you run Shannon: * Anthropic: [Real-time cyber safeguards on Claude Opus and Sonnet](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude-opus-and-sonnet) * OpenAI: [Cyber](https://chatgpt.com/cyber) This applies to the Anthropic and OpenAI providers, including when either is reached through an LLM gateway. Bedrock serves Claude models and is subject to Anthropic’s safeguards as well. ## Anthropic [Section titled “Anthropic”](#anthropic) * npx (recommended) Run the setup wizard: ```bash npx @keygraph/shannon@latest setup ``` Or export a key and model directly: ```bash export SHANNON_AI_API_KEY=sk-ant-... export SHANNON_AI_MODEL=anthropic:claude-sonnet-4-6 ``` * Build from source Add your credential and model to the `.env` file: ```bash SHANNON_AI_API_KEY=sk-ant-... SHANNON_AI_MODEL=anthropic:claude-sonnet-4-6 ``` Anthropic, OpenAI, and xAI also accept their native variables (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `XAI_API_KEY`). When the selected provider’s native variable is set, it takes precedence over `SHANNON_AI_API_KEY`. Shannon forwards only the selected provider’s credential into the scan container. ## Switching provider [Section titled “Switching provider”](#switching-provider) The pattern is the same for every provider: export the provider’s key and name the model. Two lines change, nothing else. OpenAI: ```bash export SHANNON_AI_API_KEY=sk-... export SHANNON_AI_MODEL=openai:gpt-5.6-sol ``` xAI: ```bash export SHANNON_AI_API_KEY=xai-... export SHANNON_AI_MODEL=xai:grok-4.6 ``` Source-build mode reads the same variables from the `.env` file. ## AWS Bedrock [Section titled “AWS Bedrock”](#aws-bedrock) Run `npx @keygraph/shannon@latest setup` and select **AWS Bedrock**, or set the variables directly: * npx (recommended) ```bash export AWS_REGION=us-east-1 export AWS_BEARER_TOKEN_BEDROCK=your-bearer-token export SHANNON_AI_MODEL=amazon-bedrock:us.anthropic.claude-opus-4-8 ``` * Build from source ```bash AWS_REGION=us-east-1 AWS_BEARER_TOKEN_BEDROCK=your-bearer-token SHANNON_AI_MODEL=amazon-bedrock:us.anthropic.claude-opus-4-8 ``` Bedrock uses bearer-token authentication only. IAM access keys, session tokens, assumed roles, and instance profiles are not supported. The model must be enabled in your region. ## Any other provider [Section titled “Any other provider”](#any-other-provider) Shannon accepts any provider and model in the Pi harness catalogue (browse them at [pi.dev/models](https://pi.dev/models)), as long as the provider’s credential is a single API key. Name the provider in `SHANNON_AI_MODEL` and supply its key in `SHANNON_AI_API_KEY`: ```bash export SHANNON_AI_API_KEY=your-api-key export SHANNON_AI_MODEL=openrouter:moonshotai/kimi-k3 ``` Providers that need more than a single API key are not currently supported. The setup wizard offers this path as **Other provider**, with an optional base URL to route that provider through a proxy or LLM gateway. ## Custom base URL [Section titled “Custom base URL”](#custom-base-url) `SHANNON_AI_BASE_URL` routes model traffic through a proxy or LLM gateway, such as LiteLLM, instead of the provider’s default endpoint. It changes only where requests go: the provider named in `SHANNON_AI_MODEL` still decides which credential is sent and which API dialect is spoken. An `anthropic:` model needs an endpoint that speaks Anthropic Messages, and an `openai:` model needs one that speaks OpenAI Responses. Servers that speak only Chat Completions (Ollama, vLLM, LM Studio) are reached through a custom model configuration passed with `--models-config`. See [Local and self-hosted models](#local-and-self-hosted-models). Model capability varies Models are validated against the harness catalogue, but a model that does not follow Shannon’s instructions or tool-use constraints reliably will produce weaker pentests. Evaluate the model you choose against your own targets before depending on its results. Run `npx @keygraph/shannon@latest setup` and select **Custom Base URL**, or set the variables directly: * npx (recommended) ```bash export SHANNON_AI_API_KEY=your-gateway-key export SHANNON_AI_MODEL=anthropic:claude-sonnet-4-6 export SHANNON_AI_BASE_URL=https://llm-gateway.example.com ``` * Build from source ```bash SHANNON_AI_API_KEY=your-gateway-key SHANNON_AI_MODEL=anthropic:claude-sonnet-4-6 SHANNON_AI_BASE_URL=https://llm-gateway.example.com ``` The model ID must still resolve in the harness catalogue. A gateway that serves a model under its own name needs that name described in a custom model configuration file. ## Local and self-hosted models [Section titled “Local and self-hosted models”](#local-and-self-hosted-models) Ollama, vLLM, LM Studio, and other OpenAI-compatible servers are reached through a custom model configuration. Describe the server as a provider in a `models.json` file, pass the file with `--models-config`, and name its model in `SHANNON_AI_MODEL`. Use host.docker.internal, not localhost The scan runs inside a container, so `localhost` points at the container itself rather than at your machine. A `models.json` for Ollama: ```json { "providers": { "ollama": { "baseUrl": "http://host.docker.internal:11434/v1", "api": "openai-completions", "apiKey": "ollama", "models": [ { "id": "" } ] } } } ``` Then name the model and run: ```bash export SHANNON_AI_API_KEY=ollama export SHANNON_AI_MODEL=ollama: npx @keygraph/shannon@latest start -u https://your-app.com -r /path/to/your-repo --models-config ./models.json ``` In source-build mode, pass the same flag to `./shannon start`. LM Studio and vLLM take the same shape on their own ports, `http://host.docker.internal:1234/v1` and `http://host.docker.internal:8000/v1`. The provider name is yours to choose; it only has to match the prefix in `SHANNON_AI_MODEL`. `SHANNON_AI_API_KEY` is still required even though a local server ignores it, so set it to any placeholder value. Some servers need compatibility flags. If a reasoning-capable model is rejected, turn off the roles it does not understand, at either provider or model level: ```json "compat": { "supportsDeveloperRole": false, "supportsReasoningEffort": false } ``` Local model capability Shannon drives every phase through multi-turn tool use. A model that does not follow Shannon’s instructions or tool-use constraints reliably produces weaker pentests than a frontier model, so take this path only if you know how your chosen model behaves. ## Custom model configuration [Section titled “Custom model configuration”](#custom-model-configuration) The same `--models-config` file also reaches a hosted model the catalogue does not carry, such as one a router or gateway serves under its own ID. Shannon merges the file’s definitions over the catalogue, and they take precedence over it, so `SHANNON_AI_MODEL` can then name the model like any other. [pi.dev/models](https://pi.dev/models) supplies the file contents. Find the model under the provider you want, since the same model has a different ID per provider, then open its page and expand **Show configuration** for a ready-to-paste snippet. A trimmed example for a router model: ```json { "providers": { "openrouter": { "apiKey": "YOUR_API_KEY", "api": "openai-completions", "baseUrl": "https://openrouter.ai/api/v1", "models": [ { "id": "z-ai/glm-5.3", "name": "Z.ai: GLM 5.3", "reasoning": true, "contextWindow": 1048576 } ] } } } ``` Then name the model the usual way: ```bash export SHANNON_AI_API_KEY=your-api-key export SHANNON_AI_MODEL=openrouter:z-ai/glm-5.3 ``` Leave `YOUR_API_KEY` exactly as it is. Shannon sends the credential from your environment, which takes precedence over anything the file declares, so the file describes the model and never has to hold a secret. Pi’s [models documentation](https://pi.dev/docs/latest/models) describes the full format, including routing preferences and compatibility flags. ## Subscriptions [Section titled “Subscriptions”](#subscriptions) A ChatGPT Plus or Pro (Codex) subscription or an xAI (Grok) subscription can run Shannon by reusing a login created by Pi. Complete the [cyber safeguards](#cyber-safeguards-do-this-before-your-first-scan) steps first. Then install Pi by following the instructions at [pi.dev](https://pi.dev) and log in with your subscription using Pi’s [subscription authentication guide](https://pi.dev/docs/latest/providers#subscriptions). This creates `~/.pi/agent/auth.json`. Enable Pi authentication and select a model: ```bash export SHANNON_USE_PI_AUTH=1 export SHANNON_AI_MODEL=openai-codex:gpt-5.5 # or xai:grok-4.6 ``` Run `npx @keygraph/shannon@latest start` from the same shell. In source-build mode, add the two variables to `.env` and run `./shannon start`. Supported Codex models are `gpt-5.6-sol`, `gpt-5.5`, and `gpt-5.4`. Suggested Grok models are `grok-4.6` and `grok-4.5`. Claude Code subscriptions work only on Shannon 1.9.0 (`npx @keygraph/shannon@1.9.0 setup`), the final release built on the Claude Agent SDK. The current version does not support them. ## Validation [Section titled “Validation”](#validation) Checks run before a scan starts, so a mistake fails immediately rather than partway through a run: * **Provider and model ID** are validated against the Pi harness catalogue. An unknown provider or model ID fails preflight with a pointer to [pi.dev/models](https://pi.dev/models). To run a model the catalogue does not carry, describe it with [`--models-config`](#custom-model-configuration). * **Model configuration**: when `--models-config` is passed, the file is parsed and schema-checked before the scan starts, and a fault fails preflight with the offending field named. * **Credential presence** is checked for the selected provider, or read from Pi when `SHANNON_USE_PI_AUTH=1`. * **Credential validity** is checked with one minimal request against the model the scan will use, so a rejected key, an exhausted quota, or a model the account cannot reach fails before any agent runs. Bedrock goes through the same probe. ## Upgrading from earlier versions [Section titled “Upgrading from earlier versions”](#upgrading-from-earlier-versions) | Before | Now | | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `SHANNON_AI_OPENAI_FORMAT` (2.x) | Removed in 3.1. An `openai:` model with a base URL always speaks OpenAI Responses. A Chat Completions-only endpoint goes through a [custom model configuration](#custom-model-configuration) with `"api": "openai-completions"`. | | A custom base URL exempted the model ID from catalogue validation (2.x) | The model ID must resolve in the catalogue, or be described with `--models-config`. | | `ANTHROPIC_SMALL_MODEL`, `ANTHROPIC_MEDIUM_MODEL`, `ANTHROPIC_LARGE_MODEL` (1.x) | A single `SHANNON_AI_MODEL`. | | `CLAUDE_CODE_USE_BEDROCK=1` plus three Bedrock model IDs (1.x) | `SHANNON_AI_MODEL=amazon-bedrock:`. | | `ANTHROPIC_BASE_URL` and `ANTHROPIC_AUTH_TOKEN` (1.x) | `SHANNON_AI_BASE_URL` overrides the endpoint; `SHANNON_AI_MODEL` selects the provider. | | Google Vertex AI (1.x) | No longer supported. Switch to Anthropic, AWS Bedrock, or an Anthropic-compatible base URL. | In `~/.shannon/config.toml`, the `[models]` section and `bedrock.use` are gone, each provider has its own section, and the model lives at `core.model`. Re-run `npx @keygraph/shannon@latest setup` to regenerate the file. # Authenticated Testing > Describe login flows so Shannon can test behind authentication. To test areas of an application that require a login, describe the authentication flow in your configuration file. Shannon runs the flow at scan start and reuses the authenticated session for the rest of the run. This page focuses on writing the `authentication` block. For the surrounding configuration file, see the [Configuration guide](/docs/how-to/configuration/). ## The authentication block [Section titled “The authentication block”](#the-authentication-block) ```yaml authentication: login_type: form login_url: "https://your-app.com/login" credentials: username: "test@example.com" password: "yourpassword" totp_secret: "LB2E2RX7XFHSTGCK" 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" ``` ## Writing the login flow [Section titled “Writing the login flow”](#writing-the-login-flow) Log in once in a fresh private browser window, then write the steps in the same order you perform them: * When typing into a field, reference the field by its **exact label or placeholder**. * When clicking a button, reference the **exact button text**. ```yaml login_flow: - "Type $username in " - "Click " - "Type $password in " - "Click " - "If prompted for 2FA, type $totp in " - "Click " ``` ## Supported placeholders [Section titled “Supported placeholders”](#supported-placeholders) At runtime, Shannon replaces these placeholders with the credentials passed in the config: | Placeholder | Resolves to | | ----------------- | ------------------------------------------------------------ | | `$username` | `credentials.username` | | `$password` | `credentials.password` | | `$totp` | current TOTP code from `credentials.totp_secret` | | `$email_address` | `credentials.email_login.address` | | `$email_password` | `credentials.email_login.password` | | `$email_totp` | current TOTP code from `credentials.email_login.totp_secret` | ## Two-factor authentication [Section titled “Two-factor authentication”](#two-factor-authentication) Provide `totp_secret` under `credentials` and reference `$totp` in your login flow. Shannon generates the current time-based code at runtime. ## Email-based login (magic links and email OTP) [Section titled “Email-based login (magic links and email OTP)”](#email-based-login-magic-links-and-email-otp) For magic-link or email-OTP flows, supply mailbox credentials so Shannon can read the login email: ```yaml credentials: username: "test@example.com" password: "yourpassword" email_login: address: "inbox@example.com" password: "mailbox-password" totp_secret: "JBSWY3DPEHPK3PXP" ``` Reference `$email_address`, `$email_password`, and `$email_totp` in the login flow as needed. ## Success condition [Section titled “Success condition”](#success-condition) The `success_condition` tells Shannon how to confirm that login worked. A common pattern is checking that the browser lands on a known post-login URL: ```yaml success_condition: type: url_contains value: "/dashboard" ``` # CI/CD Integrations > Run Shannon on pull requests, releases, and schedules with the official GitHub Action and GitLab CI/CD component. Shannon runs continuously against deployed staging and development environments through official integrations for [GitHub Actions](https://github.com/KeygraphHQ/shannon-action) and [GitLab CI/CD](https://gitlab.com/KeygraphHQ/shannon-ci). Both integrations: * analyze the checked-out source repository while attacking a running target; * preserve PDF, Markdown, and SARIF reports as pipeline artifacts; * preserve scan and agent logs for debugging, including incomplete runs; * support pull-request, release, and scheduled pentests; * distinguish an incomplete assessment from a completed scan with no findings; and * optionally fail the pipeline when Shannon exploits a vulnerability at or above a severity you set. Staging only Point CI scans at a staging or development environment with disposable data, never production. Shannon executes real exploits. See [Safety & Limitations](/docs/explanations/safety/). ## Add Shannon to a pipeline [Section titled “Add Shannon to a pipeline”](#add-shannon-to-a-pipeline) * GitHub Actions ```yaml name: Shannon Pentest on: workflow_dispatch: permissions: security-events: write jobs: pentest: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Run Shannon uses: KeygraphHQ/shannon-action@v1 with: url: https://staging.example.com api-key: ${{ secrets.SHANNON_AI_API_KEY }} fail-on-severity: high upload-sarif: true ``` The Action defaults `repo` to the checked-out workspace. It uploads one artifact with the security assessment reports and SARIF, plus a separate run artifact with scan and agent logs. Enabling `upload-sarif` publishes findings to GitHub code scanning, which needs the `security-events: write` permission. * GitLab CI/CD Store your provider key as a masked CI/CD variable named `SHANNON_AI_API_KEY`, then include the component: ```yaml include: - component: gitlab.com/KeygraphHQ/shannon-ci/pentest@1 inputs: url: $STAGING_URL fail-on-severity: critical shannon-pentest: timeout: 12h ``` The component defaults `repo` to `$CI_PROJECT_DIR` and `workspace` to the pipeline ID. Set `upload-sarif: true` to ingest `report.sarif` into the merge request security widget and the Security tab. The file is a downloadable artifact either way. ## Requirements [Section titled “Requirements”](#requirements) * GitHub Actions * A **private** repository. Reports and logs can contain sensitive findings about your application. * A runner with Docker and Docker Compose v2, with access to Docker Hub. `ubuntu-latest` works out of the box. * Network access from the runner to the running staging or development target. * A model-provider credential stored as a GitHub Actions secret. **Job timeout:** jobs get 6 hours by default, which covers most scans. GitHub-hosted runners are capped at 6 hours, so use a self-hosted runner for larger repositories or slower model providers. * GitLab CI/CD * A **private** project. The component runs only on private projects, since its reports and artifacts can contain sensitive findings. * A **self-hosted runner using the `shell` executor**, with Docker Engine running (runner user in the `docker` group), Node.js LTS, and `zip` installed. The runner user must be non-root. * `docker:dind` and gitlab.com shared runners do **not** work: a separate-container daemon cannot see the checked-out repo. **Job timeout:** a full scan runs far longer than GitLab’s default 60-minute timeout. Raise it to 12 hours in two places, since the lower one wins: the runner’s **Maximum job timeout**, and the job itself (the `timeout: 12h` override above, or the project’s pipeline timeout). ## Pass and fail [Section titled “Pass and fail”](#pass-and-fail) The job passes only on a **complete** assessment, where every vulnerability class was assessed. It fails when the scan produced no report, or when some class could not be assessed (a partial run). No findings for a class that was never checked is not a clean result. Finding vulnerabilities does not fail the job by itself. To gate on demonstrated impact, set `fail-on-severity` to `low`, `medium`, `high`, or `critical`. The gate counts only findings with `status: exploited`, so a code-analysis hypothesis never fails the pipeline, and an analysis-only scan (`exploit: "false"`) never trips it. When the gate fails it reports how many findings crossed the threshold, not their details. If you use it to block merges, also enable `upload-sarif` so the findings appear with their code locations. ## Inputs [Section titled “Inputs”](#inputs) Both integrations take the same core inputs: | Input | Default | Description | | ---------------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------ | | `url` | required | Target URL of the running staging or development environment. | | `repo` | checked-out workspace | Source repository to analyze. | | `config` | | Path to a Shannon [configuration file](/docs/how-to/configuration/) (authentication, scope, report options). | | `workspace` | run or pipeline ID | Named workspace. Set a stable value to resume a scan across runs. | | `model` | `anthropic:claude-sonnet-4-6` | `:`, as in `SHANNON_AI_MODEL`. | | `api-key` | | Provider API key. Always pass a secret or variable reference, never a literal. | | `base-url` | | Provider endpoint override for a proxy or LLM gateway. | | `aws-bearer-token-bedrock`, `aws-region` | | Bedrock credentials, required for `amazon-bedrock:` models. | | `fail-on-severity` | `none` | Fail on an exploited finding at or above this severity. | | `upload-sarif` | `false` | Publish SARIF to GitHub code scanning or the GitLab Security tab. | | `pipeline-testing` | `false` | Minimal prompts for fast pipeline testing. | | `version` | `3.0.0` | The `@keygraph/shannon` version to run. | | `stage` | `test` | GitLab only: pipeline stage for the job. | Pin a newer version Both integrations default to Shannon 3.0.0. Set `version` to a later release to get features such as per-provider base URLs and the network-refreshed model catalogue. The `openai-format` input applies only to Shannon 3.0.x; from 3.1, an `openai:` gateway always speaks the Responses API. See [Upgrading from earlier versions](/docs/how-to/ai-providers/#upgrading-from-earlier-versions). The integrations expose the workspace directory and report paths for downstream steps: the `workspace-dir`, `report-pdf`, `report-md`, and `sarif` outputs on GitHub, and the `SHANNON_WORKSPACE_DIR`, `SHANNON_REPORT_PDF`, `SHANNON_REPORT_MD`, and `SHANNON_SARIF` dotenv variables on GitLab. For the full option list, see the [Shannon GitHub Action](https://github.com/KeygraphHQ/shannon-action) (also on the [GitHub Marketplace](https://github.com/marketplace/actions/shannon-ai-pentester)) and the [Shannon GitLab component](https://gitlab.com/KeygraphHQ/shannon-ci). ## Other CI systems [Section titled “Other CI systems”](#other-ci-systems) On any other CI system, run Shannon headlessly with the CLI. Expose your provider key from a secret as `SHANNON_AI_API_KEY` (and set `SHANNON_AI_MODEL` if you are not using the default), then: ```bash npx @keygraph/shannon@latest start -u "$STAGING_URL" -r . --follow ``` `--follow` streams the scan log until it finishes and exits on the scan’s outcome. Exploit-mode scans write `report.sarif` by default, ready for any SARIF consumer. ## Related [Section titled “Related”](#related) * Reference: [CLI commands](/docs/reference/cli/) * How-to: [Configuration](/docs/how-to/configuration/) * Explanation: [Safety & Limitations](/docs/explanations/safety/) # Configuration > Enable authenticated testing, scope guidance, rules of engagement, optional security code analysis, report filtering, and SARIF output. 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](/docs/reference/configuration-schema/). For login flows specifically, see [Authenticated Testing](/docs/how-to/authenticated-testing/). ## Credential precedence [Section titled “Credential precedence”](#credential-precedence) * npx (recommended) `npx` mode resolves credentials from: 1. Environment variables 2. `~/.shannon/config.toml`, created by `npx @keygraph/shannon setup` * Build from source Source-build mode resolves credentials from: 1. Environment variables, such as `export ANTHROPIC_API_KEY=...` 2. `./.env` 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”](#create-a-configuration-file) Copy and modify the example configuration: ```bash cp configs/example-config.yaml ./my-app-config.yaml ``` Run with the `-c` flag: * npx (recommended) ```bash npx @keygraph/shannon@latest start -u https://example.com -r /path/to/repo -c ./my-app-config.yaml ``` * Build from source ```bash ./shannon start -u https://example.com -r /path/to/repo -c ./my-app-config.yaml ``` ## Basic configuration structure [Section titled “Basic configuration structure”](#basic-configuration-structure) ```yaml # 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" ``` Upgrading from 2.x? `vuln_classes` was removed in Shannon 3.0. Every scan now runs all five classes, and the configuration schema rejects unknown keys, so delete `vuln_classes` from existing config files or the scan fails validation. ## Security code analysis [Section titled “Security code analysis”](#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: ```yaml 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 [Section titled “Scope rules”](#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”](#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 [Section titled “SARIF output”](#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 [Section titled “Subscription plans”](#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](/docs/how-to/ai-providers/#subscriptions). # Platforms & Networking > Platform-specific notes for Windows, Linux, and macOS, plus Docker networking behavior. This guide covers platform-specific notes and Docker networking behavior. ## Windows [Section titled “Windows”](#windows) Shannon on Windows is supported through WSL2. Native Windows, including Git Bash, is not supported: the CLI refuses to start there and points you to this guide. WSL2 is unaffected. ### Ensure WSL2 [Section titled “Ensure WSL2”](#ensure-wsl2) ```powershell wsl --install wsl --set-default-version 2 # Check installed distros. wsl --list --verbose # If you do not have a distro, install one. wsl --list --online wsl --install Ubuntu-24.04 # If your distro shows VERSION 1, convert it to WSL2. wsl --set-version 2 ``` Install Docker Desktop on Windows and enable the WSL2 backend under **Settings > General > Use the WSL 2 based engine**. Run Shannon inside WSL: * npx (recommended) ```bash npx @keygraph/shannon setup npx @keygraph/shannon start -u https://your-app.com -r /path/to/your-repo ``` * Build from source ```bash git clone https://github.com/KeygraphHQ/shannon.git cd shannon cp .env.example .env pnpm install pnpm build ./shannon start -u https://your-app.com -r /path/to/your-repo ``` To open the Temporal Web UI, navigate to `http://localhost:8233` in your Windows browser. Shannon publishes the UI on the loopback address only, so use `localhost` rather than your WSL IP address. ## Linux [Section titled “Linux”](#linux) Linux works with native Docker. Depending on your Docker setup, you may need `sudo`. If output files have permission issues, ensure your user has access to the Docker socket and workspace directory. ## macOS [Section titled “macOS”](#macos) macOS works with Docker Desktop installed. ## Testing local applications [Section titled “Testing local applications”](#testing-local-applications) Docker containers cannot reach `localhost` on your host machine. Use `host.docker.internal` instead. The same applies to a [local model server](/docs/how-to/ai-providers/#local-and-self-hosted-models) such as Ollama, LM Studio, or vLLM: * npx (recommended) ```bash npx @keygraph/shannon start -u http://host.docker.internal:3000 -r /path/to/repo ``` * Build from source ```bash ./shannon start -u http://host.docker.internal:3000 -r /path/to/repo ``` ## Custom hostnames [Section titled “Custom hostnames”](#custom-hostnames) If your local stack uses custom hostnames mapped in `/etc/hosts`, Shannon forwards those entries into the worker container at scan start. To disable forwarding: ```bash export SHANNON_FORWARD_HOSTS=false ``` In source-build mode, you can also add this to `.env`: ```bash SHANNON_FORWARD_HOSTS=false ``` # Build from source & CLI > Run Shannon from a local clone, plus common CLI commands and output paths. This guide covers the source-build workflow, common CLI commands, repository paths, and output locations. For the fastest first run, use the `npx` workflow in the [Quick Start](/docs/tutorials/quick-start/). Throughout this site, command examples are shown as tabs. Pick **npx** or **Build from source** once and your choice is remembered on every page. ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * Docker * Node.js 20.19+ (the source build’s toolchain needs it; the `npx` workflow runs on Node.js 18+) * pnpm * AI provider credentials ## Clone and build [Section titled “Clone and build”](#clone-and-build) Use the source-build workflow if you want to run Shannon from a local clone, modify the open-source CLI, or keep the worker image built locally. 1. **Clone Shannon:** ```bash git clone https://github.com/KeygraphHQ/shannon.git cd shannon ``` 2. **Configure credentials:** ```bash cp .env.example .env ``` 3. **Install dependencies and build:** ```bash pnpm install pnpm build ``` 4. **Run a pentest:** ```bash ./shannon start -u https://your-app.com -r /path/to/your-repo ``` At minimum, your `.env` file should include one supported AI provider credential, such as: ```bash ANTHROPIC_API_KEY=your-api-key ``` Environment variables can also be exported directly: ```bash export ANTHROPIC_API_KEY="your-api-key" ``` See [AI Providers](/docs/how-to/ai-providers/) to choose a model and to set up OpenAI, xAI, AWS Bedrock, a custom LLM gateway, or a local model. ## Prepare your repository [Section titled “Prepare your repository”](#prepare-your-repository) Shannon can scan any repository on your machine. Pass an absolute or relative path with `-r`. The target repository is mounted read-only inside the worker container. * npx (recommended) ```bash npx @keygraph/shannon start -u https://example.com -r /path/to/repo ``` * Build from source ```bash ./shannon start -u https://example.com -r ./relative/path ``` ## Common commands [Section titled “Common commands”](#common-commands) Monitor progress: * npx (recommended) ```bash npx @keygraph/shannon logs [] # Defaults to the single running scan, else the most recent. npx @keygraph/shannon logs [] --agent # Tail one agent only; --list-agents lists them. npx @keygraph/shannon status [] # Same default; add --json for a machine-readable snapshot. npx @keygraph/shannon scans # List running and completed scans. npx @keygraph/shannon version # Print the Shannon version. ``` * Build from source ```bash ./shannon logs [] # Defaults to the single running scan, else the most recent. ./shannon logs [] --agent # Tail one agent only; --list-agents lists them. ./shannon status [] # Same default; add --json for a machine-readable snapshot. ./shannon scans # List running and completed scans. ./shannon version # Print the Shannon version. ``` With no workspace, `logs` and `status` follow the single running scan; when several are running, name one. Every scan writes one combined `.shannon/workflow.log` plus a log per agent under `.shannon/agents/`, which `--agent` reads. Open the Temporal Web UI for detailed monitoring: ```bash open http://localhost:8233 ``` Stop Shannon: * npx (recommended) ```bash npx @keygraph/shannon stop [] # Stop one scan (defaults to the single running scan; confirms first, add --yes to skip). npx @keygraph/shannon stop --all # Stop every scan (Temporal stays up). npx @keygraph/shannon reset # Stop everything and permanently remove all Temporal data (you must type confirm). ``` * Build from source ```bash ./shannon stop [] # Stop one scan (defaults to the single running scan; confirms first, add --yes to skip). ./shannon stop --all # Stop every scan (Temporal stays up). ./shannon reset # Stop everything and permanently remove all Temporal data (you must type confirm). ``` ## Usage examples [Section titled “Usage examples”](#usage-examples) * npx (recommended) ```bash # Basic pentest. npx @keygraph/shannon start -u https://example.com -r /path/to/repo # With a configuration file. npx @keygraph/shannon start -u https://example.com -r /path/to/repo -c /path/to/my-config.yaml # Custom output directory. npx @keygraph/shannon start -u https://example.com -r /path/to/repo -o ./my-reports # Named workspace. npx @keygraph/shannon start -u https://example.com -r /path/to/repo -w q1-audit # Stream the log until the scan finishes, then exit on its outcome (useful in CI). npx @keygraph/shannon start -u https://example.com -r /path/to/repo --follow # List running and completed scans. npx @keygraph/shannon scans ``` * Build from source ```bash ./shannon start -u https://example.com -r /path/to/repo ./shannon start -u https://example.com -r /path/to/repo -c /path/to/my-config.yaml ./shannon start -u https://example.com -r /path/to/repo -o ./my-reports ./shannon start -u https://example.com -r /path/to/repo -w q1-audit ./shannon start -u https://example.com -r /path/to/repo --follow ./shannon scans # Rebuild the worker image. ./shannon build --no-cache ``` See the [CLI reference](/docs/reference/cli/) for the full list of commands and flags. ## Output and results [Section titled “Output and results”](#output-and-results) Results are saved to the workspaces directory: * `./workspaces/` in source-build mode * `~/.shannon/workspaces/` in `npx` mode Use `-o ` to copy deliverables to a custom output directory after a run completes. Output structure. The run directory’s top level holds the final report, in PDF and Markdown; everything else is nested under a hidden `.shannon/` directory: ```text workspaces/{hostname}_{sessionId}/ |-- Security-Assessment-Report.pdf # the final report (PDF) |-- Security-Assessment-Report.md # the final report (Markdown) `-- .shannon/ # internals |-- deliverables/ # report source, per-phase analysis, queues |-- agents/ # per-agent logs |-- prompts/ # rendered prompts |-- scratchpad/ # screenshots, scripts |-- session.json # resume state `-- workflow.log ``` For workspace naming and resuming interrupted runs, see [Workspaces & Resuming](/docs/how-to/workspaces/). # Workspaces & Resuming > How Shannon stores scan state and how to resume interrupted runs. Shannon uses workspaces to store scan state, logs, prompts, and deliverables. Workspaces allow interrupted or failed runs to resume without re-running completed agents. ## How workspaces work [Section titled “How workspaces work”](#how-workspaces-work) * Every run creates a workspace. * Auto-named workspaces use the target hostname and a session ID, such as `example-com_shannon-1771007534808`. * `npx` mode stores workspaces in `~/.shannon/workspaces/`. * Source-build mode stores workspaces in `./workspaces/`. * Use `-w ` to give a run a custom name. * To resume a run, pass the same workspace name with `-w`. * Each agent’s progress is checkpointed so resumed runs can skip completed work. * The final report is surfaced at the workspace root as `Security-Assessment-Report.pdf` and `Security-Assessment-Report.md`. Run internals (deliverables, logs, prompts, and session state) live under a hidden `.shannon/` directory. ## Examples [Section titled “Examples”](#examples) * npx (recommended) Start with a named workspace: ```bash npx @keygraph/shannon start -u https://example.com -r /path/to/repo -w my-audit ``` Resume the same workspace (same command, same `-w` name): ```bash npx @keygraph/shannon start -u https://example.com -r /path/to/repo -w my-audit ``` Resume an auto-named workspace: ```bash npx @keygraph/shannon start -u https://example.com -r /path/to/repo -w example-com_shannon-1771007534808 ``` List running and completed scans: ```bash npx @keygraph/shannon scans ``` * Build from source Start with a named workspace: ```bash ./shannon start -u https://example.com -r /path/to/repo -w my-audit ``` Resume the same workspace (same command, same `-w` name): ```bash ./shannon start -u https://example.com -r /path/to/repo -w my-audit ``` Resume an auto-named workspace: ```bash ./shannon start -u https://example.com -r /path/to/repo -w example-com_shannon-1771007534808 ``` List running and completed scans: ```bash ./shannon scans ``` ## Workspace contents [Section titled “Workspace contents”](#workspace-contents) Each workspace directory holds the full record of a run. The top level holds the final report, in PDF and Markdown; everything else is nested under a hidden `.shannon/` directory: ```text workspaces/{hostname}_{sessionId}/ |-- Security-Assessment-Report.pdf # the final report (PDF) |-- Security-Assessment-Report.md # the final report (Markdown) `-- .shannon/ # internals |-- deliverables/ # report source, per-phase analysis, queues |-- agents/ # per-agent logs |-- prompts/ # rendered prompts |-- scratchpad/ # screenshots, scripts |-- session.json # resume state `-- workflow.log ``` # Shannon Reference > Exact, lookup-oriented facts about Keygraph and the Shannon CLI. Reference is **information-oriented**: precise, exhaustive, and dependable. It describes the machinery, it does not teach or persuade. For learning, see [Tutorials](/docs/tutorials/); for the reasoning behind a design, see [Explanations](/docs/explanations/). ## Available reference [Section titled “Available reference”](#available-reference) * **[CLI commands](/docs/reference/cli/)**: the Shannon commands, the `start` flags, and monitoring. * **[Environment variables](/docs/reference/environment-variables/)**: every variable Shannon reads, including the provider and model setting. * **[Configuration schema](/docs/reference/configuration-schema/)**: the config file field by field, with a full example. ## Coming soon [Section titled “Coming soon”](#coming-soon) * **API**: endpoints, authentication, and the finding record. * **Finding & verdict schema**: the artifact shape (proof-of-exploit, verdict, provenance). * **Supported languages & integrations**: coverage matrix. * **Self-hosting requirements**: deployment prerequisites. # CLI Commands > Reference for Shannon's command-line interface, commands, and flags. Shannon exposes the same commands through two entry points. Pick your entry point. The choice is remembered across the site. * npx (recommended) Prefix every command with `npx @keygraph/shannon`: ```bash npx @keygraph/shannon ``` Use `npx @keygraph/shannon@latest` for `setup` and `start` so npx runs the current release, not a cached older CLI. Run it with no command to open the interactive launcher, which prompts you to run `setup` the first time. * Build from source Run `./shannon` from your local clone: ```bash ./shannon ``` ## Commands [Section titled “Commands”](#commands) | Command | Description | | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | `setup` | Interactive wizard to configure AI provider credentials (`npx` mode). | | `start` | Run a pentest against a target. See flags below. | | `status [] [--json]` | Show live phase-by-phase progress. Defaults to the single running scan; add `--json` for a machine-readable snapshot. | | `logs []` | Tail a scan’s live log. Defaults to the single running scan, or the most recent workspace when none is running. | | `logs [] --agent ` | Tail one agent’s own log. Add `--list-agents` instead to list the available names. | | `scans [--json]` | List running and completed scans and where each report lives. | | `stop []` | Stop one scan (defaults to the single running scan). Prompts for confirmation; add `--yes` (or `-y`) to skip. | | `stop --all` | Stop every scan. Temporal stays up. Prompts for confirmation; add `--yes` to skip. | | `reset` | Stop everything and permanently remove all Temporal data. You must type `confirm` to proceed. | | `build [--no-cache]` | Build the worker image (source-build mode). Add `--no-cache` to skip the Docker layer cache. | | `version [--json]` | Print the Shannon version (also `-v`, `--version`). | | `help []` | Show usage help, or one command’s help page. Every command also accepts `-h` / `--help`. | ## `start` flags [Section titled “start flags”](#start-flags) Most flags have a short and a long form. | Flag | Argument | Description | | -------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `-u`, `--url` | URL | Target application URL (required). Use `host.docker.internal` for local apps. | | `-r`, `--repo` | path | Path to the target’s source repository (required, mounted read-only). Absolute or relative; a bare repo name also works in source-build mode. | | `-c`, `--config` | path | Path to a configuration YAML file. | | `--models-config` | path | Pi model config (`models.json`) for a model the harness catalogue does not carry. | | `-o`, `--output` | path | Copy deliverables to a custom output directory after the run. | | `-w`, `--workspace` | name | Named workspace (auto-resumes if it exists). | | `-f`, `--follow` | (none) | Stream the scan log until it finishes, then exit on the scan outcome (useful in CI). | | `--pipeline-testing` | (none) | Use minimal prompts for a fast test run. | | `--keep-container` | (none) | Preserve the worker container after exit for log inspection. | ## Examples [Section titled “Examples”](#examples) * npx (recommended) ```bash # Basic pentest. npx @keygraph/shannon@latest start -u https://example.com -r /path/to/repo # With a configuration file. npx @keygraph/shannon@latest start -u https://example.com -r /path/to/repo -c /path/to/my-config.yaml # Custom output directory. npx @keygraph/shannon@latest start -u https://example.com -r /path/to/repo -o ./my-reports # Named workspace. npx @keygraph/shannon@latest start -u https://example.com -r /path/to/repo -w q1-audit # Stream the log until the scan finishes, then exit on its outcome (useful in CI). npx @keygraph/shannon@latest start -u https://example.com -r /path/to/repo --follow # List running and completed scans. npx @keygraph/shannon scans ``` * Build from source ```bash ./shannon start -u https://example.com -r /path/to/repo ./shannon start -u https://example.com -r /path/to/repo -c /path/to/my-config.yaml ./shannon start -u https://example.com -r /path/to/repo -o ./my-reports ./shannon start -u https://example.com -r /path/to/repo -w q1-audit ./shannon start -u https://example.com -r /path/to/repo --follow ./shannon scans # Rebuild the worker image. ./shannon build --no-cache ``` ## Monitoring [Section titled “Monitoring”](#monitoring) * npx (recommended) ```bash npx @keygraph/shannon status [] # live phase-by-phase progress npx @keygraph/shannon status [] --json # one machine-readable snapshot npx @keygraph/shannon logs [] # the combined live log npx @keygraph/shannon logs [] --list-agents npx @keygraph/shannon logs [] --agent recon ``` * Build from source ```bash ./shannon status [] ./shannon status [] --json ./shannon logs [] ./shannon logs [] --list-agents ./shannon logs [] --agent recon ``` Every scan writes one combined `.shannon/workflow.log` and a per-agent projection of it under `.shannon/agents/`, one file per pipeline agent and per security code analysis stage. The combined log is canonical; the per-agent files are best-effort projections. Open the Temporal Web UI for detailed monitoring: ```bash open http://localhost:8233 ``` # Configuration Schema > Field-by-field reference for Shannon's YAML configuration file. This page documents the fields of Shannon’s YAML configuration file. For a guided walkthrough, see the [Configuration guide](/docs/how-to/configuration/). The schema rejects unknown top-level keys. The authoritative definition is [`config-schema.json`](https://github.com/KeygraphHQ/shannon/blob/main/apps/worker/configs/config-schema.json) in the Shannon repository. ## Top-level fields [Section titled “Top-level fields”](#top-level-fields) | Field | Type | Description | | --------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `description` | string | Free-text description of the target environment. Max 500 characters. | | `agentic_sast` | object | Opt in to multi-stage security code analysis. `enabled`: `"true"` or `"false"` (default `"false"`). It adds model time and cost. If it fails, the pentest continues and the scan finishes as partial. | | `exploit` | string | `"true"` (default) or `"false"`. Set `"false"` to skip the exploitation phase and run analysis only. | | `rules_of_engagement` | string | Free-form rules of engagement, rendered into every agent prompt. Max 1,000 characters. | | `authentication` | object | Login configuration for authenticated testing. | | `rules` | object | `avoid` and `focus` scope rules. | | `report` | object | Report filters and SARIF output. | Every scan runs all five analysis classes (Injection, Cross-Site Scripting, Authentication, Authorization, Server-Side Request Forgery). The class set has no configuration selector. Removed in 3.0 `vuln_classes` no longer exists. A config file that still sets it fails validation, so delete the key when upgrading from 2.x. ## `authentication` [Section titled “authentication”](#authentication) | Field | Description | | ------------------- | ---------------------------------------------------------- | | `login_type` | Login mechanism: `form`, `sso`, `api`, or `basic`. | | `login_url` | URL of the login page. | | `credentials` | Username, password, TOTP secret, and optional email login. | | `login_flow` | Ordered list of steps describing how to log in. | | `success_condition` | How Shannon confirms a successful login. | ### `credentials` [Section titled “credentials”](#credentials) | Field | Description | | ------------------------- | ------------------------------------------------- | | `username` | Test account username. | | `password` | Test account password. | | `totp_secret` | TOTP secret used to generate `$totp` codes. | | `email_login.address` | Mailbox address for magic-link / email-OTP flows. | | `email_login.password` | Mailbox password. | | `email_login.totp_secret` | Mailbox TOTP secret for `$email_totp`. | ### Login flow placeholders [Section titled “Login flow placeholders”](#login-flow-placeholders) `$username`, `$password`, `$totp`, `$email_address`, `$email_password`, `$email_totp`. See [Authenticated Testing](/docs/how-to/authenticated-testing/). ### `success_condition` [Section titled “success\_condition”](#success_condition) `type` is one of `url_contains`, `element_present`, `url_equals_exactly`, or `text_contains`. `value` is the string to match against. ```yaml success_condition: type: url_contains value: "/dashboard" ``` ## `rules` [Section titled “rules”](#rules) Contains `avoid` and `focus` lists. Each entry has a `description`, a `type`, and a `value`. Supported rule types: `url_path`, `subdomain`, `domain`, `method`, `header`, `parameter`, and `code_path`. `code_path` values are repo-relative file paths or globs. ```yaml rules: avoid: - description: "AI should avoid testing logout functionality" type: url_path value: "/logout" focus: - description: "AI should emphasize testing API endpoints" type: url_path value: "/api" ``` ## `report` [Section titled “report”](#report) | Field | Description | | ---------------- | --------------------------------------------------------------------------------------------------------------------------- | | `min_severity` | Minimum severity to include: `low`, `medium`, `high`, or `critical`. Applies in both exploitative and analysis-only runs. | | `min_confidence` | Minimum confidence to include: `low`, `medium`, or `high`. Applies only when `exploit` is `"false"`. | | `guidance` | Free-text guidance describing findings to drop. Max 500 characters. | | `sarif` | SARIF 2.1.0 log beside the report. On by default for exploit runs; `"false"` opts out. Ignored when `exploit` is `"false"`. | See [SARIF output](/docs/how-to/configuration/#sarif-output) for what the log contains. ## Full example [Section titled “Full example”](#full-example) ```yaml description: "Next.js e-commerce app on PostgreSQL. Local dev environment; .env files contain local-only credentials." # Every scan runs all five vulnerability classes. # agentic_sast: # enabled: "true" # exploit: "false" authentication: login_type: form login_url: "https://your-app.com/login" credentials: username: "test@example.com" password: "yourpassword" totp_secret: "LB2E2RX7XFHSTGCK" 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" focus: - description: "AI should emphasize testing API endpoints" type: url_path value: "/api" ``` # Environment Variables > Reference for the environment variables Shannon reads. Shannon reads configuration from environment variables (which always take precedence over saved config files). Set them in your shell with `export`, or in a `.env` file in source-build mode. ## Model and provider [Section titled “Model and provider”](#model-and-provider) | Variable | Description | | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | | `SHANNON_AI_MODEL` | The provider and model for the whole scan, as `:`. Default: `anthropic:claude-sonnet-4-6`. | | `SHANNON_AI_API_KEY` | Key for the provider that `SHANNON_AI_MODEL` names, or the gateway’s key when a base URL is set. | | `SHANNON_AI_BASE_URL` | Optional proxy or LLM gateway endpoint. It changes only where requests go. | | `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `XAI_API_KEY` | Native alternatives. When the selected provider’s variable is set, it is used instead of `SHANNON_AI_API_KEY`. | | `CLAUDE_CODE_OAUTH_TOKEN` | OAuth token accepted by the Anthropic provider. | A model the catalogue does not carry, including a local one, is described in a file passed with the `--models-config` flag rather than through an environment variable. See [Custom model configuration](/docs/how-to/ai-providers/#custom-model-configuration). ## AWS Bedrock [Section titled “AWS Bedrock”](#aws-bedrock) Select Bedrock with `SHANNON_AI_MODEL=amazon-bedrock:`. Bedrock uses bearer-token authentication only. | Variable | Description | | -------------------------- | ----------------------------- | | `AWS_REGION` | AWS region, e.g. `us-east-1`. | | `AWS_BEARER_TOKEN_BEDROCK` | Bedrock bearer token. | ## Subscriptions [Section titled “Subscriptions”](#subscriptions) | Variable | Description | | --------------------- | -------------------------------------------------------------------------------------------- | | `SHANNON_USE_PI_AUTH` | Set to `1` to reuse a Pi login for a ChatGPT Plus or Pro (Codex) or xAI (Grok) subscription. | ## Networking [Section titled “Networking”](#networking) | Variable | Description | | ----------------------- | ----------------------------------------------------------------------------------- | | `SHANNON_FORWARD_HOSTS` | Set to `false` to disable forwarding `/etc/hosts` custom hostnames into the worker. | ## Removed variables [Section titled “Removed variables”](#removed-variables) These no longer do anything. See [Upgrading from earlier versions](/docs/how-to/ai-providers/#upgrading-from-earlier-versions). | Removed | Replacement | | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | | `SHANNON_AI_OPENAI_FORMAT` (removed in 3.1) | None. An `openai:` model with a base URL always speaks OpenAI Responses. | | `ANTHROPIC_SMALL_MODEL`, `ANTHROPIC_MEDIUM_MODEL`, `ANTHROPIC_LARGE_MODEL` | A single `SHANNON_AI_MODEL`. | | `CLAUDE_CODE_USE_BEDROCK` | `SHANNON_AI_MODEL=amazon-bedrock:`. | | `ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN` | `SHANNON_AI_BASE_URL`. | | `CLAUDE_CODE_USE_VERTEX`, `CLOUD_ML_REGION`, `ANTHROPIC_VERTEX_PROJECT`, `GOOGLE_APPLICATION_CREDENTIALS` | None. Vertex AI is no longer supported; use Anthropic, Bedrock, or a custom base URL. | | `CLAUDE_CODE_MAX_OUTPUT_TOKENS`, `CLAUDE_ADAPTIVE_THINKING` | None. | See [AI Providers](/docs/how-to/ai-providers/) for full setup sequences and [Platforms & Networking](/docs/how-to/platforms/) for networking details. # Shannon Tutorials > Guided, start-to-finish lessons for getting started with Keygraph and Shannon. Tutorials are **learning-oriented**: they take you from zero to a working result by doing, with every step spelled out. For solving one specific task, see [How-to guides](/docs/how-to/); for exhaustive options, see [Reference](/docs/reference/). ## Start here [Section titled “Start here”](#start-here) * **[Quick Start](/docs/tutorials/quick-start/)**: run your first Shannon pentest with npx or a build from source, then find your first proof-of-exploit report. * **[Run Shannon in CI](/docs/how-to/ci-cd/)**: add the official [GitHub Action](https://github.com/KeygraphHQ/shannon-action) (`KeygraphHQ/shannon-action@v1`) or the [GitLab CI/CD component](https://gitlab.com/KeygraphHQ/shannon-ci) to run pull-request, release, and scheduled pentests, with severity gates that fail only on exploited findings. ## Coming soon [Section titled “Coming soon”](#coming-soon) * **Your first whitebox run**: point Shannon at your own source and validate an exploit against the running app. * **Read your first verdict**: interpret a proof-of-exploit and an exploitable-vs-confirmed-non-exploitable verdict. # Shannon Quick Start > Run your first Shannon pentest with npx or a build from source. There are two ways to run Shannon: the **`npx`** workflow (fastest, no clone) and a **build from source** using a local clone. Pick a tab below. Your choice is remembered across every page on this site. Authorized use only Shannon actively executes exploits. Run it only against applications and environments you own or have explicit written authorization to test. **Do not run Shannon against production systems.** See [Safety & Limitations](/docs/explanations/safety/). ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * **Docker**: required for the worker container. * **Node.js**: 18+ for the `npx` workflow, or 20.19+ for a build from source. * **pnpm**: required for a build from source. * **AI provider credentials**: Shannon runs on Anthropic, OpenAI, xAI, AWS Bedrock, and any other provider in the Pi harness catalogue, and any of them can point at a proxy or LLM gateway through a custom base URL. You bring your own key, and Keygraph never proxies your model traffic. See [AI Providers](/docs/how-to/ai-providers/). * **Cyber safeguards cleared with your provider**: Anthropic and OpenAI apply real-time safeguards to security workloads, which can stop a scan partway through. Complete their guidance for legitimate security testers before your first run. See [AI Providers](/docs/how-to/ai-providers/#cyber-safeguards-do-this-before-your-first-scan). ## Run Shannon [Section titled “Run Shannon”](#run-shannon) * npx (recommended) The quickest start is the interactive launcher, which walks you through setup and your first pentest: ```bash npx @keygraph/shannon@latest ``` Or run each step yourself: 1. **Configure credentials** with the interactive wizard: ```bash npx @keygraph/shannon@latest setup ``` 2. **Run a pentest** against a source-available target: ```bash npx @keygraph/shannon@latest start -u https://your-app.com -r /path/to/your-repo ``` Shannon pulls the worker image from Docker Hub, starts the required local infrastructure, mounts the target repository read-only inside an ephemeral worker container, and writes results to a local workspace. * Build from source 1. **Clone and build Shannon:** ```bash git clone https://github.com/KeygraphHQ/shannon.git cd shannon cp .env.example .env # add your SHANNON_AI_API_KEY and SHANNON_AI_MODEL pnpm install pnpm build ``` 2. **Run a pentest** against a source-available target: ```bash ./shannon start -u https://your-app.com -r /path/to/your-repo ``` See [Build from source & CLI](/docs/how-to/source-build/) for the full local-development workflow. The `-u` flag is the target URL. The `-r` flag is the path to the target’s source repository (mounted read-only inside the worker). Add `--follow` to stream the log in the same terminal until the scan finishes. ## What happens during a run [Section titled “What happens during a run”](#what-happens-during-a-run) Shannon runs autonomously through authentication validation (skipped when no login is configured), pre-reconnaissance, reconnaissance, per-class vulnerability analysis, exploitation, and reporting. If you enable [security code analysis](/docs/how-to/configuration/#security-code-analysis), its candidates are reconciled with the pentest’s own before exploitation. A full run typically takes **a few hours** and may incur LLM API costs depending on model pricing and application complexity. ## Monitor progress [Section titled “Monitor progress”](#monitor-progress) From another terminal, check live phase-by-phase progress, tail the log, or list scans. With no workspace given, `status` and `logs` follow the single running scan, or the most recent one when none is running. * npx (recommended) ```bash npx @keygraph/shannon status [] npx @keygraph/shannon logs [] npx @keygraph/shannon scans ``` * Build from source ```bash ./shannon status [] ./shannon logs [] ./shannon scans ``` For detailed, per-step monitoring, open the Temporal Web UI: ```bash open http://localhost:8233 ``` ## Find your report [Section titled “Find your report”](#find-your-report) Results are saved to the workspaces directory: `~/.shannon/workspaces/` in `npx` mode, or `./workspaces/` in source-build mode. The final report is written to the workspace root as a PDF and in Markdown: ```text workspaces/{hostname}_{sessionId}/Security-Assessment-Report.pdf workspaces/{hostname}_{sessionId}/Security-Assessment-Report.md ``` Exploit-mode runs also write `report.sarif` (SARIF 2.1.0) for GitHub code scanning or any SARIF consumer, alongside structured JSON. Run internals (deliverables, logs, prompts, and session state) live under a hidden `.shannon/` directory inside the workspace. Use the `-o ` flag to copy deliverables to a custom output directory after a run completes. ## Stop Shannon [Section titled “Stop Shannon”](#stop-shannon) * npx (recommended) ```bash npx @keygraph/shannon stop [] # Stop one scan (defaults to the single running scan; confirms first, add --yes to skip). npx @keygraph/shannon stop --all # Stop every scan (Temporal stays up). npx @keygraph/shannon reset # Stop everything and permanently remove all Temporal data (you must type confirm). ``` * Build from source ```bash ./shannon stop [] # Stop one scan (defaults to the single running scan; confirms first, add --yes to skip). ./shannon stop --all # Stop every scan (Temporal stays up). ./shannon reset # Stop everything and permanently remove all Temporal data (you must type confirm). ``` A stopped or interrupted scan resumes when you re-run `start` with the same `-w` workspace name. See [Workspaces & Resuming](/docs/how-to/workspaces/). ## Next steps [Section titled “Next steps”](#next-steps) * Run Shannon on pull requests, releases, or a schedule with [CI/CD integrations](/docs/how-to/ci-cd/). * Test a login-gated application with the [Configuration](/docs/how-to/configuration/) and [Authenticated Testing](/docs/how-to/authenticated-testing/) guides. * Prefer running from a local clone? See [Build from source & CLI](/docs/how-to/source-build/). * Testing an app on your own machine? See [Platforms & Networking](/docs/how-to/platforms/) for the `host.docker.internal` workaround.