贡献
安全与公开边界
仓库是公开的:14 条红线(路径 4 条 + 内容 10 条)、它们为什么不能进文档,以及本地自检命令与误报处理。
这个仓库是公开的。任何提交进 Git 的内容都会永久留在历史里——删除文件不会删除历史记录。 因此边界不是"发布前检查一下",而是"写的时候就不过线"。
为什么有这条边界
三条来自真实失效模式的理由:
- 历史不可撤销。一个凭证进了
main,撤销方式是轮换,不是git rm。所以审计同时扫描 当前文件和历史 blob。 - 文档会离开仓库。文档站、发布包、镜像、AI 索引都会复制同一份内容,任何一处泄漏都会扩散。
- AI 会读它。本站提供
llms.txt与逐页 Markdown 路由,文档内容会被编码 Agent 直接消费。 写进文档的"示例凭证"很容易被当成真实配置使用。
14 条红线
scripts/public-surface-audit.mjs 定义了两组检查:路径与文本内容。
路径类(4 条)
| # | 红线 | 覆盖范围 |
|---|---|---|
| 1 | 构建与工具产物 | .artifacts/、.playwright-cli/、.zread/ |
| 2 | 运行时与缓存目录 | node_modules/、.scratch/、.dsh/、.agentkit/、.codex/、.ssh/、profiles/ |
| 3 | 私钥文件 | id_rsa、id_dsa、id_ecdsa、id_ed25519 以及 .p12 / .pfx / .p8 / .key |
| 4 | 环境与凭证命名 | .env 及其变体;名字里带 credential / secret / token 的 json / yaml / toml / ini / env 文件;private-key 命名的文件 |
这些路径整体拒绝,不进入内容扫描——因为在公开仓库里它们没有正当用途。
内容类(10 条)
| # | 红线 | 判定 |
|---|---|---|
| 5 | 私钥块 | PEM 格式的私钥头 |
| 6 | 内部代码托管域名 | 公司内网代码托管的域名 |
| 7 | 内网服务域名 | .internal / .intranet / .corp 域名,以及内网 API 主机 |
| 8 | 私网地址 | RFC 1918 私有网段地址 |
| 9 | URL 内嵌凭证 | scheme://user:password@host 形态 |
| 10 | 个人绝对路径 | macOS / Linux / Windows 的用户主目录路径 |
| 11 | GitHub 令牌 | ghp_ / ghs_ / github_pat_ 形态 |
| 12 | AWS Access Key | AKIA 开头的长令牌 |
| 13 | 供应商 API Key | sk- 与 AIza 形态的模型供应商密钥 |
| 14 | 私有分类标记 | 大写的中文密级短语,以及 CI 专用的分类标签 |
官方服务端点例外:少数几个官方服务域名虽然只在内网可达,但属于公开客户端契约的一部分,
被显式列入批准清单(APPROVED_INTERNAL_SERVICE_HOSTS)。这份清单只能通过评审变更,
不要为了让扫描通过而往里加条目。
为什么这些不能进文档
| 你可能会想 | 为什么不行 |
|---|---|
| "这只是个示例密钥" | 示例会被复制成真实配置;而且无法证明它不是真的 |
| "这是测试环境的地址" | 测试环境与生产环境往往共享命名规则,地址本身就是情报 |
| "路径里没有密钥" | 用户名会泄漏组织成员,也会让本地复现失败 |
| "这个域名是公开的" | 内网可达 ≠ 可以公开;批准清单之外一律拒绝 |
| "我删掉了,所以没问题" | 历史 blob 仍可检出,public-history-audit.mjs 会扫到 |
替代写法:
- 凭证 →
<YOUR-API-KEY> - 主机 →
example.test(.test/.example是保留域名) - 路径 → 相对路径
<your-workspace> - 私网地址 → 说明"私网地址"而不是写出来
本地自检
四条命令,从便宜到彻底:
# 1. 公开面:全部受控文件 + 未忽略的新文件的内容与路径
make public-surface-audit
# 2. 历史:公共分支可达的每一个 blob 与历史路径(需要完整检出)
node scripts/public-history-audit.mjs
# 3. 密钥:Gitleaks 8.30.1,历史 + 快照两次扫描
make secret-scan
# 4. 可移植性:受版本控制文件里没有个人绝对路径或 file:/// URL
node scripts/check-portability.mjs浅克隆会直接报错
历史扫描要求完整检出。CI 使用 fetch-depth: 0;本地浅克隆请先 git fetch --unshallow,
否则审计会以 "requires a complete checkout" 失败——这是有意的,半份历史等于没扫。
审计不会泄漏它发现的东西
命中时只输出 文件:行号 与规则名,不打印匹配内容、作者、远端 URL 或报告全文。
这也是为什么本地跑和 CI 跑同样安全。
误报了怎么办
先假设它是真的。确认无误后,只有三种正当处理方式:
| 情况 | 做法 |
|---|---|
| 公开的合成测试夹具 | 在 scripts/public-surface-audit.mjs 的批准清单里加入精确值,同时写清理由 |
| 历史里已经存在的合成值 | 加入 scripts/public-history-baseline.mjs,且必须绑定 blob 摘要与行号 |
| 官方服务端点 | 加入 APPROVED_INTERNAL_SERVICE_HOSTS,并在评审里说明为什么它是公开契约 |
不允许的做法:整文件豁免、整提交豁免、按指纹豁免、临时注释掉整条规则。
ci/gitleaks.toml 里没有任何文件或提交级豁免——只有三条精确的合成夹具值。
上报安全问题
如果你发现了已经进入仓库的凭证或敏感信息:
- 不要开公开 issue,不要在建言区贴出具体值。
- 按
SECURITY.md的渠道私下报告,说明文件与行号。 - 假定该凭证已泄漏,先在源头轮换,再清理仓库。