salmanabdurrahman/pi-security-review
GitHub: salmanabdurrahman/pi-security-review
一个基于 Pi 扩展的本地优先 AI 代码安全审查工具，通过 Git diff 范围构建上下文并调用 LLM 模型分析 HIGH/MEDIUM 级别安全发现，生成结构化报告。
Stars: 0 | Forks: 0
# pi-security-review
针对 Pi 的高信噪比安全审查包。它根据本地 Git diffs 构建有边界的审查上下文，通过 Pi 的活动 model/provider 排队发送与 provider 无关的 prompt，捕获结构化结果，在交互式/工具流程中应用确定性的误报过滤器，并可选择发布受控的 GitHub PR 评论。
本包针对 Pi 包生态系统调整了来自 [`anthropics/claude-code-security-review`](https://github.com/anthropics/claude-code-security-review) 的安全审查理念：Pi 命令、Pi LLM 工具、Pi model/provider 生命周期、有限的本地报告、与 provider 无关的 prompt 以及明确的写入批准。
该包以本地优先、无遥测为原则，专为交互式 Pi 审查以及无头 CI 产物/最终报告工作流而设计。
## 目录
- [概述](#overview)
- [包边界](#package-boundary)
- [核心能力](#core-capabilities)
- [命令面](#command-surface)
- [LLM 工具](#llm-tools)
- [文档导航](#documentation-map)
- [技术栈](#tech-stack)
- [快速开始](#getting-started)
- [配置](#configuration)
- [审查工作流](#review-workflow)
- [自定义指令](#custom-instructions)
- [报告](#reports)
- [CI/CD](#cicd)
- [隐私与安全](#privacy-and-security)
- [开发工作流](#development-workflow)
- [测试与验证](#testing-and-verification)
- [项目结构](#project-structure)
- [发布说明](#publishing-notes)
- [贡献指南](#contribution-guide)
## 概述
`pi-security-review` 帮助 Pi 将安全审查重点放在修改的代码上，而不是阅读整个代码库。它解析本地、暂存、分支或显式的 diff 范围；过滤掉生成的/供应商的/类似密钥的路径；构建有边界的 prompt；仅向活动的 Pi model 询问 HIGH/MEDIUM 结果；然后将规范化的 Markdown 和 JSON 报告存储在 `.pi/security-review/` 下。
本代码库负责：
- Pi 扩展入口点和包清单。
- 代码库本地 config schema、默认值、验证和创建。
- Git repo 发现、工作树状态、GitHub remote 检测以及安全的 diff 范围解析。
- 包含明确漏洞利用路径和不回显密钥规则的安全 prompt 生成。
- 来自有限的代码库相对文件或内联文本的可选自定义扫描/过滤指令。
- Marker 解析器、规范化的结果模型、确定性的误报过滤器、Markdown 报告渲染以及有效的 SARIF 2.1.0 导出。
- 通过 Pi `message_end` hook 捕获最新报告以及报告面板重放。
- 带有明确批准关卡和安全 marker 更新的 GitHub PR 评论预览/发布集成。
- 无头 CI 上下文生成、外部最终报告摄取、失败关卡、复合 GitHub Action 以及 CI 文档。
- 用于状态、diff 分析、上下文构建、过滤、渲染和 GitHub 评论预览/发布的有限 LLM 辅助工具。
## 包边界
该包负责安全审查上下文生成和报告处理。它不负责 model provider 凭据、漏洞修复、部署策略或通用的 SAST 替代。
| 领域 | 职责 |
| ---------------- | ------------------------------------------------------------------------------ |
| Pi extension | 命令、工具、prompt 排队、状态 UI、最新报告面板 |
| 审查核心 | Diff 范围、上下文边界、prompt 合约、marker 解析器、报告渲染器 |
| 过滤 | 确定性的置信度/严重性阈值和严格的误报排除 |
| 集成 | 可选的 code-review-graph 上下文、GitHub PR 评论、CI 产物 |
| 安全 | 无遥测、无源码编辑、默认无网络写入、密钥脱敏 |
| 发布工作流 | 构建输出、包审计、npm pack dry-run、公开文档 |
## 核心能力
| 能力 | 状态 |
| --------------------------- | ------------------------------------------------------------------------------- |
| Repo 状态 | 通过 `/security-review-status` 实现 |
| 配置创建 | 通过 `/security-review-config --create` 实现 |
| Diff 范围审查 | 通过 `/security-review` 结合当前、分支和显式 refs 实现 |
| Model 覆盖 | 当 Pi host 暴露 model registry 时，通过 `--model provider/model` 实现 |
| 自定义扫描/过滤指令 | 通过安全的文件 flags 和内联文本 flags 实现 |
| 报告捕获 | 通过在 assistant 响应结束时进行结构化 marker 解析实现 |
| 最新报告面板 | 通过 `/security-review-panel` 实现 |
| 确定性过滤器 | 针对置信度、严重性以及已知的低信号结果类别实现 |
| SARIF 渲染 | 通过 `security_review_render_report` 结合 `format: "sarif"` 实现 |
| GitHub PR 评论 | 默认 dry-run；发布需要明确批准 |
| 内联 PR 评论 | 尽力而为，根据已更改的 PR 行进行验证；当映射失败时回退为摘要 |
| CI 产物模式 | 已实现；默认不调用 model 且不对 GitHub 进行写入 |
| 外部最终报告模式 | 已实现，带有针对 HIGH/MEDIUM 结果的失败关卡 |
| 复合 GitHub Action | 通过根目录的 `action.yml` 实现 |
## 命令面
```
/security-review-status
/security-review-config [--create]
/security-review [--base ] [--head ] [--from ] [--to ] [--model ] [--scan-instructions-file ] [--filter-instructions-file ] [--scan-instructions-text ] [--filter-instructions-text ] [focus paths...]
/security-review-panel
/security-review-comment [--dry-run] [--pr ] [--yes] [--update-existing] [--inline]
/security-review-ci-help
```
### 命令详情
**`/security-review-status`** — 显示 repo 根目录、config 状态、最新报告、活动 model、配置的 model profiles、GitHub remote、尽力而为的 `gh` 认证状态以及默认的网络写入姿态。在 Git repo 之外运行时不会崩溃。
**`/security-review-config`** — 显示 repo 本地的 config 状态。添加 `--create` 以在缺失时写入带有默认值的 `.pi/security-review.json`。
**`/security-review`** — 为当前或显式的 diff 范围构建有边界的上下文，并通过 Pi 排队发送安全 prompt。该 prompt 仅要求提供由所提供的更改引入或暴露的具体 HIGH/MEDIUM 漏洞。
示例：
```
/security-review
/security-review --base origin/main --head HEAD
/security-review --from v0.1.0 --to HEAD src/auth src/api
/security-review --model openai/gpt-5.1-codex
/security-review --scan-instructions-file .github/security-scan.txt
```
**`/security-review-panel`** — 在可用时在编辑器中打开 `.pi/security-review/latest-report.md`，或显示回退通知文本。格式错误的报告 JSON 警告将被展示，而不是导致崩溃。
**`/security-review-comment`** — 默认将最新报告预览为 GitHub PR 评论。发布需要 `--yes`。现有的 marker 评论可以通过 `--update-existing` 更新；可选的 `--inline` 评论仅针对经过验证的已更改 PR 行进行，并在映射失败时回退为摘要。
```
/security-review-comment --dry-run --pr 123
/security-review-comment --pr 123 --yes --update-existing
/security-review-comment --pr 123 --yes --inline
```
**`/security-review-ci-help`** — 打印简短的 CI 指南。
## LLM 工具
```
security_review_stats
security_review_analyze_diff
security_review_build_context
security_review_model_profiles
security_review_filter_findings
security_review_render_report
security_review_github_comment
```
工具输出在到达 model 之前被限制在 Pi 风格的限额内：50 KB 或 2,000 行。
| 工具 | 目的 |
| --------------------------------- | ------------------------------------------------------ |
| `security_review_stats` | 显示 repo/config/latest-report/model/GitHub 状态 |
| `security_review_analyze_diff` | 解析审查范围并返回有限的 diff 元数据 |
| `security_review_build_context` | 构建与 provider 无关的安全审查上下文 payload |
| `security_review_model_profiles` | 检查配置的 role/model 元数据 |
| `security_review_filter_findings` | 规范化并确定性地过滤 model 发现 |
| `security_review_render_report` | 渲染 Markdown、JSON 或有效的 SARIF 2.1.0 JSON |
| `security_review_github_comment` | 预览或发布受控的 GitHub PR 评论 |
默认情况下，修改工具的行为是安全的。除非同时设置了 `post: true` 和 `approve: true`，否则 `security_review_github_comment` 仅进行预览。
## 文档导航
请按此阅读顺序进行审查、CI 设置或发布交接：
1. `docs/PRIVACY_SECURITY.md` — 本地优先行为、model 边界、密钥处理、GitHub 写入以及 prompt injection 警告。
2. `docs/PROMPT_CONTRACT.md` — 审查范围、所需的发现格式、JSON marker、解析器兼容性和渲染合约。
3. `docs/CI_GITHUB_ACTIONS.md` — 仅产物的 CI、外部最终报告模式、复合 action 用法、PR 评论和 fork 安全性。
4. `docs/RELEASE.md` — 维护者关卡、包内容、受信任的发布、回滚路径和发布检查清单。
## 技术栈
| 领域 | 选择 |
| ------------------- | -------------------------------------------------------------------------- |
| Runtime 目标 | 通过 TypeScript 加载器实现 Pi extension runtime |
| 开发 runtime | Bun |
| 语言 | TypeScript |
| 格式化/linter | Biome |
| Schema 验证 | 用于工具参数 schemas 的 TypeBox；用于 repo config 的本地 config 验证器 |
| 测试运行器 | `bun test` |
| GitHub 集成 | 运行时使用 `gh` CLI/GitHub token 进行批准的评论 |
| 发布目标 | 带有 Pi manifest 和复合 GitHub Action 元数据的 npm 包 |
## 快速开始
安装已发布的包：
```
pi install npm:pi-security-review
/reload
/security-review-status
```
运行首次本地审查：
```
/security-review-config --create
/security-review
/security-review-panel
/security-review-comment --dry-run
```
本地包冒烟测试：
```
bun install
bun run build
pi install .
/reload
/security-review-status
/security-review-config --create
/security-review
```
在测试构建输出而未安装包时的直接扩展冒烟测试：
```
pi install ./dist/index.ts
/reload
```
由包创建或使用的 repo 本地文件：
```
.pi/security-review.json
.pi/security-review/latest-report.md
.pi/security-review/latest-report.json
.pi/security-review/ci-context.json
.pi/security-review/ci-report.md
```
## 配置
默认 config 路径：
```
.pi/security-review.json
```
使用 `/security-review-config --create` 创建它。
关键选项：
| 选项 | 目的 |
| -------------------------------------- | ------------------------------------------------------------------------ |
| `enabled` | 为 repo 启用或禁用包 |
| `include` / `exclude` | 控制符合条件的路径 |
| `excludeDocumentation` | 默认排除文档以减少低信号发现 |
| `excludeTestsByDefault` | 除非明确指定，否则默认排除测试 |
| `maxDiffBytes` | 限制捕获的 diff 文本 |
| `maxContextChars` | 限制 prompt/context 大小 |
| `maxFiles` | 限制文件数量 |
| `maxCommits` | 限制 commit 元数据 |
| `confidenceThreshold` | 丢弃低于置信度阈值的发现，默认为 `0.8` |
| `severityThreshold` | 仅保留 `medium`+ 或 `high` |
| `enableHardExclusions` | 启用确定性的误报类别 |
| `enableModelFiltering` | 为基于 model 的过滤器运行器保留；确定性过滤器仍会运行 |
| `modelProfiles` | 默认/审计者/过滤器/报告者的 role 元数据 |
| `agentPipeline` | 活动 role pipeline 元数据，默认为 `auditor` |
| `customSecurityScanInstructions` | config 中可选的 repo 相对扫描指令文件路径 |
| `falsePositiveFilteringInstructions` | config 中可选的 repo 相对过滤指令文件路径 |
| `github.commentByDefault` | 安全默认值保持为 false |
| `github.updateExistingComment` | 批准后更新 marker 评论 |
| `github.commentMarker` | PR 评论 marker，默认为 `` |
| `ci.failOnHigh` / `ci.failOnMedium` | CI 策略默认值；CLI flags 可控制最终报告 |
| `optionalIntegrations.codeReviewGraph` | 可用时包含尽力而为的 CRG 上下文 |
最小示例：
```
{
"enabled": true,
"severityThreshold": "medium",
"confidenceThreshold": 0.8,
"github": {
"commentByDefault": false,
"updateExistingComment": true,
"commentMarker": ""
}
}
```
## 审查工作流
1. 解析 Git repo 和 config。
2. 从显式 refs/paths 或当前工作树解析 diff 范围。
3. 应用 include/exclude 和类似密钥的路径过滤器。
4. 在需要时构建带有截断警告的有边界上下文。
5. 添加可选的自定义扫描/过滤指令。
6. 可用时添加可选的 code-review-graph 上下文。
7. 通过 Pi 活动 model/provider 排队发送与 provider 无关的 prompt。
8. 在 `message_end` 时捕获 assistant 输出 marker。
9. 在交互式捕获期间规范化、脱敏并确定性地过滤发现。
10. 将最新的 Markdown 和 JSON 报告写入 `.pi/security-review/` 下。
11. 在明确批准后，可选择预览/发布 GitHub PR 评论。
## 自定义指令
对于持久的组织策略，推荐使用文件模式：
```
/security-review --scan-instructions-file .github/security-scan.txt --filter-instructions-file .github/security-filter.txt
```
内联模式适用于一次性的审查重点：
```
/security-review --scan-instructions-text "Check tenant boundary bypasses"
```
指令文件安全防护：
- 仅限 repo 相路径。
- 最大文件大小 64 KiB。
- 拒绝绝对路径和 `..` 目录遍历。
- 拒绝类似密钥的路径，包括 `.env`、token/credential/private-key 名称以及 key/cert 文件。
- Config 字段引用 repo 相对的指令文件。
- CLI/工具的 `*-instructions-text` 字段用于内联的一次性指令。
- 自定义扫描指令扩展了默认的安全类别。
- 自定义过滤指令调整误报标准，但不会禁用确定性的硬过滤器。
旧版别名 `--scan-instructions` 和 `--filter-instructions` 仍可作为带有警告的内联文本使用。
## 报告
首选的 assistant 输出以一个 marker 块结尾：
```
{
"findings": [],
"excludedFindings": [],
"analysisSummary": {
"filesReviewed": 0,
"highSeverity": 0,
"mediumSeverity": 0,
"lowSeverity": 0,
"reviewCompleted": true,
"diffTruncated": false,
"contextTruncated": false
}
}
```
解析器还尽力接受原始 JSON、围栏 JSON、带有空格的 marker 变体以及参考风格的 snake_case 字段，如 `exploit_scenario`、`analysis_summary` 和 `files_reviewed`。
存储的输出：
```
.pi/security-review/latest-report.md
.pi/security-review/latest-report.json
```
报告处理安全防护：
- 格式错误/不完整的输出会记录可操作的警告，而不是崩溃。
- 常见的类似密钥的值会在本地写入或 GitHub 评论渲染之前被脱敏。
- 交互式 `message_end` 捕获和 `security_review_filter_findings` 在存储/渲染之前运行确定性过滤器。
- CI 外部最终报告模式会对受信任的 model 输出进行规范化和脱敏；如果 CI runner 需要确定性的重新过滤，请单独运行 `security_review_filter_findings`。
- 过滤元数据记录了运行确定性过滤器时保留/排除的计数和阶段。
- 除非由 runner 实现，否则 model 端的过滤角色目前会被推迟。
## CI/CD
仅产物模式构建有边界的上下文和 prompt。它不调用 model，也不是最终的安全结果：
```
bun run security-review:ci -- --base origin/main --head HEAD
```
外部最终报告模式读取 model 生成的 marker 输出并应用失败关卡：
```
bun run security-review:ci -- \
--base origin/main \
--head HEAD \
--final-report artifacts/final-security-report.md \
--fail-on-high \
--fail-on-medium
```
PR 评论模式需要最终报告和明确的批准：
```
bun run security-review:ci -- \
--base origin/main \
--head HEAD \
--final-report artifacts/final-security-report.md \
--pr 123 \
--comment \
--yes
```
复合 action 默认为仅产物模式，并且没有供应商 API key 输入：
```
- uses: owner/pi-security-review@v0.1.0
with:
base: origin/${{ github.base_ref }}
head: HEAD
```
有关完整的工作流模板、权限、最终报告模式、评论和 fork 安全性，请参阅 `docs/CI_GITHUB_ACTIONS.md`。
## 隐私与安全
`pi-security-review` 是本地优先的。
- 无遥测。
- 无源码编辑或 autofix 行为。
- 默认无 GitHub 评论或网络写入。
- 本包不存储 provider API key。
- Runtime 辅助工具使用固定的 argv 数组，而不是 shell 插值。
- 类似密钥的路径和值在存储或评论之前会被过滤/脱敏。
- 报告/config 存储在 `.pi/` 下，并从包输出中排除。
- Model prompt 仅在用户运行审查后通过 Pi 的活动 provider/model 生命周期发送。
- AI 审查并未针对来自修改的代码/文档/评论/自定义指令的 prompt injection 进行强化。
对于不受信任的 fork，请使用仅产物模式。在对外部贡献进行基于 model 的审查或具有写入权限的工作流之前，需要获得维护者的批准。请参阅 `docs/PRIVACY_SECURITY.md`。
## 开发工作流
安装依赖项：
```
bun install
```
运行本地检查：
```
bun run check
```
构建包输出：
```
bun run build
```
运行 npm 包 dry-run：
```
bun run pack:dry-run
```
在发布前运行包审计：
```
bun run prepublish:audit
```
## 测试与验证
交接前的快速验证：
```
bun run typecheck
bun run lint
bun test ./test
bun run build
bun run smoke:security-review
bun run pack:dry-run
```
发布验证还应包括：
```
bun run security-review:ci -- --base HEAD --head HEAD
bun run prepublish:audit
pi install .
/reload
/security-review-status
/security-review-config --create
/security-review
/security-review-panel
/security-review-comment --dry-run
```
## 项目结构
```
.
|-- action.yml
|-- docs/
| |-- CI_GITHUB_ACTIONS.md
| |-- PRIVACY_SECURITY.md
| |-- PROMPT_CONTRACT.md
| `-- RELEASE.md
|-- scripts/
| |-- audit-npm-package.ts
| |-- build-package.ts
| |-- security-review-ci.ts
| `-- smoke-security-review.ts
|-- src/
| |-- config/
| |-- git/
| |-- github/
| |-- security/
| |-- store/
| |-- tools/
| |-- util/
| `-- extension.ts
|-- test/
|-- index.ts
|-- package.json
`-- README.md
```
## 发布说明
发布路径：
1. 完成 `docs/RELEASE.md` 中的维护者发布检查清单。
2. 运行 `bun run check`。
3. 运行 `bun run smoke:security-review`。
4. 运行 `bun run security-review:ci -- --base HEAD --head HEAD`。
5. 运行 `bun run prepublish:audit`。
6. 运行 `bun run pack:dry-run`。
7. 仅在维护者批准后创建并推送发布 tag。
8. 配置后，让 GitHub Actions 通过 npm trusted publishing/OIDC 进行发布。
Pi manifest 在 `package.json` 中声明：
```
{
"pi": {
"extensions": ["./dist/index.ts"]
}
}
```
npm 包白名单包括 runtime `dist`、`scripts/security-review-ci.ts`、`action.yml`、精选的公开文档、README、license 和包元数据。
## 贡献指南
在更改行为之前：
- 保持更改最小，并与单一的安全审查能力相关联。
- 为行为更改添加或更新测试。
- 保持文档与实际的命令/工具 flags 和默认安全行为一致。
- 保留无遥测、默认无网络写入和无源码编辑的保证。
- 不要削弱密钥/路径过滤或 prompt injection 警告。
- 在交接之前运行相关的验证，并记录跳过的检查。
标签：DevSecOps, Git工具, 上游代理, 云安全监控, 人工智能, 暗色界面, 用户模式Hook绕过, 自动化攻击, 静态分析