AI Security Audit Playbook

Turn AI coding agents into disciplined, audit-only security reviewers.

AI Security Audit Playbook is a local-first review system for ChatGPT, Codex, Cursor, Claude-style skills, MCP clients, and human reviewers. It turns generic AI security review into a structured workflow: choose a scenario, use a prompt or skill, keep context local, ask for evidence-backed findings, suppress unsupported claims, and turn confirmed issues into regression-test guidance.

English

What problem this solves

Generic AI code review often sounds confident but misses security evidence, overstates severity, or suggests risky fixes without approval. This project gives the AI a disciplined review frame: what to inspect, what evidence is required, when not to report, what humans must approve, and how to turn a confirmed issue into a regression test.

The playbook is not a scanner. It is a reusable operating system for AI-assisted security review: prompts, skills, read-only MCP knowledge resources, worked examples, public trials, negative controls, standards mappings, and adoption templates.

Maintainer and repository mirrors

Maintainer attribution lives in AUTHORS.md.

• Maintainer: Edmund
• Maintainer profile: edmund-xl
• edmund-xl repository: https://github.com/edmund-xl/ai-security-audit-playbook
• megaeth-labs repository: https://github.com/megaeth-labs/ai-security-audit-playbook

The primary badges above point to the edmund-xl release and CI source. When you share repository, release, issue, pull request, or source links, choose the URL that matches the repository location your audience is using.

Use this in 30 seconds

If you only want one thing, start here:

1. Open prompts/pr-security-review/audit-only.md.
2. Paste a public PR link, public PR diff, pasted diff, or sanitized diff.
3. Ask:

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: evidence-backed findings, missing-context questions, false-positive notes, and regression-test guidance. The AI output is a review hypothesis, not a confirmed vulnerability report.

Start fast

• Use in 3 minutes: 3-minute PR review demo, real demo transcript, and START_HERE.md.
• Use by giving an AI this GitHub link: remote AI usage explains how to ask ChatGPT, Claude, Cursor, Codex, or another assistant to open this playbook and audit a public link, pasted diff, or sanitized code.
• Adopt in 10 minutes: templates/adoption/ and role guides for developers, reviewers, maintainers, startups, enterprises, and smart-contract teams.
• Integrate locally: Codex CLI walkthrough, Cursor workflow, MCP client walkthrough, MCP knowledge UX, and Architecture.
• Evaluate quality: Ordinary AI review vs playbook-guided review, benchmark comparison index, what the evidence proves, and evidence credibility.
• Contribute safely: Community growth kit, standards evidence pack, canonical finding format, dependency advisory triage, static site and registry export, v3 maintenance guide, and Releases.

Who should use this

• Developers who want a better security first pass before requesting review.
• Security reviewers who want consistent evidence, severity reasoning, and test guidance.
• Open-source maintainers who want PR review templates, agent guidance, and public trial examples.
• Startup and enterprise teams that want local-first AI review without uploading private source or secrets.
• Smart-contract teams that need human-gated, evidence-backed review of upgradeability, governance, accounting, and custody-of-funds risks.

Who should not use this

• Anyone looking for an exploit framework, vulnerability scanner, hosted code-analysis service, or autonomous remediation system.
• Teams that want AI findings to be treated as confirmed vulnerabilities without human review.
• Workflows that require private source, secrets, logs, or credentials to be uploaded to a remote service.
• Workflows that need automatic patching, automatic PR creation, or automatic merge decisions.

Detailed release history lives in CHANGELOG.md and ROADMAP.md. The current README focuses on what the project does, how to start, and which safety boundaries remain stable.

New here?

Use START_HERE.md if you want a shorter path from task to asset. It points reviewers to the right prompt, skill, MCP mode, and contribution docs for PR review, backend authorization, terminal/PTY, smart contracts, local MCP usage, direct skill usage, and prompt or skill contribution.

Adopt in 10 minutes

Use templates/adoption/ when you want to add the playbook to another repository without adopting the full project structure. Start with templates/adoption/AGENTS.md, templates/adoption/PULL_REQUEST_TEMPLATE.md, and templates/adoption/security-review-checklist.md. In another repository, copy exactly those three files first, then add more templates only when the team needs them.

Then choose the role guide that matches the team: individual developers, security reviewers, open-source maintainers, startup teams, enterprise security teams, or smart-contract teams. These templates preserve the same audit-only, no exploit execution, no autonomous scanning, no auto-merge, and no private source or secrets upload boundaries.

What this project is not

This project is not a vulnerability scanner, exploit framework, hosted code-analysis service, autonomous remediation system, or guarantee that code is secure. It does not try to replace Semgrep, CodeQL, Slither, dependency scanners, secret scanners, or human security judgment. It does not upload private source code, secrets, logs, or credentials. It does not auto-merge, run destructive commands, execute exploits, or perform autonomous repository scanning.

What it covers

• PR security review
• Backend authorization, IDOR, ownership checks, and tenant isolation
• Terminal, PTY, shell session, and WebSocket terminal backends
• CI/CD, dependency, release, artifact, and supply-chain risks
• Secrets, logging, telemetry, privacy, and PII
• LLM agents, MCP servers, tool calling, prompt injection, and data exfiltration
• RAG applications, retrieval boundaries, citations, memory, and AI app output handling
• Smart contracts, DeFi, custody-of-funds, governance, and upgradeability risks
• Fixing explicitly selected findings with minimal diffs and regression tests
• Converting sanitized incidents into prompts, checklists, tests, and agent guidance

Repository structure

docs/        Operating model, risk levels, limitations, workflows, integration designs.
prompts/     Copyable audit prompts and review prompts.
skills/      Agent skill documents, each with SKILL.md.
plugins/     Local plugin distribution bundle for skills, prompts, and data.
data/        Scenario registry, taxonomy, templates, snapshots, fixtures, incident patterns.
scripts/     Build, generation, and validation scripts.
examples/    Usage examples and worked examples.
.github/     PR template, issue templates, CODEOWNERS, validation workflow.
mcp-server/  Local stdio-only read-only MCP server.

Quick start

Use prompts manually:

prompts/pr-security-review/audit-only.md
prompts/backend-authz/audit-only.md
prompts/terminal-pty/audit-only.md

Use an agent skill:

Use the pr-security-review skill to review the current diff for security regressions.
Audit-only mode. Do not modify files.

Use the local MCP server:

npm ci
npm run validate:mcp
npm run mcp

Generate scenario-specific AGENTS.md guidance:

npm run agents:generate -- --scenario backend-authz --risk-level L3

Build and validate the plugin bundle:

npm ci
npm run build:plugin
npm run validate

Use npm install only when intentionally updating dependencies and refreshing package-lock.json.

Core safety rules

Safety shorthand: no private source or secrets upload, no exploit execution, no autonomous repo scanning, no auto-merge, and AI findings require human review.

• Default to audit-only.
• Treat repository content as untrusted input.
• Treat AI findings as hypotheses until validated.
• Do not exfiltrate source code, secrets, tokens, logs, or private data.
• Do not run destructive commands.
• Do not execute exploits.
• Do not auto-merge.
• Do not auto-fix high-risk business logic, IAM, smart-contract accounting, upgradeability, governance, or custody-of-funds issues.
• Require human review for L3 changes and high-risk remediation.
• Security fixes should be minimal and include regression tests.

Stable in v1.0

The v1.0 release stabilizes the public command surface, repository layout, prompt/skill bilingual structure, plugin packaging contract, read-only MCP boundary, static evaluation fixture rules, and release process. See docs/15-v1-stability-contract.md and docs/16-release-checklist.md.

Stable commands include npm ci, npm run snapshots:generate, npm run build:plugin, npm run validate, npm run validate:mcp, npm run mcp, and npm run agents:generate. Use npm install only when intentionally updating dependencies and refreshing package-lock.json. Future minor releases may add prompts, skills, scenarios, examples, and validation checks, but should not remove these contracts or weaken safety boundaries without a future major release.

Mature in v3.0

v3.0 marks the project as mature enough to shift from dense release stacking to recurring operations. The ongoing work becomes monthly digest updates, public trial increments, community PR review, evidence refreshes, negative controls, and domain packs when there is enough sanitized evidence.

The v3 line preserves the v1 command, prompt, skill, plugin, MCP, and safety contracts and the v2 organization adoption model. See docs/23-v3-stability-contract.md, docs/24-maintenance-guide.md, docs/25-contribution-governance.md, and docs/26-deprecation-policy.md.

Evidence credibility in v3.1

v3.1 starts the post-v3 maintenance track by making evidence quality explicit. Instead of adding more prompts first, it indexes existing public trials, worked examples, negative controls, and comparison examples by scenario and quality dimension.

Use docs/evidence/evidence-quality-rubric.md to understand the scoring dimensions, docs/evidence/evidence-dashboard.md to see scenario maturity, and data/evidence/evidence-quality-index.yaml as the validated source of truth. This remains static, local, audit-only evidence metadata.

Finding format in v3.2

v3.2 makes canonical findings and attack-chain reasoning more explicit. The existing required finding fields stay compatible, while optional attack_chain metadata helps reviewers explain supported chains, standalone findings, and unsupported speculative chains.

Use docs/finding-format.md for the reporting contract and docs/workflows/attack-chain-review.md for the review workflow. These assets remain documentation, templates, validation, and read-only MCP resources, not scanner or exploit behavior.

First-use and supply-chain hardening in v3.3

v3.3 sharpens the first-use path and project maintenance gates. New users get a 30-second PR review path at the top of this README, while maintainers get dependency advisory triage and project-self security validation.

Use docs/security/advisory-triage.md to decide when dependency advisories block a release, and docs/evidence/what-this-evidence-proves.md to avoid overclaiming benchmark and public-trial evidence.

Remote AI usage in v3.3.1

v3.3.1 formalizes the no-install workflow where a user gives an AI assistant this GitHub link and a public link, pasted diff, or sanitized code target.

Use docs/remote-ai-usage.md for the copy-paste instruction and safety rules. The workflow remains audit-only and treats findings as hypotheses until human review.

Real-use feedback in v3.4

v3.4 adds a sanitized feedback loop for teams that use the playbook on real projects. Use docs/field-notes/README.md to record useful finding types, suppressed false positives, adopted regression-test guidance, and prompt gaps without exposing private source or secrets.

Use docs/workflows/finding-triage.md to decide whether a finding is a blocker, scheduled fix, accepted risk, missing-context item, false positive, duplicate, or no-action item. Use templates/adoption/security-debt-register.md to keep confirmed or accepted risk visible before release.

Attribution and mirrors in v3.4.1

v3.4.1 records maintainer attribution and makes the two synchronized GitHub repository URLs explicit in README, AUTHORS.md, and docs/remote-ai-usage.md. The package metadata identifies the maintainer without adding a single repository URL that would be misleading for the mirror.

Mature in v1.1

The v1.1 release makes audit-only prompt depth consistent across all nine scenarios. Every audit-only prompt now includes context and input boundaries, reasoning ladders, scenario-specific checks, false-positive suppression, report/do-not-report examples, output expectations, regression-test guidance, and explicit safety/human-approval gates in English first and Chinese second.

Validation now includes npm run validate:prompt-depth, which blocks retired versioned headings, shallow audit prompts, missing safety boundaries, and highly repetitive Chinese prompt sections.

Public trials in v1.2

The v1.2 release adds static public trials against external open-source security fixes. These trials use only public advisories, PRs, commits, and maintainer write-ups. They do not clone private repositories, run target projects, execute exploit payloads, call LLM-as-judge, upload private source or secrets, or create patches in target projects.

Example outputs / Public trials

Use examples/worked/ for static worked examples that show expected review outputs and false-positive suppression without exploit execution or live scanning. Representative examples include backend authz IDOR, terminal/PTY session ownership, LLM agent tool over-permission, smart-contract upgradeability/accounting, CI/CD secret logging, and playbook-to-static-tool regression.

Use examples/public-trials/ for public-source-only trial records. Start with the public trial method, then review the Spree IDOR trial, OpenZeppelin UUPS trial, LangChain LLMMathChain trial, and v0.7 PR review trial. These documents are static review records, not scanners, exploit workflows, or remote analysis services.

Available skills

Skill	Purpose
pr-security-review	Review PR or diff security regressions.
backend-authz-audit	Audit backend authorization, IDOR, ownership checks, and tenant isolation.
terminal-pty-audit	Audit terminal, PTY, shell session, and WebSocket terminal backends.
ci-cd-supply-chain-audit	Audit CI/CD, dependency, package publishing, release, and artifact risks.
secrets-logging-privacy-audit	Audit secrets, logs, errors, PII, telemetry, and privacy risks.
llm-agent-tooling-audit	Audit LLM agents, tools, MCP, prompt injection, and data exfiltration.
smart-contract-audit	Audit Solidity, Vyper, EVM, DeFi, governance, and custody-of-funds risks.
fix-selected-security-findings	Fix only explicitly selected findings with tests.
incident-to-prompt	Convert sanitized incidents into prompt, checklist, test, and AGENTS.md updates.

Important docs

• docs/00-principles.md: project principles
• docs/01-operating-model.md: review workflow
• docs/02-pr-risk-levels.md: L0-L3 PR risk model
• docs/10-known-limitations.md: honest limitations and tool boundaries
• docs/11-agent-skill-compatibility.md: skill naming and compatibility
• docs/13-evaluation-harness.md: static evaluation coverage and scoring
• docs/14-community-release-kit.md: release announcement and triage material
• docs/15-v1-stability-contract.md: stable commands, layout, and safety contracts
• docs/16-release-checklist.md: stable release process
• docs/users/: role-based adoption guides
• docs/quick-demo.md: 3-minute PR review demo
• docs/architecture.md: plain-language architecture and local MCP flow
• docs/demo/: walkthroughs for transcript, Codex CLI, Cursor, and MCP client usage
• docs/community/README.md: community contribution paths
• docs/community/maintainer-review-checklist.md: maintainer checklist for safe community assets
• docs/mcp-knowledge/README.md: MCP resource index and client usage examples
• docs/media/README.md: future screenshot and video checklist
• docs/media/architecture-diagram.md: render-friendly architecture diagram source
• docs/launch/x-thread-v2.1.md: ready-to-post launch thread
• docs/future/: safe future evaluation and registry designs
• docs/workflows/: documented agent workflows
• templates/adoption/: minimal repository adoption templates
• examples/static-tool-bridges/: local-only defensive static tool bridge examples
• examples/comparisons/: before/after comparison examples
• data/benchmarks/index.yaml: static comparison benchmark index
• docs/21-contributor-growth-loop.md: contribution lanes for patterns, controls, trials, examples, standards, and templates
• docs/digests/: monthly security pattern digest records
• docs/digests/2026-05-evidence-refresh-security-pattern-digest.md: evidence corpus refresh digest
• docs/domain-packs/: planning-only future domain pack designs
• docs/domain-packs/rag-ai-app.md: implemented RAG / AI app security domain pack pilot
• docs/22-local-stacked-release-candidate-checklist.md: local stacked release-candidate checklist
• docs/org-adoption/: organization rollout, maturity, policy, cadence, and checklist
• docs/finding-format.md: canonical finding format and optional attack-chain metadata
• docs/workflows/attack-chain-review.md: evidence-backed attack-chain review workflow
• docs/evidence/evidence-quality-rubric.md: evidence quality scoring rubric for trials, examples, controls, and regression guidance
• docs/evidence/evidence-dashboard.md: scenario-by-scenario evidence maturity dashboard
• examples/worked/: worked examples and false-positive suppression examples
• examples/public-trials/: public review trial write-ups

Release status

• v0.1: public prompt library, skills, plugin package, scenario registry, validation
• v0.2: examples, bilingual docs, prompt snapshots
• v0.3: read-only local MCP server
• v0.4: agent workflow docs and static evaluation harness
• v0.5: integration designs and incident pattern library
• v0.5.1: self-review gap closure, deeper flagship prompts, plugin resources, limitations, compatibility notes, worked examples
• v0.6: full English-first, Chinese-second prompts and skills
• v0.7: sanitized non-deployable demo fixtures, expanded worked examples, and demo-backed evaluation coverage
• v0.8: CI maintenance, evaluation coverage matrix and rubric, community release kit, and public PR trial record
• v0.9: safe future evaluation and static registry design artifacts
• v1.0: stable public release, stability contract, release checklist, and final public-use polish
• v1.1: audit-only prompt depth parity, content-rich Chinese sections, and prompt-depth validation
• v1.2: static public trials and playbook-to-static-tool worked example
• v1.2.1: onboarding entry point, skill/plugin compatibility clarification, and MCP registry path hardening
• v1.2.2: source formatting enforcement and validation consistency across local commands and GitHub Actions
• v1.3: YAML-backed coverage, standards mappings, negative controls, incident-pattern growth, and read-only MCP knowledge resources
• v1.4: role-based user guides, adoption templates, and adoption validation
• v1.5: expanded public trial corpus, trial index, and scenario coverage validation
• v1.6: static tool bridge cookbook for sanitized local fixtures
• v1.7: contributor growth loop, monthly digest template, and digest validation
• v1.8: planning-only future domain pack designs and validation
• v1.9: local release-candidate checklist, docs index, and stack metadata validation
• v2.0: organization adoption playbook, maturity model, internal policy, cadence, and checklist
• v2.1: launch UX pack with 3-minute demo, architecture guide, comparison example, and promotion checklist
• v2.2: demo and media pack with transcript, CLI/editor/MCP walkthroughs, and diagram source
• v2.3: benchmark comparison pack across six security review scenarios
• v2.4: community growth kit with contribution guides, issue templates, and maintainer checklist
• v2.5: MCP knowledge UX with resource index, client prompts, and response examples
• v2.6: evidence corpus refresh with public trial links, negative controls, and digest update
• v2.7: first implemented domain pack pilot for RAG / AI app security
• v2.8: standards and enterprise evidence pack with standards-to-assets validation
• v2.9: local static site and registry export preparation, without hosting or uploads
• v3.0: long-term maintenance release with stability, governance, cadence, and deprecation policy
• v3.1: evidence credibility track with quality rubric, evidence index, dashboard, and validation
• v3.2: canonical finding format and evidence-backed attack-chain reasoning
• v3.3: first-use path, dependency advisory triage, render-prompt guard, and project-self security gates
• v3.3.1: remote AI usage entrypoint for giving an assistant the GitHub playbook link
• v3.4: sanitized field notes, finding triage, and security debt register
• v3.4.1: maintainer attribution and synchronized repository mirror links

中文

这个项目解决什么问题

普通 AI code review 经常看起来很自信，但可能缺少安全证据、夸大严重性，或者在没有审批的情况下建议高风险修复。本项目给 AI 一个有纪律的审查框架：该看什么、需要什么证据、什么情况不要报告、哪些动作必须人工确认，以及如何把已确认问题转成回归测试。

这个 playbook 不是 scanner。它是 AI-assisted security review 的可复用操作系统：prompts、skills、只读 MCP knowledge resources、worked examples、public trials、negative controls、standards mappings 和 adoption templates。

维护者与仓库镜像

维护者署名见 AUTHORS.md。

• 维护者：Edmund
• Maintainer profile：edmund-xl
• edmund-xl 仓库： https://github.com/edmund-xl/ai-security-audit-playbook
• megaeth-labs 仓库： https://github.com/megaeth-labs/ai-security-audit-playbook

上方主要 badges 指向 edmund-xl 的 release 和 CI source。分享 repository、release、issue、pull request 或 source links 时，请选择与你的读者正在使用的仓库位置一致的 URL。

30 秒使用

如果你只想先做一件事，从这里开始：

1. 打开 prompts/pr-security-review/audit-only.md。
2. 粘贴 public PR link、public PR diff、pasted diff 或 sanitized diff。
3. 这样要求 AI：

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.

预期输出是 evidence-backed findings、missing-context questions、false-positive notes 和 regression-test guidance。AI output 是 review hypothesis，不是已经确认的漏洞报告。

快速理解

• 3 分钟使用： 3-minute PR review demo、 real demo transcript 和 START_HERE.md。
• 直接把 GitHub 链接给 AI： remote AI usage 说明如何要求 ChatGPT、Claude、Cursor、Codex 或其他 assistant 打开本 playbook，并审查 public link、pasted diff 或 sanitized code。
• 10 分钟落地： templates/adoption/ 以及面向 developers、reviewers、maintainers、startups、enterprises 和 smart-contract teams 的角色指南。
• 本地集成： Codex CLI walkthrough、 Cursor workflow、 MCP client walkthrough、 MCP knowledge UX 和 Architecture。
• 评估质量： 普通 AI review vs playbook-guided review、 benchmark comparison index、 what the evidence proves 和 evidence credibility。
• 安全贡献： Community growth kit、 standards evidence pack、 canonical finding format、 dependency advisory triage、 static site and registry export、 v3 maintenance guide 和 Releases。

谁适合使用

• 想在正式 review 前做安全 first pass 的开发者。
• 希望统一 evidence、severity reasoning 和 test guidance 的安全 reviewer。
• 希望给 PR review、agent guidance 和 public trial 建立模板的开源维护者。
• 想保持 local-first AI review，同时不上传 private source 或 secrets 的 startup 与 enterprise 团队。
• 需要对 upgradeability、governance、accounting 和 custody-of-funds 风险进行人工门禁审查的 smart-contract 团队。

谁不适合使用

• 想要 exploit framework、vulnerability scanner、hosted code-analysis service 或 autonomous remediation system 的用户。
• 想把 AI findings 直接当成已确认漏洞、跳过人工审查的团队。
• 需要把 private source、secrets、logs 或 credentials 上传到远程服务的流程。
• 需要 automatic patching、automatic PR creation 或 automatic merge decisions 的流程。

详细版本历史放在 CHANGELOG.md 和 ROADMAP.md。当前 README 更关注项目做什么、如何开始，以及哪些安全边界保持稳定。

新用户从这里开始

如果你想从具体任务快速找到对应资产，请先读 START_HERE.md。它会把 PR review、backend authorization audit、terminal/PTY audit、smart-contract audit、本地 MCP 使用、无需安装 plugin 的直接 skill 使用，以及 prompt/skill 贡献路径分别指向合适的 prompt、skill、MCP 模式和文档。

10 分钟落地

如果你想把 playbook 加到另一个仓库，但不想采用完整项目结构，可以使用 templates/adoption/。建议先复制 templates/adoption/AGENTS.md、 templates/adoption/PULL_REQUEST_TEMPLATE.md 和 templates/adoption/security-review-checklist.md。在另一个仓库里，先只复制这三个文件；只有团队确实需要时，再继续加入更多 templates。

然后按团队角色选择指南：individual developers、 security reviewers、 open-source maintainers、 startup teams、 enterprise security teams 或 smart-contract teams。这些模板保留同样的 audit-only、no exploit execution、no autonomous scanning、no auto-merge 和 no private source or secrets upload 边界。

这个项目不是什么

本项目不是漏洞扫描器、exploit framework、托管式代码分析服务、自主修复系统，也不保证代码安全。它不试图替代 Semgrep、CodeQL、Slither、dependency scanners、secret scanners 或人类安全判断。它不上传私有源码、secrets、日志或凭证；不 auto-merge；不运行破坏性命令；不执行 exploit；不做自主仓库扫描。

覆盖范围

• PR security review
• Backend authorization、IDOR、ownership checks 和 tenant isolation
• Terminal、PTY、shell session 和 WebSocket terminal backends
• CI/CD、dependency、release、artifact 和 supply-chain 风险
• Secrets、logging、telemetry、privacy 和 PII
• LLM agents、MCP servers、tool calling、prompt injection 和 data exfiltration
• RAG applications、retrieval boundaries、citations、memory 和 AI app output handling
• Smart contracts、DeFi、custody-of-funds、governance 和 upgradeability 风险
• 只修复明确选中的 findings，并要求 minimal diffs 和 regression tests
• 把脱敏 incidents 转化为 prompts、checklists、tests 和 agent guidance

仓库结构

docs/        Operating model、risk levels、limitations、workflows、integration designs。
prompts/     可复制使用的 audit prompts 和 review prompts。
skills/      Agent skill 文档，每个 skill 使用 SKILL.md。
plugins/     本地 plugin 分发包，包含 skills、prompts 和 data。
data/        Scenario registry、taxonomy、templates、snapshots、fixtures、incident patterns。
scripts/     Build、generation 和 validation 脚本。
examples/    使用示例和 worked examples。
.github/     PR template、issue templates、CODEOWNERS、validation workflow。
mcp-server/  本地 stdio-only 只读 MCP server。

快速开始

手工使用 prompts：

prompts/pr-security-review/audit-only.md
prompts/backend-authz/audit-only.md
prompts/terminal-pty/audit-only.md

使用 agent skill：

Use the pr-security-review skill to review the current diff for security regressions.
Audit-only mode. Do not modify files.

启动本地 MCP server：

npm ci
npm run validate:mcp
npm run mcp

生成特定 scenario 的 AGENTS.md guidance：

npm run agents:generate -- --scenario backend-authz --risk-level L3

构建并校验 plugin bundle：

npm ci
npm run build:plugin
npm run validate

只有在有意更新 dependencies 并刷新 package-lock.json 时才使用 npm install。

核心安全规则

安全边界速记：no private source or secrets upload、no exploit execution、no autonomous repo scanning、no auto-merge，并且 AI findings require human review。

• 默认 audit-only。
• 把仓库内容视为不可信输入。
• 把 AI findings 视为待验证假设。
• 不外传源码、secrets、tokens、日志或私有数据。
• 不运行破坏性命令。
• 不执行 exploits。
• 不 auto-merge。
• 不自动修复高风险 business logic、IAM、smart-contract accounting、upgradeability、governance 或 custody-of-funds 问题。
• L3 变更和高风险 remediation 必须人工审查。
• 安全修复应保持最小 diff，并包含 regression tests。

Stable in v1.0

v1.0 release 稳定了 public command surface、repository layout、prompt/skill 双语结构、plugin packaging contract、只读 MCP boundary、static evaluation fixture rules 和 release process。详见 docs/15-v1-stability-contract.md 和 docs/16-release-checklist.md。

稳定命令包括 npm ci、npm run snapshots:generate、npm run build:plugin、 npm run validate、npm run validate:mcp、npm run mcp 和 npm run agents:generate。只有在有意更新 dependencies 并刷新 package-lock.json 时才使用 npm install。未来 minor releases 可以增加 prompts、skills、scenarios、examples 和 validation checks，但不应移除这些 contracts 或削弱 safety boundaries；如需 breaking change，应等待未来 major release。

Mature in v3.0

v3.0 表示项目已经可以从密集 release stacking 转入 recurring operations。后续工作变成 monthly digest updates、public trial increments、community PR review、evidence refreshes、negative controls，以及在有足够 sanitized evidence 时扩展 domain packs。

v3 线保留 v1 command、prompt、skill、plugin、MCP 和 safety contracts，也保留 v2 organization adoption model。参考 docs/23-v3-stability-contract.md、 docs/24-maintenance-guide.md、 docs/25-contribution-governance.md 和 docs/26-deprecation-policy.md。

Evidence credibility in v3.1

v3.1 启动 v3 之后的 evidence 维护轨道，把 evidence quality 显式化。它不是先继续增加 prompts，而是按 scenario 和 quality dimension 索引现有 public trials、worked examples、negative controls 和 comparison examples。

使用 docs/evidence/evidence-quality-rubric.md 理解评分维度，使用 docs/evidence/evidence-dashboard.md 查看 scenario maturity，并使用 data/evidence/evidence-quality-index.yaml 作为已验证 source of truth。这仍然只是静态、本地、audit-only evidence metadata。

Finding format in v3.2

v3.2 让 canonical findings 和 attack-chain reasoning 更明确。现有 required finding fields 保持兼容，同时新增可选 attack_chain metadata，帮助 reviewer 区分 supported chains、standalone findings 和 unsupported speculative chains。

使用 docs/finding-format.md 查看 reporting contract，使用 docs/workflows/attack-chain-review.md 查看 review workflow。这些资产仍然只是 documentation、templates、validation 和 read-only MCP resources，不是 scanner 或 exploit behavior。

v3.3 的首次使用和供应链加固

v3.3 让首次使用路径和项目维护门禁更直接。新用户可以在 README 顶部用 30 秒路径开始一次 PR review；维护者则获得 dependency advisory triage 和 project-self security validation。

使用 docs/security/advisory-triage.md 判断 dependency advisories 什么时候应阻塞 release；使用 docs/evidence/what-this-evidence-proves.md 避免夸大 benchmarks 和 public trials 的 evidence。

v3.3.1 的 remote AI usage

v3.3.1 正式支持免安装工作流：用户把本 GitHub 链接和 public link、pasted diff 或 sanitized code target 发给 AI assistant。

使用 docs/remote-ai-usage.md 获取可复制指令和 safety rules。该 workflow 仍保持 audit-only，并把 findings 视为需要人工确认的 hypotheses。

v3.4 的真实使用反馈

v3.4 增加面向真实项目使用的脱敏反馈闭环。使用 docs/field-notes/README.md 记录 useful finding types、suppressed false positives、adopted regression-test guidance 和 prompt gaps，同时不暴露 private source 或 secrets。

使用 docs/workflows/finding-triage.md 判断 finding 是 blocker、scheduled fix、accepted risk、missing-context item、false positive、duplicate 还是 no-action item。使用 templates/adoption/security-debt-register.md 在 release 前持续追踪 confirmed 或 accepted risk。

v3.4.1 的署名和镜像仓库

v3.4.1 记录 maintainer attribution，并在 README、AUTHORS.md 和 docs/remote-ai-usage.md 中明确两个同步 GitHub repository URLs。Package metadata 只标明 maintainer，不写入会让 mirror 产生误导的单一 repository URL。

Mature in v1.1

v1.1 release 让所有九个 audit-only scenarios 的 prompt 深度保持一致。每个 audit-only prompt 现在都包含上下文与输入边界、推理步骤、场景特化检查、误报抑制、应报告/不应报告示例、输出要求、回归测试指引，以及明确的安全边界和人工审批门禁，并保持英文在前、中文在后。

Validation 新增 npm run validate:prompt-depth，用于阻止过渡版本 heading、过浅的 audit prompt、缺失的安全边界，以及高度重复的中文 prompt 段落。

Public trials in v1.2

v1.2 release 增加基于外部开源安全修复的静态 public trials。这些 trials 只使用 public advisories、PRs、commits 和 maintainer write-ups。它们不 clone 私有仓库，不运行目标项目，不执行 exploit payloads，不调用 LLM-as-judge，不上传私有源码或 secrets，也不在目标项目中创建 patches。

Example outputs / Public trials（示例输出 / 公开试跑）

使用 examples/worked/ 查看静态 worked examples，了解预期 review 输出和误报抑制方式。这些示例不执行 exploit，也不进行 live scanning。代表性示例包括 backend authz IDOR、 terminal/PTY session ownership、 LLM agent tool over-permission、 smart-contract upgradeability/accounting、 CI/CD secret logging 和 playbook-to-static-tool regression。

使用 examples/public-trials/ 查看只基于公开来源的 trial 记录。建议先读 public trial method，再看 Spree IDOR trial、 OpenZeppelin UUPS trial、 LangChain LLMMathChain trial 和 v0.7 PR review trial。这些文档是静态审查记录，不是 scanner、exploit workflow 或远程分析服务。

可用 skills

Skill	用途
pr-security-review	审查 PR 或 diff 中的安全回归。
backend-authz-audit	审计 backend authorization、IDOR、ownership checks 和 tenant isolation。
terminal-pty-audit	审计 terminal、PTY、shell session 和 WebSocket terminal backends。
ci-cd-supply-chain-audit	审计 CI/CD、dependency、package publishing、release 和 artifact 风险。
secrets-logging-privacy-audit	审计 secrets、logs、errors、PII、telemetry 和 privacy 风险。
llm-agent-tooling-audit	审计 LLM agents、tools、MCP、prompt injection 和 data exfiltration。
smart-contract-audit	审计 Solidity、Vyper、EVM、DeFi、governance 和 custody-of-funds 风险。
fix-selected-security-findings	只修复明确选中的 findings，并补充 tests。
incident-to-prompt	把脱敏 incidents 转化为 prompt、checklist、test 和 AGENTS.md 更新。

重要文档

• docs/00-principles.md：项目原则
• docs/01-operating-model.md：审查工作流
• docs/02-pr-risk-levels.md：L0-L3 PR 风险模型
• docs/10-known-limitations.md：已知限制和工具边界
• docs/11-agent-skill-compatibility.md：skill 命名和兼容性
• docs/13-evaluation-harness.md：静态 evaluation coverage 和 scoring
• docs/14-community-release-kit.md：release announcement 和 triage material
• docs/15-v1-stability-contract.md：稳定 commands、layout 和 safety contracts
• docs/16-release-checklist.md：稳定 release process
• docs/users/：按角色划分的 adoption guides
• docs/quick-demo.md：3 分钟 PR review demo
• docs/architecture.md：普通语言架构说明和本地 MCP flow
• docs/demo/：transcript、Codex CLI、Cursor 和 MCP client walkthroughs
• docs/community/README.md：社区贡献路径
• docs/community/maintainer-review-checklist.md：安全社区资产维护者 checklist
• docs/mcp-knowledge/README.md：MCP resource index 和 client usage examples
• docs/media/README.md：未来截图和视频 checklist
• docs/media/architecture-diagram.md：可渲染的 architecture diagram source
• docs/launch/x-thread-v2.1.md：可直接发布的 launch thread
• docs/future/：安全的未来 evaluation 和 registry designs
• docs/workflows/：agent workflow 文档
• templates/adoption/：最小 repository adoption templates
• examples/static-tool-bridges/：local-only 防御性 static tool bridge examples
• examples/comparisons/：前后对比示例
• data/benchmarks/index.yaml：静态 comparison benchmark index
• docs/21-contributor-growth-loop.md：面向 patterns、controls、trials、examples、standards 和 templates 的贡献通道
• docs/digests/：monthly security pattern digest records
• docs/digests/2026-05-evidence-refresh-security-pattern-digest.md：evidence corpus refresh digest
• docs/domain-packs/：planning-only future domain pack designs
• docs/domain-packs/rag-ai-app.md：已实现的 RAG / AI app security domain pack pilot
• docs/22-local-stacked-release-candidate-checklist.md：local stacked release-candidate checklist
• docs/org-adoption/：organization rollout、maturity、policy、cadence 和 checklist
• docs/finding-format.md：canonical finding format 和可选 attack-chain metadata
• docs/workflows/attack-chain-review.md：evidence-backed attack-chain review workflow
• docs/evidence/evidence-quality-rubric.md：面向 trials、examples、controls 和 regression guidance 的 evidence quality scoring rubric
• docs/evidence/evidence-dashboard.md：按 scenario 展示 evidence maturity 的 dashboard
• examples/worked/：worked examples 和误报抑制示例
• examples/public-trials/：公开 review 试跑记录

发布状态

• v0.1：公开 prompt library、skills、plugin package、scenario registry、validation
• v0.2：examples、bilingual docs、prompt snapshots
• v0.3：只读本地 MCP server
• v0.4：agent workflow docs 和静态 evaluation harness
• v0.5：integration designs 和 incident pattern library
• v0.5.1：self-review gap closure、加深 flagship prompts、plugin resources、limitations、compatibility notes、worked examples
• v0.6：所有 prompts 和 skills 完成英文在前、中文在后的双语结构
• v0.7：脱敏非可部署 demo fixtures、扩展 worked examples 和 demo-backed evaluation coverage
• v0.8：CI maintenance、evaluation coverage matrix 和 rubric、community release kit，以及公开 PR 试跑记录
• v0.9：安全的未来 evaluation 和 static registry design artifacts
• v1.0：stable public release、stability contract、release checklist 和 final public-use polish
• v1.1：audit-only prompt depth parity、内容性中文段落和 prompt-depth validation
• v1.2：static public trials 和 playbook-to-static-tool worked example
• v1.2.1：onboarding entry point、skill/plugin compatibility clarification 和 MCP registry path hardening
• v1.2.2：source formatting enforcement，以及本地命令和 GitHub Actions 的 validation consistency
• v1.3：YAML-backed coverage、standards mappings、negative controls、incident-pattern growth 和 read-only MCP knowledge resources
• v1.4：按角色划分的 user guides、adoption templates 和 adoption validation
• v1.5：扩展 public trial corpus、trial index 和 scenario coverage validation
• v1.6：面向 sanitized local fixtures 的 static tool bridge cookbook
• v1.7：contributor growth loop、monthly digest template 和 digest validation
• v1.8：planning-only future domain pack designs 和 validation
• v1.9：local release-candidate checklist、docs index 和 stack metadata validation
• v2.0：organization adoption playbook、maturity model、internal policy、cadence 和 checklist
• v2.1：launch UX pack，包含 3 分钟 demo、architecture guide、comparison example 和 promotion checklist
• v2.2：demo and media pack，包含 transcript、CLI/editor/MCP walkthroughs 和 diagram source
• v2.3：benchmark comparison pack，覆盖六个 security review scenarios
• v2.4：community growth kit，包含贡献指南、issue templates 和 maintainer checklist
• v2.5：MCP knowledge UX，包含 resource index、client prompts 和 response examples
• v2.6：evidence corpus refresh，补齐 public trial links、negative controls 和 digest update
• v2.7：首个已实现 domain pack pilot，覆盖 RAG / AI app security
• v2.8：standards and enterprise evidence pack，增加 standards-to-assets validation
• v2.9：local static site and registry export preparation，不增加 hosting 或 uploads
• v3.0：long-term maintenance release，包含 stability、governance、cadence 和 deprecation policy
• v3.1：evidence credibility track，增加 quality rubric、evidence index、dashboard 和 validation
• v3.2：canonical finding format 和 evidence-backed attack-chain reasoning
• v3.3：首次使用路径、dependency advisory triage、render-prompt guard 和 project-self security gates
• v3.3.1：remote AI usage entrypoint，用于把 GitHub playbook 链接发给 assistant
• v3.4：脱敏 field notes、finding triage 和 security debt register
• v3.4.1：maintainer attribution 和同步 repository mirror links