Secret Scanner 可检测受支持的 Apifox 资产中可能存在的 API Key、访问令牌、凭据、webhook URL 以及其他敏感值。检测结果会显示可能存在密钥的位置，但不会展示其完整值。
本教程将介绍如何查看检测结果、处理真实的泄漏事件、记录解决状态，以及在团队使用内部密钥格式时添加自定义检测规则。
开始之前
Secret Scanner 仅适用于企业 SaaS 版，目前暂不支持 Apifox 私有化部署版。
功能权限取决于您的角色：
| 角色 | 可用操作 |
|---|---|
| 组织 Owner 或 Admin | 查看跨团队的组织级报告 |
| 团队 Owner 或 Admin | 查看团队检测结果、解决或重新打开检测结果、管理自定义规则以及查看分析数据 |
| 团队成员或访客 | 仅查看其有权访问的项目中的检测结果 |
测试时请使用虚构值。切勿仅仅为了验证扫描功能而将真实凭据粘贴到资源中。
步骤 1：查看组织报告
组织 Owner 和 Admin 可以使用组织报告来识别存在未解决检测结果的团队。
- 打开组织级的 Secret Scanner 报告。
- 查看未解决检测结果和已发布泄漏的数量。
- 检查最近检测时间和扫描状态。
- 打开受影响的团队或联系对应的团队 Owner 或团队 Admin。
组织报告可帮助管理员识别哪些团队需要跟进。
该报告是一个汇总排查视图。具体的调查与解决操作需要在受影响团队的 Secret Scanner 页面中进行。
步骤 2：打开并筛选团队的检测结果
在团队中，打开 Secret Scanner 并选择 Secrets Detected。
使用可用的筛选条件缩小列表范围：
- 状态
- 项目
- 规则（pattern）
- 资源类型
- 关键字
每个检测结果均按其检测规则和安全指纹进行分组。当同一个被检测到的值出现在多个位置时，一个检测结果会包含多个匹配项（occurrences）。
敏感值已进行脱敏遮蔽。请结合项目、资源类型、匹配项数量和来源位置来排查检测结果。
建议优先处理标记为已发布泄漏的未解决结果，然后再排查出现在多个资源或项目中的结果。
步骤 3：检查每个匹配项
打开某个检测结果并查看其具体匹配项。针对每个匹配项，请确认：
- 包含该值的项目和资源
- 资源类型和来源位置
- 该值是否出现在已发布的文档中
- 首次与最近检测到的时间
- 该值是真实凭据还是误报（false positive）
在判断某个值是否为真实的凭据时，切勿仅凭脱敏后的代码片段做决定。请检查源资源，必要时请资源所有者在不将凭据复制到工单或聊天消息中的前提下识别出签发系统。
步骤 4：响应真实泄露
Secret Scanner 仅报告可能存在的泄露风险，并不会修改凭据。对于已确认的敏感信息（secret），请在其签发系统中进行处理。
请按以下顺序处理：
- 在外部服务中撤销（Revoke）、轮换（Rotate）或使该凭据失效（Invalidate）。
- 审查可用的使用日志，排查是否存在异常活动。
- 从 Apifox 中显示的每一个源码出现位置中移除该值。
- 如果工作流仍需要该凭据，将原始值替换为适当的变量或 Vault Secret 引用。
- 保存每个已修改的资源，以便重新触发异步扫描。
如果凭据出现在已发布的文档中，即使未观察到可疑的使用记录，也应将其视为已在外部泄露。
从 Apifox 中移除某个值并不会使可能已存在于其他地方的副本失效。对于真实的泄露事件，轮换或撤销才是主要的控制处置手段。
步骤 5：记录处理结果
完成响应处理后，请设置检测结果的解决原因（resolution reason）。
| 解决原因 | 适用场景 |
|---|---|
| Revoked | 该值是真实的敏感信息，并且已在 Apifox 外部被撤销、轮换或失效 |
| False positive | 检测到的值不是敏感信息 |
| Won't fix | 该值是真实的敏感信息，但团队已接受该风险且不准备对其进行修改 |
将检测结果标记为已解决仅会修改其在 Apifox 中的状态，并不会撤销、轮换、失效、移除或替换底层的凭据值。
如果后续需要采取进一步行动，可以重新打开该检测结果。
步骤 6：验证清理结果
Secret Scanner 是异步运行的，而非实时运行。当添加支持的资源，或在修改支持的资源后点击保存时，均会触发扫描。
完成修复后：
- 确认所有已知的源码出现位置均已更改
- 保存受影响的资源
- 等待异步扫描完成
- 审查检测结果及其最近一次检测到的时间
- 单独确认旧凭据在签发服务中已无法使用
扫描器的状态并不等同于凭据有效性测试。请在外部服务中确认撤销状态。
步骤 7：添加自定义检测规则
团队所有者（Team Owner）和团队管理员（Team Admin）可以针对组织特定的敏感信息格式创建自定义规则（custom pattern）。
- 打开 Secret Scanner > Patterns。
- 选择创建自定义规则的选项。
- 输入清晰明确的名称。
- 添加正则表达式以及任何有用的关键字。
- 使用虚拟值进行测试。
- 启用该规则并保存。
当前限制如下：
- 每个团队最多支持 5 个自定义规则；
- 规则名称最长支持 128 个字符；
- 界面中的正则表达式最长支持 256 个字符；
- 最多支持 10 个关键字；
- 每个关键字最长支持 64 个字符。
内置规则是只读的。其内部的正则表达式不会显示，且无法进行编辑、删除、启用或禁用。
步骤 8：查看团队分析
团队所有者（Team Owner）和团队管理员（Team Admin）可以打开 Analytics（分析）查看匹配结果的集中分布区域。
使用分析功能识别需要进一步审查的项目、规则和资产类型。
分析功能有助于排定工作的优先顺序，但每个检测结果仍需要在源码或源资源层面上进行排查。
支持的资产类型
Secret Scanner 目前支持扫描以下类型的资产：
- API 及 API 请求
- 接口用例
- 项目模块及项目模块变量
- 响应示例
- Markdown 文档及数据模型
- 环境变量、全局变量及团队变量
- 公共脚本及公共参数
检测结果中可用的来源详情取决于其资源类型及查看者的权限。
故障排查
| 问题 | 检查项 |
|---|---|
| 最近的修改尚无检测结果 | 扫描是异步进行的。请确认资源已保存，稍后再重新查看。 |
| 团队成员看不到检测结果 | 请确认该成员拥有相关项目的访问权限。 |
| 用户无法管理规则或查看分析 | 规则管理和分析功能需要团队所有者（Team Owner）或团队管理员（Team Admin）权限。 |
| 已标记解决的检测结果中仍包含生效的密钥 | 解决状态不会修改凭据本身。请在对应的颁发服务中将其撤销或轮换。 |
| 外部代码仓库未被扫描 | Secret Scanner 不会扫描外部 GitHub 或 GitLab 代码仓库。请结合使用代码仓库提供商的扫描工具。 |
重要限制
Secret Scanner 不会阻止用户输入密钥、不会拦截文档发布、不会扫描外部代码仓库，也不能保证检测出所有格式的密钥。此外，它不会自动删除源值，也不会将其替换为变量或 Vault 引用。
请将其作为凭据管理流程的一部分使用，该流程还应包含最小权限颁发、安全存储、轮换、撤销以及使用监控。
相关 API 治理教程：
这些教程介绍了用于管理企业 API 工作空间的互补控制措施：
- API 治理框架 — 连接所有权、控制措施、证据与生命周期决策。
- 与 Microsoft Entra ID 的 SAML 组映射 — 根据身份提供商的分组分配团队访问权限。
- Secret Scanner — 审查受支持的 Apifox 资产中可能泄露的凭据。
- 审计日志 — 排查并导出组织级别的管理活动。
- SCIM 供应 — 在整个身份生命周期中管理组织用户。
- 企业策略 — 配置凭据、成员身份、SSO 会话和邀请控制。
- 自助式 API 团队 — 允许成员创建团队，同时保留所有权监督。
- GitHub Enterprise Cloud 集成 — 连接受支持的 GHE.com 代码仓库以支持 OpenAPI 工作流。
相关官方文档：
开发必备：API 全流程管理神器 Apifox
介绍完上文的内容，我想额外介绍一个对开发者同样重要的效率工具 —— Apifox。作为一个集 API 文档、调试、设计、测试、Mock、自动化测试于一体的工具，Apifox 是目前提升研发效率的首选。
如果你正在开发项目，不妨试试其极其友好的界面设计，它完全兼容 Postman 和 Swagger 数据格式，导入数据非常方便，，即使是新手也能很快上手，点击这里即可注册使用。
值得一提的是，除了个人和常规团队使用，针对有高安全合规要求、或需要在内网环境协作的企业，Apifox 还提供了深度定制的私有化部署方案。
获取专属报价与部署方案
详细的私有化部署系统架构与安全白皮书
针对您公司规模的专属报价单
免费的 1v1 专属产品演示 (Demo) 机会
