secret-scanning

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Secret Scanning

秘密扫描（Secret Scanning）

This skill provides procedural guidance for configuring GitHub secret scanning — detecting leaked credentials, preventing secret pushes, defining custom patterns, and managing alerts.

本技能提供配置GitHub Secret Scanning的流程指导——包括检测泄露的凭证、阻止秘密内容推送、定义自定义规则以及管理告警。

When to Use This Skill

适用场景

Use this skill when the request involves:

Enabling or configuring secret scanning for a repository or organization
Setting up push protection to block secrets before they reach the repository
Defining custom secret patterns with regular expressions
Resolving a blocked push from the command line
Triaging, dismissing, or remediating secret scanning alerts
Configuring delegated bypass for push protection
Excluding directories from secret scanning via
```
secret_scanning.yml
```
Understanding alert types (user, partner, push protection)
Enabling validity checks or extended metadata checks

当请求涉及以下内容时，可使用本技能：

启用或配置仓库/组织的Secret Scanning
设置推送保护以在秘密内容进入仓库前拦截它们
使用正则表达式定义自定义秘密规则
从命令行解决被拦截的推送
分类、关闭或修复Secret Scanning告警
配置推送保护的委托绕过权限
通过
```
secret_scanning.yml
```
排除目录以避免Secret Scanning扫描
了解告警类型（用户告警、合作伙伴告警、推送保护告警）
启用有效性检查或扩展元数据检查

How Secret Scanning Works

Secret Scanning 工作原理

Secret scanning automatically detects exposed credentials across:

Entire Git history on all branches
Issue descriptions, comments, and titles (open and closed)
Pull request titles, descriptions, and comments
GitHub Discussions titles, descriptions, and comments
Wikis and secret gists

Secret Scanning会自动在以下场景中检测暴露的凭证：

所有分支的完整Git历史
Issue的描述、评论和标题（已打开和已关闭的）
Pull Request的标题、描述和评论
GitHub Discussions的标题、描述和评论
Wiki和私密Gist

Availability

可用范围

Repository Type	Availability
Public repos	Automatic, free
Private/internal (org-owned)	Requires GitHub Secret Protection on Team/Enterprise Cloud
User-owned	Enterprise Cloud with Enterprise Managed Users

仓库类型	可用情况
公共仓库	自动启用，免费
私有/内部仓库（组织所有）	需要Team/Enterprise Cloud版的GitHub Secret Protection
用户自有仓库	需带Enterprise Managed Users的Enterprise Cloud版

Core Workflow — Enable Secret Scanning

核心流程——启用Secret Scanning

Step 1: Enable Secret Protection

步骤1：启用Secret Protection

Navigate to repository Settings → Advanced Security
Click Enable next to "Secret Protection"
Confirm by clicking Enable Secret Protection

For organizations, use security configurations to enable at scale:

Settings → Advanced Security → Global settings → Security configurations

导航至仓库设置 → 高级安全
点击“Secret Protection”旁的启用
点击启用Secret Protection确认

对于组织，可使用安全配置批量启用：

设置 → 高级安全 → 全局设置 → 安全配置

Step 2: Enable Push Protection

步骤2：启用推送保护

Push protection blocks secrets during the push process — before they reach the repository.

Navigate to repository Settings → Advanced Security
Enable "Push protection" under Secret Protection

Push protection blocks secrets in:

Command line pushes
GitHub UI commits
File uploads
REST API requests
REST API content creation endpoints

推送保护会在推送过程中拦截秘密内容——在它们进入仓库之前。

导航至仓库设置 → 高级安全
在Secret Protection下启用“推送保护”

推送保护会拦截以下场景中的秘密内容：

命令行推送
GitHub UI提交
文件上传
REST API请求
REST API内容创建端点

Step 3: Configure Exclusions (Optional)

步骤3：配置排除规则（可选）

Create

.github/secret_scanning.yml

to auto-close alerts for specific directories:

yaml

paths-ignore:
  - "docs/**"
  - "test/fixtures/**"
  - "**/*.example"

Limits:

Maximum 1,000 entries in
```
paths-ignore
```
File must be under 1 MB
Excluded paths also skip push protection checks

Best practices:

Be as specific as possible with exclusion paths
Add comments explaining why each path is excluded
Review exclusions periodically — remove stale entries
Inform the security team about exclusions

创建

.github/secret_scanning.yml

文件，自动关闭特定目录的告警：

yaml

paths-ignore:
  - "docs/**"
  - "test/fixtures/**"
  - "**/*.example"

限制：

```
paths-ignore
```
中最多可添加1000条条目
文件大小不得超过1MB
被排除的路径也会跳过推送保护检查

最佳实践：

排除路径应尽可能具体
添加注释说明每条路径被排除的原因
定期审查排除规则——移除过时的条目
告知安全团队排除规则的设置

Step 4: Enable Additional Features (Optional)

步骤4：启用附加功能（可选）

Non-provider patterns — detect private keys, connection strings, generic API keys:

Settings → Advanced Security → enable "Scan for non-provider patterns"

AI-powered generic secret detection — uses Copilot to detect unstructured secrets like passwords:

Settings → Advanced Security → enable "Use AI detection"

Validity checks — verify if detected secrets are still active:

Settings → Advanced Security → enable "Validity checks"
GitHub periodically tests detected credentials against provider APIs
Status shown in alert:
```
active
```
,
```
inactive
```
, or
```
unknown
```

Extended metadata checks — additional context about who owns a secret:

Requires validity checks to be enabled first
Helps prioritize remediation and identify responsible teams

非供应商规则——检测私钥、连接字符串、通用API密钥：

设置 → 高级安全 → 启用“扫描非供应商规则”

AI驱动的通用秘密检测——使用Copilot检测非结构化秘密（如密码）：

设置 → 高级安全 → 启用“使用AI检测”

有效性检查——验证检测到的秘密是否仍处于活跃状态：

设置 → 高级安全 → 启用“有效性检查”
GitHub会定期通过供应商API测试检测到的凭证
告警中会显示状态：
```
active
```
（活跃）、
```
inactive
```
（已失效）或
```
unknown
```
（未知）

扩展元数据检查——提供关于秘密所有者的额外上下文：

需先启用有效性检查
有助于优先处理修复工作并识别负责团队

Core Workflow — Resolve Blocked Pushes

核心流程——解决推送被拦截问题

When push protection blocks a push from the command line:

当推送保护在命令行拦截推送时：

Option A: Remove the Secret

选项A：移除秘密内容

If the secret is in the latest commit:

bash

undefined

如果秘密在最新提交中：

bash

undefined

Remove the secret from the file

从文件中移除秘密内容

Then amend the commit

然后修改提交

git commit --amend --all git push


**If the secret is in an earlier commit:**
```bash

git commit --amend --all git push


**如果秘密在较早的提交中：**
```bash

Find the earliest commit containing the secret

找到包含秘密的最早提交

git log

Start interactive rebase before that commit

在该提交之前启动交互式变基

git rebase -i <COMMIT-ID>~1

Change 'pick' to 'edit' for the offending commit

将该提交的'pick'改为'edit'

Remove the secret, then:

移除秘密内容，然后执行：

git add . git commit --amend git rebase --continue git push

undefined

git add . git commit --amend git rebase --continue git push

undefined

Option B: Bypass Push Protection

选项B：绕过推送保护

Visit the URL returned in the push error message (as the same user)
Select a bypass reason:
- It's used in tests — alert created and auto-closed
- It's a false positive — alert created and auto-closed
- I'll fix it later — open alert created
Click Allow me to push this secret
Re-push within 3 hours

访问推送错误信息中返回的URL（使用同一用户）
选择绕过原因：
- 用于测试——创建告警并自动关闭
- 误报——创建告警并自动关闭
- 稍后修复——创建未关闭的告警
点击允许我推送该秘密内容
在3小时内重新推送

Option C: Request Bypass Privileges

选项C：申请绕过权限

If delegated bypass is enabled and you lack bypass privileges:

Visit the URL from the push error
Add a comment explaining why the secret is safe
Click Submit request
Wait for email notification of approval/denial
If approved, push the commit; if denied, remove the secret

For detailed bypass and delegated bypass workflows, search
references/push-protection.md
.

如果已启用委托绕过且你没有绕过权限：

访问推送错误信息中的URL
添加注释说明该秘密内容安全的原因
点击提交申请
等待审批/拒绝的邮件通知
若获批，推送提交；若被拒绝，移除秘密内容

如需详细的绕过和委托绕过流程，请搜索
references/push-protection.md
。

Custom Patterns

自定义规则

Define organization-specific secret patterns using regular expressions.

使用正则表达式定义组织专属的秘密规则。

Quick Setup

快速设置

Settings → Advanced Security → Custom patterns → New pattern
Enter pattern name and regex for secret format
Add a sample test string
Click Save and dry run to test (up to 1,000 results)
Review results for false positives
Click Publish pattern
Optionally enable push protection for the pattern

设置 → 高级安全 → 自定义规则 → 新建规则
输入规则名称和秘密格式的正则表达式
添加测试示例字符串
点击保存并试运行进行测试（最多返回1000条结果）
检查结果是否存在误报
点击发布规则
可选：为该规则启用推送保护

Scopes

适用范围

Custom patterns can be defined at:

Repository level — applies to that repo only
Organization level — applies to all repos with secret scanning enabled
Enterprise level — applies across all organizations

自定义规则可在以下层级定义：

仓库层级——仅适用于该仓库
组织层级——适用于所有启用了Secret Scanning的仓库
企业层级——适用于所有组织

Copilot-Assisted Pattern Generation

Copilot辅助规则生成

Use Copilot secret scanning to generate regex from a text description of the secret type, including optional example strings.

For detailed custom pattern configuration, search
references/custom-patterns.md
.

使用Copilot Secret Scanning根据秘密类型的文本描述生成正则表达式，可包含可选的示例字符串。

如需详细的自定义规则配置，请搜索
references/custom-patterns.md
。

Alert Management

告警管理

Alert Types

告警类型

Type	Description	Visibility
User alerts	Secrets found in repository	Security tab
Push protection alerts	Secrets pushed via bypass	Security tab (filter: `bypassed: true` )
Partner alerts	Secrets reported to provider	Not shown in repo (provider-only)

类型	描述	可见性
用户告警	在仓库中发现的秘密内容	安全标签页
推送保护告警	通过绕过推送的秘密内容	安全标签页（筛选条件： `bypassed: true` ）
合作伙伴告警	上报给供应商的秘密内容	仓库中不可见（仅供应商可见）

Alert Lists

告警列表

Default alerts — supported provider patterns and custom patterns
Generic alerts — non-provider patterns and AI-detected secrets (limited to 5,000 per repo)

默认告警——支持的供应商规则和自定义规则
通用告警——非供应商规则和AI检测到的秘密内容（每个仓库最多5000条）

Remediation Priority

修复优先级

Rotate the credential immediately — this is the critical action
Review the alert for context (location, commit, author)
Check validity status:
```
active
```
(urgent),
```
inactive
```
(lower priority),
```
unknown
```
Remove from Git history if needed (time-intensive, often unnecessary after rotation)

立即轮换凭证——这是最关键的操作
查看告警的上下文信息（位置、提交、作者）
检查有效性状态：
```
active
```
（紧急）、
```
inactive
```
（低优先级）、
```
unknown
```
如有必要，从Git历史中移除（耗时较长，通常轮换凭证后无需执行）

Dismissing Alerts

关闭告警

Dismiss with a documented reason:

False positive — detected string is not a real secret
Revoked — credential has already been revoked
Used in tests — secret is only in test code

For detailed alert types, validity checks, and REST API, search
references/alerts-and-remediation.md
.

关闭告警时需记录原因：

误报——检测到的字符串并非真实秘密
已撤销——凭证已被撤销
用于测试——秘密仅存在于测试代码中

如需详细的告警类型、有效性检查和REST API说明，请搜索
references/alerts-and-remediation.md
。

Reference Files

参考文档

For detailed documentation, load the following reference files as needed:

```
references/push-protection.md
```
— Push protection mechanics, bypass workflow, delegated bypass, user push protection
- Search patterns:
```
bypass
```
  ,
```
delegated
```
  ,
```
bypass request
```
  ,
```
command line
```
  ,
```
REST API
```
  ,
```
user push protection
```
```
references/custom-patterns.md
```
— Custom pattern creation, regex syntax, dry runs, Copilot regex generation, scopes
- Search patterns:
```
custom pattern
```
  ,
```
regex
```
  ,
```
dry run
```
  ,
```
publish
```
  ,
```
organization
```
  ,
```
enterprise
```
  ,
```
Copilot
```
```
references/alerts-and-remediation.md
```
— Alert types, validity checks, extended metadata, generic alerts, secret removal, REST API
- Search patterns:
```
user alert
```
  ,
```
partner alert
```
  ,
```
validity
```
  ,
```
metadata
```
  ,
```
generic
```
  ,
```
remediation
```
  ,
```
git history
```
  ,
```
REST API
```

如需详细文档，可按需加载以下参考文件：

```
references/push-protection.md
```
——推送保护机制、绕过流程、委托绕过、用户推送保护
- 搜索关键词：
```
bypass
```
  、
```
delegated
```
  、
```
bypass request
```
  、
```
command line
```
  、
```
REST API
```
  、
```
user push protection
```
```
references/custom-patterns.md
```
——自定义规则创建、正则表达式语法、试运行、Copilot正则生成、适用范围
- 搜索关键词：
```
custom pattern
```
  、
```
regex
```
  、
```
dry run
```
  、
```
publish
```
  、
```
organization
```
  、
```
enterprise
```
  、
```
Copilot
```
```
references/alerts-and-remediation.md
```
——告警类型、有效性检查、扩展元数据、通用告警、秘密内容移除、REST API
- 搜索关键词：
```
user alert
```
  、
```
partner alert
```
  、
```
validity
```
  、
```
metadata
```
  、
```
generic
```
  、
```
remediation
```
  、
```
git history
```
  、
```
REST API
```