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

可以通过生成一个或多个正则表达式来定义自己的自定义模式，以扩展 secret scanning 的功能。

谁可以使用此功能？

具有管理员角色的存储库所有者、组织所有者、安全管理员、企业管理员和用户

secret scanning 的自定义模式可用于以下存储库：

本文内容

关于 secret scanning 的自定义模式

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

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

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

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

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

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

正则表达式可以手动输入，也可以使用 Copilot 机密扫描 的 正则表达式生成器 生成。

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

可以通过 UI 中的“More options ”部分手动编写正则表达式****。

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

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

使用 Copilot 机密扫描 的 正则表达式生成器

Copilot 机密扫描 的 正则表达式生成器 使用了一个生成式 AI 模型，你可以输入你想要检测的模式类型的文本描述，包括应该被检测到的可选示例字符串。 模型最多返回三个正则表达式供查看。有关更多信息，请参阅 使用 Copilot 机密扫描负责地生成正则表达式 和 使用 Copilot 机密扫描为自定义模式生成正则表达式。

定义仓库的自定义模式

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

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

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

    存储库标头的屏幕截图，其中显示了选项卡。 “设置”选项卡以深橙色边框突出显示。

  3. 在边栏的“Security”部分中，单击“Code security”****。

  4. 在“Code security”下，找到“GitHub Advanced Security”。

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

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

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

    填充自定义 secret scanning 模式窗体的屏幕截图。

  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 来为组织中的所有存储库启用 secret scanning。 如需了解更多信息，请参阅 关于批量启用安全功能。

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

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

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

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

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

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

    填充自定义 secret scanning 模式窗体的屏幕截图。

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

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

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

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

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

    显示试运行结果的屏幕截图。

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

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

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

    Note

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

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

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

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

Note

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

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

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

  3. 在页面左侧的企业帐户边栏中，单击 “策略”。 1. 在 "Policies" 下，单击 Code security********。

  4. 在“Code security”下，单击“Security features”****。

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

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

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

    填充自定义 secret scanning 模式窗体的屏幕截图。

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

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

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

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

    显示试运行结果的屏幕截图。

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

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

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

    Note

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

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

其他阅读材料