pentest-ai - Open-source AI pentester that proves every finding

项目说明

!Pentest-AI — open-source AI pentesting. Findings you can reproduce.

![PyPI]() ![Python]() ![License: MIT]()

Website · Quick start · · Documentation · Issues

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

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

> Test only systems you own or ha authorization to assess. Read the acceptable-use policy and terms before running an engagement.

Quick start

Recommended: Codex or Claude Code

Use Python 3.10–3.14 and install pipx
first. Run pipx ensurepath and reopen your terminal if needed. pipx isolates
Pentest-AI's dependencies and makes its commands a across folders.

Install your AI client's CLI first. Setup asks before connecting **all detected
supported clients**, including both Codex and Claude Code when installed. It
preser registrations. Restart your client afterward.

The wizard uses user-wide settings. It does not install clients, sign you in,
download models or configure Ollama. Your AI client supplies the model; no separate
model API key is required by the MCP server. Use ptai setup --mcp --dry-run to
preview changes. See single-client and per-repository setup
for Codex .codex/config.toml and Claude Code .mcp.json instructions.

For upgrades, use pipx upgrade ptai. In an existing activated en,
python -m pip install --upgrade ptai is also supported; keep that en
a after registering it with your AI client.

Alternati and local models

Install Pentest-AI as above, but skip MCP setup for this route.
Install and start Ollama, then pull a model
with tool-calling support. Use ollama list to find its exact installed name.

In PowerShell:

Replace the placeholders before running. A local model needs no cloud API key.
Model quality and a memory affect results. See the
model guide for endpoint configuration.

Try the bundled demo

No API key or external target required.

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

Other model pro

For standalone cloud models and optional scanner dependencies, see the installation guide and provider guide. Keep API keys out of source control.

How works

!A candidate becomes only after an oracle repeats the exploit and checks a control. The resulting proof capsule can be replayed.

1. Find a candidate. A probe or scanner identifies behaviour worth in.
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 e. A 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 pri content with the attack header and deny access without it. A server that answers every request with HTTP 200 is not sufficient e.

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

A 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 design

What you can do

| Workflow | What Pentest-AI provides |
| --- | --- |
| In web applications | Probes for injection, access control, request handling and other application weaknesses |
| Work through an AI client | MCP tools for engagements, in and |
| 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 |

Co by probe and oracle. Optional scanners need their own binaries, and some integrations provide raw output rather than structured findings. Consult the documentation and changelog for your ; main may contain unreleased work.

View the capability in checked by CI.

Put findings into CI

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

Export findings using the engagement ID from the run:

--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 e for failed builds. Upload the resulting file through your CI provider's SARIF integration.

CI setup and templates

E, benchmarks and limits

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

Expect incomplete co. A scan with no findings is not a security assessment of e an application does. Authentication, application state, unsupported bug classes and en changes affect what can be found and reproduced. Review results and keep a human in 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 ha own network behaviour. Blind- checks can use an external out-of-band collaborator; callback metadata is to that service.

Use your own collaborator where required, or disable callbacks:

Get in

Use Issues for reproducible bugs and Discussions for questions and ideas. See the agent and contributor guide for build and test instructions.

The optional pentest-ai-agents repository contains Claude Code subagent files.

Pentest-AI is open source under the MIT license.

项目信息

开发语言：Python

Star 数：1717

技术要点

该项目属于安全软件方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕Open-source AI pentester that proves every finding. Machine oracles re-run each exploit; verified bugs ship a proof capsule you can replay yourself.展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。