Metadata-Version: 2.4
Name: ptai
Version: 1.4.1.post1
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

Configure your model provider, an authorized target and first-run consent in your CI environment. Keep secrets in the CI provider's secret store.

```sh
ptai start https://your-authorized-target.example --ci --fail-on verified --no-sync
```

Export verified findings using the engagement ID from the run:

```sh
ptai export YOUR_ENGAGEMENT_ID --sarif pentest.sarif
```

`--sarif` is an export option, not a `ptai start` option. Retain the engagement ID and run the export even when the finding gate fails if you want evidence for failed builds. Upload the resulting file through your CI provider's SARIF integration.

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