Metadata-Version: 2.5
Name: zen-agent
Version: 1.1.1
Summary: Open-source offensive security agents for autonomous pentesting
Project-URL: Homepage, https://zenney.uk
Project-URL: Documentation, https://docs.zenney.uk
Project-URL: Repository, https://github.com/zenneyy/zen-ai
Project-URL: Discord, https://discord.gg/v5dPr4wcTz
Author-email: zenneyy <zenney031@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agent,ai,cli,cybersecurity,pentest,scanner,security,vulnerability
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Security
Requires-Python: >=3.12
Requires-Dist: caido-sdk-client>=0.2.0
Requires-Dist: claude-agent-sdk==0.2.130
Requires-Dist: cryptography<49,>=48.0.1
Requires-Dist: cvss>=3.2
Requires-Dist: docker>=7.1.0
Requires-Dist: litellm
Requires-Dist: openai-agents[litellm]<0.20,>=0.19.0
Requires-Dist: openai<3,>=2.45.0
Requires-Dist: pydantic-settings>=2.13.0
Requires-Dist: pydantic>=2.11.3
Requires-Dist: pypdf>=5.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: reportlab>=4.0
Requires-Dist: requests>=2.32.0
Requires-Dist: rich
Provides-Extra: bedrock
Requires-Dist: boto3>=1.28.0; extra == 'bedrock'
Provides-Extra: claude-sub
Requires-Dist: claude-agent-sdk; extra == 'claude-sub'
Provides-Extra: vertex
Requires-Dist: google-auth>=2.0.0; extra == 'vertex'
Description-Content-Type: text/markdown

<p align="center">
  <a href="https://zenney.uk/">
    <pre>
███████╗███████╗███╗   ██╗ 
╚══███╔╝██╔════╝████╗  ██║
  ███╔╝ █████╗  ██╔██╗ ██║
 ███╔╝  ██╔══╝  ██║╚██╗██║
███████╗███████╗██║ ╚████║
╚══════╝╚══════╝╚═╝  ╚═══╝    
    </pre>
  </a>
</p>

<div align="center">

# Zen

### Open-source offensive security agents. Autonomous pentesting that discovers, exploits, and remediates vulnerabilities in running code.

<br/>

<a href="https://docs.zenney.uk"><img src="https://img.shields.io/badge/Docs-docs.zenney.uk-2b9246?style=for-the-badge&logo=gitbook&logoColor=white" alt="Docs"></a>
<a href="https://zenney.uk"><img src="https://img.shields.io/badge/Website-zenney.uk-f0f0f0?style=for-the-badge&logoColor=000000" alt="Website"></a>
<a href="https://discord.gg/v5dPr4wcTz"><img src="https://img.shields.io/badge/Discord-Join-5865F2?style=for-the-badge&logo=discord&logoColor=white" alt="Discord"></a>

<a href="https://deepwiki.com/zenneyy/zen-ai"><img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki"></a>
<a href="https://github.com/zenneyy/zen-ai"><img src="https://img.shields.io/github/stars/zenneyy/zen-ai?style=flat-square" alt="GitHub Stars"></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache%202.0-3b82f6?style=flat-square" alt="License"></a>
<a href="https://pypi.org/project/zen-agent/"><img src="https://img.shields.io/pypi/v/zen-agent?style=flat-square" alt="PyPI Version"></a>

<a href="https://x.com/zen_ai"><img src="https://img.shields.io/badge/X-Follow-000000?style=flat-square&logo=x&logoColor=white" alt="Follow on X"></a>

</div>


> [!TIP]
> **New:** 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).

---


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


<br>

## 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](https://docs.zenney.uk/llm-providers/overview) that will back the agents (OpenAI, Anthropic, Google, and others)

### Install and run an assessment

```bash
# 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
```

> [!NOTE]
> The sandbox image is pulled on first execution. Run artifacts are written to `zen_runs/<run-name>`

---

## ☁️ Managed platform

**[app.zenney.uk](https://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 →**](https://app.zenney.uk)

---

## 🤖 Driving Zen from a coding agent

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

```bash
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](https://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`](AGENTS.md) for the condensed reference, [docs.zenney.uk/llms.txt](https://docs.zenney.uk/llms.txt) for CLI documentation, and [docs.app.zenney.uk](https://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:

```bash
# 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

```bash
# 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:

```bash
# 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

```bash
# 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.

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

### GitHub Actions integration

A minimal workflow is sufficient to assess every pull request:

```yaml
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
```

> [!TIP]
> During pull request runs, Zen restricts quick reviews to the changed file set automatically.
> Where the diff scope cannot be resolved, confirm the checkout retrieved full history
> (`fetch-depth: 0`), or supply `--diff-base` explicitly.

### Environment configuration

```bash
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)
```

> [!NOTE]
> Configuration is persisted to `~/.zen/cli-config.json` on write, so these values survive between runs.

#### ChatGPT subscription authentication

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

```bash
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:

```json
[
  {
    "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](https://openai.com/api/) - `openai/gpt-5.4`
- [Anthropic Claude Sonnet 4.6](https://claude.com/platform/api) - `anthropic/claude-sonnet-4-6`
- [Google Gemini 3 Pro Preview](https://cloud.google.com/vertex-ai) - `vertex_ai/gemini-3-pro-preview`

Vertex AI, Bedrock, Azure, and locally hosted models are supported as well; the [LLM Providers documentation](https://docs.zenney.uk/llm-providers/overview) enumerates every provider.

## Enterprise

The same engine under organizational controls: [enterprise-grade](https://zenney.uk/demo) 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](https://zenney.uk/demo).

## Reference documentation

The complete reference lives at **[docs.zenney.uk](https://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](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).

## Community

Questions, defect reports, and design discussion happen on **[Discord](https://discord.gg/v5dPr4wcTz)**.

## Support

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

## Upstream projects

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


> [!WARNING]
> **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.
> 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.

</div>
