feat: Shannon 3.0 Agentic SAST (#433)

* feat(worker): add agentic static analysis Add the ten-stage Agentic SAST pipeline, confined repository tools, model runtime, prompt templates, and SARIF export. Make retries, repair sessions, reduced coverage, usage accounting, and model-output drift durable across Temporal replay and resume. Keep retry diagnostics in their actionable closed vocabulary. Package the Mantis-derived license material with the prompts that require it. * feat(worker): deduplicate static and runtime findings before exploitation Parse Agentic SAST SARIF into typed observations, enrich and route those observations, and reconcile them with pentest findings before exploitation. Publish deterministic exploitation queues with stable lineage, exact-path Git commits, retry-safe manifests, named drop reasons, and confined task formation. Reject duplicate producer IDs before commit and adopt either legal provenance shape after a lost acknowledgement. * feat(config)!: replace vuln_classes with agentic_sast Wire Agentic SAST and reconciliation into the main pipeline, persist their durable state, and add the Miscellaneous finding and exploitation lane. Make scan completion, cancellation, partial outcomes, resume identity, and report recovery use the integrated final workflow contract. Introduce the atomic finalization, ordering, renumbering, compaction, and output services that workflow calls. Keep completed Miscellaneous work and report drafts idempotent across resume, preserve public main's default-on exploit SARIF behavior, and describe stage-fallback candidates without claiming they were exported. BREAKING CHANGE: `vuln_classes` has been removed. Configs containing it now fail validation, and all five core pentest classes run on every scan. Workspaces created by Shannon 2.x cannot be resumed. Finish or discard in-flight scans before upgrading, then start a new workspace name. * perf: overlap static analysis and the Miscellaneous lane with the pentest Run Agentic SAST alongside vulnerability analysis and run Miscellaneous exploitation alongside the specialist exploitation lanes. Keep reconciliation dependent on the completed static-analysis result while preserving parallel work everywhere that has no data dependency. * feat(cli)!: default the scan target and add a JSON error contract List local scans, resolve the active or most recent workspace automatically, and make logs, status, and stop use one canonical scan identity. Add stable machine-readable failures, richer status output, explicit help errors, and seven-day Temporal retention. Treat absent Temporal pending-activity failures as absent whether the decoder represents them as `null` or missing. BREAKING CHANGE: `status --json` now returns a fixed `failureMessage`. Read `partialReasons`, `agenticSast`, and `workflow.log` for diagnostic detail. * feat(logging): trace tool calls and write a log per agent Record complete tool-call arguments in the workflow log and project each agent's events into its own durable log. Add agent listing and agent-specific log tailing while preserving byte-exact output and draining log handles before activities return. * feat(worker): standardize severity and reporting guidance in exploit prompts Give every exploit agent the same status, confidence, severity-reasoning, report-writing, credential-handling, and scope contract. Apply the same task-formation and SAST-enrichment procedure to the Miscellaneous lane. * feat(worker): disclose scan coverage and make reporting auditable Build on the retry-safe finalization foundation to preserve correct identities, source locations, scan dates, partial-coverage limitations, and consistent report JSON, Markdown, SARIF, and PDF output. Report Agentic SAST, reconciliation wall-clock time, stage usage, retry spend, and background work without duplicate or hardcoded totals. Keep report findings canonical, drop cross-class restatements, name enrichment losses, and render the executive-summary narrative in the PDF. * chore(license): attribute Mantis and Pi and refresh the docs Add the final Mantis and Pi notices, license copies, acknowledgements, and residual copyright updates. Update the README, maintained documentation, contributor guidance, and hand-maintained mirrors to describe Agentic SAST, reconciliation, the Miscellaneous lane, current CLI behavior, and the final release contract. Correct stale workspace and container guidance and annotate long-standing internals for maintainers. * fix(logging): treat a slash as a word separator in agent labels * feat(cli)!: rebuild scan status around model work - show Capella stages beneath the concurrent Agentic SAST phase - attach reconciliation time to the class row it feeds - hide completed bookkeeping and the duplicate miscellaneous wrapper - carry validated child-workflow progress into durable parent state - derive the terminal tree and status JSON from the same phase shape BREAKING CHANGE: `status --json` replaces phase `parallel` with `children` and `meta`, adds phase summaries and notes plus agent attachment fields, and removes the `analysis-engines` and `operational-work` phases. * fix(report): drop the empty Critical Findings section from the PDF summary * fix(sast): align Capella export with the submit-time code-path contract The export gate required every code_paths entry to be file:line, but submit only requires the primary sink to be file:line and accepts bare trace steps. A single malformed trace step therefore dropped an otherwise-valid finding at export. - add isValidPrimaryCodePath as the one shared primary-sink contract - validate only the primary at export; buildResult already drops unusable steps - route the submit-time validator through the same helper so the two cannot drift * feat(sast): tolerate hygiene-only Capella reductions instead of going partial A reduction only makes a run partial when it loses real coverage or a whole finding. Malformed model output, salvaged turn-limit work, and rejected duplicate verdicts are recorded as evidence but no longer flip the run to partial. - add reductionIsTolerable: partial only when genuine-loss counts are nonzero - drive runCapella's partial reasons and display coverage off non-tolerable ones - keep every reduction in agenticSast.reductions so nothing is lost as evidence * feat(logging): record the provider reason for a failed agent turn A failed provider turn collapsed to AGENT_EXECUTION_FAILED/unknown with the underlying reason discarded, so a model-side rejection or safeguard was indistinguishable from a transport fault in the error log. - add safeProviderTurnDetails: write bounded, non-sensitive fields (provider, model, responseId, stop reason, tool-in-flight, category, retryable) to error.log - gate a sanitized errorMessage snippet behind SHANNON_DEBUG_PROVIDER_ERRORS, off by default - forward SHANNON_DEBUG_PROVIDER_ERRORS from the CLI into the worker container * fix(cli): keep shannon logs tailing through a Temporal blip - End the interactive tail on the log's own terminal marker or Ctrl-C, so a transient Temporal outage no longer aborts the command with exit 1. - Rebuild the memoized Temporal client after a failed poll: a wedged gRPC channel was cached forever, so "retrying…" could never reconnect. - Keep start --follow (CI) bounded — a genuinely dead Temporal still fails the run instead of hanging. * fix(worker): correct PDF finding reporting - Render OWASP category, authentication state, and remediation - Omit the redundant per-finding exploited status - Preserve canonical category and field ordering across report modes - Continue Proof of Impact numbering across embedded code blocks - Wrap long PDF code lines without changing canonical report content * fix: attribute a reconciliation failure to exploitation only - Stop marking a class's vulnerability-analysis agent failed when that agent succeeded and only reconciliation failed; the status tree now renders the analysis row completed and the exploitation row failed - Consume the worker's failedReconciliations signal in the CLI, which the mirrored PipelineState already declared but never read - Correct the class_reconciliation_failed message, which claimed the class's analysis results were still in the report when the class is excluded from it * fix(pi): give each task sub-session its own resource loader to prevent stale extension ctx * fix(prompts): scope exploit agents to in-band proof, mark OOB-only findings blocked * fix(cli): reject a shell credential that shadows a gateway config.toml key * fix(cli): make scan shutdown verifiable - preselect and persist workflow identity before worker launch - cancel first, then verify bounded Temporal termination - reconcile Docker workers with Temporal open workflows - fail closed on stale images and unavailable lifecycle state - mark cancellation only after confirmed shutdown * feat(cli): prompt for setup on a bare npx invocation with no credentials * fix(cli): don't blame anthropic when no credentials are configured at all * chore(release): bump beta base version to 3.0.0 * feat(cli): show a 'start your first scan' box in help on a TTY * docs: refresh README and platform overview for Shannon 3.0 - lead with the 3.0 launch note and rewrite key capabilities around security code analysis, the rebuilt terminal experience, native CI/CD, and PDF/SARIF - recast the editions table as Shannon Open Source against the Keygraph Enterprise Platform, stating open source is not a trial edition - rewrite the platform overview around exhaustive agentic SAST, canonical findings, automated remediation, targeted verification, and governance - add five product screenshots under assets/keygraph-platform/, referenced relative to docs/ * docs: add the Shannon naming section and swap in the 3.0 demo GIF - explain the Claude Shannon information-theory origin under "What is Shannon?" - point "Shannon in Action" at the 3.0 recording in assets/Shannon3GIF.gif Both taken from the README half of #438. * docs: document CI/CD integrations and the reconciled analysis pipeline - add a CI/CD Integrations section covering the official GitHub Action and GitLab component, pipeline artifacts, and exploit-only severity gates - redraw the architecture section as a Mermaid flow: agentic code analysis and recon feed finding reconciliation, then exploitation and reporting - describe open-source code analysis as a multi-stage agentic workflow and reserve parsed-code CPGs and exhaustive verification for Enterprise - sharpen the privacy wording: results stay local, but model requests carry source context to whichever endpoint you configure - drop the "not recommended" framing on local models and add a section on why Shannon complements rather than replaces human pentesters - regenerate llms-full.txt from the updated README and docs * docs: add the Photoview benchmark across three models - Add a "Shannon in Action" table for Photoview 2.4.0 runs on DeepSeek v4 Flash, Grok 4.6, and Claude Opus 5, each linking its PDF report and SARIF output - Store the per-model reports under benchmark/ - Link the (forthcoming) benchmark writeup from the section intro * docs: add the Shannon vs XBOW/Aikido Photoview benchmark writeup - Add docs/shannon-xbow-aikido-benchmark.md with methodology, per-model cost/coverage tables, and links to each model's report and SARIF - Link the writeup from the README "Shannon in Action" section * docs: link the benchmark announcement discussion from the README * fix(readme): restore theme-aware banner, badge, and buttons * feat!: trigger the Shannon 3.0 major release --------- Co-authored-by: ezl-keygraph <ezhil@keygraph.io>
2026-09-16 06:55:37 +02:00 · 2026-09-02 14:34:26 +05:30
parent 6108de3cfc
commit 9767ebe633
267 changed files with 127389 additions and 3268 deletions
@@ -42,8 +42,11 @@ Source-build equivalent:
 # Describe your target environment.
 description: "Next.js e-commerce app on PostgreSQL. Local dev environment; .env files contain local-only credentials."

-# Limit which vulnerability classes run end-to-end.
-# vuln_classes: [injection, xss, auth, authz, ssrf]
+# Every scan runs all five vulnerability classes.
+
+# Agentic static analysis. `enabled` is its only setting.
+# agentic_sast:
+#   enabled: "true"

 # Skip the exploitation phase.
 # exploit: "false"
@@ -102,6 +105,25 @@ rules:
 #   sarif: "false"
 ```

+## Analysis Scope and Agentic SAST
+
+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.
+
+Agentic static analysis is opt-in:
+
+```yaml
+agentic_sast:
+  enabled: "true"
+```
+
+`enabled` is the only setting. Omitting the block, or setting `enabled: "false"`, turns agentic static analysis off;
+`"true"` turns it on. Either way, all five vulnerability classes still run.
+
+Agentic static analysis reads the repository for vulnerabilities before the pentest and passes what it finds into the
+exploitation phase. It adds model time and cost. If it fails, the pentest continues without its findings and the scan
+finishes as "partial".
+
 ## Report Options

 | Key | Effect |
@@ -122,7 +144,9 @@ report:
  sarif: "false"
 ```

-Each finding becomes one SARIF result, filed under a rule per vulnerability class (`shannon/injection`, `shannon/xss`, `shannon/auth`, `shannon/authz`, `shannon/ssrf`) 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`, everything else becomes `note`.
+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`, everything else becomes `note`.
+
+If the SARIF log cannot be written, the JSON and Markdown reports are still produced and the scan finishes as "partial".

 The log is written only for exploitative runs. `sarif` is ignored when `exploit` is `"false"`.

@@ -57,21 +57,31 @@ The target repository is mounted read-only inside the worker container.
 Monitor progress:

 ```bash
-npx @keygraph/shannon logs <workspace>
-npx @keygraph/shannon status <workspace>
+npx @keygraph/shannon logs [<workspace>]     # defaults to the single running scan, else the most recent
+npx @keygraph/shannon status [<workspace>]   # same default target; add --json for a machine-readable snapshot
 npx @keygraph/shannon scans
 npx @keygraph/shannon version
 ```

+With no workspace, `logs` and `status` follow the single running scan; when several are running, name one.
+
 Source-build equivalents:

 ```bash
-./shannon logs <workspace>
-./shannon status <workspace>
+./shannon logs [<workspace>]                 # the combined live log (unchanged default)
+./shannon logs [<workspace>] --agent <name>  # tail one agent's own log
+./shannon logs [<workspace>] --list-agents   # list the agents with their own log
+./shannon status [<workspace>]
 ./shannon scans
 ./shannon version
 ```

+Every scan writes one combined `.shannon/workflow.log` and a per-agent projection of it under
+`.shannon/agents/`: one file per pipeline agent (`recon.log`, `xss-vuln.log`, …) and one per Capella
+stage (`agentic-sast-research.log`, …). Delegated subagents fold into their parent's file, and a
+Capella stage's concurrent sessions share its file with an inline session label. The combined log
+stays canonical; the per-agent files are best-effort projections.
+
 Open the Temporal Web UI for detailed monitoring:

 ```bash
@@ -81,7 +91,7 @@ open http://localhost:8233
 Stop Shannon:

 ```bash
-npx @keygraph/shannon stop <workspace>   # stop one scan (confirms first; add --yes/-y to skip)
+npx @keygraph/shannon stop [<workspace>] # stop one scan (defaults to the single running scan; confirms first; add --yes/-y to skip)
 npx @keygraph/shannon stop --all         # stop all scans (Temporal stays up)
 npx @keygraph/shannon reset              # stop everything and wipe all Temporal data (type 'confirm' to proceed; cannot be skipped)
 ```
@@ -89,7 +99,7 @@ npx @keygraph/shannon reset              # stop everything and wipe all Temporal
 Source-build equivalents:

 ```bash
-./shannon stop <workspace>               # stop one scan (confirms first; add --yes/-y to skip)
+./shannon stop [<workspace>]             # stop one scan (defaults to the single running scan; confirms first; add --yes/-y to skip)
 ./shannon stop --all                     # stop all scans (Temporal stays up)
 ./shannon reset                          # stop everything and wipe all Temporal data (type 'confirm' to proceed; cannot be skipped)
 ```
@@ -112,7 +122,7 @@ 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 completed scans.
+# List running and completed scans.
 npx @keygraph/shannon scans
 ```

@@ -147,7 +157,7 @@ workspaces/{hostname}_{sessionId}/
 |-- Security-Assessment-Report.md   # the final report (Markdown)
 `-- .shannon/                       # internals
    |-- deliverables/               # report source, per-phase analysis, queues
-    |-- agents/                     # per-agent logs
+    |-- agents/                     # per-agent log projections, one file per agent/Capella stage
    |-- prompts/                    # rendered prompts
    |-- scratchpad/                 # screenshots, scripts
    |-- session.json                # resume state
@@ -1,94 +1,133 @@
-# Keygraph Platform
+# Keygraph Enterprise Platform

-The Keygraph platform is Keygraph's commercial continuous pentesting and AppSec platform for teams running security across many repositories, services, and environments. While Shannon is a local white-box pentesting CLI, the Keygraph platform is a complete AppSec system: it combines parsed-code SAST, source-to-sink analysis, black-box and white-box agentic pentesting, verified remediation, CI/CD gating, SLA tracking, and reporting for security and compliance teams.
+Shannon 3.0 makes advanced, code-informed autonomous pentesting available to everyone. The open-source CLI maps routes and data flows, understands application architecture, executes real attacks, and produces PDF and SARIF results—locally, in CI/CD, or fully air-gapped with your own model.

-This repository contains Shannon, the AGPL-3.0 open-source CLI for strictly white-box pentesting. The Keygraph platform supports both white-box and black-box agentic pentesting and adds static analysis, finding management, remediation workflows, reporting, and enterprise deployment options.
+The **Keygraph Enterprise Platform** is the commercial AppSec operating system for organizations that need to run that process continuously across many repositories, teams, and environments. It adds exhaustive agentic SAST, business-logic and source-to-sink analysis, broader scanner coverage, centralized vulnerability management, automated remediation and targeted verification, enterprise governance, and organization-wide reporting.

-## Who Should Consider the Keygraph Platform
+> Shannon Open Source is a complete autonomous pentester, not a trial edition. Keygraph Enterprise is for teams that need greater analysis depth, shared control, and a closed-loop vulnerability-management program.

-The Keygraph platform is intended for organizations that need:
+## Who It Is For

- Continuous AppSec coverage across many repositories and services
- White-box pentesting when source code is available
- Black-box pentesting against deployed applications and APIs without source-code access
- Agentic SAST, SCA with reachability, secrets scanning, IaC scanning, container scanning, and business logic testing
- Canonical finding management, deduplication, ownership, status tracking, and severity tracking
- Sync into developer workflows, including ticketing and source-control systems
- User-initiated remediation with verification before delivery
- SLA tracking, reporting dashboards, and compliance evidence
- Commercial support
- Self-hosted, air-gapped, BYOK, and customer-controlled LLM gateway deployment options
+Keygraph Enterprise is designed for organizations that need to:

-## Full Vulnerability Lifecycle
+- continuously test hundreds or thousands of repositories, services, applications, and APIs;
+- combine agentic pentesting, SAST, SCA, secrets, and business-logic findings in one system;
+- enforce security policy in GitHub Actions, GitLab CI, and enterprise delivery pipelines;
+- give developers one canonical, actionable record for each vulnerability instead of duplicate scanner alerts;
+- assign owners, apply SLAs, track status, and measure risk and remediation performance across the organization;
+- generate fixes and verify them without rerunning an entire scan;
+- enforce enterprise identity, authorization, audit, and API-access controls; and
+- deploy fully on-premises or air-gapped with customer-controlled models, keys, and routing.

-The Keygraph platform is designed to cover the full vulnerability lifecycle, not only discovery:
+## Close the Entire AppSec Loop

-1. **Find** exploitable issues with white-box pentesting, black-box pentesting, SAST, SCA, secrets, IaC, container, and business logic testing.
-2. **Normalize** results into canonical findings so duplicate scanner outputs become one tracked vulnerability per repository.
-3. **Prioritize** findings using exploit evidence, reachability, severity, ownership, and business context.
-4. **Sync** work into developer workflows through ticketing and source-control integrations.
-5. **Remediate** with user-initiated patch generation when teams want help moving from evidence to code changes.
-6. **Verify** fixes by re-running the relevant scanner or exploit workflow before a remediation is delivered.
-7. **Track** ownership, status, SLAs, MTTR, and drift over time.
-8. **Report** through dashboards for risk, trends, compliance evidence, and security program operations.
+The platform connects discovery, triage, remediation, and verification in one continuous workflow:

-## Pentesting Modes
+1. **Analyze** every repository with exhaustive agentic SAST and complementary scanners.
+2. **Prove** exploitability with source-aware white-box, black-box, and grey-box pentesting.
+3. **Normalize and deduplicate** results into a canonical finding per vulnerability and repository.
+4. **Prioritize and assign** using severity, reachability, exploit evidence, ownership, policy, and business context.
+5. **Remediate** with an AI-authored patch delivered as a reviewable pull request.
+6. **Verify** the specific fix with deterministic checks and adversarial agent reasoning—without rerunning the full scan.
+7. **Track and govern** status, exceptions, SLAs, audit history, trends, and compliance evidence until closure.

-Shannon is strictly white-box: it requires access to the target application's source code and repository layout.
+## Exhaustive Agentic SAST

-The Keygraph platform supports two pentesting modes:
+Shannon 3.0's open-source code analysis runs a multi-stage agentic workflow. It models application architecture, trust boundaries, exposed interfaces, and data flows, opens targeted investigations, reviews the candidates they turn up, and hands the survivors to live pentesting agents. That workflow is built for practical local and CI/CD runs.

- **White-box agentic pentesting**: Agents use source-code context to understand architecture, identify realistic attack paths, and validate exploitability against the running application.
- **Black-box agentic pentesting**: Agents test deployed applications and APIs without source-code access, useful for third-party surfaces, production-like external validation, or environments where source access is unavailable.
+The Enterprise engine goes further, for audits at organization scale. It parses the codebase and builds persistent structural context before agents start reasoning about security:

-Both modes follow the same core principle: do not report what might be vulnerable when an exploit can prove what is vulnerable.
+- **Repository and architecture modeling** identifies services, frameworks, entry points, assets, trust boundaries, and cross-repository relationships.
+- **Interprocedural call and data-flow analysis** traces values across functions, files, fields, containers, and framework-managed request lifecycles.
+- **Source, sink, and sanitizer modeling** follows untrusted input to sensitive operations and records where validation, encoding, authorization, or other controls alter the path.
+- **Threat-driven decomposition** breaks large applications into risk, taint-flow, framework, and specialist analysis tasks so deep scans remain systematic.
+- **Exhaustive adversarial verification** challenges candidates across multiple review passes, weighing structural evidence against what the agents found, then asks whether each one is viable in the application's production configuration.
+- **Semantic deduplication and exploit-chain analysis** consolidate variants of the same defect and identify combinations whose impact is greater than any isolated issue.
+- **Business-logic invariant testing** derives rules the code is supposed to preserve—such as tenant isolation, workflow order, approval limits, balances, and state transitions—then agents fuzz those invariants for application-specific flaws.

-## AppSec Coverage
+The result is broad vulnerability hunting with precise paths back to the relevant code, not a flat list of pattern matches.

-The Keygraph platform combines agentic pentesting with broader AppSec coverage:
+<p align="center">
+  <img src="../assets/keygraph-platform/agentic-sast-results.png" alt="Keygraph Enterprise SAST results grouped into business-logic issues, point issues, and secrets" width="100%">
+</p>

- **Agentic SAST**: Code Property Graph analysis with LLM reasoning for data flow, context, and sanitization decisions.
- **SCA with reachability**: Dependency vulnerability analysis that prioritizes issues reachable from application entry points.
- **Secrets scanning**: Detection and validation of credentials, tokens, and API keys.
- **Business logic testing**: Authorization bypass, IDOR, workflow abuse, state-machine flaws, race conditions, and other application-specific logic issues.
- **IaC scanning**: Terraform, CloudFormation, Kubernetes, Helm, and related infrastructure configuration checks.
- **Container scanning**: Vulnerable packages, exposed secrets, and misconfigurations across image layers.
+## Complete Application-Security Coverage

-## Static-Dynamic Correlation
+Agentic SAST and pentesting work alongside additional first-class scanners:

-Static-dynamic correlation is a core product difference. A static finding, such as unsanitized input reaching a SQL query, is not treated as a purely theoretical issue. It is sent to an exploit agent, tested against the live application, and traced back to the exact source-code location when confirmed.
+- **SCA with reachability** prioritizes vulnerable dependencies that application code can actually reach.
+- **Full secrets scanning** detects credentials, tokens, and keys across source and repository history.
+- **Agentic pentesting** correlates code intelligence with live application behavior and attempts real exploitation. The core rule remains: no exploit, no pentest finding.

-The result is a finding with proof of exploitability, source context when available, ownership, status, SLA, remediation history, and reporting metadata.
+## One System of Record for Every Finding

-## Enterprise Deployment
+Keygraph ingests results from every analysis source, correlates them, and maintains one canonical finding per vulnerability per repository. Security and engineering teams work from the same record, with evidence, source location, severity, scan history, status, assignee, resolution, and last-verification state.

-The Keygraph platform supports enterprise deployment patterns for teams with strict data, model, and network requirements:
+The vulnerability-management layer provides:

- **Self-hosted deployments** inside the customer's cloud or infrastructure
- **Air-gapped deployments** for isolated environments
- **Strict BYOK model access** using customer-managed model credentials
- **Customer-controlled LLM gateway patterns** for routing, policy, logging, and isolation
- **Enterprise identity and provisioning** such as SSO and SCIM
- **Deep integrations** with source control, ticketing, chat, registries, and cloud environments
+- deterministic and semantic deduplication across scans and scanners;
+- ownership, assignment, triage, false-positive, risk-acceptance, and resolution workflows;
+- SLA policies, escalation, aging, and last-verified tracking;
+- bidirectional developer-workflow integrations and APIs;
+- dashboards for risk, coverage, trends, new versus resolved findings, SLA compliance, and MTTR; and
+- exportable evidence for customers, auditors, and compliance programs.

-Deployments can be designed so source code, scan results, prompts, completions, and model traffic remain inside the customer's security perimeter.
+<p align="center">
+  <img src="../assets/keygraph-platform/canonical-findings.png" alt="Keygraph Enterprise canonical findings inventory with severity, status, source, and verification filters" width="100%">
+</p>

-## Capability Comparison
+## Remediate, Then Verify the Fix

-| Need | Shannon | Keygraph platform |
+From an individual finding, a user can ask Keygraph to produce a focused patch. The remediation agent reasons from the root cause and evidence, changes only the required code, and opens a pull request into the existing review process. It does not silently apply fixes to a protected branch.
+
+<p align="center">
+  <img src="../assets/keygraph-platform/automated-remediation.png" alt="Keygraph Enterprise remediation workflow for generating a fix and opening a pull request" width="100%">
+</p>
+
+After a patch is available, targeted verification re-analyzes the affected code and, for dynamic pentest findings, re-tests the original proof of concept against the target. Deterministic checks and adversarial agent reasoning produce a clear verdict without the cost and delay of rerunning the entire scan.
+
+<p align="center">
+  <img src="../assets/keygraph-platform/targeted-verification.png" alt="Keygraph Enterprise targeted finding-verification workflow" width="100%">
+</p>
+
+## Enterprise Governance and Integrations
+
+Keygraph is built for shared operation across security, platform, and engineering teams:
+
+- SAML 2.0 or OIDC single sign-on and SCIM provisioning;
+- organization, team, and user management;
+- built-in and custom roles with granular relationship-, attribute-, and role-based authorization (ReBAC, ABAC, and RBAC);
+- repository, pentest-profile, scanner, finding, and administration boundaries;
+- full audit logging and scoped API keys;
+- integrations with source control, CI/CD, ticketing, chat, and cloud environments; and
+- commercial support and enterprise onboarding.
+
+<p align="center">
+  <img src="../assets/keygraph-platform/enterprise-access-control.png" alt="Keygraph Enterprise granular roles and repository visibility controls" width="100%">
+</p>
+
+## On-Premises, Air-Gapped, and Customer-Controlled AI
+
+Keygraph Enterprise can run entirely inside your AWS, GCP, Azure, or on-premises environment, including networks with no public internet access. Deployments can keep source code, scan artifacts, findings, prompts, completions, and model traffic inside your security perimeter.
+
+AI access is bring-your-own-key and bring-your-own-model. Organizations can route workloads through approved commercial providers, private cloud endpoints, an internal LLM gateway, or local open-source models, with granular routing and policy controlled by the customer. There is no requirement for a Keygraph-operated control plane or model proxy.
+
+Keygraph maintains a SOC 2 Type II audit and makes the current report available to customers under appropriate confidentiality terms.
+
+## Shannon 3.0 vs. Keygraph Enterprise
+
+| | Shannon Open Source | Keygraph Enterprise Platform |
 | --- | --- | --- |
-| Licensing | AGPL-3.0 | Commercial |
-| White-box pentesting | Yes; source code required | Yes; source-aware testing with platform workflows |
-| Black-box pentesting | No | Yes; autonomous testing without source-code access |
-| Code analysis / SAST | Prompting and source pass-through to guide pentesting | Actual code parsing, Code Property Graph analysis, source-to-sink path analysis, and agentic SAST |
-| AppSec coverage | OWASP-focused agentic pentesting | Agentic pentesting, SAST, SCA, secrets, IaC, containers, and business logic testing |
-| CI/CD and gating | Manual/local CLI runs | Headless commercial CLI for CI/CD gating across enterprise CI/CD platforms |
-| Finding lifecycle | Local Markdown reports | Canonical findings, deduplication, ownership, status, SLA tracking, workflow sync, and reporting dashboards |
-| Remediation | Manual | User-initiated remediation with verification before delivery |
-| Fix verification | None; manual reruns only | Targeted verification without rerunning the entire scan, completing the remediation lifecycle |
-| Enterprise deployment | Local CLI and Docker worker | Self-hosted, air-gapped, BYOK, and customer-controlled LLM gateway options |
-| Support | Community | Commercial support |
+| Best for | Individual developers and teams running pentests locally or in CI/CD | Security organizations running a continuous AppSec program across many teams and repositories |
+| Code analysis | Multi-stage agentic review maps architecture, trust boundaries, exposed interfaces, and data flows, filters candidate vulnerabilities, and hands the survivors to live pentesting agents | Exhaustive parsed-code analysis: persistent Code Property Graphs, interprocedural source-to-sink and sanitizer modeling, cross-repository context, exploit-chain analysis, and business-logic invariant testing |
+| Pentesting | On-demand, source-aware white-box pentesting with proof by exploitation | Continuous white-box, black-box, and grey-box pentesting across applications and environments |
+| Additional AppSec coverage | Not included | SCA with reachability, secrets scanning, and business-logic invariant testing |
+| CI/CD and reporting | Official GitHub Action and reusable GitLab CI/CD component; staging, release, merge-request, and scheduled pentests; demonstrated-vulnerability severity gates; PDF, Markdown, JSON, SARIF, artifacts, and native security-workflow ingestion | Organization-wide policies and gating, centrally managed integrations, canonical findings, dashboards, analytics, SLA tracking, and compliance evidence |
+| Automated remediation and verification | Not included | AI-authored pull requests with targeted code and exploit verification |
+| Enterprise governance | N/A — local, single-operator CLI | SSO, SCIM, teams, ReBAC/ABAC/RBAC, audit logs, API keys, ownership, and SLA policies |
+| Deployment and AI | Self-hosted, no telemetry, BYOM, and fully air-gapped with a local model | Fully on-premises or air-gapped, BYOK/BYOM, and granular routing through customer-controlled gateways |
+| License and support | AGPL-3.0 and community support | Commercial license, enterprise support, and SOC 2 Type II controls |

-## Contact
+## Talk to Keygraph

-Learn more on the [Keygraph website](https://keygraph.io), start a free trial, book a [Keygraph demo](https://cal.com/team/keygraph/shannon-pro), or contact [shannon@keygraph.io](mailto:shannon@keygraph.io).
+Visit [keygraph.io](https://keygraph.io), book a [Keygraph demo](https://cal.com/team/keygraph/shannon-pro), or contact [shannon@keygraph.io](mailto:shannon@keygraph.io).
@@ -0,0 +1,137 @@
+**TL;DR.** Doyensec recently published a side-by-side of Aikido and XBOW on two open-source apps. We ran Shannon v3, our open-source pentester, against the same Photoview deployment with three different models. All three caught the critical SQL injection; the cheapest run cost $6.10 in tokens. The Claude Opus 5 run found 23 verified issues for $115, against Aikido's 32 and XBOW's 7 at $4,000 each. 
+
+| Model | Report | SARIF |
+| --- | --- | --- |
+| DeepSeek v4 Flash | [View report](../benchmark/photoview-deepseek-v4-flash.pdf) | [SARIF](../benchmark/photoview-deepseek-v4-flash.sarif) |
+| Grok 4.6 | [View report](../benchmark/photoview-grok-4-6.pdf) | [SARIF](../benchmark/photoview-grok-4-6.sarif) |
+| Claude Opus 5 | [View report](../benchmark/photoview-opus-5.pdf) | [SARIF](../benchmark/photoview-opus-5.sarif) |
+
+|  | Shannon v3 (DeepSeek v4 Flash) | Shannon v3 (Grok 4.6) | Shannon v3 (Claude Opus 5) | Aikido | XBOW |
+| --- | --- | --- | --- | --- | --- |
+| Cost | $6.10 | $35.07 | $115 | $4,000 | $4,000 |
+| Scan time | 2h 37m | 5h 26m | 2h 24m | < 8h | ~2 days |
+| Reported | 18 | 10 | 24 | 32 | 7 |
+| True positives | 18 | 10 | 23 | 32 | 7 |
+| False positives | 0 | 0 | 1 | 0 | 0 |
+| Severity agreement | 72% | 50% | 62% | 66% | 57% |
+
+# Introduction
+
+In Comparing AI Application Security Testing Platforms, an Aikido-sponsored study, Doyensec ran Aikido's Attack AI Pentest and XBOW's Lightspeed against two randomly selected self-hosted apps, Fider 0.33.0 and Photoview 2.4.0. Both platforms received source code and credentials. A Doyensec researcher validated every finding by hand, a different researcher per platform, and re-scored it for severity. 
+
+Fider and Photoview have similar stacks, Go backends with React frontends, so either would exercise the same parts of Shannon. We chose Photoview. Both apps have shipped security fixes since the versions Doyensec tested, which gives us a partial ground truth for recall below. Photoview's fixes landed in July 2026 and Fider's in April, and the later batch reduces the chance the models saw the fixes in training. 
+
+---
+
+## Benchmark Setup
+
+We ran Shannon against Photoview version 2.4.0, using a deployment that matched the one Doyensec tested: MariaDB, standalone username/password authentication, and two seeded accounts (one admin and one normal user). Similar to the XBOW setup, which received only the admin account,  we gave Shannon just the admin credentials only.
+
+This was our setup run:
+
+```
+./shannon start \
+  -u http://host.docker.internal:4800 \
+  -r ~/photoview-v240/repo \
+  -c ~/photoview-v240/config.yaml
+```
+
+`config.yaml`
+
+```yaml
+agentic_sast:
+  enabled: "true"
+
+exploit: "true"
+
+report:
+  sarif: "true"
+
+authentication:
+  login_type: form
+  login_url: "http://host.docker.internal:4800/login"
+  credentials:
+    username: "admin"
+    password: "PhotoviewAdmin!2026"
+  login_flow:
+    - "Go to http://host.docker.internal:4800/login"
+    - "Type $username into the Username field"
+    - "Type $password into the Password field"
+    - "Click the Sign in button"
+```
+
+The scan config was optional and only carried login details. Shannon started its local infrastructure, mounted the target repository read-only, and wrote its results to a local workspace.
+
+## Results
+
+### Photoview 2.4.0
+
+|  | Shannon 3.0 (Deepseek v4 Flash) | Shannon 3.0 (Opus 5) | Shannon 3.0 (Grok 4.6) | Aikido |  XBOW |
+| --- | --- | --- | --- | --- | --- |
+| Cost | $6.10 | **$115** | $35.07 | $4,000 | $4,000 |
+| Time | 2h 37min | 2.4h | 5h 26m | < 8h | ~2 days |
+| Reported | 18 | 24 | 10 | 32 | 7 |
+| True positives | 18 | 23 | 10 | 32 | 7 |
+| False positives | 0 | 1 | 0 | 0 | 0 |
+| Exact severity agreement | 72% | 62% | 50% | 66% | 57% |
+
+Once our reports generated, we went through and verified the accuracy of our finding( how many were true positives, and how accurate were the severity ratings.)
+
+### The one false positive
+
+Opus flagged `userAddRootPath` (INJ-02) as missing path confinement. It's an admin-only feature for registering local media directories on a host the admin already controls, so the agent read an intended feature as an exploit. Shannon still rated it Low rather than escalating it, but it points to a broader problem we are working on: enhancing business logic understanding. the same code is an exploit in one app and a feature in another, so before an agent can tell the two apart it has to understand the full context of the app it is testing.
+
+### **Comparing Shannon’s findings to Photoview’s security fixes**
+
+The tables below list the security vulnerabilities Photoview patched after the commit used for each scan and show which ones each model flagged. We built the list by scraping Photoview’s commit history after the scanned version for security-related keywords, then reviewing the matching commits. Photoview’s maintainers chose to fix these issues independently of our benchmark. When a Shannon finding matches one of those fixes, it’s a strong signal that the finding represents a real problem the maintainers cared enough to patch.
+
+Most notably, all three models flagged the critical SQL injection that Photoview has since patched. The bug turned one endpoint into a boolean oracle, letting an unauthenticated attacker read the entire database. Every scan caught it, regardless of model. At these price points, it’s exciting because results like this can widen access to meaningful security testing.
+
+The other clear signal is how coverage changes with model strength. Opus, the heaviest model, caught 6/7 of the patched vulnerabilities, including the more nuanced, higher-severity issues. Grok caught 3/7: the critical issue, one high, and one medium. DeepSeek also caught 3/7: the critical issue and two mediums.
+
+As the price point dropped, coverage of the subtler, higher-severity findings fell off, but every model still caught the most urgent issue. That supports the cadence we had in mind for Shannon. Teams can run Grok or DeepSeek regularly, then bring in Opus periodically to catch the harder findings.
+
+### Photoview findings compared to patched vulnerabilities
+
+| Vulnerability Photoview patched | CVSS 3.1 | Commit / PR | Opus 5 | Grok 4.6 | DeepSeek v4 Flash |
+| --- | --- | --- | --- | --- | --- |
+| Pre-auth SQL injection in the album-download route | 9.8 Critical | `deb1b216` / PR #1453 | ✅ INJ-01 | ✅ INJ-01 | ✅ INJ-01 |
+| Share-link authz: admin check tested the token owner, not the caller | 8.1 High | `3512ca26` / PR #1452 | ✅ AUTHZ-03 | ✅ AUTHZ-05 | ❌ |
+| WebSocket session never re-validated after upgrade | 8.1 High | `95d3d16a` / PR #1353 | ✅ MISC-01 | ❌ | ❌ |
+| Share-token expiry never enforced | 5.3 Medium | `2b1240b8` #1202 · `2598c362` #1348 | ✅ AUTH-04 | ✅ AUTHZ-07 | ✅ AUTH-06 |
+| Unauth nil-pointer panic / DoS on unknown `/api/photo` & `/api/video` | 5.3 Medium | `27a0b082` #1201 · `2b1240b8` #1202 | ✅ MISC-03 | ❌ | ❌  |
+| WebSocket origin check fails open (cross-site WS hijack) | 4.7 Medium | `eeb8d0e9` #1363 · `95d3d16a` #1353 | ✅ AUTH-06 | ❌ | ✅ AUTH-09 |
+| Malformed EXIF GPS data accepted (media-parsing input validation) | 4.3 Medium | `df9af39a` / PR #951 | ❌ | ❌ | ❌ |
+| **Total** |  |  | **6 / 7** | **3 / 7** | **3 / 7** |
+
+### Severity Discussion
+
+To assess our severity ratings, we manually scored each true finding against CVSS 3.1 and compared it to the severity we had originally reported. Admittedly, we had a fair amount of adjusting to do, but in most cases the reported severity was only one band off its CVSS equivalent, and never wildly exaggerated. More rigorous CVSS scoring is on our roadmap.
+
+We also noticed a number of findings that could fall under an “informational” category. Most were already reported as Low, so it is less about correcting inflated severities and more about giving them a more precise label. We plan to eventually move these types of finding into a more accurate category.
+
+### Cost and Scan time
+
+For Doyensec’s study, Aikido’s Standard tier and XBOW’s Plus tier each cost $4,000 per scan. Against that baseline, our $115 Opus scan of Photoview was 35x cheaper. The $35.07 Grok scan was 114x cheaper, while the $6.10 DeepSeek scan was 656x cheaper.
+
+Time also differed. Once the Photoview target was ready, all three Shannon runs finished in under five and a half hours. Doyensec reported just under eight hours for Aikido’s Photoview scan. XBOW’s Photoview scan started on April 6, and the final report arrived on April 8 with no interruptions. These aren’t like-for-like scanner runtimes. They do show the operational difference between Shannon’s same-day local runs and XBOW’s multi-day process.
+
+**Ensembling**
+
+Ensembling, or running multiple models and merging their outputs, is a proven way to boost coverage and reliability. The benchmark results above reflect only single-model runs, meaning there is still significant performance left on the table.
+
+For example, Grok and DeepSeek each found three of the seven patched vulnerabilities, but their findings didn't perfectly overlap. Merging their reports would cover four out of seven vulnerabilities for just $41. A multi-model approach also acts as a built-in critic: a second model verifying trust boundaries would likely have caught Opus's single false positive (INJ-02).
+
+While Shannon doesn’t natively orchestrate ensembling yet, its architecture makes it incredibly easy to implement. Because Shannon is BYOM (bring your own model) and outputs standard SARIF files, merging and deduplicating results from different models is straightforward when paired with your favorite agentic coding tool. All of this can be done seamlessly in a CI flow.
+
+#### Deploy this in your CI system today
+
+Shannon v3 runs headlessly in GitHub Actions or GitLab CI. Run `npx @keygraph/shannon setup` once on the runner to store your provider key. After that, the pipeline calls `npx @keygraph/shannon start` with the target URL and repo path. Shannon pulls the worker image, mounts the checkout read-only in a throwaway container, scans, and exits. The only traffic that leaves your runner goes to the model provider you configured.
+
+Exploit-mode scans write SARIF 2.1.0 by default, so findings land in GitHub code scanning or GitLab's vulnerability report alongside your other scanners. Out of the box, the run fails on Critical or High findings. Lower severities show up as annotations, and the threshold is configurable.
+
+### Conclusion
+
+The complaint we hear most from CISOs about AI pentesting isn't accuracy, it's cost. At $4,000 a scan, the tier Doyensec purchased from both XBOW and Aikido, the math works for an annual check-up. It doesn't work per release, and teams are shipping faster than ever. A large enterprise with 5,000 repositories is looking at $20 million for a single pass.
+
+Shannon v3 running DeepSeek v4 Flash scanned Photoview for $6.10 and caught the same critical SQL injection the $4,000 platforms caught. The same enterprise would pay about $30,000 for that pass. The cheap model doesn't catch everything: our Claude Opus 5 run found 6 of 7 patched vulnerabilities to DeepSeek's 3, for $115. That's the point. Run the cheap model on every change, run the heavy one on a schedule, and continuous pentesting becomes affordable.
@@ -36,7 +36,7 @@ Resume an auto-named workspace:
 npx @keygraph/shannon start -u https://example.com -r /path/to/repo -w example-com_shannon-1771007534808
 ```

-List completed scans:
+List running and completed scans:

 ```bash
 npx @keygraph/shannon scans