为机密扫描定义自定义模式

关于 secret scanning 的自定义模式

您可以定义自定义模式来标识 secret scanning 支持的默认模式未检测到的机密。 例如，您可能有一个属于您组织内部的密钥模式。 有关支持的机密和服务提供商的详细信息，请参阅“支持的机密扫描模式”。

您可以为企业、组织或存储库定义自定义模式。 Secret scanning支持每个组织或企业帐户最多 500 个自定义模式，每个存储库最多 100 个自定义模式。

还可以为自定义模式启用推送保护。 有关推送保护的详细信息，请参阅“关于推送保护”。

关于对自定义模式使用正则表达式

你可以将 secret scanning 的自定义模式指定为一个或多个正则表达式。

Secret scanning 使用 Hyperscan 库，只支持 Hyperscan 正则表达式构造（PCRE 语法的子集）。 不支持 Hyperscan 选项修饰符。 有关 Hyperscan 模式构造的详细信息，请参阅 Hyperscan 文档中的“模式支持”。

可以手动输入或使用正则表达式生成器生成正则表达式。

用于手动定义自定义模式的正则表达式语法

UI 中的“更多选项 **** 部分可帮助你手动编写正则表达式。

• 机密格式： 描述机密本身格式的表达式。
• 机密之前： 描述机密之前的字符的表达式。 默认情况下，此值设置为 \A|[^0-9A-Za-z]，这意味着机密必须位于行首或前面有非字母数字字符。
• 机密之后： 描述机密后面的字符的表达式。 默认情况下，此值设置为 \z|[^0-9A-Za-z]，这意味着机密后面必须跟有新行或非字母数字字符。
• 其他匹配要求： 机密本身必须或不得匹配的一个或多个可选表达式。

对于简单令牌，通常只需指定机密格式。 其他字段提供了灵活性，以便您可以指定更复杂的机密，而无需创建复杂的正则表达式。 有关自定义模式的示例，请参阅下面的“使用附加要求指定的自定义模式示例”。

使用正则表达式生成器

生成器使用生成式 AI 模型，你可以在其中输入要检测的模式类型的文本说明，包括要检测的可选示例字符串。 模型最多返回三个正则表达式供查看。有关更多信息，请参阅“负责任使用 AI 以定义正则表达式”和“使用 AI 为自定义模式生成正则表达式”。

定义仓库的自定义模式

在定义自定义模式之前，您必须确保仓库上启用了 secret scanning。 有关详细信息，请参阅“为存储库启用机密扫描”。

1. 在 GitHub 上，导航到存储库的主页面。

2. 在存储库名称下，单击 “设置”。 如果看不到“设置”选项卡，请选择“”下拉菜单，然后单击“设置”。

   

3. 在边栏的“安全性”部分中，单击“ 代码安全性和分析”。

4. 在“代码安全性和分析”下，查找“GitHub Advanced Security”。

5. 在“Secret scanning”下的“自定义模式”下，单击“新建模式”。

6. 输入新自定义模式的详细信息。 您至少必须提供模式的名称，以及秘密模式格式的正则表达式。

   1. 在“模式名称”字段中，键入模式的名称。
   2. 在“机密格式”字段中，键入机密模式格式的正则表达式。或者，可以使用生成器为你生成正则表达式。 有关详细信息，请参阅“使用 AI 为自定义模式生成正则表达式”。
   3. 可以单击“更多选项”来提供密钥格式的其他周围内容或额外匹配要求。
   4. 提供一个示例测试字符串，用于确保配置与预期模式匹配。
   

7. 准备好测试新的自定义模式时，若要识别存储库中的匹配项而不创建警报，请单击“保存并试运行”。

8. 试运行完成后，你将看到结果示例（最多 1000 个）。 查看结果并确定任何误报结果。

   

9. 编辑新的自定义模式以修复结果的任何问题，然后测试更改，单击“保存并试运行”。

10. 如果对新的自定义模式感到满意，请单击“发布模式”。

11. 根据需要，若要为自定义模式启用推送保护，请单击“启用”。

    Note

    在试运行成功并发布模式之前，“启用”按钮不可用。

    有关推送保护的详细信息，请参阅“关于推送保护”。

模式创建后，secret scanning 将在 GitHub 仓库中存在的所有分支上扫描整个 Git 历史记录的任何密钥。 有关查看 机密扫描警报 警报的详细信息，请参阅“管理来自机密扫描的警报”。

使用其他要求指定的自定义模式示例

公司具有具有五个特征的内部令牌。 它们使用不同的字段来指定如何标识令牌，如下所示：

特征	字段和正则表达式
长度介于 5 到 10 个字符之间	机密格式：[$#%@AA-Za-z0-9]{5,10}
不以 . 结尾	机密之后：[^\.]
包含数字和大写字母	其他要求：机密必须匹配 [A-Z] 和 [0-9]
一行中不包含多个小写字母	其他要求：机密不得匹配 [a-z]{2,}
包含 $%@! 之一	其他要求：机密必须匹配 [$%@!]

这些令牌将与上述自定义模式匹配：

a9@AAfT!         # Secret string match: a9@AAfT
ee95GG@ZA942@aa  # Secret string match: @ZA942@a
a9@AA!ee9        # Secret string match: a9@AA

这些字符串与上述自定义模式不匹配：

a9@AA.!
a@AAAAA
aa9@AA!ee9
aAAAe9

定义组织的自定义模式

在定义自定义模式之前，您必须确保在组织中为要扫描的仓库启用 secret scanning。 可以使用 security configurations 为使用 GitHub-recommended security configuration 的组织中的所有存储库启用 secret scanning，或者可以创建 custom security configuration。 有关详细信息，请参阅“在组织中应用 GitHub 建议的安全配置”和“Creating a custom security configuration”。

1. 在 GitHub 的右上角，选择个人资料照片，然后单击 “你的组织”。

2. 在组织旁边，单击“设置”。

3. 在边栏的“安全”部分中，选择****“代码安全”下拉菜单，然后单击 Global settings。

4. 在“自定义模式”下，单击“新建模式”。

5. 输入新自定义模式的详细信息。 您至少必须提供模式的名称，以及秘密模式格式的正则表达式。

   1. 在“模式名称”字段中，键入模式的名称。
   2. 在“机密格式”字段中，键入机密模式格式的正则表达式。或者，可以使用生成器为你生成正则表达式。 有关详细信息，请参阅“使用 AI 为自定义模式生成正则表达式”。
   3. 可以单击“更多选项”来提供密钥格式的其他周围内容或额外匹配要求。
   4. 提供一个示例测试字符串，用于确保配置与预期模式匹配。
   

6. 准备好测试新的自定义模式时，若要在不创建警报的情况下识别所选存储库中的匹配项，请单击“保存并试运行”。

7. 选择要在其中执行试运行的存储库。

   • 若要在整个组织中执行试运行，请选择“组织中的所有存储库”。
   • 若要指定要在其中执行试运行的存储库，请选择“所选存储库”，然后搜索并选择最多 10 个存储库。

8. 准备好测试新的自定义模式后，请单击“运行”。

9. 试运行完成后，你将看到结果示例（最多 1000 个）。 查看结果并确定任何误报结果。

   

10. 编辑新的自定义模式以修复结果的任何问题，然后测试更改，单击“保存并试运行”。

11. 如果对新的自定义模式感到满意，请单击“发布模式”。

12. 根据需要，若要为自定义模式启用推送保护，请单击“启用”。 有关详细信息，请参阅“关于推送保护”。

    Note

    • 启用推送保护的选项仅对已发布的模式可见。
    • 自定义模式的推送保护仅适用于组织中启用了 secret scanning 作为推送保护的存储库。 有关详细信息，请参阅“关于推送保护”。
    • 为常见的自定义模式启用推送保护可能会对参与者造成干扰。

创建模式后，secret scanning 扫描组织的仓库中的任何密钥，包括其所有分支的整个 Git 历史记录。 组织所有者和仓库管理员将会收到发现的任何密钥警报通知，并且可以审查发现密钥的仓库中的警报。 有关查看 机密扫描警报 的详细信息，请参阅“管理来自机密扫描的警报”。

为企业帐户定义自定义模式

在定义自定义模式之前，必须确保为企业帐户启用机密扫描。 有关详细信息，请参阅“为企业启用 GitHub Advanced Security”。

• 在企业级别，只有自定义模式的创建者才能编辑模式，并在试运行中使用它。
• 只能对具有管理访问权限的存储库执行试运行。 如果企业所有者想要对组织中的任何存储库执行试运行，则必须分配有组织所有者角色才可以。 有关详细信息，请参阅“管理企业拥有的组织中的角色”。

1. 在 GitHub 的右上角，单击你的个人资料照片。

2. 根据环境，单击“你的企业”，或单击“你的企业”，然后单击要查看的企业********。

3. 在页面左侧的企业帐户边栏中，单击 “策略”。 1. 在 “策略”下，单击“代码安全性和分析”。

4. 在“代码安全和分析”下，单击“安全功能”。

5. 在“机密扫描自定义模式”下，单击“新建模式”。

6. 输入新自定义模式的详细信息。 您至少必须提供模式的名称，以及秘密模式格式的正则表达式。

   1. 在“模式名称”字段中，键入模式的名称。
   2. 在“机密格式”字段中，键入机密模式格式的正则表达式。或者，可以使用生成器为你生成正则表达式。 有关详细信息，请参阅“使用 AI 为自定义模式生成正则表达式”。
   3. 可以单击“更多选项”来提供密钥格式的其他周围内容或额外匹配要求。
   4. 提供一个示例测试字符串，用于确保配置与预期模式匹配。
   

7. 准备好测试新的自定义模式时，若要识别企业中的匹配项而不创建警报，请单击“保存并试运行”。

8. 搜索并选择最多 10 个要在其中执行试运行的存储库。

9. 准备好测试新的自定义模式后，请单击“运行”。

10. 试运行完成后，你将看到结果示例（最多 1000 个）。 查看结果并确定任何误报结果。

    

11. 编辑新的自定义模式以修复结果的任何问题，然后测试更改，单击“保存并试运行”。

12. 如果对新的自定义模式感到满意，请单击“发布模式”。

13. 根据需要，若要为自定义模式启用推送保护，请单击“启用”。 有关详细信息，请参阅“关于推送保护”。

    Note

    • 若要为自定义模式启用推送保护，需要在企业级启用 secret scanning 作为推送保护。 有关详细信息，请参阅“关于推送保护”。
    • 为常见的自定义模式启用推送保护可能会对参与者造成干扰。

创建模式后，secret scanning 扫描企业组织内存储库中的任何机密，并启用 GitHub Advanced Security，包括其所有分支上的整个 Git 历史记录。 组织所有者和仓库管理员将会收到发现的任何密钥警报通知，并且可以审查发现密钥的仓库中的警报。 有关查看 机密扫描警报 的详细信息，请参阅“管理来自机密扫描的警报”。

其他阅读材料

• “管理自定义模式”
• “自定义模式的指标”