Metadata-Version: 2.4
Name: ptai
Version: 1.4.1
Summary: AI pentesting that proves its findings: machine oracles re-run each exploit, and every verified bug ships a proof capsule you can replay yourself
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: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Testing
Requires-Python: <3.15,>=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
Requires-Dist: hashids>=1.3
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: pytest-timeout>=2.3; 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"
Requires-Dist: lxml>=5.2; extra == "dev"
Requires-Dist: tomli>=2.0; python_version < "3.11" and 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"
Provides-Extra: litellm
Requires-Dist: litellm>=1.50; extra == "litellm"
Provides-Extra: api
Requires-Dist: fastapi>=0.115; extra == "api"
Requires-Dist: uvicorn[standard]>=0.30; extra == "api"
Requires-Dist: websockets>=13.0; extra == "api"
Provides-Extra: menu
Requires-Dist: questionary>=2.0; extra == "menu"
Provides-Extra: browser
Requires-Dist: playwright>=1.45; extra == "browser"
Provides-Extra: stealth
Requires-Dist: scrapling[all]>=0.4.7; extra == "stealth"
Provides-Extra: tracing
Requires-Dist: opentelemetry-api>=1.27; extra == "tracing"
Requires-Dist: opentelemetry-sdk>=1.27; extra == "tracing"
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.27; extra == "tracing"
Provides-Extra: all
Requires-Dist: ptai[api,browser,cloud,litellm,menu,stealth,tracing]; extra == "all"
Dynamic: license-file

![Pentest-AI — open-source AI pentesting. Findings you can reproduce.](https://raw.githubusercontent.com/0xSteph/pentest-ai/main/assets/readme/pentest-ai-banner.png)

[![PyPI](https://img.shields.io/pypi/v/ptai?color=72e8de&label=PyPI)](https://pypi.org/project/ptai/) [![Python](https://img.shields.io/badge/Python-3.10%2B-72e8de)](https://pypi.org/project/ptai/) [![License: MIT](https://img.shields.io/badge/License-MIT-72e8de)](https://github.com/0xSteph/pentest-ai/blob/main/LICENSE)

[Website](https://pentestai.xyz/) · [Quick start](#quick-start) · [Verification](#how-verification-works) · [Documentation](https://github.com/0xSteph/pentest-ai/tree/main/docs) · [Issues](https://github.com/0xSteph/pentest-ai/issues)

Pentest-AI connects an AI client or model to a penetration-testing workflow. It investigates applications, records findings, and uses **machine oracles to check whether an exploit can be reproduced**. Verified findings carry evidence you can replay.

Use it through **MCP**, from the **CLI**, or in **CI**. The model helps drive the investigation; an oracle determines whether a finding earns a verified verdict.

> Test only systems you own or have explicit authorization to assess. Read the [acceptable-use policy](https://pentestai.xyz/aup) and [terms](https://pentestai.xyz/terms) before running an engagement.

## Quick start

### Try the bundled demo

No API key or external target required.

```bash
pip install ptai
ptai demo
```

The demo tests a bundled vulnerable application, replays a finding from its proof capsule, and checks the hardened routes. Inspect the evidence workflow before configuring a real engagement.

### Use your AI client

One setup command detects supported installed clients and offers to connect them:

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

**Codex and Claude Code** use the same Pentest-AI MCP tools. Install the client's CLI and make `codex` or `claude` available on your PATH before running setup. The wizard also detects Claude Desktop, Cursor and VS Code configuration directories. It preserves existing Pentest-AI registrations.

Restart your client, then use its Pentest-AI tools with an authorized target. Your client supplies the model; the MCP server does not require a separate model API key. Use `ptai setup --mcp --dry-run` to preview setup without writing settings.

Prefer to connect just one client? These direct commands also work with earlier Pentest-AI versions:

```bash
# Codex
codex mcp add pentest-ai -- ptai mcp

# Claude Code (available across your projects)
claude mcp add --scope user --transport stdio pentest-ai -- ptai mcp
```

### Run the standalone CLI

Configure your model provider, then start an engagement:

```bash
export ANTHROPIC_API_KEY="your-api-key"
ptai start https://your-authorized-target.example
```

OpenAI and local Ollama models are also supported. See the [installation guide](https://pentestai.xyz/docs/getting-started/) for configuration and optional scanner dependencies. Keep real API keys out of source control.

### Use a local model with Ollama

Ollama supplies the model to the standalone CLI; it is not itself an MCP client. With Ollama running and a tool-capable model already pulled, choose its exact installed name:

```bash
# Bash / zsh
PENTEST_AI_LLM_PROVIDER=ollama PENTEST_AI_MODEL="your-installed-model" ptai start https://your-authorized-target.example
```

```powershell
# PowerShell
$env:PENTEST_AI_LLM_PROVIDER = "ollama"
$env:PENTEST_AI_MODEL = "your-installed-model"
ptai start https://your-authorized-target.example
```

Use `ollama list` to find installed model names. Tool calling and investigation quality depend on the model; small local models can struggle with the agent workflow. See [AI client and local-model setup](https://github.com/0xSteph/pentest-ai/blob/main/docs/ai-clients.md) for requirements and troubleshooting.

## How verification works

![A candidate becomes verified only after an oracle repeats the exploit and checks a control. The resulting proof capsule can be replayed.](https://raw.githubusercontent.com/0xSteph/pentest-ai/main/assets/readme/verification-flow.svg)

1. **Find a candidate.** A probe or scanner identifies behaviour worth investigating.
2. **Reproduce it and check a control.** A named oracle repeats the exploit and compares it with a control that should not demonstrate the weakness.
3. **Keep the evidence.** A verified finding records the oracle and its results in a portable proof capsule. Use `ptai replay` to check it again.

For example, a trusted-header bypass must return privileged content with the attack header and deny access without it. A server that answers every request with HTTP 200 is not sufficient evidence.

**The model cannot award a verified verdict.** Third-party scanner output remains unverified until an oracle independently proves it. Findings without a supported verification recipe remain candidates.

A verified verdict applies to the tested conditions. It does not mean the entire application is secure. Proof capsules are unsigned; rerunning the check is the trust mechanism.

[Read the verification design](https://github.com/0xSteph/pentest-ai/blob/main/docs/why-verification.md)

## What you can do

| Workflow | What Pentest-AI provides |
| --- | --- |
| Investigate web applications | Probes for injection, access control, request handling and other application weaknesses |
| Work through an AI client | MCP tools for engagements, investigation and verification |
| Reproduce a finding | Oracle results and replayable proof capsules |
| Check a fix | Rerun the recorded check against the updated target |
| Report to your team | Reports and SARIF output for existing engineering workflows |
| Keep engagement data local | Findings stored on your machine in SQLite |

Coverage varies by probe and oracle. Optional scanners need their own binaries, and some integrations provide raw output rather than structured findings. Consult the [documentation](https://github.com/0xSteph/pentest-ai/tree/main/docs) and [changelog](https://github.com/0xSteph/pentest-ai/blob/main/CHANGELOG.md) for your version; `main` may contain unreleased work.

[View the capability inventory checked by CI](https://github.com/0xSteph/pentest-ai/blob/main/docs/capability-inventory.md).

## Put verified findings into CI

These steps assume `ptai` is installed and your model provider, target authorization and first-run consent are configured in CI:

```yaml
- run: ptai start "${{ vars.STAGING_URL }}" --ci --fail-on verified --sarif pentest.sarif
- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: pentest.sarif
```

`--fail-on verified` gates the build on findings that passed verification, rather than every scanner candidate.

[CI setup and templates](https://github.com/0xSteph/pentest-ai/blob/main/docs/ci-cd.md)

## Evidence, benchmarks and limits

Benchmark findings, challenge completion and oracle-verified findings are different measurements. These reports record the versions, targets and methodology behind their results:

- [Benchmark reports and artifacts](https://github.com/0xSteph/pentest-ai/tree/main/benchmarks)
- [Juice Shop methodology](https://github.com/0xSteph/pentest-ai/blob/main/docs/benchmarks/juice-shop.md)
- [Vulnerable test harness](https://github.com/0xSteph/pentest-ai/tree/main/tests/honeypot)
- [Clean-application checks](https://github.com/0xSteph/pentest-ai/tree/main/tests/cleanapp)

**Expect incomplete coverage.** A scan with no verified findings is not a security assessment of everything an application does. Authentication, application state, unsupported bug classes and environmental changes affect what can be found and reproduced. Review results and keep a human involved in the engagement.

## Data and network behaviour

Findings are stored locally. Anonymous usage counters are opt-in through `ptai telemetry enable`.

Local storage does not mean every operation stays on your machine: model-provider calls and installed scanners have their own network behaviour. Blind-vulnerability checks can use an external out-of-band collaborator; callback metadata is visible to that service.

Use your own collaborator where required, or disable callbacks:

```bash
ptai start https://your-authorized-target.example --oast-server https://your-collaborator.example
ptai start https://your-authorized-target.example --no-oast
```

## Get involved

Use [Issues](https://github.com/0xSteph/pentest-ai/issues) for reproducible bugs and [Discussions](https://github.com/0xSteph/pentest-ai/discussions) for questions and ideas. See the [agent and contributor guide](https://github.com/0xSteph/pentest-ai/blob/main/AGENTS.md) for build and test instructions.

The optional [pentest-ai-agents](https://github.com/0xSteph/pentest-ai-agents) repository contains Claude Code subagent files.

Pentest-AI is open source under the [MIT license](https://github.com/0xSteph/pentest-ai/blob/main/LICENSE).
