Metadata-Version: 2.4
Name: ptai
Version: 0.10.2
Summary: Autonomous AI pentesting with 200+ tools, exploit chaining, PoC validation, and credential-safe MCP server
Author: 0xSteph
License: MIT
Project-URL: Homepage, https://pentestai.xyz
Project-URL: Repository, https://github.com/0xSteph/pentest-ai
Project-URL: Documentation, https://pentestai.xyz
Project-URL: Issues, https://github.com/0xSteph/pentest-ai/issues
Keywords: pentest,pentesting,security,mcp,ai,cybersecurity,exploit,vulnerability
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastmcp>=2.0
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.0
Requires-Dist: rich>=13.0
Requires-Dist: typer>=0.9
Requires-Dist: aiosqlite>=0.20
Requires-Dist: pyyaml>=6.0
Requires-Dist: python-dotenv>=1.0
Requires-Dist: jinja2>=3.1
Requires-Dist: cryptography>=42.0
Requires-Dist: dnspython>=2.6
Requires-Dist: scapy>=2.5
Requires-Dist: paramiko>=3.4
Requires-Dist: impacket>=0.11
Requires-Dist: bloodhound>=1.7
Requires-Dist: requests>=2.31
Requires-Dist: beautifulsoup4>=4.12
Requires-Dist: aiohttp>=3.9
Requires-Dist: tenacity>=8.2
Requires-Dist: structlog>=24.1
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: ruff>=0.3; extra == "dev"
Requires-Dist: mypy>=1.8; extra == "dev"
Requires-Dist: pre-commit>=3.6; extra == "dev"
Requires-Dist: types-PyYAML>=6.0; extra == "dev"
Provides-Extra: cloud
Requires-Dist: boto3>=1.34; extra == "cloud"
Requires-Dist: azure-identity>=1.15; extra == "cloud"
Requires-Dist: azure-mgmt-resource>=23.0; extra == "cloud"
Requires-Dist: google-cloud-storage>=2.14; extra == "cloud"
Dynamic: license-file

<div align="center">

<img src="assets/transparentbanner.png" alt="pentest-ai" width="640">

<h1>pentest-ai</h1>

**Autonomous pentests from one command. Real tools. Real PoCs. Real reports.**

[![PyPI](https://img.shields.io/pypi/v/ptai?color=red&label=pypi&style=flat-square)](https://pypi.org/project/ptai/)
[![Downloads](https://img.shields.io/pypi/dm/ptai?color=red&style=flat-square)](https://pypi.org/project/ptai/)
[![Python](https://img.shields.io/badge/python-3.10%2B-red?style=flat-square)](https://pypi.org/project/ptai/)
[![License](https://img.shields.io/github/license/0xSteph/pentest-ai?color=red&style=flat-square)](LICENSE)
[![Stars](https://img.shields.io/github/stars/0xSteph/pentest-ai?color=red&style=flat-square)](https://github.com/0xSteph/pentest-ai/stargazers)
[![Tests](https://img.shields.io/badge/tests-500%20passing-red?style=flat-square)](https://github.com/0xSteph/pentest-ai/actions)

[**Website**](https://pentestai.xyz) · [**Install**](#install) · [**Docs**](docs/) · [**Agents**](https://github.com/0xSteph/pentest-ai-agents)

</div>

---

Point it at a target. It runs recon, logs into the app, chains vulnerabilities into attack paths, proves every finding with a working PoC, and hands back a report your blue team can act on.

No cloud. No telemetry. Your laptop, your keys, your data.

## See it run

```console
$ ptai auth profile add staging-acme            # one-time, password from your secrets manager
$ ptai start https://staging.acme.com --auth-profile staging-acme

[+] engagement eng-e512f47b  target=staging.acme.com  scope=web

[auth]      ✓ Logged in as admin. Session captured, refresh in 14:32.
[recon]     ✓ 3 open ports, 7 subdomains, Apache/PHP fingerprint.
[web]       ✓ 21 findings behind auth. 3 SQLi, 4 XSS, missing CSP, CSRF gap.
[chain]     ✓ Attack path found in 2 hops:
              reflected XSS + cookie without Secure flag → admin session hijack
[validate]  ✓ 3 findings proven with non-destructive PoCs.
[detect]    ✓ Generated Sigma, SPL, KQL rules for the blue team.
[report]    ✓ reports/eng-e512f47b.html  ·  12 pages  ·  client-ready

Total: 4m 18s. Cost: $0.73 in Claude tokens.
```

That was one command. You were pouring coffee. The password came from an env var, 1Password, HashiCorp Vault, or AWS Secrets Manager — see [Credentialed scans](docs/credentialed-scans.md).

## Install

```bash
pip install ptai
```

### Use it with your Claude Code account (recommended)

Already pay for Claude Pro or Max? Skip the API key. Wire `ptai` into Claude Code as an MCP server and your subscription runs the engagement.

**Option A — one-line CLI (Claude Code users):**

```bash
claude mcp add pentest-ai -- ptai mcp
```

Done. Restart Claude Code and the tools show up.

**Option B — interactive wizard (Claude Desktop, Cursor, VS Code Copilot):**

```bash
ptai setup --mcp
```

Auto-detects the clients you have installed, writes their config files, and tells you to restart them.

Then, in any of those clients:

> *Run an authenticated pentest against staging.acme.com. Login is at /login with username admin and password in $APP_PASS. Summarize the high-severity findings when done.*

Claude Code (or Cursor, or Copilot) picks up the tools, runs the engagement through your subscription, and streams results back into your conversation. Zero API spend.

### Or use an API key

For CI pipelines, scheduled runs, or standalone use without an MCP client:

```bash
export ANTHROPIC_API_KEY=sk-ant-...   # Claude (best results)
# or
export OPENAI_API_KEY=sk-...          # OpenAI
# or, fully local, no cloud
export OLLAMA_HOST=localhost:11434    # Ollama
```

```bash
ptai start https://your-target.com
```

First run installs the tool deps it needs (nmap, nuclei, ffuf, sqlmap, gobuster, and more). No setup afterwards.

### Optional: cloud workspace (Pro / Team / Enterprise)

The CLI is free forever and stores everything locally. If you want engagement history, branded client-ready PDF reports, and team collaboration in a dashboard, link the CLI to an [app.pentestai.xyz](https://app.pentestai.xyz) workspace:

```bash
# 1. Sign up, then Dashboard → API Keys → Generate → copy ptai_...
ptai auth login        # paste the key (hidden prompt)
ptai auth status       # confirm link
# or use an env var for CI:
export PENTESTAI_API_KEY=ptai_...
```

Now every `ptai start` / `ptai scan` run auto-syncs findings to your cloud workspace. No cloud = no calls; the integration is silently off unless you log in. To unlink: `ptai auth logout`.

## What makes it different

|  |  |
|---|---|
| 🤖 **Autonomous** | Ten agents cover recon, web, AD, cloud, chaining, PoC, detection, and report. They coordinate on their own. |
| 🔐 **It logs in** | Most scanners die at the login page. This one holds a session, rotates creds, and every downstream tool inherits the cookie. |
| 🔑 **Credentials never leak** | Auth profiles store *references* (env vars, `op://`, Vault paths, AWS Secrets Manager ARNs), never the value. Passwords never enter your shell history, the LLM context, the findings DB, or process argv. |
| 🧪 **Every finding is proven** | A working proof of concept runs against the target. No more triaging 40 maybes from a noisy scanner. |
| 📋 **Your methodology, in YAML** | Encode your pentest checklist as a playbook. Share it. Fork someone else's. Like Nuclei templates, for methodology. |
| 🔄 **Diff mode** | `ptai retest <id>` shows what's new, fixed, or still broken. The fix → retest → confirm loop becomes one command. |
| ⚡ **CI-native** | A GitHub Action, GitLab template, severity gates, SARIF output, and PR comments. Works the day you drop it in. |
| 🧠 **LLM red team** | Probe your AI features for prompt injection, jailbreaks, and OWASP LLM Top 10. Eighty probes built in. |
| 🔌 **Works with Claude, Cursor, Copilot** | An MCP server with 35+ tools. Talk to your assistant: *"diff last week's engagement against today's."* |
| 💾 **Runs on your laptop** | MIT licensed. No cloud calls. Works offline with Ollama. Your findings stay on your disk. |

## How it works

```
┌─────────────────────────────────────────────────────────────┐
│                    ptai start <target>                      │
└─────────────────────────────────────────────────────────────┘
                             │
          ┌──────────────────┼──────────────────┐
          ▼                  ▼                  ▼
      ┌────────┐        ┌────────┐        ┌─────────┐
      │ recon  │   →    │  auth  │   →    │   web   │
      └────────┘        └────────┘        └─────────┘
                                               │
          ┌────────────────────────────────────┤
          ▼                                    ▼
      ┌────────┐                          ┌─────────┐
      │   ad   │   ┌──────────────────┐   │ cloud   │
      └────────┘   │  Findings DB     │   └─────────┘
          │        │  (sqlite + evidence)│       │
          └───────▶│  scope-guarded     │◀──────┘
                   │  deduplicated      │
                   └──────────────────┘
                             │
                ┌────────────┼────────────┐
                ▼            ▼            ▼
           ┌──────┐    ┌─────────┐  ┌──────────┐
           │chain │    │validate │  │ detect   │
           └──────┘    └─────────┘  └──────────┘
                             │
                             ▼
                       ┌──────────┐
                       │  report  │   md · html · pdf · SARIF · JUnit
                       └──────────┘
```

Each agent runs with an LLM when you've set a key, or as a deterministic tool loop when you haven't. Either way the phase order is the same.

## Who uses it for what

**AppSec teams.** Wire `ptai` into your CI. Every PR against staging gets an authenticated scan. The build fails on high-severity findings. The fix → retest → confirm loop runs on its own.

**Consultants.** Scope a week-long engagement, point `ptai` at the estate, and spend your time on the creative work instead of glueing scanners together and writing the report. The report is already written.

**Bug bounty hunters.** Run it over breakfast. Come back to a list of validated findings with PoCs ready to paste into HackerOne.

**Red teamers.** Drop your internal AD methodology into a YAML playbook. Run it against every new engagement. Share it with your team.

**Developers shipping AI features.** Enable `--enable-llm-redteam` against your chatbot. Get an OWASP LLM Top 10 report in minutes.

## Playbooks

Your methodology as a file. Checked into git. Shared with your team.

```yaml
name: internal-ad-pentest
inputs:
  domain: { required: true, prompt: "AD domain" }
  dc_ip:  { required: true, prompt: "DC IP" }

phases:
  - id: recon
    tools: [nmap, masscan]

  - id: ad-enum
    depends_on: [recon]
    condition: "any_finding(type='open_port', port=445)"
    tools: [enum4linux, ldapsearch, bloodhound-python]

  - id: kerberoast
    requires_finding: { type: ad_user_enumerated }
    tools: [impacket-getuserspns]
    llm_decide: true         # let the LLM skip if context says useless
```

```bash
ptai playbook list                  # show installed playbooks
ptai playbook show web-app-quick    # preview before running
ptai playbook run ./my-ad.yaml      # execute
```

Five playbooks ship built-in. A community catalog is coming.

## Drop it into your CI

```yaml
# .github/workflows/security.yml
name: Security scan
on: [pull_request]

jobs:
  ptai:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pip install ptai
      - run: |
          ptai start ${{ vars.STAGING_URL }} \
            --ci \
            --fail-on high \
            --sarif pentest.sarif
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
      - uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: pentest.sarif
```

Findings post as a PR comment, SARIF uploads to GitHub Code Scanning, and the build fails on gated severity. GitLab and Jenkins templates in [docs/ci-cd.md](docs/ci-cd.md).

## vs the field

|  | `ptai` | Sn1per | Nuclei | Burp Pro | PentestGPT |
|---|:-:|:-:|:-:|:-:|:-:|
| Autonomous phase loop | ✓ | ✓ | | | ✓ |
| Authenticated scanning | ✓ | partial | raw HTTP | ✓ | |
| Exploit chaining | ✓ | | | | partial |
| PoC validation | ✓ | | | partial | |
| Diff and retest | ✓ | | | | |
| CI-native (SARIF + gates) | ✓ | | partial | partial | |
| LLM red team | ✓ | | | | |
| YAML playbooks | ✓ | | templates | | |
| MCP server | ✓ | | | | |
| License | MIT | GPL | MIT | commercial | MIT |

## What's inside

- **10 agents** across recon, web, AD, cloud, exploit chaining, PoC validation, detection, reporting, LLM red team, and social engineering
- **200+ tool wrappers** with auto-install: nmap, masscan, nuclei, ffuf, sqlmap, gobuster, wapiti, nikto, dalfox, xsstrike, enum4linux, bloodhound-python, impacket's full suite, trufflehog, gitleaks, kube-hunter, trivy, and more
- **35+ MCP tools** for LLM-driven engagements
- **3 LLM providers**: Anthropic Claude, OpenAI, Ollama
- **6 output formats**: Markdown, HTML, PDF, SARIF 2.1.0, JUnit XML, compliance mappings (OWASP, CWE, CVE, CVSS v3.1)
- **500 tests** at 81% coverage
- **MIT licensed**, 100% yours

<details>
<summary><strong>All ten agents (click to expand)</strong></summary>

| Agent | Phase | Does |
|---|---|---|
| `recon` | 1 | Port scan, DNS and subdomain enum, service fingerprinting |
| `web` | 2 | Authenticated OWASP Testing Guide v4 pass |
| `ad` | 3 | AD enum, Kerberoasting, BloodHound pathfinding, delegation abuse |
| `cloud` | 4 | AWS, Azure, GCP IAM, misconfig, K8s RBAC, serverless |
| `exploit_chain` | 5 | Correlates findings into multi-step attack paths |
| `poc_validator` | 6 | Non-destructive proof of concept per finding |
| `detection` | 7 | Sigma, SPL, KQL rules for the blue team |
| `report` | 8 | Markdown, HTML, PDF, SARIF, JUnit, compliance maps |
| `llm_redteam` | opt | OWASP LLM Top 10 probes |
| `social_engineer` | opt | Phishing corpus and pretext generation |

Plus `mobile` and `wireless` agents for out-of-band engagements.

</details>

## Responsible use

`ptai` is for authorized testing. On startup it loads a scope file. Out-of-scope hosts are refused at tool-invocation time. PoCs are non-destructive by default. Rate limits kick in automatically in stealth mode.

You are responsible for having written authorization before pointing this at anything you don't own. Don't be that person.

## The ecosystem

| Repo | What |
|---|---|
| [**pentest-ai**](https://github.com/0xSteph/pentest-ai) | The CLI and MCP server (you are here) |
| [**pentest-ai-agents**](https://github.com/0xSteph/pentest-ai-agents) | Claude Code subagent definitions for the same methodology |

## Beyond the OSS

Running this on a team and need more? The [website](https://pentestai.xyz) has the team dashboard and managed-assessment options.

The OSS tool stays OSS. Free forever.

## Contributing

PRs welcome. Before you submit:

```bash
ruff check . && mypy . && pytest -q
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for the full flow.

## Star history

<a href="https://star-history.com/#0xSteph/pentest-ai&Date">
  <img src="https://api.star-history.com/svg?repos=0xSteph/pentest-ai&type=Date" alt="Star history chart" width="600">
</a>

## License

MIT. Do whatever you want with it.

<div align="center">

**If `ptai` saved you a Sunday, [star the repo](https://github.com/0xSteph/pentest-ai). It's the only payment I ask for.**

</div>
