\n\n# Zen\n\n### Open-source offensive security agents. Autonomous pentesting that discovers, exploits, and remediates vulnerabilities in running code.\n\n \n\n\n\n\n\n\n\n\n\n\n\n\n
\n\n\n> [!TIP]\n> Zen executes natively inside GitHub Actions and other CI/CD systems. Assess every pull request and stop exploitable code at the merge boundary rather than in production - [Get started with no setup required](https://app.zenney.uk).\n\n---\n\n\n## What is Zen\n\nZen dispatches a fleet of autonomous agents that execute your application, observe its runtime behavior, and confirm each defect by exploiting it. Nothing is reported until it has been reproduced, so the output is a set of demonstrated attacks rather than a queue of suspicions. It targets engineering organizations that need security validation at a cadence manual assessment cannot sustain, and at a precision static analysis does not reach.\n\n**Core capabilities:**\n\n- **Complete offensive tooling** — reconnaissance, exploitation, and verification in one runtime, with nothing to assemble\n- **Multi-agent execution** — specialized agents partition the target and scale horizontally across it\n- **Proof-carrying findings** — every report ships with a proof-of-concept that executes against the live target\n- **Terminal-native workflow** — output written for the engineer who has to land the fix, remediation context included\n- **Automated remediation and reporting** — generated patches, plus assessment documents formatted for audit\n\n\n \n\n## Where it fits\n\n- **Application Security Testing** — locate exploitable defects across an application and confirm each one is reachable\n- **Rapid Penetration Testing** — compress a full engagement, compliance documentation included, from weeks into hours\n- **Bug Bounty Automation** — automate the reconnaissance and exploitation loop, then submit against generated proof-of-concepts\n- **CI/CD Integration** — enforce a security gate in the pipeline so exploitable code never reaches production\n\n## 🚀 Get started\n\n**Requirements:**\n- A running Docker daemon\n- One of:\n - **Claude Code** installed and signed in, with the Zen bridge running — no API key required\n - A **DeepSeek API key**\n\nSee [supported providers](https://docs.zenney.uk/llm-providers/overview) for the full list.\n\n### Install and run an assessment\n\n```bash\n# Install Zen\ncurl -sSL https://zenney.uk/install | bash\n\n# Option A — Claude via the bridge\nnpm install -g @anthropic-ai/claude-code\nclaude # sign in once, then exit\npython -m zen.bridge # starts the bridge; connects the session automatically\n\nexport ZEN_LLM=\"claude/claude-opus-4-8\"\n\n# Option B — DeepSeek API key\nexport ZEN_LLM=\"deepseek/deepseek-v4-pro\"\nexport DEEPSEEK_API_KEY=\"your-deepseek-api-key\"\n\n# Run your first security assessment\nzen --target ./app-directory\n```\n\n> [!NOTE]\n> The sandbox image (`ghcr.io/zenneyy/zen-sandbox:1.2.0`) is pulled on first execution. Run artifacts are written to `zen_runs/`.\n\n---\n\n## ✨ Architecture\n\n### Agent tooling\n\nEvery agent operates the same instrumentation a professional penetration tester would reach for:\n\n- **HTTP Interception Proxy** — Caido, integrated for complete request and response manipulation and analysis\n- **Browser Exploitation** — an instrumented browser covering XSS, CSRF, clickjacking, and authentication bypass flows\n- **Shell & Command Execution** — an interactive terminal for exploit development and post-exploitation activity\n- **Custom Exploit Runtime** — a Python sandbox in which proof-of-concept code is authored and verified\n- **Reconnaissance & OSINT** — automated attack surface mapping, subdomain enumeration, and service fingerprinting\n- **Static & Dynamic Code Analysis** — SAST and DAST in combination, so both the code and its running form are covered\n- **Vulnerability Knowledge Base** — findings held in structured form, with CVSS scoring and OWASP classification\n\n### Vulnerability coverage\n\nDetection, validation, and exploitation span the OWASP Top 10 and extend well past it:\n\n- **Broken Access Control** — IDOR, horizontal and vertical privilege escalation, authorization bypass\n- **Injection Attacks** — SQL and NoSQL injection, OS command injection, SSTI\n- **Server-Side Vulnerabilities** — SSRF, remote code execution, insecure deserialization, XXE\n- **Client-Side Attacks** — stored, reflected, and DOM-based XSS, prototype pollution, CSRF\n- **Business Logic Flaws** — workflow bypass, payment manipulation, race conditions\n- **Authentication & Session** — credential stuffing vectors, session fixation, JWT attacks\n- **Infrastructure & Cloud** — misconfiguration, unintentionally exposed services, cloud security weaknesses\n- **API Security** — broken authentication, mass assignment, rate limit bypass\n\n### Agent graph (distributed execution)\n\nCoordination between agents is what makes that breadth tractable:\n\n- **Distributed Pentesting** — reconnaissance, exploitation, and post-exploitation each assigned to a specialist agent\n- **Scalable Security Testing** — targets assessed concurrently, so coverage does not trade against wall-clock time\n- **Dynamic Coordination** — agents propagate discoveries between themselves and chain vulnerabilities the way a red team does\n\n---\n\n## 🖥️ Local result viewer\n\nArtifacts are written to disk as the assessment proceeds. A single command renders them in a local dashboard:\n\n```bash\n# Open the most recent run\nzen view\n\n# ...or open a specific run by name\nzen view my-run-name\n\n# Expose the viewer on all IPv4 interfaces at a fixed port\nzen view --host 0.0.0.0 --port 8080 --no-open\n```\n\n`zen view` binds a lightweight server to `127.0.0.1` on an ephemeral port and opens a private, token-scoped URL in your browser. Nothing transits the network: the dashboard reads run files directly from the filesystem, with no account provisioning and no upload step. The interface is compiled into the distribution, so there is no additional dependency and no JavaScript build to run.\n\nTo reach the viewer from another host, pass `--host 0.0.0.0` and substitute a resolvable hostname or address for the `0.0.0.0` in the emitted URL. Handle that URL as a credential: its token authorizes access to the selected run's scan data, history, and steering interface, so restrict distribution and firewall the port accordingly. Requests that carry no token-derived session are refused.\n\n### Viewer surfaces\n\n- **Overview**: current run state, the configured target, and a severity distribution across findings so far.\n- **Vulnerabilities**: each validated finding with severity, supporting detail, and a reproduction sequence.\n- **Agent graph**: a live topology of the agent fleet, showing the task assigned to each node.\n- **Steering**: inject instructions into an in-flight assessment and redirect the agents without restarting.\n- **History**: every prior run recorded on this host, addressable directly.\n- **Reports**: compile a distributable report and dispatch it by email.\n\n---\n\n## Usage patterns\n\n### Common invocations\n\n```bash\n# Scan a local codebase\nzen --target ./app-directory\n\n# Security review of a GitHub repository\nzen --target https://github.com/org/repo\n\n# Black-box web application assessment\nzen --target https://your-app.com\n```\n\n### Assessment from an API specification (OpenAPI / Swagger / Postman)\n\nSupply a contract and Zen exercises every endpoint the specification\ndeclares, instead of inferring the surface by crawling. Pair the\nspecification with the live base URL so requests are routed correctly:\n\n```bash\n# OpenAPI / Swagger file (.json / .yaml)\nzen --target ./openapi.yaml --target https://api.your-app.com\n\n# Postman collection export\nzen --target ./collection.postman_collection.json --target https://api.your-app.com\n\n# Postman collection pulled live by id (no manual export)\nexport POSTMAN_API_KEY=\"PMAK-...\"\nzen --target postman://\n\n# ...with a Postman environment to resolve {{baseUrl}} / token variables\nzen --target \"postman://?env=\"\n```\n\n\n### Advanced invocations\n\n```bash\n# Grey-box authenticated testing\nzen --target https://your-app.com --instruction \"Perform authenticated testing using credentials: user:pass\"\n\n# Multi-target testing (source code + deployed app)\nzen -t https://github.com/org/app -t https://your-app.com\n\n# Targets from a file, one target per non-empty, non-comment line\nzen --target-list ./targets.txt\n\n# White-box source-aware scan (local repository)\nzen --target ./app-directory --scan-mode standard\n\n# Focused testing with custom instructions\nzen --target api.your-app.com --instruction \"Focus on business logic flaws and IDOR vulnerabilities\"\n\n# Provide detailed instructions through file (e.g., rules of engagement, scope, exclusions)\nzen --target api.your-app.com --instruction-file ./instruction.md\n\n# Force PR diff-scope against a specific base branch\nzen -n --target ./ --scan-mode quick --scope-mode diff --diff-base origin/main\n```\n\n### Headless execution\n\n`-n/--non-interactive` disables the terminal UI, which is the correct mode for servers and scheduled jobs. Findings stream to stdout as they are validated, the final report follows, and the process terminates with a non-zero status when anything was found.\n\n```bash\nzen -n --target https://your-app.com\n```\n\n### GitHub Actions integration\n\nA minimal workflow is sufficient to assess every pull request:\n\n```yaml\nname: zen-penetration-test\n\non:\n pull_request:\n\njobs:\n security-scan:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v6\n with:\n fetch-depth: 0\n\n - name: Install Zen\n run: curl -sSL https://zenney.uk/install | bash\n\n - name: Run Zen\n env:\n ZEN_LLM: ${{ secrets.ZEN_LLM }}\n DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_API_KEY }}\n\n run: zen -n -t ./ --scan-mode quick\n```\n\n> [!TIP]\n> During pull request runs, Zen restricts quick reviews to the changed file set automatically.\n> Where the diff scope cannot be resolved, confirm the checkout retrieved full history\n> (`fetch-depth: 0`), or supply `--diff-base` explicitly.\n>\n> CI runners cannot complete an interactive Claude Code sign-in, so use the DeepSeek API key path\n> for pipeline runs.\n\n### Environment configuration\n\n```bash\n# Model selection — pick one\nexport ZEN_LLM=\"claude/claude-opus-4-8\" # Claude, via the bridge\nexport ZEN_LLM=\"claude/claude-opus-4-6\" # Prior Claude generation, same path\nexport ZEN_LLM=\"deepseek/deepseek-v4-pro\" # DeepSeek V4 Pro, API key required\nexport ZEN_LLM=\"deepseek/deepseek-v4-flash\" # DeepSeek V4 Flash, API key required\n\n# API keys — only required for DeepSeek\nexport DEEPSEEK_API_KEY=\"your-deepseek-api-key\"\n\n# Optional\nexport LLM_API_BASE=\"your-api-base-url\" # if using a local model (Ollama, LMStudio)\nexport PERPLEXITY_API_KEY=\"your-api-key\" # for search capabilities\nexport ZEN_REASONING_EFFORT=\"high\" # thinking effort (default: high, quick scan: medium)\n```\n\n> [!NOTE]\n> Configuration is persisted to `~/.zen/cli-config.json` on write, so these values survive between runs. Claude credentials are not written there — the bridge reads them from the Claude Code session at runtime.\n\n#### Sign in with a ChatGPT subscription\n\nInstead of a metered API key, you can run Zen on your ChatGPT Plus/Pro subscription:\n\n```bash\nzen auth login chatgpt # sign in with your ChatGPT account\nexport ZEN_LLM=\"chatgpt/gpt-5.4\" # chatgpt/ runs on the subscription\nzen auth status # show the active sign-in, or logout to forget it\n```\n#### Claude via the bridge\n\nZen has no Claude login of its own. Install Claude Code, sign in there once, then start the bridge — it picks up that session automatically and serves it to Zen for the duration of the run.\n\n```bash\n# One-time setup\nnpm install -g @anthropic-ai/claude-code\nclaude # sign in on first run, then exit\n\n# Start the bridge (leave it running)\npython -m zen.bridge\n\n# In another shell\nexport ZEN_LLM=\"claude/claude-opus-4-8\"\nzen --target ./app-directory\n```\n\nThe bridge is a long-running local process: start it before a scan and leave it up. No API key is stored, and no credentials are copied into Zen's own configuration. If the Claude Code session expires, run `claude` again to sign back in — the bridge reconnects without a restart.\n\nUse the DeepSeek API key path instead if you need a metered, non-subscription setup, if you plan to run at concurrency that exceeds subscription rate limits, or if you are running in CI where an interactive sign-in is not possible.\n\n#### MCP server integration\n\nZen can attach to Model Context Protocol (MCP) servers and expose their tools to the agents during a run. Declare them in `~/.zen/mcp-servers.json` as a JSON array. Each entry is either a `stdio` server that Zen launches as a local subprocess, or a remote `http` endpoint:\n\n```json\n[\n {\n \"name\": \"local_fs\",\n \"transport\": \"stdio\",\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem\", \"/path/to/project\"]\n },\n {\n \"name\": \"github\",\n \"transport\": \"http\",\n \"url\": \"https://api.githubcopilot.com/mcp/\",\n \"auth\": { \"kind\": \"bearer\", \"token\": \"your-token\" },\n \"allowed_tools\": [\"list_issues\"]\n }\n]\n```\n\nTool identifiers are namespaced under the server's `name` — `local_fs_read_file`, for example. Omitting `allowed_tools` exposes the server's full tool set; supplying a list constrains the agents to those entries. The file itself is optional, and a server that fails to connect is skipped without aborting the run. Set `ZEN_MCP_CONFIG` to load the declaration from another path.\n\n**Recommended model configurations:**\n\n- [Anthropic Claude Opus 4.8](https://claude.com/platform/api) — `claude/claude-opus-4-8` (via the bridge, no API key)\n- [Anthropic Claude Opus 4.6](https://claude.com/platform/api) — `claude/claude-opus-4-6` (via the bridge, prior generation)\n- [DeepSeek V4 Pro](https://platform.deepseek.com/) — `deepseek/deepseek-v4-pro` (API key)\n- [DeepSeek V4 Flash](https://platform.deepseek.com/) — `deepseek/deepseek-v4-flash` (API key, faster and cheaper tier)\n\nLocally hosted models are supported through the `LLM_API_BASE` override; the [LLM Providers documentation](https://docs.zenney.uk/llm-providers/overview) enumerates every configuration option.\n\n## Reference documentation\n\nThe complete reference lives at **[docs.zenney.uk](https://docs.zenney.uk)**, covering usage, CI/CD integration, skills, and advanced configuration.\n\n## Development and contributions\n\nCode, documentation, and new skills are all in scope. Start from the [Contributing Guide](https://docs.zenney.uk/contributing), or go directly to a [pull request](https://github.com/zenneyy/zen-ai/pulls)/[issue](https://github.com/zenneyy/zen-ai/issues).\n\n## Community\n\nQuestions, defect reports, and design discussion happen on **[Discord](https://discord.gg/v5dPr4wcTz)**.\n\n## Support\n\nIf Zen earns a place in your toolchain, a ⭐ on GitHub helps others find it.\n\n## License and attribution\n\nZen is licensed under the Apache License, Version 2.0. See [`LICENSE`](LICENSE) for the full text and [`NOTICE`](NOTICE) for attribution.\n\nZen is a derivative work of [Strix](https://github.com/usestrix/strix), Copyright 2025 OmniSecure Inc., licensed under Apache-2.0. Files throughout this distribution have been modified from the original Strix sources. Our thanks to the Strix team for the foundation this builds on.\n\n## Upstream projects\n\nZen and Strix both build on [LiteLLM](https://github.com/BerriAI/litellm), [Caido](https://github.com/caido/caido), [Nuclei](https://github.com/projectdiscovery/nuclei), [Playwright](https://github.com/microsoft/playwright), and [Bubble Tea](https://github.com/charmbracelet/bubbletea). Our thanks to the teams maintaining them.\n\n\n> [!WARNING]\n> **Authorized use only.** Zen executes live attacks against whatever target it is given. Run it exclusively against systems you own or hold **explicit, written permission** to assess, and remain within the agreed scope. Unauthorized testing carries criminal liability in most jurisdictions.\n>\n> Obtaining that authorization and complying with applicable law is the operator's responsibility. Zen is distributed \"as is\", without warranty, and its authors accept no liability for misuse.\n>\n> **Model behavior.** Autonomous agents backed by large language models can misinterpret scope, execute unexpected actions, and produce false-positive findings. Review every reported vulnerability before treating it as actionable, and confine test runs to isolated environments where any collateral impact stays contained.\n\n\n"}
![\"Docs\"](\"https://img.shields.io/badge/Docs-docs.zenney.uk-02A3CF?style=for-the-badge&logo=gitbook&logoColor=white\"){kind=icon}
\n![\"Website\"](\"https://img.shields.io/badge/Website-zenney.uk-f0f0f0?style=for-the-badge&logoColor=000000\"){kind=icon}
\n![\"Discord\"](\"https://img.shields.io/badge/Discord-Join-5865F2?style=for-the-badge&logo=discord&logoColor=white\"){kind=icon}
\n\n![\"Ask](\"https://deepwiki.com/badge.svg\"){kind=icon}
\n![\"GitHub](\"https://img.shields.io/github/stars/zenneyy/zen-ai?style=flat-square\")
\n![\"License\"](\"https://img.shields.io/badge/License-Apache%202.0-3b82f6?style=flat-square\"){kind=icon}
\n![\"PyPI](\"https://img.shields.io/pypi/v/zen-agent?style=flat-square\")
\n\n![\"Follow](\"https://img.shields.io/badge/X-Follow-000000?style=flat-square&logo=x&logoColor=white\"){kind=icon}
\n\n