机密扫描与机密保护

提交到仓库中的凭据会暴露给所有能克隆该仓库的人以及它的每一份备份。Gitea Enterprise v27.3.8 增加了两层防护：

机密扫描读取仓库的代码（可选地包括历史），并把已提交的机密作为发现显示在仓库的安全页面。
机密保护（推送保护）在推送入库之前读取它，并在其引入机密时拒绝推送，因此凭据不会进入仓库。

机密扫描属于安全扫描功能的一部分，与依赖扫描和代码扫描并列。三者共用同一个安全页签、同一个设置页面、同一套生命周期（打开、关闭、驳回）和同一套 API。

启用机密扫描

站点级别

打开 站点管理 > 安全，在**机密（Secrets）**部分可以设置：

设置	说明
允许在整个站点使用机密扫描	站点范围内运行机密扫描器的总开关（默认开启）。关闭时仓库已保存的偏好会保留，重新开启后继续生效。
默认启用机密扫描	从未保存过自己安全扫描设置的仓库会跟随该开关（默认关闭，避免升级后在无人要求的仓库里开始报告机密）。

仓库级别

打开 仓库 > 设置 > 安全扫描。
启用安全扫描，并选择要扫描的分支模式，例如 main、release/*。留空只扫描默认分支。
在机密部分选择扫描器并设置选项。
保存。保存后会按新配置重新扫描。

组织和用户所有者可以在自己的设置页面设置默认值。新仓库会复制这些默认值，从未保存过自己设置的仓库会跟随它们。

扫描器

扫描器	说明
内置	自带一组常见凭据的检测规则：AWS 访问密钥 ID 和密钥、GitHub 与 GitLab 令牌、Slack 令牌、Google API 密钥和服务账号密钥、Stripe 正式密钥、Azure 存储密钥、私钥、JSON Web Token、证书，以及只对高熵值触发的通用“名称 = 值”规则。可以单独关闭某条规则，也可以添加自定义规则。
Gitleaks 规则集	使用仓库在 `.gitea/gitleaks.toml` 中提交的 Gitleaks TOML 规则集（`[[rules]]`、`[rules.allowlist]`）。没有该文件的仓库不会被此扫描器扫描。

选项

选项	说明
路径	把扫描器限制在这些路径内，每行一个模式，例如 `src/**`。留空扫描整个仓库。
内置规则	启用或禁用每条内置规则。
自定义规则	JSON 数组，例如 `[{"id":"internal-token","name":"Internal token","regex":"...","severity":"high"}]`。
允许的路径	扫描器不读取的路径，例如 `testdata/**`。
允许的匹配	与发现的值进行匹配的正则表达式，匹配到的不会被报告。
允许的发现	不希望被报告的发现，用发现页面上显示的指纹标识。
读取分支的历史	同时读取分支顶端之前的提交。后续提交删除的机密仍然存在于提交中，仍然需要轮换。
拒绝引入机密的推送	启用机密保护，见下文。

设置页面的扫描历史按钮会重新读取每个被扫描分支的完整历史，而不只是上次扫描之后的变化。清理会删除已不存在分支上的发现。设置页面还会列出最近的扫描运行，包括提交、状态以及发现、新增和已修复的数量，并可以重试失败的运行。

忽略文件

仓库可以把例外放在代码里，随代码一起评审和版本化。创建 .gitea/secret-scan-ignore，每行一个条目。以 # 开头的行是注释。条目可以是路径（文件、目录或通配符，例如 third_party 或 **/*.env），也可以是发现的 64 位指纹。该文件最大 64 KiB、最多 1000 个条目。两种机密扫描器都会读取它。

发现

打开仓库的安全页签并选择机密。每个发现会显示规则、机密类型、文件和行号、遮盖后的匹配内容、值的哈希、熵以及指纹。机密本身从不存储，只存储遮盖后的预览和哈希。

可以按状态（打开、关闭、驳回）、严重级别、分支、规则和文件路径过滤。对安全单元具有写权限的用户可以带原因驳回发现（已经开始修复、没有精力修复、风险可以接受、发现不准确、仅在测试中使用），也可以重新打开。后续扫描不再发现时发现会被关闭；启用历史扫描后，仅仅在后续提交里删除机密不会关闭发现：凭据仍然在历史中，必须轮换。

机密保护

为仓库启用拒绝引入机密的推送后，每次推送都会在引用移动之前被读取。只读取推送新增的行，因此文件里原本就有的机密不会算在这次推送头上；强制推送读取的是它恢复的内容。

被拒绝的推送会列出每个机密所属的规则、文件和行号，并附带遮盖后的预览。机密本身从不会被打印或记录。

要在真正拒绝之前评估误报率，可以启用只说明会被拒绝的内容。推送会被放行，审计日志会记录原本会被拒绝的内容。

仓库管理员可以给出原因后强行推送：

git push -o security.push-protection.bypass="test fixture, rotated" origin main

拒绝、本应拒绝和绕过都会记录到审计日志。

该检查有上限，因此不会让推送等待太久：超过 200 个新提交或 20000 个新增行、或读取耗时超过 10 秒的推送会被不读取直接放行。推送之后的扫描仍会记录发现，所以机密不会因此隐形，但不会被拒绝。只有能在推送时间内完成的扫描器才提供保护：内置扫描器和 Gitleaks 规则集（规则集从推送之前的仓库状态读取，因此一次推送无法同时删除规则集并添加机密）。

API

所有类型的发现（包括机密）都可以通过带有 security 范围的令牌，由 API 访问：

接口	说明
`GET /repos/{owner}/{repo}/security/findings`	列出发现。
`GET /repos/{owner}/{repo}/security/findings/{index}`	获取发现。
`POST /repos/{owner}/{repo}/security/findings/{index}/dismiss`	驳回发现。
`POST /repos/{owner}/{repo}/security/findings/{index}/reopen`	重新打开发现。
`GET /repos/{owner}/{repo}/security/findings/sarif`	以 SARIF 格式导出发现。

Agents

安全 Agent 可以判断所有扫描器（包括机密）的发现是真实问题还是误报，结论会显示在发现上（发现页面上的 Triage with agent 可以请求一次判断）。机密一旦被确认，请立即轮换：从代码中删除并不会让它重新变成秘密。