diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 82abb31..697b556 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -16,7 +16,7 @@ concurrency: jobs: check: name: Type-check & lint - runs-on: runners-farhoodliquor + runs-on: runners-farhoodlabs steps: - name: Checkout uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 @@ -43,7 +43,7 @@ jobs: name: Build & push worker image needs: check if: github.event_name == 'push' && github.ref == 'refs/heads/main' - runs-on: runners-farhoodliquor + runs-on: runners-farhoodlabs permissions: contents: read packages: write @@ -68,14 +68,14 @@ jobs: context: . push: true tags: | - ghcr.io/farhoodliquor/shannon:latest - ghcr.io/farhoodliquor/shannon:sha-${{ github.sha }} + ghcr.io/farhoodlabs/shannon:latest + ghcr.io/farhoodlabs/shannon:sha-${{ github.sha }} build-api: name: Build & push API image needs: check if: github.event_name == 'push' && github.ref == 'refs/heads/main' - runs-on: runners-farhoodliquor + runs-on: runners-farhoodlabs permissions: contents: read packages: write @@ -102,5 +102,5 @@ jobs: push: true no-cache: true tags: | - ghcr.io/farhoodliquor/hightower-api:latest - ghcr.io/farhoodliquor/hightower-api:sha-${{ github.sha }} + ghcr.io/farhoodlabs/hightower-api:latest + ghcr.io/farhoodlabs/hightower-api:sha-${{ github.sha }} diff --git a/.github/workflows/release-beta.yml b/.github/workflows/release-beta.yml index 07f8bf8..9a45427 100644 --- a/.github/workflows/release-beta.yml +++ b/.github/workflows/release-beta.yml @@ -13,7 +13,7 @@ concurrency: jobs: preflight: name: Preflight - runs-on: runners-farhoodliquor + runs-on: runners-farhoodlabs outputs: version: ${{ steps.version.outputs.version }} @@ -47,7 +47,7 @@ jobs: build-docker: name: Build Docker (worker) needs: preflight - runs-on: runners-farhoodliquor + runs-on: runners-farhoodlabs permissions: contents: read @@ -76,7 +76,7 @@ jobs: build-docker-api: name: Build Docker (API) needs: preflight - runs-on: runners-farhoodliquor + runs-on: runners-farhoodlabs permissions: contents: read @@ -106,7 +106,7 @@ jobs: sign-docker: name: Sign Docker images needs: [preflight, build-docker, build-docker-api] - runs-on: runners-farhoodliquor + runs-on: runners-farhoodlabs permissions: contents: read id-token: write @@ -165,7 +165,7 @@ jobs: publish-npm: name: Publish npm (beta) needs: [preflight, sign-docker] - runs-on: runners-farhoodliquor + runs-on: runners-farhoodlabs permissions: contents: read id-token: write diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index d0c5525..fad3056 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -13,7 +13,7 @@ concurrency: jobs: preflight: name: Preflight - runs-on: runners-farhoodliquor + runs-on: runners-farhoodlabs permissions: contents: write outputs: @@ -60,7 +60,7 @@ jobs: name: Build Docker (worker) needs: preflight if: needs.preflight.outputs.should_release == 'true' - runs-on: runners-farhoodliquor + runs-on: runners-farhoodlabs permissions: contents: read @@ -92,7 +92,7 @@ jobs: name: Build Docker (API) needs: preflight if: needs.preflight.outputs.should_release == 'true' - runs-on: runners-farhoodliquor + runs-on: runners-farhoodlabs permissions: contents: read @@ -124,7 +124,7 @@ jobs: sign-docker: name: Sign Docker images needs: [preflight, build-docker, build-docker-api] - runs-on: runners-farhoodliquor + runs-on: runners-farhoodlabs permissions: contents: read id-token: write @@ -183,7 +183,7 @@ jobs: publish-npm: name: Publish npm needs: [preflight, sign-docker] - runs-on: runners-farhoodliquor + runs-on: runners-farhoodlabs permissions: contents: read id-token: write @@ -228,7 +228,7 @@ jobs: release: name: Create GitHub release needs: [preflight, publish-npm] - runs-on: runners-farhoodliquor + runs-on: runners-farhoodlabs permissions: contents: write diff --git a/.github/workflows/rollback-beta.yml b/.github/workflows/rollback-beta.yml index 34bd766..0ea165a 100644 --- a/.github/workflows/rollback-beta.yml +++ b/.github/workflows/rollback-beta.yml @@ -18,7 +18,7 @@ concurrency: jobs: rollback: name: Roll back npm beta dist-tag - runs-on: runners-farhoodliquor + runs-on: runners-farhoodlabs steps: - name: Validate target version id: target diff --git a/.github/workflows/rollback.yml b/.github/workflows/rollback.yml index ceb5f8b..13b916e 100644 --- a/.github/workflows/rollback.yml +++ b/.github/workflows/rollback.yml @@ -18,7 +18,7 @@ concurrency: jobs: rollback: name: Roll back npm, Docker, and GitHub release latest - runs-on: runners-farhoodliquor + runs-on: runners-farhoodlabs steps: - name: Checkout tags uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 diff --git a/CLAUDE.md b/CLAUDE.md index c69e8ee..1cceb1c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,78 +1,12 @@ # CLAUDE.md -AI-powered penetration testing agent for defensive security analysis. Automates vulnerability assessment by combining reconnaissance tools with AI-powered code analysis. +Hightower is a fork of [Shannon](https://github.com/KeygraphHQ/shannon) by Keygraph — an AI-powered penetration testing agent for defensive security analysis. It wraps Shannon's autonomous pentesting engine with a REST API and Kubernetes deployment tooling. + +**Upstream policy:** `apps/cli/` and `apps/worker/` are kept as close to upstream Shannon as possible for backporting. Only `apps/api/`, CI/CD workflows, and infra are Hightower-specific. ## Commands -**Prerequisites:** Docker, AI provider credentials (`.env` for local, `shn setup` or env vars for npx) - -### Dual CLI - -Shannon supports two CLI modes, auto-detected based on the current working directory: - -| | **npx** (`npx @keygraph/shannon`) | **Local** (`./shannon`) | -|---|---|---| -| **Install** | Zero-install via npm | Clone the repo | -| **Image** | Pulled from Docker Hub (`keygraph/shannon:latest`) | Built locally (`shannon-worker`) | -| **State** | `~/.shannon/` | Project directory | -| **Credentials** | `~/.shannon/config.toml` (via `shn setup`) or env vars | `./.env` | -| **Config** | `~/.shannon/config.toml` (via `shn setup`) | N/A | -| **Prompts** | Bundled in Docker image | Mounted from `./apps/worker/prompts/` (live-editable) | - -Mode auto-detection: local mode activates when env var `SHANNON_LOCAL=1` is set by the `./shannon` entry point (`apps/cli/src/mode.ts`). Otherwise npx mode. - -### npx Quick Start - ```bash -# Configure credentials (interactive wizard) -npx @keygraph/shannon setup - -# Or export env vars directly (non-interactive / CI) -export ANTHROPIC_API_KEY=your-key - -# Run -npx @keygraph/shannon start -u -r /path/to/repo -``` - -### Local (Development) Quick Start - -```bash -# Setup -echo "ANTHROPIC_API_KEY=your-key" > .env - -# Build (auto-runs if image missing) -./shannon build - -# Run -./shannon start -u -r my-repo -./shannon start -u -r my-repo -c ./apps/worker/configs/my-config.yaml -./shannon start -u -r /any/path/to/repo -``` - -### Common Commands - -```bash -# Setup (npx mode only — one-time credential configuration) -npx @keygraph/shannon setup - -# Workspaces & Resume -./shannon start -u -r my-repo -w my-audit # New named workspace -./shannon start -u -r my-repo -w my-audit # Resume (same command) -./shannon workspaces # List all workspaces - -# Monitor -./shannon logs # Tail workflow log -./shannon status # Show running workers -# Temporal Web UI: http://localhost:8233 - -# Stop -./shannon stop # Preserves workflow data -./shannon stop --clean # Full cleanup including volumes (confirms first) - -# Image management -./shannon build [--no-cache] # Local mode: build worker image -npx @keygraph/shannon uninstall # npx mode: remove ~/.shannon/ (confirms first) - # Build TypeScript (development) pnpm run build # Build all packages via Turborepo pnpm run check # Type-check all packages @@ -82,42 +16,25 @@ pnpm biome:fix # Auto-fix lint, format, and import sorting **Monorepo tooling:** pnpm workspaces, Turborepo for task orchestration, Biome for linting/formatting. TypeScript compiler options shared via `tsconfig.base.json` at the root. All packages extend it, overriding only `rootDir` and `outDir`. Shared devDependencies (`typescript`, `@types/node`, `turbo`, `@biomejs/biome`) are hoisted to the root workspace. -**Options:** `-c ` (YAML config), `-o ` (output directory), `-w ` (named workspace; auto-resumes if exists), `--pipeline-testing` (minimal prompts, 10s retries), `--router` (multi-model routing via [claude-code-router](https://github.com/musistudio/claude-code-router)) - ## Architecture ### Monorepo Layout ``` -apps/cli/ — @keygraph/shannon (published to npm, bundled with tsdown) -apps/worker/ — @shannon/worker (private, Temporal worker + pipeline logic) +apps/api/ — @shannon/api (Hightower REST API, K8s-native) +apps/cli/ — @keygraph/shannon (upstream CLI, not used in production) +apps/worker/ — @shannon/worker (upstream Temporal worker + pipeline logic) ``` +### API Package (`apps/api/`) +Hightower-specific REST API for triggering and managing pentests. Deployed on Kubernetes. + ### CLI Package (`apps/cli/`) -Published as `@keygraph/shannon` on npm. Contains only Docker orchestration logic — no Temporal SDK, business logic, or prompts. Bundled with tsdown for single-file ESM output. - -- `apps/cli/src/index.ts` — CLI dispatcher (`setup`, `start`, `stop`, `logs`, `workspaces`, `status`, `build`, `uninstall`, `info`) -- `apps/cli/src/mode.ts` — Auto-detection: local mode if `SHANNON_LOCAL=1` env var is set -- `apps/cli/src/docker.ts` — Compose lifecycle, image pull/build, ephemeral `docker run` worker spawning -- `apps/cli/src/home.ts` — State directory management (`~/.shannon/` for npx, `./` for local) -- `apps/cli/src/env.ts` — `.env` loading, TOML fallback (npx only) via `apps/cli/src/config/resolver.ts`, credential validation, env flag building -- `apps/cli/src/config/resolver.ts` — Cascading config (npx only): env vars → `~/.shannon/config.toml` (parsed with `smol-toml`) -- `apps/cli/src/config/writer.ts` — TOML serialization and secure file persistence (0o600) -- `apps/cli/src/commands/setup.ts` — Interactive TUI wizard (`@clack/prompts`) for provider credential setup (npx only) -- `apps/cli/src/paths.ts` — Repo/config path resolution (bare name → `./repos/`, or any absolute/relative path) -- `apps/cli/src/commands/` — Command handlers -- `apps/cli/infra/compose.yml` — Bundled Temporal + router compose file for npx mode -- `apps/cli/tsdown.config.ts` — tsdown bundler config -- `shannon` — Node.js entry point (`#!/usr/bin/env node`) that delegates to `apps/cli/dist/index.mjs` - -### Docker Architecture -Infra (Temporal + router) runs via `docker-compose.yml`. Workers are ephemeral `docker run --rm` containers, one per scan, each with a unique task queue and isolated volume mounts. - -- `docker-compose.yml` — Infra only: `shannon-temporal` (port 7233/8233) and `shannon-router` (port 3456, optional via profile). Network: `shannon-net` -- `Dockerfile` — 2-stage build (builder + Chainguard Wolfi runtime). Uses pnpm. Entrypoint: `CMD ["node", "apps/worker/dist/temporal/worker.js"]` -- No `docker-compose.docker.yml` — host gateway handled via `--add-host` flag in CLI +Upstream Shannon CLI — kept for backporting compatibility. Not used in Hightower's K8s deployment. ### Worker Package (`apps/worker/`) +Upstream Shannon worker — Temporal worker + pipeline logic. Runs as ephemeral K8s Jobs. + - `apps/worker/src/paths.ts` — Centralized path constants (`PROMPTS_DIR`, `CONFIGS_DIR`, `WORKSPACES_DIR`) - `apps/worker/src/session-manager.ts` — Agent definitions (`AGENTS` record). Agent types in `apps/worker/src/types/agents.ts` - `apps/worker/src/config-parser.ts` — YAML config parsing with JSON Schema validation @@ -135,6 +52,7 @@ Durable workflow orchestration with crash recovery, queryable progress, intellig - `apps/worker/src/temporal/summary-mapper.ts` — Maps `PipelineSummary` to `WorkflowSummary` - `apps/worker/src/temporal/worker.ts` — Combined worker + client entry point (per-invocation task queue, submits workflow, waits for result) - `apps/worker/src/temporal/shared.ts` — Types, interfaces, query definitions + ### Five-Phase Pipeline 1. **Pre-Recon** (`pre-recon`) — External scans (nmap, subfinder, whatweb) + source code analysis @@ -143,8 +61,15 @@ Durable workflow orchestration with crash recovery, queryable progress, intellig 4. **Exploitation** (5 parallel agents, conditional) — Exploits confirmed vulnerabilities 5. **Reporting** (`report`) — Executive-level security report +### Docker Images +- `Dockerfile` — Worker image: 2-stage build (builder + Chainguard Wolfi runtime). Uses pnpm. Entrypoint: `CMD ["node", "apps/worker/dist/temporal/worker.js"]` +- `apps/api/Dockerfile` — API image: minimal Alpine build + +### Kubernetes Infrastructure +K8s manifests live in a separate repository: [farhoodlabs/hightower-infra](https://github.com/farhoodlabs/hightower-infra). + ### Supporting Systems -- **Configuration** — YAML configs in `apps/worker/configs/` with JSON Schema validation (`config-schema.json`). Supports auth settings, MFA/TOTP, and per-app testing parameters. Credential resolution — local mode: env vars → `./.env`; npx mode: env vars → `~/.shannon/config.toml` (via `shn setup`) +- **Configuration** — YAML configs in `apps/worker/configs/` with JSON Schema validation (`config-schema.json`). Supports auth settings, MFA/TOTP, and per-app testing parameters - **Prompts** — Per-phase templates in `apps/worker/prompts/` with variable substitution (`{{TARGET_URL}}`, `{{CONFIG_CONTEXT}}`). Shared partials in `apps/worker/prompts/shared/` via `apps/worker/src/services/prompt-manager.ts` - **SDK Integration** — Uses `@anthropic-ai/claude-agent-sdk` with `maxTurns: 10_000` and `bypassPermissions` mode. Browser automation via `playwright-cli` with session isolation (`-s=`). TOTP generation via `generate-totp` CLI tool. Login flow template at `apps/worker/prompts/shared/login-instructions.txt` supports form, SSO, API, and basic auth - **Audit System** — Crash-safe append-only logging in `workspaces/{hostname}_{sessionId}/`. Tracks session metrics, per-agent logs, prompts, and deliverables. WorkflowLogger (`apps/worker/src/audit/workflow-logger.ts`) provides unified human-readable per-workflow logs, backed by LogStream (`apps/worker/src/audit/log-stream.ts`) shared stream primitive @@ -171,7 +96,7 @@ Durable workflow orchestration with crash recovery, queryable progress, intellig - **Modular Error Handling** — `ErrorCode` enum, `Result` for explicit error propagation, automatic retry (3 attempts per agent) - **Services Boundary** — Activities are thin Temporal wrappers; `apps/worker/src/services/` owns business logic, accepts `ActivityLogger`, returns `Result`. No Temporal imports in services - **DI Container** — Per-workflow in `apps/worker/src/services/container.ts`. `AuditSession` excluded (parallel safety) -- **Ephemeral Workers** — Each scan runs in its own `docker run --rm` container with a per-invocation task queue. Temporal routes activities by queue name, so per-scan queues ensure activities never land on a worker with the wrong repo mounted +- **Ephemeral Workers** — Each scan runs in its own container with a per-invocation task queue. Temporal routes activities by queue name, so per-scan queues ensure activities never land on a worker with the wrong repo mounted ### Security Defensive security tool only. Use only on systems you own or have explicit permission to test. @@ -223,26 +148,16 @@ Comments must be **timeless** — no references to this conversation, refactorin ## Key Files -**CLI:** `shannon` (entry point), `apps/cli/src/index.ts` (dispatcher), `apps/cli/src/docker.ts` (orchestration), `apps/cli/src/mode.ts` (auto-detection) +**API:** `apps/api/src/` (Hightower REST API), `apps/api/Dockerfile` **Entry Points:** `apps/worker/src/temporal/workflows.ts`, `apps/worker/src/temporal/activities.ts`, `apps/worker/src/temporal/worker.ts` **Core Logic:** `apps/worker/src/session-manager.ts`, `apps/worker/src/ai/claude-executor.ts`, `apps/worker/src/config-parser.ts`, `apps/worker/src/services/`, `apps/worker/src/audit/` -**Config:** `docker-compose.yml`, `apps/cli/infra/compose.yml`, `apps/worker/configs/`, `apps/worker/prompts/`, `tsconfig.base.json` (shared compiler options), `turbo.json`, `biome.json` +**Config:** `Dockerfile`, `apps/worker/configs/`, `apps/worker/prompts/`, `tsconfig.base.json` (shared compiler options), `turbo.json`, `biome.json` -**CI/CD:** `.github/workflows/release.yml` (Docker Hub push + npm publish + GitHub release, manual dispatch) +**CI/CD:** `.github/workflows/ci.yml` (type-check, lint, build & push images to GHCR), `.github/workflows/release.yml` (Docker Hub push + GitHub release, manual dispatch) ## Package Installation Package managers are configured with a minimum release age (7 days). Requires pnpm >= 10.16.0. If `pnpm install` fails due to a package being too new, **do not attempt to bypass it** — report the blocked package to the user and stop. - -## Troubleshooting - -- **"Repository not found"** — Pass a bare name (`-r my-repo`) for `./repos/my-repo`, or a path (`-r /path/to/repo`) for any directory -- **"Temporal not ready"** — Wait for health check or `docker compose logs temporal` -- **Worker not processing** — Check `docker ps --filter "name=shannon-worker-"` -- **Reset state** — `./shannon stop --clean` -- **Local apps unreachable** — Use `host.docker.internal` instead of `localhost` -- **Missing tools** — Use `--pipeline-testing` to skip nmap/subfinder/whatweb (graceful degradation) -- **Container permissions** — On Linux, may need `sudo` for docker commands diff --git a/README.md b/README.md index 4825592..afc9c80 100644 --- a/README.md +++ b/README.md @@ -1,935 +1,116 @@ ->[!NOTE] -> **[📢 New: Shannon is now available via `npx @keygraph/shannon`. →](https://github.com/KeygraphHQ/shannon/discussions/249)** -
-Shannon — AI Pentester for Web Applications and APIs +Hightower — AI Pentester -# Shannon — AI Pentester by Keygraph +# Hightower — AI Pentester -KeygraphHQ%2Fshannon | Trendshift +Hightower is a fork of [Shannon](https://github.com/KeygraphHQ/shannon) by Keygraph, wrapped with a REST API and Kubernetes tooling for cluster-based deployments. -Shannon is an autonomous, white-box AI pentester for web applications and APIs.
-It analyzes your source code, identifies attack vectors, and executes real exploits to prove vulnerabilities before they reach production. - ---- - -Join Discord -Visit Keygraph.io - ----
-## What is Shannon? +## What is Hightower? -Shannon is an 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. +Hightower is an API-driven AI pentester built on top of Shannon's autonomous penetration testing engine. It performs white-box security testing of web applications and 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 (injection attacks, authentication bypass, SSRF, XSS) against the running application and its APIs. Only vulnerabilities with a working proof-of-concept are included in the final report. +Unlike the upstream Shannon CLI, Hightower is designed to run as a service on Kubernetes — scans are triggered via REST API, orchestrated by Temporal, and executed in ephemeral worker pods. -**Why Shannon Exists** - -Thanks to tools like Claude Code and Cursor, your team ships code non-stop. But your penetration test? That happens once a year. This creates a *massive* security gap. For the other 364 days, you could be unknowingly shipping vulnerabilities to production. - -Shannon closes that gap by providing on-demand, automated penetration testing that can run against every build or release. - -## Shannon in Action - -Shannon identified 20+ vulnerabilities in OWASP Juice Shop, including authentication bypass and database exfiltration. [Full report →](sample-reports/shannon-report-juice-shop.md) - -![Demo](assets/shannon-action.gif) +> [!IMPORTANT] +> **White-box only.** Hightower expects access to your application's source code and repository layout. ## Features -- **Fully Autonomous Operation**: A single command launches the full pentest. Shannon handles 2FA/TOTP logins (including SSO), browser navigation, exploitation, and report generation without manual intervention. +- **Fully Autonomous Operation**: A single API call launches the full pentest. Handles 2FA/TOTP logins (including SSO), browser navigation, exploitation, and report generation without manual intervention. - **Reproducible Proof-of-Concept Exploits**: The final report contains only proven, exploitable findings with copy-and-paste PoCs. Vulnerabilities that cannot be exploited are not reported. -- **OWASP Vulnerability Coverage**: Identifies and validates Injection, XSS, SSRF, and Broken Authentication/Authorization, with additional categories in development. +- **OWASP Vulnerability Coverage**: Identifies and validates Injection, XSS, SSRF, and Broken Authentication/Authorization. - **Code-Aware Dynamic Testing**: Analyzes source code to guide attack strategy, then validates findings with live browser and CLI-based exploits against the running application. - **Integrated Security Tooling**: Leverages Nmap, Subfinder, WhatWeb, and Schemathesis during reconnaissance and discovery phases. - **Parallel Processing**: Vulnerability analysis and exploitation phases run concurrently across all attack categories. -## Product Line +## Architecture -Shannon is developed by [Keygraph](https://keygraph.io) and available in two editions: +Hightower uses a multi-agent architecture that combines white-box source code analysis with dynamic exploitation across five phases: -| Edition | License | Best For | -|---------|---------|----------| -| **Shannon Lite** | AGPL-3.0 | Local testing of your own applications. | -| **Shannon Pro** | Commercial | Organizations needing a single AppSec platform (SAST, SCA, secrets, business logic testing, autonomous pentesting) with CI/CD integration and self-hosted deployment. | - -> **This repository contains Shannon Lite,** the core autonomous AI pentesting framework. **Shannon Pro** is Keygraph's all-in-one AppSec platform, combining SAST, SCA, secrets scanning, business logic security testing, and autonomous AI pentesting in a single correlated workflow. Every finding is validated with a working proof-of-concept exploit. - -> [!IMPORTANT] -> **White-box only.** Shannon Lite is designed for **white-box (source-available)** application security testing. -> It expects access to your application's source code and repository layout. - -### Shannon Pro: Architecture Overview - -Shannon Pro is an all-in-one application security platform that replaces the need to stitch together separate SAST, SCA, secrets scanning, and pentesting tools. It operates as a two-stage pipeline: agentic static analysis of the codebase, followed by autonomous AI penetration testing. Findings from both stages are cross-referenced and correlated, so every reported vulnerability has a working proof-of-concept exploit and a precise source code location. - -**Stage 1: Agentic Static Analysis** - -Shannon Pro transforms the codebase into a Code Property Graph (CPG) combining the AST, control flow graph, and program dependence graph. It then runs five analysis capabilities: - -- **Data Flow Analysis (SAST)**: Identifies sources (user input, API requests) and sinks (SQL queries, command execution), then traces paths between them. At each node, an LLM evaluates whether the specific sanitization applied is sufficient for the specific vulnerability in context, rather than relying on a hard-coded allowlist of safe functions. -- **Point Issue Detection (SAST)**: LLM-based detection of single-location vulnerabilities: weak cryptography, hardcoded credentials, insecure configuration, missing security headers, weak RNG, disabled certificate validation, and overly permissive CORS. -- **Business Logic Security Testing (SAST)**: LLM agents analyze the codebase to discover application-specific invariants (e.g., "document access must verify organizational ownership"), generate targeted fuzzers to violate those invariants, and synthesize full PoC exploits. This catches authorization failures and domain-specific logic errors that pattern-based scanners cannot detect. -- **SCA with Reachability Analysis**: Goes beyond flagging CVEs by tracing whether the vulnerable function is actually reachable from application entry points via the CPG. Unreachable vulnerabilities are deprioritized. -- **Secrets Detection**: Combines regex pattern matching with LLM-based detection (for dynamically constructed credentials, custom formats, obfuscated tokens) and performs liveness validation against the corresponding service using read-only API calls. - -**Stage 2: Autonomous Dynamic Penetration Testing** - -The same multi-agent pentest pipeline as Shannon Lite (reconnaissance, parallel vulnerability analysis, parallel exploitation, reporting), enhanced with static findings injected into the exploitation queue. Static findings are mapped to Shannon's five attack domains (Injection, XSS, SSRF, Auth, Authz), and exploit agents attempt real proof-of-concept attacks against the running application for each finding. - -**Static-Dynamic Correlation** - -This is the core differentiator. A data flow vulnerability identified in static analysis (e.g., unsanitized input reaching a SQL query) is not reported as a theoretical risk. It is fed to the corresponding exploit agent, which attempts to exploit it against the live application. Confirmed exploits are traced back to the exact source code location, giving developers both proof of exploitability and the line of code to fix. - -**Deployment Model** - -Shannon Pro supports a self-hosted runner model (similar to GitHub Actions self-hosted runners). The data plane, which handles code access and all LLM API calls, runs entirely within the customer's infrastructure using the customer's own API keys. Source code never leaves the customer's network. The Keygraph control plane handles job orchestration, scan scheduling, and the reporting UI, receiving only aggregate findings. - -| Capability | Shannon Lite | Shannon Pro (All-in-One AppSec) | -| --- | --- | --- | -| **Licensing** | AGPL-3.0 | Commercial | -| **Static Analysis** | Code review prompting | Full agentic SAST, SCA, secrets, business logic testing | -| **Dynamic Testing** | Autonomous AI pentesting | Autonomous AI pentesting with static-dynamic correlation | -| **Analysis Engine** | Code review prompting | CPG-based data flow with LLM reasoning at every node | -| **Business Logic** | None | Automated invariant discovery, fuzzer generation, exploit synthesis | -| **CI/CD Integration** | Manual / CLI | Native CI/CD, GitHub PR scanning | -| **Deployment** | CLI | Managed cloud or self-hosted runner | -| **Boundary Analysis** | None | Automatic service boundary detection with team routing | - -[Full technical details →](./SHANNON-PRO.md) - -## Table of Contents - -- [What is Shannon?](#what-is-shannon) -- [Shannon in Action](#shannon-in-action) -- [Features](#features) -- [Product Line](#product-line) -- [Setup & Usage Instructions](#setup--usage-instructions) - - [Prerequisites](#prerequisites) - - [Quick Start (Recommended: npx)](#quick-start-recommended-npx) - - [Clone and Build](#clone-and-build) - - [Prepare Your Repository](#prepare-your-repository) - - [Common Commands](#common-commands) - - [Workspaces and Resuming](#workspaces-and-resuming) - - [Credentials and Configuration](#credentials-and-configuration) - - [AWS Bedrock](#aws-bedrock) - - [Google Vertex AI](#google-vertex-ai) - - [Custom Base URL](#custom-base-url) - - [Router Mode](#experimental---unsupported-router-mode-alternative-providers) - - [Platform-Specific Instructions](#platform-specific-instructions) - - [Output and Results](#output-and-results) -- [Sample Reports](#sample-reports) -- [Benchmark](#benchmark) -- [Architecture](#architecture) -- [Coverage and Roadmap](#coverage-and-roadmap) -- [Disclaimers](#disclaimers) -- [License](#license) -- [Community & Support](#community--support) -- [Get in Touch](#get-in-touch) - ---- - -## Setup & Usage Instructions - -### Prerequisites - -- **Docker** - Container runtime ([Install Docker](https://docs.docker.com/get-docker/)) -- **Node.js 18+** - Required for `npx` usage ([Install Node.js](https://nodejs.org/)) -- **pnpm** - Required for Clone and Build mode ([Install pnpm](https://pnpm.io/installation)) -- **AI Provider Credentials** (choose one): - - **Anthropic API key** (recommended) - Get from [Anthropic Console](https://console.anthropic.com) - - **Claude Code OAuth token** - - **AWS Bedrock** - Route through Amazon Bedrock with AWS credentials (see [AWS Bedrock](#aws-bedrock)) - - **Google Vertex AI** - Route through Google Cloud Vertex AI (see [Google Vertex AI](#google-vertex-ai)) - - **[EXPERIMENTAL - UNSUPPORTED] Alternative providers via Router Mode** - OpenAI or Google Gemini via OpenRouter (see [Router Mode](#experimental---unsupported-router-mode-alternative-providers)) - -> [!NOTE] -> Docker is still required to use the `npx` workflow. Under the hood, the CLI pulls and runs a prebuilt Shannon worker image from Docker Hub, which is approximately 1 GB and contains Shannon plus all required dependencies. - -### Quick Start (Recommended: npx) - -```bash -# 1. Configure credentials (interactive wizard — one-time setup) -npx @keygraph/shannon setup - -# Or export env vars directly -export ANTHROPIC_API_KEY=your-api-key - -# 2. Run a pentest -npx @keygraph/shannon start -u https://your-app.com -r /path/to/your-repo +``` + +----------------------+ + | Pre-Reconnaissance | + | (nmap, subfinder, | + | whatweb, code scan) | + +----------+-----------+ + | + v + +----------------------+ + | Reconnaissance | + | (attack surface | + | mapping) | + +----------+-----------+ + | + v + +----------+----------+ + | | | + v v v + +-----------+ +---------+ +---------+ + | Vuln | | Vuln | | ... | + |(Injection)| | (XSS) | | | + +-----+-----+ +----+----+ +----+----+ + | | | + v v v + +-----------+ +---------+ +---------+ + | Exploit | | Exploit | | ... | + |(Injection)| | (XSS) | | | + +-----+-----+ +----+----+ +----+----+ + | | | + +------+------+-----------+ + | + v + +----------------------+ + | Reporting | + +----------------------+ ``` -Shannon will pull the worker image from Docker Hub, start the infrastructure, and launch an ephemeral worker container for the scan. +Each scan runs as an ephemeral Kubernetes Job with a per-invocation Temporal task queue, enabling concurrent scans with different target repositories. -### Clone and Build +## Deployment -Use this if you want to run Shannon from a local clone, modify Shannon itself, or keep the worker image built locally. - -```bash -# 1. Clone Shannon -git clone https://github.com/KeygraphHQ/shannon.git -cd shannon - -# 2. Configure credentials (choose one method) - -# Option A: Create a .env file -cat > .env << 'EOF' -ANTHROPIC_API_KEY=your-api-key -CLAUDE_CODE_MAX_OUTPUT_TOKENS=64000 -EOF - -# Option B: Export environment variables -export ANTHROPIC_API_KEY="your-api-key" # or CLAUDE_CODE_OAUTH_TOKEN -export CLAUDE_CODE_MAX_OUTPUT_TOKENS=64000 # recommended - -# 3. Install dependencies and build -pnpm install -pnpm build - -# 4. Run a pentest -./shannon start -u https://your-app.com -r /path/to/your-repo -``` - -Shannon will build the worker image locally, start the infrastructure, and launch an ephemeral worker container for the scan. - -### Prepare Your Repository - -Shannon can scan any repository on your machine. Pass an absolute or relative path with `-r`. - -Examples: - -```bash -npx @keygraph/shannon start -u https://example.com -r /path/to/repo -``` - -
-Clone and Build command equivalents - -```bash -./shannon start -u https://example.com -r ./relative/path -``` - -
- -### Common Commands - -#### Monitoring Progress - -```bash -npx @keygraph/shannon logs -npx @keygraph/shannon status -``` - -Open the Temporal Web UI for detailed monitoring: - -```bash -open http://localhost:8233 -``` - -
-Clone and Build command equivalents - -```bash -./shannon logs -./shannon status -``` - -
- -#### Stopping Shannon - -```bash -npx @keygraph/shannon stop -npx @keygraph/shannon stop --clean -npx @keygraph/shannon uninstall -``` - -
-Clone and Build command equivalents - -```bash -./shannon stop -./shannon stop --clean -``` - -
- -#### Usage Examples - -```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 - -# List all workspaces -npx @keygraph/shannon workspaces -``` - -
-Clone and Build command equivalents - -```bash -# Basic pentest -./shannon start -u https://example.com -r /path/to/repo - -# With a configuration file -./shannon start -u https://example.com -r /path/to/repo -c /path/to/my-config.yaml - -# Custom output directory -./shannon start -u https://example.com -r /path/to/repo -o ./my-reports - -# Named workspace -./shannon start -u https://example.com -r /path/to/repo -w q1-audit - -# List all workspaces -./shannon workspaces - -# Rebuild worker image -./shannon build --no-cache -``` - -
- -### Workspaces and Resuming - -Shannon supports **workspaces** that allow you to resume interrupted or failed runs without re-running completed agents. - -**How it works:** - -- Every run creates a workspace (auto-named by default, for example `example-com_shannon-1771007534808`) -- Workspaces are stored in `./workspaces/` (local mode) or `~/.shannon/workspaces/` (npx mode) -- Use `-w ` to give your run a custom name for easier reference -- To resume any run, pass its workspace name via `-w` — Shannon detects which agents completed successfully and picks up where it left off -- Each agent's progress is checkpointed via git commits, so resumed runs start from a clean, validated state - -```bash -# Start with a named workspace -npx @keygraph/shannon start -u https://example.com -r /path/to/repo -w my-audit - -# Resume the same workspace (skips completed agents) -npx @keygraph/shannon start -u https://example.com -r /path/to/repo -w my-audit - -# Resume an auto-named workspace from a previous run -npx @keygraph/shannon start -u https://example.com -r /path/to/repo -w example-com_shannon-1771007534808 - -# List all workspaces and their status -npx @keygraph/shannon workspaces -``` - -
-Clone and Build command equivalents - -```bash -./shannon start -u https://example.com -r /path/to/repo -w my-audit -./shannon start -u https://example.com -r /path/to/repo -w my-audit -./shannon start -u https://example.com -r /path/to/repo -w example-com_shannon-1771007534808 -./shannon workspaces -``` - -
- -> [!NOTE] -> The `URL` must match the original workspace URL when resuming. Shannon will reject mismatched URLs to prevent cross-target contamination. - -### Credentials and Configuration - -#### Credential Precedence - -**Local mode** resolves credentials from: - -1. **Environment variables** - `export ANTHROPIC_API_KEY=...` -2. **`.env` file** - `./.env` - -**npx mode** uses TOML instead of `.env`: - -1. **Environment variables** - `export ANTHROPIC_API_KEY=...` -2. **`~/.shannon/config.toml`** - created by `npx @keygraph/shannon setup` - -Environment variables always win, so you can override saved config for a single session without editing files. - -#### Configuration (Optional) - -While you can run without a config file, creating one enables authenticated testing and customized analysis. Pass any configuration file path with `-c`. - -##### Create Configuration File - -Copy and modify the example configuration: - -```bash -cp configs/example-config.yaml ./my-app-config.yaml -``` - -##### Basic Configuration Structure - -```yaml -# Optional: describe your target environment (max 500 chars) -description: "Next.js e-commerce app on PostgreSQL. Local dev environment — .env files contain local-only credentials, not deployed to production." - -authentication: - login_type: form - login_url: "https://your-app.com/login" - credentials: - username: "test@example.com" - password: "yourpassword" - totp_secret: "LB2E2RX7XFHSTGCK" # Optional for 2FA - - 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: path - url_path: "/logout" - - focus: - - description: "AI should emphasize testing API endpoints" - type: path - url_path: "/api" -``` - -Run with: - -```bash -npx @keygraph/shannon start -u https://example.com -r /path/to/repo -c ./my-app-config.yaml -``` - -
-Clone and Build command equivalents - -```bash -./shannon start -u https://example.com -r /path/to/repo -c ./my-app-config.yaml -``` - -
- -#### TOTP Setup for 2FA - -If your application uses two-factor authentication, simply add the TOTP secret to your config file. The AI will automatically generate the required codes during testing. - -#### Subscription Plan Rate Limits - -Anthropic subscription plans reset usage on a **rolling 5-hour window**. The default retry strategy (30-min max backoff) will exhaust retries before the window resets. Add this to your config: - -```yaml -pipeline: - retry_preset: subscription # Extends max backoff to 6h, 100 retries - max_concurrent_pipelines: 2 # Run 2 of 5 pipelines at a time (reduces burst API usage) -``` - -`max_concurrent_pipelines` controls how many vulnerability pipelines run simultaneously (1-5, default: 5). Lower values reduce the chance of hitting rate limits but increase wall-clock time. - -### AWS Bedrock - -Shannon also supports [Amazon Bedrock](https://aws.amazon.com/bedrock/) instead of using an Anthropic API key. - -#### Quick Setup - -Run `npx @keygraph/shannon setup` and select **AWS Bedrock**. The wizard will prompt for your region, bearer token, and model IDs. - -Or export env vars directly: - -```bash -export CLAUDE_CODE_USE_BEDROCK=1 -export AWS_REGION=us-east-1 -export AWS_BEARER_TOKEN_BEDROCK=your-bearer-token -export ANTHROPIC_SMALL_MODEL=us.anthropic.claude-haiku-4-5-20251001-v1:0 -export ANTHROPIC_MEDIUM_MODEL=us.anthropic.claude-sonnet-4-6 -export ANTHROPIC_LARGE_MODEL=us.anthropic.claude-opus-4-6 -``` - -
-Clone and Build: add to .env instead - -```bash -CLAUDE_CODE_USE_BEDROCK=1 -AWS_REGION=us-east-1 -AWS_BEARER_TOKEN_BEDROCK=your-bearer-token -ANTHROPIC_SMALL_MODEL=us.anthropic.claude-haiku-4-5-20251001-v1:0 -ANTHROPIC_MEDIUM_MODEL=us.anthropic.claude-sonnet-4-6 -ANTHROPIC_LARGE_MODEL=us.anthropic.claude-opus-4-6 -``` - -
- -Shannon uses three model tiers: **small** (`claude-haiku-4-5-20251001`) for summarization, **medium** (`claude-sonnet-4-6`) for security analysis, and **large** (`claude-opus-4-6`) for deep reasoning. Set `ANTHROPIC_SMALL_MODEL`, `ANTHROPIC_MEDIUM_MODEL`, and `ANTHROPIC_LARGE_MODEL` to the Bedrock model IDs for your region. - -### Google Vertex AI - -Shannon also supports [Google Vertex AI](https://cloud.google.com/vertex-ai) instead of using an Anthropic API key. - -Create a service account with the `roles/aiplatform.user` role in the [GCP Console](https://console.cloud.google.com/iam-admin/serviceaccounts), then download a JSON key file. - -#### Quick Setup - -Run `npx @keygraph/shannon setup` and select **Google Vertex AI**. The wizard will prompt for your region, project ID, service account key file path, and model IDs. The key file is securely copied to `~/.shannon/google-sa-key.json`. - -Or export env vars directly: - -```bash -export CLAUDE_CODE_USE_VERTEX=1 -export CLOUD_ML_REGION=us-east5 -export ANTHROPIC_VERTEX_PROJECT_ID=your-gcp-project-id -export GOOGLE_APPLICATION_CREDENTIALS=/path/to/your-sa-key.json -export ANTHROPIC_SMALL_MODEL=claude-haiku-4-5@20251001 -export ANTHROPIC_MEDIUM_MODEL=claude-sonnet-4-6 -export ANTHROPIC_LARGE_MODEL=claude-opus-4-6 -``` - -
-Clone and Build: add to .env instead - -```bash -CLAUDE_CODE_USE_VERTEX=1 -CLOUD_ML_REGION=us-east5 -ANTHROPIC_VERTEX_PROJECT_ID=your-gcp-project-id -GOOGLE_APPLICATION_CREDENTIALS=./credentials/google-sa-key.json -ANTHROPIC_SMALL_MODEL=claude-haiku-4-5@20251001 -ANTHROPIC_MEDIUM_MODEL=claude-sonnet-4-6 -ANTHROPIC_LARGE_MODEL=claude-opus-4-6 -``` - -
- -Set `CLOUD_ML_REGION=global` for global endpoints, or a specific region like `us-east5`. Some models may not be available on global endpoints — see the [Vertex AI Model Garden](https://console.cloud.google.com/vertex-ai/model-garden) for region availability. - -### Custom Base URL - -Shannon supports pointing the SDK at any Anthropic-compatible endpoint (proxies, gateways, etc.) via `ANTHROPIC_BASE_URL`. - -Run `npx @keygraph/shannon setup` and select **Custom Base URL**. The wizard will prompt for your endpoint URL, auth token, and optionally let you override the default model tiers. - -Or export env vars directly: - -```bash -export ANTHROPIC_BASE_URL=https://your-proxy.example.com -export ANTHROPIC_AUTH_TOKEN=your-auth-token - -# Optionally override model tiers (defaults are used if not set) -export ANTHROPIC_SMALL_MODEL=claude-haiku-4-5-20251001 -export ANTHROPIC_MEDIUM_MODEL=claude-sonnet-4-6 -export ANTHROPIC_LARGE_MODEL=claude-opus-4-6 -``` - -
-Clone and Build: add to .env instead - -```bash -ANTHROPIC_BASE_URL=https://your-proxy.example.com -ANTHROPIC_AUTH_TOKEN=your-auth-token -ANTHROPIC_SMALL_MODEL=claude-haiku-4-5-20251001 -ANTHROPIC_MEDIUM_MODEL=claude-sonnet-4-6 -ANTHROPIC_LARGE_MODEL=claude-opus-4-6 -``` - -
- -### [EXPERIMENTAL - UNSUPPORTED] Router Mode (Alternative Providers) - -Shannon can experimentally route requests through alternative AI providers using claude-code-router. This mode is not officially supported and is intended primarily for: - -- **Model experimentation** — try Shannon with GPT-5.2 or Gemini 3-family models - -#### Quick Setup - -Run `npx @keygraph/shannon setup` and select **Router**. The wizard will prompt you to choose a provider (OpenAI or OpenRouter), enter your API key, and select a default model. - -Or export env vars directly: - -```bash -export OPENAI_API_KEY=sk-... # or OPENROUTER_API_KEY=sk-or-... -export ROUTER_DEFAULT=openai,gpt-5.2 # provider,model format -``` - -```bash -npx @keygraph/shannon start -u https://example.com -r /path/to/repo --router -``` - -
-Clone and Build: add to .env and run with --router - -```bash -OPENAI_API_KEY=sk-... -# OR -OPENROUTER_API_KEY=sk-or-... -ROUTER_DEFAULT=openai,gpt-5.2 -``` - -```bash -./shannon start -u https://example.com -r /path/to/repo --router -``` - -
- -#### Experimental Models - -| Provider | Models | -|----------|--------| -| OpenAI | gpt-5.2, gpt-5-mini | -| OpenRouter | google/gemini-3-flash-preview | - -#### Disclaimer - -This feature is experimental and unsupported. Output quality depends heavily on the model. Shannon is built on top of the Anthropic Agent SDK and is optimized and primarily tested with Anthropic Claude models. Alternative providers may produce inconsistent results (including failing early phases like Recon) depending on the model and routing setup. - -### Platform-Specific Instructions - -**For Windows:** - -*Native (Git Bash):* - -Install [Git for Windows](https://git-scm.com/install/windows) and run Shannon from **Git Bash** with Docker Desktop installed. Both `npx @keygraph/shannon` and local clone mode are supported. - -*WSL2 (Recommended):* - -**Step 1: Ensure WSL 2** - -```powershell -wsl --install -wsl --set-default-version 2 - -# Check installed distros -wsl --list --verbose - -# If you don't have a distro, install one (Ubuntu 24.04 recommended) -wsl --list --online -wsl --install Ubuntu-24.04 - -# If your distro shows VERSION 1, convert it to WSL 2: -wsl --set-version 2 -``` - -See [WSL basic commands](https://learn.microsoft.com/en-us/windows/wsl/basic-commands) for reference. - -**Step 2: Install Docker Desktop on Windows** and enable **WSL2 backend** under *Settings > General > Use the WSL 2 based engine*. - -**Step 3: Run Shannon inside WSL** using either flow. - -**npx inside WSL:** - -```bash -npx @keygraph/shannon setup -npx @keygraph/shannon start -u https://your-app.com -r /path/to/your-repo -``` - -
-Clone and Build command equivalents - -```bash -git clone https://github.com/KeygraphHQ/shannon.git -cd shannon -cp .env.example .env # Edit with your API key -./shannon start -u https://your-app.com -r /path/to/your-repo -``` - -
- -To access the Temporal Web UI, run `ip addr` inside WSL to find your WSL IP address, then navigate to `http://:8233` in your Windows browser. - -Windows Defender may flag exploit code in reports as false positives; see [Antivirus False Positives](#6-windows-antivirus-false-positives) below. - -**For Linux (Native Docker):** - -You may need to run commands with `sudo` depending on your Docker setup. If you encounter permission issues with output files, ensure your user has access to the Docker socket. - -**For macOS:** - -Works out of the box with Docker Desktop installed. - -**Testing Local Applications:** - -Docker containers cannot reach `localhost` on your host machine. Use `host.docker.internal` in place of `localhost`: - -```bash -npx @keygraph/shannon start -u http://host.docker.internal:3000 -r /path/to/repo -``` - -
-Clone and Build command equivalents - -```bash -./shannon start -u http://host.docker.internal:3000 -r /path/to/repo -``` - -
- -### Output and Results - -All results are saved to the workspaces directory: `./workspaces/` (local mode) or `~/.shannon/workspaces/` (npx mode). Use `-o ` to copy deliverables to a custom output directory after the run completes. - -Output structure: - -```text -workspaces/{hostname}_{sessionId}/ -├── session.json # Metrics and session data -├── workflow.log # Human-readable workflow log -├── agents/ # Per-agent execution logs -├── prompts/ # Prompt snapshots for reproducibility -└── deliverables/ - └── comprehensive_security_assessment_report.md # Final comprehensive security report -``` - ---- +Kubernetes manifests live in a separate repository: [farhoodlabs/hightower-infra](https://github.com/farhoodlabs/hightower-infra). ## Sample Reports Sample penetration test reports from industry-standard vulnerable applications: -#### **OWASP Juice Shop** • [GitHub](https://github.com/juice-shop/juice-shop) - -*A notoriously insecure web application maintained by OWASP, designed to test a tool's ability to uncover a wide range of modern vulnerabilities.* - -**Results**: Identified over 20 vulnerabilities across targeted OWASP categories in a single automated run. - -**Notable findings**: - -- Authentication bypass and full user database exfiltration via SQL injection -- Privilege escalation to administrator through registration workflow bypass -- IDOR vulnerabilities enabling access to other users' data and shopping carts -- SSRF enabling internal network reconnaissance - -[View Complete Report →](sample-reports/shannon-report-juice-shop.md) - ---- - -#### **c{api}tal API** • [GitHub](https://github.com/Checkmarx/capital) - -*An intentionally vulnerable API from Checkmarx, designed to test a tool's ability to uncover the OWASP API Security Top 10.* - -**Results**: Identified approximately 15 critical and high-severity vulnerabilities. - -**Notable findings**: - -- Root-level command injection via denylist bypass in a hidden debug endpoint -- Authentication bypass through a legacy, unpatched v1 API endpoint -- Privilege escalation via Mass Assignment in the user profile update function -- Zero false positives for XSS (correctly confirmed robust XSS defenses) - -[View Complete Report →](sample-reports/shannon-report-capital-api.md) - ---- - -#### **OWASP crAPI** • [GitHub](https://github.com/OWASP/crAPI) - -*A modern, intentionally vulnerable API from OWASP, designed to benchmark a tool's effectiveness against the OWASP API Security Top 10.* - -**Results**: Identified over 15 critical and high-severity vulnerabilities. - -**Notable findings**: - -- Authentication bypass via multiple JWT attacks (Algorithm Confusion, alg:none, weak key injection) -- Full PostgreSQL database compromise via injection, exfiltrating user credentials -- SSRF attack forwarding internal authentication tokens to an external service -- Zero false positives for XSS (correctly identified robust XSS defenses) - -[View Complete Report →](sample-reports/shannon-report-crapi.md) - ---- +- **OWASP Juice Shop** — 20+ vulnerabilities including auth bypass and database exfiltration. [View Report](sample-reports/shannon-report-juice-shop.md) +- **c{api}tal API** — ~15 critical/high vulnerabilities including command injection and auth bypass. [View Report](sample-reports/shannon-report-capital-api.md) +- **OWASP crAPI** — 15+ critical/high vulnerabilities including JWT attacks and database compromise. [View Report](sample-reports/shannon-report-crapi.md) ## Benchmark Shannon Lite scored **96.15% (100/104 exploits)** on a hint-free, source-aware variant of the XBOW security benchmark. -**[Full results with detailed agent logs and per-challenge pentest reports →](https://github.com/KeygraphHQ/xbow-validation-benchmarks/blob/main/xben-benchmark-results/)** - ---- - -## Architecture - -Shannon uses a multi-agent architecture that combines white-box source code analysis with dynamic exploitation across five phases: - -``` - ┌──────────────────────┐ - │ Pre-Reconnaissance │ - │ (nmap, subfinder, │ - │ whatweb, code scan) │ - └──────────┬───────────┘ - │ - ▼ - ┌──────────────────────┐ - │ Reconnaissance │ - │ (attack surface │ - │ mapping) │ - └──────────┬───────────┘ - │ - ▼ - ┌──────────┴───────────┐ - │ │ │ - ▼ ▼ ▼ - ┌───────────┐ ┌───────────┐ ┌───────────┐ - │ Vuln │ │ Vuln │ │ ... │ - │(Injection)│ │ (XSS) │ │ │ - └─────┬─────┘ └─────┬─────┘ └─────┬─────┘ - │ │ │ - ▼ ▼ ▼ - ┌───────────┐ ┌───────────┐ ┌───────────┐ - │ Exploit │ │ Exploit │ │ ... │ - │(Injection)│ │ (XSS) │ │ │ - └─────┬─────┘ └─────┬─────┘ └─────┬─────┘ - │ │ │ - └──────┬───────┴─────────────┘ - │ - ▼ - ┌──────────────────────┐ - │ Reporting │ - └──────────────────────┘ -``` - -### Architectural Overview - -Shannon uses Anthropic's Claude Agent SDK as its reasoning engine within a multi-agent architecture. The system combines white-box source code analysis with black-box dynamic exploitation, managed by an orchestrator across five phases. The architecture is designed for minimal false positives through a "no exploit, no report" policy. - -Each scan runs in its own ephemeral Docker container (`docker run --rm`) with a per-invocation Temporal task queue, enabling concurrent scans with different target repositories. - ---- - -#### **Phase 1: Pre-Reconnaissance** - -External scanning using nmap, subfinder, and whatweb to fingerprint the target's infrastructure and tech stack. Simultaneously performs source code analysis to identify the application framework, entry points, and potential attack surface from the codebase. - -#### **Phase 2: Reconnaissance** - -Builds a comprehensive attack surface map from the pre-recon findings. Shannon performs live application exploration via browser automation to correlate code-level insights with real-world behavior, producing a detailed map of all entry points, API endpoints, and authentication mechanisms. - -#### **Phase 3: Vulnerability Analysis** - -To maximize efficiency, this phase operates in parallel with 5 concurrent agents. Using the reconnaissance data, specialized agents for each OWASP category (injection, XSS, auth, authz, SSRF) hunt for potential flaws in parallel. For vulnerabilities like Injection and SSRF, agents perform a structured data flow analysis, tracing user input to dangerous sinks. This phase produces a key deliverable: a list of **hypothesized exploitable paths** that are passed on for validation. - -#### **Phase 4: Exploitation** - -Continuing the parallel workflow to maintain speed, this phase is dedicated entirely to turning hypotheses into proof. Dedicated exploit agents receive the hypothesized paths and attempt to execute real-world attacks using browser automation, command-line tools, and custom scripts. This phase enforces a strict **"No Exploit, No Report"** policy: if a hypothesis cannot be successfully exploited to demonstrate impact, it is discarded as a false positive. - -#### **Phase 5: Reporting** - -The final phase compiles all validated findings into a professional, actionable report. An agent consolidates the reconnaissance data and the successful exploit evidence, cleaning up any noise or hallucinated artifacts. Only verified vulnerabilities are included, complete with **reproducible, copy-and-paste Proof-of-Concepts**, delivering a final pentest-grade report focused exclusively on proven risks. - - -## Coverage and Roadmap - -For detailed information about Shannon's security testing coverage and development roadmap, see our [Coverage and Roadmap](./COVERAGE.md) documentation. +[Full results with detailed agent logs and per-challenge pentest reports](https://github.com/KeygraphHQ/xbow-validation-benchmarks/blob/main/xben-benchmark-results/) ## Disclaimers -### Important Usage Guidelines & Disclaimers - -Please review the following guidelines carefully before using Shannon (Lite). As a user, you are responsible for your actions and assume all liability. - -#### **1. Potential for Mutative Effects & Environment Selection** - -This is not a passive scanner. The exploitation agents are designed to **actively execute attacks** to confirm vulnerabilities. This process can have mutative effects on the target application and its data. - > [!WARNING] -> **DO NOT run Shannon on production environments.** -> -> - It is intended exclusively for use on sandboxed, staging, or local development environments where data integrity is not a concern. -> - Potential mutative effects include, but are not limited to: creating new users, modifying or deleting data, compromising test accounts, and triggering unintended side effects from injection attacks. - -#### **2. Legal & Ethical Use** - -Shannon is designed for legitimate security auditing purposes only. +> **DO NOT run Hightower on production environments.** +> It actively executes attacks to confirm vulnerabilities. Use only on sandboxed, staging, or local development environments. > [!CAUTION] -> **You must have explicit, written authorization** from the owner of the target system before running Shannon. -> -> Unauthorized scanning and exploitation of systems you do not own is illegal and can be prosecuted under laws such as the Computer Fraud and Abuse Act (CFAA). Keygraph is not responsible for any misuse of Shannon. - -#### **3. LLM & Automation Caveats** - -- **Verification is Required**: While significant engineering has gone into our "proof-by-exploitation" methodology to eliminate false positives, the underlying LLMs can still generate hallucinated or weakly-supported content in the final report. **Human oversight is essential** to validate the legitimacy and severity of all reported findings. -- **Comprehensiveness**: The analysis in Shannon Lite may not be exhaustive due to the inherent limitations of LLM context windows. For a more comprehensive, graph-based analysis of your entire codebase, **Shannon Pro** leverages its advanced data flow analysis engine to ensure deeper and more thorough coverage. - -#### **4. Scope of Analysis** - -- **Targeted Vulnerabilities**: The current version of Shannon Lite specifically targets the following classes of *exploitable* vulnerabilities: - - Broken Authentication & Authorization - - Injection - - Cross-Site Scripting (XSS) - - Server-Side Request Forgery (SSRF) -- **What Shannon Lite Does Not Cover**: This list is not exhaustive of all potential security risks. Shannon Lite's "proof-by-exploitation" model means it will not report on issues it cannot actively exploit, such as vulnerable third-party libraries or insecure configurations. These types of deep static-analysis findings are a core focus of the advanced analysis engine in **Shannon Pro**. - -#### **5. Cost & Performance** - -- **Time**: As of the current version, a full test run typically takes **1 to 1.5 hours** to complete. -- **Cost**: Running the full test using Anthropic's Claude 4.5 Sonnet model may incur costs of approximately **$50 USD**. Costs vary based on model pricing and application complexity. - -#### **6. Windows Antivirus False Positives** - -Windows Defender may flag files in `xben-benchmark-results/` or `deliverables/` as malware. These are false positives caused by exploit code in the reports. Add an exclusion for the Shannon directory in Windows Defender, or use Docker/WSL2. - -#### **7. Security Considerations** - -Shannon Lite is designed for scanning repositories and applications you own or have explicit permission to test. Do not point it at untrusted or adversarial codebases. Like any AI-powered tool that reads source code, Shannon Lite is susceptible to prompt injection from content in the scanned repository. +> **You must have explicit, written authorization** from the owner of the target system before running Hightower. Unauthorized scanning is illegal. +- **Verification is Required**: Human oversight is essential to validate all reported findings. LLMs can still generate hallucinated content. +- **Targeted Vulnerabilities**: Broken Authentication & Authorization, Injection, XSS, SSRF. +- **Cost**: A full test run typically takes 1-1.5 hours and may cost ~$50 USD using Claude Sonnet. ## License -Shannon Lite is released under the [GNU Affero General Public License v3.0 (AGPL-3.0)](LICENSE). +Released under the [GNU Affero General Public License v3.0 (AGPL-3.0)](LICENSE). -Shannon is open source (AGPL v3). This license allows you to: -- Use it freely for all internal security testing. -- Modify the code privately for internal use without sharing your changes. +## Support -The AGPL's sharing requirements primarily apply to organizations offering Shannon as a public or managed service (such as a SaaS platform). In those specific cases, any modifications made to the core software must be open-sourced. - - -## Community & Support - -### Community Resources - -**1:1 Office Hours** — Thursdays, two time zones -Book a free 15-min session for hands-on help with bugs, deployments, or config questions. -→ US/EU: 10:00 AM PT | Asia: 2:00 PM IST -→ [Book a slot](https://cal.com/george-flores-keygraph/shannon-community-office-hours) - -[Join our Discord](https://discord.gg/cmctpMBXwE) to ask questions, share feedback, and connect with other Shannon users. - -**Contributing:** At this time, we're not accepting external code contributions (PRs). -Issues are welcome for bug reports and feature requests. - -- **Report bugs** via [GitHub Issues](https://github.com/KeygraphHQ/shannon/issues) -- **Suggest features** in [Discussions](https://github.com/KeygraphHQ/shannon/discussions) - -### Stay Connected - -- **Twitter**: [@KeygraphHQ](https://twitter.com/KeygraphHQ) -- **LinkedIn**: [Keygraph](https://linkedin.com/company/keygraph) -- **Website**: [keygraph.io](https://keygraph.io) - - - -## Get in Touch - -### Shannon Pro - -Shannon Pro is Keygraph's all-in-one AppSec platform. For organizations that need unified SAST, SCA, and autonomous pentesting with static-dynamic correlation, CI/CD integration, or self-hosted deployment, see the [Shannon Pro technical overview](./SHANNON-PRO.md). - -

- - Shannon Pro Inquiry - -

- -**Email**: [shannon@keygraph.io](mailto:shannon@keygraph.io) +- **Report bugs**: [GitHub Issues](https://github.com/farhoodlabs/hightower/issues) +- **Discussions**: [GitHub Discussions](https://github.com/farhoodlabs/hightower/discussions) ---

- Built by Keygraph + Based on Shannon by Keygraph

diff --git a/apps/api/infra/base/deployment.yaml b/apps/api/infra/base/deployment.yaml deleted file mode 100644 index 70f7e85..0000000 --- a/apps/api/infra/base/deployment.yaml +++ /dev/null @@ -1,62 +0,0 @@ -apiVersion: apps/v1 -kind: Deployment -metadata: - name: hightower-api - namespace: hightower - labels: - app: hightower-api -spec: - replicas: 1 - selector: - matchLabels: - app: hightower-api - template: - metadata: - labels: - app: hightower-api - annotations: - kubectl.kubernetes.io/restartedAt: "2026-04-21T22:21:00Z" - spec: - serviceAccountName: hightower-api - containers: - - name: api - image: ghcr.io/farhoodliquor/hightower-api:sha-a0efe7604ebc2f27cc37ee88f117ae619e57003f - imagePullPolicy: Always - ports: - - containerPort: 3000 - name: http - env: - - name: TEMPORAL_ADDRESS - value: hightower-temporal:7233 - - name: WORKER_IMAGE - value: ghcr.io/farhoodliquor/shannon:latest - - name: K8S_NAMESPACE - value: hightower - envFrom: - - secretRef: - name: hightower-credentials - volumeMounts: - - name: workspaces - mountPath: /app/workspaces - livenessProbe: - httpGet: - path: /healthz - port: 3000 - initialDelaySeconds: 5 - periodSeconds: 10 - readinessProbe: - httpGet: - path: /readyz - port: 3000 - initialDelaySeconds: 10 - periodSeconds: 10 - resources: - requests: - memory: 128Mi - cpu: 100m - limits: - memory: 256Mi - volumes: - - name: workspaces - persistentVolumeClaim: - claimName: hightower-workspaces diff --git a/apps/api/infra/base/kustomization.yaml b/apps/api/infra/base/kustomization.yaml deleted file mode 100644 index 834c27d..0000000 --- a/apps/api/infra/base/kustomization.yaml +++ /dev/null @@ -1,7 +0,0 @@ -apiVersion: kustomize.config.k8s.io/v1beta1 -kind: Kustomization -resources: - - deployment.yaml - - service.yaml - - serviceaccount.yaml - - rbac.yaml diff --git a/apps/api/infra/base/rbac.yaml b/apps/api/infra/base/rbac.yaml deleted file mode 100644 index 6da2114..0000000 --- a/apps/api/infra/base/rbac.yaml +++ /dev/null @@ -1,53 +0,0 @@ -apiVersion: rbac.authorization.k8s.io/v1 -kind: Role -metadata: - name: hightower-api - namespace: hightower -rules: - - apiGroups: ["batch"] - resources: ["jobs"] - verbs: ["create", "get", "list", "delete", "watch"] - - apiGroups: [""] - resources: ["pods"] - verbs: ["get", "list", "watch"] - - apiGroups: [""] - resources: ["pods/log"] - verbs: ["get"] ---- -apiVersion: rbac.authorization.k8s.io/v1 -kind: RoleBinding -metadata: - name: hightower-api - namespace: hightower -subjects: - - kind: ServiceAccount - name: hightower-api - namespace: hightower -roleRef: - kind: Role - name: hightower-api - apiGroup: rbac.authorization.k8s.io ---- -apiVersion: rbac.authorization.k8s.io/v1 -kind: Role -metadata: - name: hightower-deploy-manager - namespace: hightower -rules: - - apiGroups: ["apps"] - resources: ["deployments"] - verbs: ["get", "list", "watch", "update", "patch"] ---- -apiVersion: rbac.authorization.k8s.io/v1 -kind: RoleBinding -metadata: - name: farh-net-deploy-manager - namespace: hightower -subjects: - - kind: ServiceAccount - name: farh-net-paperclip - namespace: farh-net -roleRef: - kind: Role - name: hightower-deploy-manager - apiGroup: rbac.authorization.k8s.io diff --git a/apps/api/infra/base/service.yaml b/apps/api/infra/base/service.yaml deleted file mode 100644 index b335760..0000000 --- a/apps/api/infra/base/service.yaml +++ /dev/null @@ -1,12 +0,0 @@ -apiVersion: v1 -kind: Service -metadata: - name: hightower-api - namespace: hightower -spec: - selector: - app: hightower-api - ports: - - name: http - port: 3000 - targetPort: 3000 diff --git a/apps/api/infra/base/serviceaccount.yaml b/apps/api/infra/base/serviceaccount.yaml deleted file mode 100644 index 7c02492..0000000 --- a/apps/api/infra/base/serviceaccount.yaml +++ /dev/null @@ -1,5 +0,0 @@ -apiVersion: v1 -kind: ServiceAccount -metadata: - name: hightower-api - namespace: hightower diff --git a/apps/api/infra/overlays/dev/kustomization.yaml b/apps/api/infra/overlays/dev/kustomization.yaml deleted file mode 100644 index 5f9a5ee..0000000 --- a/apps/api/infra/overlays/dev/kustomization.yaml +++ /dev/null @@ -1,16 +0,0 @@ -apiVersion: kustomize.config.k8s.io/v1beta1 -kind: Kustomization -resources: - - ../../base -patches: - - patch: |- - apiVersion: apps/v1 - kind: Deployment - metadata: - name: hightower-api - spec: - template: - spec: - containers: - - name: api - imagePullPolicy: Never diff --git a/apps/cli/infra/compose.yml b/apps/cli/infra/compose.yml deleted file mode 100644 index df8fbde..0000000 --- a/apps/cli/infra/compose.yml +++ /dev/null @@ -1,50 +0,0 @@ -networks: - default: - name: shannon-net - -services: - temporal: - image: temporalio/temporal:latest - container_name: shannon-temporal - command: ["server", "start-dev", "--db-filename", "/home/temporal/temporal.db", "--ip", "0.0.0.0"] - ports: - - "127.0.0.1:7233:7233" - - "127.0.0.1:8233:8233" - volumes: - - temporal-data:/home/temporal - healthcheck: - test: ["CMD", "temporal", "operator", "cluster", "health", "--address", "localhost:7233"] - interval: 10s - timeout: 5s - retries: 10 - start_period: 30s - - router: - image: node:20-slim - container_name: shannon-router - profiles: ["router"] - command: > - sh -c "apt-get update && apt-get install -y gettext-base && - npm install -g @musistudio/claude-code-router && - mkdir -p /root/.claude-code-router && - envsubst < /config/router-config.json > /root/.claude-code-router/config.json && - ccr start" - ports: - - "127.0.0.1:3456:3456" - volumes: - - ./router-config.json:/config/router-config.json:ro - environment: - - HOST=0.0.0.0 - - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY:-} - - OPENAI_API_KEY=${OPENAI_API_KEY:-} - - OPENROUTER_API_KEY=${OPENROUTER_API_KEY:-} - - ROUTER_DEFAULT=${ROUTER_DEFAULT:-openai,gpt-4o} - healthcheck: - test: ["CMD", "node", "-e", "require('http').get('http://localhost:3456/health', r => process.exit(r.statusCode === 200 ? 0 : 1)).on('error', () => process.exit(1))"] - interval: 10s - timeout: 5s - retries: 5 - start_period: 30s - -volumes: - temporal-data: diff --git a/apps/cli/infra/k8s/router.yaml b/apps/cli/infra/k8s/router.yaml deleted file mode 100644 index 9c25871..0000000 --- a/apps/cli/infra/k8s/router.yaml +++ /dev/null @@ -1,69 +0,0 @@ -apiVersion: apps/v1 -kind: Deployment -metadata: - name: hightower-router - namespace: hightower - labels: - app: hightower-router -spec: - replicas: 1 - selector: - matchLabels: - app: hightower-router - template: - metadata: - labels: - app: hightower-router - spec: - containers: - - name: router - image: node:20-slim - command: - - sh - - -c - - | - apt-get update && apt-get install -y gettext-base && - npm install -g @musistudio/claude-code-router && - mkdir -p /root/.claude-code-router && - envsubst < /config/router-config.json > /root/.claude-code-router/config.json && - ccr start - ports: - - containerPort: 3456 - envFrom: - - secretRef: - name: hightower-credentials - env: - - name: HOST - value: "0.0.0.0" - volumeMounts: - - name: config - mountPath: /config - readOnly: true - readinessProbe: - httpGet: - path: /health - port: 3456 - initialDelaySeconds: 30 - periodSeconds: 10 - timeoutSeconds: 5 - failureThreshold: 5 - resources: - requests: - memory: 128Mi - cpu: 100m - volumes: - - name: config - configMap: - name: hightower-router-config ---- -apiVersion: v1 -kind: Service -metadata: - name: hightower-router - namespace: hightower -spec: - selector: - app: hightower-router - ports: - - port: 3456 - targetPort: 3456 diff --git a/apps/cli/infra/k8s/temporal.yaml b/apps/cli/infra/k8s/temporal.yaml deleted file mode 100644 index 56ea1bc..0000000 --- a/apps/cli/infra/k8s/temporal.yaml +++ /dev/null @@ -1,98 +0,0 @@ -# CNPG PostgreSQL cluster for Temporal persistence -apiVersion: postgresql.cnpg.io/v1 -kind: Cluster -metadata: - name: hightower-temporal-db - namespace: hightower -spec: - instances: 1 - storage: - size: 5Gi - storageClass: ceph-block - bootstrap: - initdb: - database: temporal - owner: temporal - postInitSQL: - - CREATE DATABASE temporal_visibility OWNER temporal; ---- -# Temporal auto-setup — handles schema creation/migration automatically -apiVersion: apps/v1 -kind: Deployment -metadata: - name: hightower-temporal - namespace: hightower - labels: - app: hightower-temporal -spec: - replicas: 1 - selector: - matchLabels: - app: hightower-temporal - template: - metadata: - labels: - app: hightower-temporal - spec: - containers: - - name: temporal - image: temporalio/auto-setup:latest - ports: - - containerPort: 7233 - name: grpc - - containerPort: 8233 - name: web-ui - env: - - name: DB - value: postgres12 - - name: DB_PORT - value: "5432" - - name: POSTGRES_SEEDS - value: hightower-temporal-db-rw - - name: DBNAME - value: temporal - - name: VISIBILITY_DBNAME - value: temporal_visibility - - name: POSTGRES_USER - valueFrom: - secretKeyRef: - name: hightower-temporal-db-app - key: username - - name: POSTGRES_PWD - valueFrom: - secretKeyRef: - name: hightower-temporal-db-app - key: password - - name: NUM_HISTORY_SHARDS - value: "4" - - name: SKIP_DB_CREATE - value: "true" - readinessProbe: - tcpSocket: - port: 7233 - initialDelaySeconds: 30 - periodSeconds: 10 - timeoutSeconds: 5 - failureThreshold: 15 - resources: - requests: - memory: 512Mi - cpu: 250m - limits: - memory: 1Gi ---- -apiVersion: v1 -kind: Service -metadata: - name: hightower-temporal - namespace: hightower -spec: - selector: - app: hightower-temporal - ports: - - name: grpc - port: 7233 - targetPort: 7233 - - name: web-ui - port: 8233 - targetPort: 8233 diff --git a/apps/cli/infra/k8s/workspaces-pvc.yaml b/apps/cli/infra/k8s/workspaces-pvc.yaml deleted file mode 100644 index 94633d1..0000000 --- a/apps/cli/infra/k8s/workspaces-pvc.yaml +++ /dev/null @@ -1,12 +0,0 @@ -apiVersion: v1 -kind: PersistentVolumeClaim -metadata: - name: hightower-workspaces - namespace: hightower -spec: - accessModes: - - ReadWriteMany - storageClassName: ceph-filesystem - resources: - requests: - storage: 10Gi diff --git a/docker-compose.yml b/docker-compose.yml deleted file mode 100644 index 6c0e5a4..0000000 --- a/docker-compose.yml +++ /dev/null @@ -1,52 +0,0 @@ -networks: - default: - name: shannon-net - -services: - temporal: - image: temporalio/temporal:latest - container_name: shannon-temporal - command: ["server", "start-dev", "--db-filename", "/home/temporal/temporal.db", "--ip", "0.0.0.0"] - ports: - - "127.0.0.1:7233:7233" # gRPC - - "127.0.0.1:8233:8233" # Web UI (built-in) - volumes: - - temporal-data:/home/temporal - healthcheck: - test: ["CMD", "temporal", "operator", "cluster", "health", "--address", "localhost:7233"] - interval: 10s - timeout: 5s - retries: 10 - start_period: 30s - - # Optional: claude-code-router for multi-model support - # Start with: ROUTER=true ./shannon start ... - router: - image: node:20-slim - container_name: shannon-router - profiles: ["router"] # Only starts when explicitly requested - command: > - sh -c "apt-get update && apt-get install -y gettext-base && - npm install -g @musistudio/claude-code-router && - mkdir -p /root/.claude-code-router && - envsubst < /config/router-config.json > /root/.claude-code-router/config.json && - ccr start" - ports: - - "127.0.0.1:3456:3456" - volumes: - - ./apps/cli/infra/router-config.json:/config/router-config.json:ro - environment: - - HOST=0.0.0.0 - - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY:-} - - OPENAI_API_KEY=${OPENAI_API_KEY:-} - - OPENROUTER_API_KEY=${OPENROUTER_API_KEY:-} - - ROUTER_DEFAULT=${ROUTER_DEFAULT:-openai,gpt-4o} - healthcheck: - test: ["CMD", "node", "-e", "require('http').get('http://localhost:3456/health', r => process.exit(r.statusCode === 200 ? 0 : 1)).on('error', () => process.exit(1))"] - interval: 10s - timeout: 5s - retries: 5 - start_period: 30s - -volumes: - temporal-data: diff --git a/shannon b/shannon deleted file mode 100755 index 6a3efae..0000000 --- a/shannon +++ /dev/null @@ -1,3 +0,0 @@ -#!/usr/bin/env node -process.env.SHANNON_LOCAL = '1'; -import('./apps/cli/dist/index.mjs');