███████╗███████╗███╗   ██╗ 
╚══███╔╝██╔════╝████╗  ██║
  ███╔╝ █████╗  ██╔██╗ ██║
 ███╔╝  ██╔══╝  ██║╚██╗██║
███████╗███████╗██║ ╚████║
╚══════╝╚══════╝╚═╝  ╚═══╝    
    

What is Zen

Zen 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.

Core capabilities:

• Complete offensive tooling — reconnaissance, exploitation, and verification in one runtime, with nothing to assemble
• Multi-agent execution — specialized agents partition the target and scale horizontally across it
• Proof-carrying findings — every report ships with a proof-of-concept that executes against the live target
• Terminal-native workflow — output written for the engineer who has to land the fix, remediation context included
• Automated remediation and reporting — generated patches, plus assessment documents formatted for audit

Where it fits

• Application Security Testing — locate exploitable defects across an application and confirm each one is reachable
• Rapid Penetration Testing — compress a full engagement, compliance documentation included, from weeks into hours
• Bug Bounty Automation — automate the reconnaissance and exploitation loop, then submit against generated proof-of-concepts
• CI/CD Integration — enforce a security gate in the pipeline so exploitable code never reaches production

🚀 Get started

Requirements:

• A running Docker daemon
• An API key for any supported provider that will back the agents (OpenAI, Anthropic, Google, and others)

Install and run an assessment

# Install Zen
curl -sSL https://zenney.uk/install | bash

# Configure your AI provider
export ZEN_LLM="openai/gpt-5.4"
export LLM_API_KEY="your-api-key"

# Run your first security assessment
zen --target ./app-directory

☁️ Managed platform

app.zenney.uk hosts the same engine as a managed service. Register an account, attach your repositories and domains, and assessments dispatch without any local infrastructure.

• Validated findings with PoCs — a reproducible exploit and its reproduction sequence accompany every reported vulnerability
• One-click autofix — model-generated security patches delivered as reviewable pull requests
• Continuous pentesting — assessment on a persistent schedule, tracking your deployment velocity
• DevSecOps integrations — GitHub, GitLab, Bitbucket, Slack, Jira, Linear, and CI/CD pipelines
• Continuous learning — prior findings inform subsequent runs; the system adapts to your codebase and suppresses recurring false positives

Run your first assessment →

🤖 Driving Zen from a coding agent

Zen publishes its workflows as installable skills. Claude Code, Cursor, Codex, and any SKILL.md-compatible agent can dispatch assessments, apply the patches that come back, and configure CI enforcement:

npx skills add zenneyy/zen-ai

The package installs nine skills. penetration-testing-with-zen dispatches headless assessments and parses their artifacts; managed-pentesting-with-zen operates the hosted app.zenney.uk platform over REST, requiring neither Docker nor an LLM credential on the host; fix-security-vulnerabilities-with-zen patches reported findings and re-executes to confirm the fix; ci-security-scanning-with-zen wires PR assessment into CI. Five more are scoped to a target class: application-security-testing, web-app-penetration-testing, api-security-testing, owasp-top-10-testing, and find-security-vulnerabilities-in-code. Both execution paths resolve to the same engine — select the open-source CLI where local infrastructure exists, the managed cloud where it does not. Agents should consult AGENTS.md for the condensed reference, docs.zenney.uk/llms.txt for CLI documentation, and docs.app.zenney.uk for the REST API.

✨ Architecture

Agent tooling

Every agent operates the same instrumentation a professional penetration tester would reach for:

• HTTP Interception Proxy — Caido, integrated for complete request and response manipulation and analysis
• Browser Exploitation — an instrumented browser covering XSS, CSRF, clickjacking, and authentication bypass flows
• Shell & Command Execution — an interactive terminal for exploit development and post-exploitation activity
• Custom Exploit Runtime — a Python sandbox in which proof-of-concept code is authored and verified
• Reconnaissance & OSINT — automated attack surface mapping, subdomain enumeration, and service fingerprinting
• Static & Dynamic Code Analysis — SAST and DAST in combination, so both the code and its running form are covered
• Vulnerability Knowledge Base — findings held in structured form, with CVSS scoring and OWASP classification

Vulnerability coverage

Detection, validation, and exploitation span the OWASP Top 10 and extend well past it:

• Broken Access Control — IDOR, horizontal and vertical privilege escalation, authorization bypass
• Injection Attacks — SQL and NoSQL injection, OS command injection, SSTI
• Server-Side Vulnerabilities — SSRF, remote code execution, insecure deserialization, XXE
• Client-Side Attacks — stored, reflected, and DOM-based XSS, prototype pollution, CSRF
• Business Logic Flaws — workflow bypass, payment manipulation, race conditions
• Authentication & Session — credential stuffing vectors, session fixation, JWT attacks
• Infrastructure & Cloud — misconfiguration, unintentionally exposed services, cloud security weaknesses
• API Security — broken authentication, mass assignment, rate limit bypass

Agent graph (distributed execution)

Coordination between agents is what makes that breadth tractable:

• Distributed Pentesting — reconnaissance, exploitation, and post-exploitation each assigned to a specialist agent
• Scalable Security Testing — targets assessed concurrently, so coverage does not trade against wall-clock time
• Dynamic Coordination — agents propagate discoveries between themselves and chain vulnerabilities the way a red team does

🖥️ Local result viewer

Artifacts are written to disk as the assessment proceeds. A single command renders them in a local dashboard:

# Open the most recent run
zen view

# ...or open a specific run by name
zen view my-run-name

# Expose the viewer on all IPv4 interfaces at a fixed port
zen view --host 0.0.0.0 --port 8080 --no-open

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.

To 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.

Viewer surfaces

• Overview: current run state, the configured target, and a severity distribution across findings so far.
• Vulnerabilities: each validated finding with severity, supporting detail, and a reproduction sequence.
• Agent graph: a live topology of the agent fleet, showing the task assigned to each node.
• Steering: inject instructions into an in-flight assessment and redirect the agents without restarting.
• History: every prior run recorded on this host, addressable directly.
• Reports: compile a distributable report and dispatch it by email.

Usage patterns

Common invocations

# Scan a local codebase
zen --target ./app-directory

# Security review of a GitHub repository
zen --target https://github.com/org/repo

# Black-box web application assessment
zen --target https://your-app.com

Assessment from an API specification (OpenAPI / Swagger / Postman)

Supply a contract and Zen exercises every endpoint the specification declares, instead of inferring the surface by crawling. Pair the specification with the live base URL so requests are routed correctly:

# OpenAPI / Swagger file (.json / .yaml)
zen --target ./openapi.yaml --target https://api.your-app.com

# Postman collection export
zen --target ./collection.postman_collection.json --target https://api.your-app.com

# Postman collection pulled live by id (no manual export)
export POSTMAN_API_KEY="PMAK-..."
zen --target postman://<collection-uuid>

# ...with a Postman environment to resolve {{baseUrl}} / token variables
zen --target "postman://<collection-uuid>?env=<environment-uuid>"

Advanced invocations

# Grey-box authenticated testing
zen --target https://your-app.com --instruction "Perform authenticated testing using credentials: user:pass"

# Multi-target testing (source code + deployed app)
zen -t https://github.com/org/app -t https://your-app.com

# Targets from a file, one target per non-empty, non-comment line
zen --target-list ./targets.txt

# White-box source-aware scan (local repository)
zen --target ./app-directory --scan-mode standard

# Focused testing with custom instructions
zen --target api.your-app.com --instruction "Focus on business logic flaws and IDOR vulnerabilities"

# Provide detailed instructions through file (e.g., rules of engagement, scope, exclusions)
zen --target api.your-app.com --instruction-file ./instruction.md

# Force PR diff-scope against a specific base branch
zen -n --target ./ --scan-mode quick --scope-mode diff --diff-base origin/main

Headless execution

-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.

zen -n --target https://your-app.com

GitHub Actions integration

A minimal workflow is sufficient to assess every pull request:

name: zen-penetration-test

on:
  pull_request:

jobs:
  security-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0

      - name: Install Zen
        run: curl -sSL https://zenney.uk/install | bash

      - name: Run Zen
        env:
          ZEN_LLM: ${{ secrets.ZEN_LLM }}
          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}

        run: zen -n -t ./ --scan-mode quick

Environment configuration

export ZEN_LLM="openai/gpt-5.4"
export LLM_API_KEY="your-api-key"

# Optional
export LLM_API_BASE="your-api-base-url"  # if using a local model, e.g. Ollama, LMStudio
export PERPLEXITY_API_KEY="your-api-key"  # for search capabilities
export ZEN_REASONING_EFFORT="high"  # control thinking effort (default: high, quick scan: medium)

ChatGPT subscription authentication

In place of a metered API key, Zen can authenticate against an existing ChatGPT Plus or Pro subscription:

zen auth login chatgpt      # sign in with your ChatGPT account

export ZEN_LLM="chatgpt/gpt-5.4"   # chatgpt/<model> runs on the subscription
zen --target ./app-directory

zen auth status             # show the active sign-in
zen auth logout             # forget the sign-in

MCP server integration

Zen 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:

[
  {
    "name": "local_fs",
    "transport": "stdio",
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
  },
  {
    "name": "github",
    "transport": "http",
    "url": "https://api.githubcopilot.com/mcp/",
    "auth": { "kind": "bearer", "token": "your-token" },
    "allowed_tools": ["list_issues"]
  }
]

Tool 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.

Recommended model configurations:

• OpenAI GPT-5.4 - openai/gpt-5.4
• Anthropic Claude Sonnet 4.6 - anthropic/claude-sonnet-4-6
• Google Gemini 3 Pro Preview - vertex_ai/gemini-3-pro-preview

Vertex AI, Bedrock, Azure, and locally hosted models are supported as well; the LLM Providers documentation enumerates every provider.

Enterprise

The same engine under organizational controls: enterprise-grade SSO via SAML or OIDC, custom penetration testing reports mapped to SOC 2, ISO 27001, and PCI DSS, dedicated support under SLA, flexible deployment topologies including VPC and self-hosted, BYOK model access, and agents tuned against your environment. Learn more.

Reference documentation

The complete reference lives at docs.zenney.uk, covering usage, CI/CD integration, skills, and advanced configuration.

Development and contributions

Code, documentation, and new skills are all in scope. Start from the Contributing Guide, or go directly to a pull request/issue.

Community

Questions, defect reports, and design discussion happen on Discord.

Support

If Zen earns a place in your toolchain, a ⭐ on GitHub helps others find it.

Upstream projects

Zen is built on LiteLLM, Caido, Nuclei, Playwright, and Bubble Tea. Our thanks to the teams maintaining them.