AgentKit Studio
贡献

安全与公开边界

仓库是公开的:14 条红线(路径 4 条 + 内容 10 条)、它们为什么不能进文档,以及本地自检命令与误报处理。

这个仓库是公开的。任何提交进 Git 的内容都会永久留在历史里——删除文件不会删除历史记录。 因此边界不是"发布前检查一下",而是"写的时候就不过线"。

为什么有这条边界

三条来自真实失效模式的理由:

  1. 历史不可撤销。一个凭证进了 main,撤销方式是轮换,不是 git rm。所以审计同时扫描 当前文件和历史 blob。
  2. 文档会离开仓库。文档站、发布包、镜像、AI 索引都会复制同一份内容,任何一处泄漏都会扩散。
  3. 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 私有网段地址
9URL 内嵌凭证scheme://user:password@host 形态
10个人绝对路径macOS / Linux / Windows 的用户主目录路径
11GitHub 令牌ghp_ / ghs_ / github_pat_ 形态
12AWS Access KeyAKIA 开头的长令牌
13供应商 API Keysk- 与 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 里没有任何文件或提交级豁免——只有三条精确的合成夹具值。

上报安全问题

如果你发现了已经进入仓库的凭证或敏感信息:

  1. 不要开公开 issue,不要在建言区贴出具体值。
  2. 按 SECURITY.md 的渠道私下报告,说明文件与行号。
  3. 假定该凭证已泄漏,先在源头轮换,再清理仓库。

完整的门禁分层见门禁与验证;文档侧的写作禁令见文档写作规范。

本页导航