Content
# AI Security Audit Playbook
<a href="LICENSE">
<img alt="license" src="https://img.shields.io/badge/license-MIT-green">
</a>
**Turn AI coding agents into disciplined, audit-only security reviewers.**
AI Security Audit Playbook is a local-first security review system for ChatGPT, Codex, Cursor,
Claude-style agents, MCP clients, and human reviewers. It does not try to replace security tools or
human judgment. It gives AI-assisted review a stricter operating frame: inspect evidence, suppress
unsupported claims, explain severity, and turn confirmed issues into regression-test guidance.
## English
### Review a PR now
If you only need one path, do this:
1. Open [prompts/pr-security-review/audit-only.md](prompts/pr-security-review/audit-only.md).
2. Provide a public PR link, public PR diff, pasted diff, or sanitized diff.
3. Ask:
```text
Use this playbook in audit-only mode.
Return evidence-backed findings, false-positive notes, and regression-test guidance.
Do not patch files unless a human explicitly approves the selected finding.
```
Expected output: findings with evidence, missing-context questions, false-positive notes, and
regression-test guidance. AI findings require human review.
### Choose the right path
| Need | Start here | What you get |
| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| Review one PR or diff | [engineer quickstart](docs/engineer-quickstart.md) | Copyable commands and prompts for real review work |
| See the full first-use flow | [3-minute PR review demo](docs/quick-demo.md) and [demo transcript](docs/demo/3-minute-pr-review-transcript.md) | A small sanitized review from input to finding |
| Ask ChatGPT/Cursor/Codex to use this repo URL | [remote AI usage](docs/remote-ai-usage.md) | A safe no-install workflow for public or sanitized inputs |
| Use a fixed local agent role | [Main vs Agent](docs/agent-vs-playbook.md) | When to use `main` versus `agent/ai-security-reviewer` |
| Use local MCP | [MCP knowledge guide](docs/mcp-knowledge/README.md) | Read-only resources and client prompts |
| Adopt this in another repo | [templates/adoption/](templates/adoption/) and [docs/users/](docs/users/) | Copyable team templates and role guidance |
| Evaluate quality | [evidence dashboard](docs/evidence/evidence-dashboard.md) | Public trials, examples, negative controls, and evidence status |
### What problem this solves
Generic AI code review often sounds confident while missing the proof needed for a useful security
finding. This project forces a better review loop: define the scenario, inspect only provided or
public context, require concrete evidence, name missing context, avoid unsupported severity, and
propose regression tests only after a human-confirmed issue.
The result should be a review record, not a magic verdict. For the expected artifact shape, see the
[report artifact contract](docs/report-artifact-contract.md) and the
[PR security review demo bundle](examples/report-bundles/pr-security-review-demo/).
### Who should use this
- Developers who want a security first pass before requesting review.
- Security reviewers who want consistent finding format, severity reasoning, and test guidance.
- Open-source maintainers who want safe PR review prompts and adoption templates.
- Teams that want local-first AI review without private source or secrets upload.
- Smart-contract teams reviewing upgradeability, governance, accounting, and custody-of-funds risks.
### Who should not use this
Do not use this if you want a vulnerability scanner, exploit framework, hosted code-analysis
service, autonomous remediation system, model judge, or automatic merge decision-maker. The project
preserves no exploit execution, no autonomous repo scanning, no hosted MCP, no auto-merge, no model
judge, and no private source or secrets upload.
### Use the agent
Use the agent branch when you want one stable local reviewer role instead of browsing the whole
playbook.
```text
Act as the AI Security Review Agent from:
<current-repository-url>/tree/agent/ai-security-reviewer
```
Read [Main vs Agent](docs/agent-vs-playbook.md) and the [branching policy](docs/branching-policy.md)
before changing the agent branch. `main` remains the source of truth; the agent branch receives
updates from `main` and is not merged back.
### Use local MCP
The MCP server is local, stdio-only, and read-only. It exposes public playbook resources; it does
not read user repositories, execute shell commands, call the network, write files, or upload private
review content.
```bash
npm ci
npm run validate:mcp
npm run mcp
```
See [Architecture](docs/architecture.md), [MCP knowledge guide](docs/mcp-knowledge/README.md),
[Codex CLI walkthrough](docs/demo/codex-cli-walkthrough.md),
[Cursor workflow](docs/demo/cursor-workflow.md),
[MCP client walkthrough](docs/demo/mcp-client-walkthrough.md), and the
[architecture diagram source](docs/media/architecture-diagram.md).
### Adopt in 10 minutes
Copy these first:
- [templates/adoption/AGENTS.md](templates/adoption/AGENTS.md)
- [templates/adoption/PULL_REQUEST_TEMPLATE.md](templates/adoption/PULL_REQUEST_TEMPLATE.md)
- [templates/adoption/security-review-checklist.md](templates/adoption/security-review-checklist.md)
Then use [docs/users/](docs/users/) to choose role-specific defaults. The adoption path is designed
for audit-only review, human approval, and no private source or secrets upload.
### Evaluate evidence
Use these when deciding whether the playbook is useful for your team:
- [Ordinary AI review vs playbook-guided review](examples/comparisons/ordinary-ai-review-vs-playbook.md)
- [benchmark comparison index](examples/comparisons/index.md)
- [what this evidence proves](docs/evidence/what-this-evidence-proves.md)
- [Evidence credibility dashboard](docs/evidence/evidence-dashboard.md)
- [public trials](examples/public-trials/)
- [negative controls](docs/19-negative-controls.md)
These assets show review structure, evidence discipline, false-positive suppression, and
regression-test guidance. They do not prove model superiority or guarantee vulnerability discovery.
### Contribute safely
Start with [docs/community/README.md](docs/community/README.md) and the
[maintainer review checklist](docs/community/maintainer-review-checklist.md). Contributions should
improve one of these assets: incident patterns, negative controls, public trials, benchmark
examples, adoption templates, or documentation quality records.
Do not submit private source, secrets, exploit payloads, unredacted logs, or claims that cannot be
reviewed from public or sanitized evidence.
### Maintain the project
- [START_HERE.md](START_HERE.md): task-oriented entrypoint.
- [documentation quality standard](docs/documentation-quality-standard.md): anti-slop and
paper-grade documentation rules.
- [documentation quality index](data/docs/documentation-quality-index.yaml): validated source of
truth for indexed docs.
- [Codex continuation handoff](docs/codex-continuation-handoff.md): new-machine and fresh-session
continuation.
- [static site export](docs/static-site-export.md): local-only static registry export.
- [release checklist](docs/16-release-checklist.md): release verification.
- [maintenance guide](docs/24-maintenance-guide.md): monthly digest, community PR review, public
trials, and recurring operations.
### Release status
Stable in v1.0: commands, layout, prompt and skill structure, MCP boundaries, and release process.
Mature in v3.0: long-term maintenance, monthly digest, community PR review, and recurring evidence
operations. Evidence credibility was strengthened in v3.1, finding format and attack-chain reasoning
in v3.2, first-use and supply-chain hardening in v3.3, field notes in v3.4, agent branch separation
in v3.5, documentation maturity in v4.0, and engineer onboarding plus review bundles in v4.1.
Detailed release history lives in [CHANGELOG.md](CHANGELOG.md) and [ROADMAP.md](ROADMAP.md).
Maintainer attribution lives in [AUTHORS.md](AUTHORS.md). Repository links should use the current
GitHub repository URL shown in your browser address bar.
## 中文
### 现在审查一个 PR
如果你只想马上开始，用这一条路径：
1. 打开 [prompts/pr-security-review/audit-only.md](prompts/pr-security-review/audit-only.md)。
2. 提供公开 PR link、公开 PR diff、粘贴的 diff，或脱敏 diff。
3. 让 AI 按下面这段执行：
```text
Use this playbook in audit-only mode.
Return evidence-backed findings, false-positive notes, and regression-test guidance.
Do not patch files unless a human explicitly approves the selected finding.
```
预期输出是有证据的 findings、缺失上下文问题、误报说明和 regression-test guidance。AI findings
require human review。
### 选择正确路径
| 需求 | 从这里开始 | 你会得到什么 |
| -------------------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| 审查一个 PR 或 diff | [engineer quickstart](docs/engineer-quickstart.md) | 可以直接复制的审查指令和命令 |
| 看完整首次使用流程 | [3-minute PR review demo](docs/quick-demo.md) 和 [demo transcript](docs/demo/3-minute-pr-review-transcript.md) | 从输入到 finding 的脱敏示例 |
| 让 ChatGPT/Cursor/Codex 使用本仓库链接 | [remote AI usage](docs/remote-ai-usage.md) | 不安装插件也能使用的安全路径 |
| 使用固定 agent 角色 | [Main vs Agent](docs/agent-vs-playbook.md) | 何时使用 `main`，何时使用 `agent/ai-security-reviewer` |
| 使用本地 MCP | [MCP knowledge guide](docs/mcp-knowledge/README.md) | 只读资源和 client prompt 示例 |
| 在另一个仓库落地 | [templates/adoption/](templates/adoption/) 和 [docs/users/](docs/users/) | 可复制的团队模板和角色指南 |
| 评估质量 | [evidence dashboard](docs/evidence/evidence-dashboard.md) | public trials、examples、negative controls 和证据状态 |
### 这个项目解决什么问题
普通 AI code
review 容易给出自信但证据不足的安全判断。这个项目把 review 拉回到更严格的流程：明确场景、只使用提供的或公开的上下文、要求具体证据、指出缺失上下文、避免不受支持的 severity，并且只在人工确认问题后给出 regression
test 建议。
最终产物应该是一份可复核的 review record，而不是魔法结论。输出结构见
[report artifact contract](docs/report-artifact-contract.md) 和
[PR security review demo bundle](examples/report-bundles/pr-security-review-demo/)。
### 谁适合使用
- 希望在正式 review 前做安全 first pass 的开发者。
- 需要统一 finding 格式、severity reasoning 和测试建议的安全 reviewer。
- 想给开源 PR 增加安全审查模板的维护者。
- 希望 local-first、避免 private source 或 secrets upload 的团队。
- 审查 upgradeability、governance、accounting 和 custody-of-funds 风险的智能合约团队。
### 谁不适合使用
如果你想要 vulnerability scanner、exploit framework、hosted code-analysis service、autonomous
remediation system、model judge 或自动 merge 决策工具，不要使用这个项目。项目保留 no exploit
execution、no autonomous repo scanning、no hosted MCP、no auto-merge、no model judge、no private
source or secrets upload。
### 使用 agent
当你想固定一个本地安全 reviewer 角色，而不是浏览完整 playbook 时，使用 agent 分支。
```text
Act as the AI Security Review Agent from:
<current-repository-url>/tree/agent/ai-security-reviewer
```
修改 agent 分支前，请先读 [Main vs Agent](docs/agent-vs-playbook.md) 和
[branching policy](docs/branching-policy.md)。`main` 是事实来源；agent 分支只从 `main`
同步，不反向合并。
### 使用本地 MCP
MCP server 是本地、stdio-only、只读的。它只暴露公开 playbook
resources；不读取用户仓库、不执行 shell、不访问网络、不写文件，也不上传私有 review 内容。
```bash
npm ci
npm run validate:mcp
npm run mcp
```
参考 [Architecture](docs/architecture.md)、[MCP knowledge guide](docs/mcp-knowledge/README.md)、
[Codex CLI walkthrough](docs/demo/codex-cli-walkthrough.md)、[Cursor workflow](docs/demo/cursor-workflow.md)、
[MCP client walkthrough](docs/demo/mcp-client-walkthrough.md) 和
[architecture diagram source](docs/media/architecture-diagram.md)。
### 10 分钟落地
先复制这三个文件：
- [templates/adoption/AGENTS.md](templates/adoption/AGENTS.md)
- [templates/adoption/PULL_REQUEST_TEMPLATE.md](templates/adoption/PULL_REQUEST_TEMPLATE.md)
- [templates/adoption/security-review-checklist.md](templates/adoption/security-review-checklist.md)
然后用 [docs/users/](docs/users/) 选择角色默认路径。adoption path 保持 audit-only、human
approval、no private source or secrets upload。
### 评估证据
团队评估项目价值时，优先看这些材料：
- [Ordinary AI review vs playbook-guided review](examples/comparisons/ordinary-ai-review-vs-playbook.md)
- [benchmark comparison index](examples/comparisons/index.md)
- [what this evidence proves](docs/evidence/what-this-evidence-proves.md)
- [Evidence credibility dashboard](docs/evidence/evidence-dashboard.md)
- [public trials](examples/public-trials/)
- [negative controls](docs/19-negative-controls.md)
这些材料证明的是 review 结构、证据纪律、误报抑制和 regression-test
guidance 的改善，不证明某个模型一定更强，也不保证发现所有漏洞。
### 安全贡献
从 [docs/community/README.md](docs/community/README.md) 和
[maintainer review checklist](docs/community/maintainer-review-checklist.md)
开始。贡献应改善 incident patterns、negative controls、public trials、benchmark examples、adoption
templates 或 documentation quality records。
不要提交 private source、secrets、exploit payloads、未脱敏日志，或无法从公开/脱敏证据复核的 claim。
### 维护项目
- [START_HERE.md](START_HERE.md)：任务入口。
- [documentation quality standard](docs/documentation-quality-standard.md)：anti-slop 和 paper-grade 文档规则。
- [documentation quality index](data/docs/documentation-quality-index.yaml)：被验证的文档质量事实来源。
- [Codex continuation handoff](docs/codex-continuation-handoff.md)：新机器和新会话继续维护流程。
- [static site export](docs/static-site-export.md)：local-only static registry export。
- [release checklist](docs/16-release-checklist.md)：发布验证。
- [maintenance guide](docs/24-maintenance-guide.md)：monthly digest、community PR review、public
trials 和 recurring operations。
### 发布状态
Stable in v1.0：命令、目录、prompt/skill 结构、MCP 边界和发布流程稳定。Mature in
v3.0：长期维护、monthly digest、community PR review 和 recurring evidence
operations 成熟。v3.1 强化 Evidence credibility，v3.2 强化 finding format 和 attack-chain
reasoning，v3.3 强化首次使用和供应链门禁，v3.4 加入 field notes，v3.5 完成 agent branch
separation，v4.0 提升 documentation maturity，v4.1 增加 engineer onboarding 和 review bundles。
完整 release history 在 [CHANGELOG.md](CHANGELOG.md) 和 [ROADMAP.md](ROADMAP.md)。维护者署名见
[AUTHORS.md](AUTHORS.md)。仓库链接应使用浏览器地址栏里的 current GitHub repository URL。
