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

本文内容

你可以扩展 secret scanning 以检测默认模式之外的机密。

合作伙伴的机密扫描警报 在 GitHub.com 上的公共存储库和公共 npm 包中自动运行，以向服务提供商通知泄漏的机密情况。

用户的机密扫描警报 在所有公共存储库上免费提供。 使用 GitHub Enterprise Cloud 且拥有 GitHub Advanced Security 许可证的组织也可以在其专用存储库和内部存储库上启用 用户的机密扫描警报。

如果你的企业拥有 GitHub Advanced Security 的许可证，则 有关详细信息，请参阅 “关于机密扫描”和“关于 GitHub 高级安全性”。

有关如何免费试用 GitHub Advanced Security 的信息，请参阅“安装 GitHub Advanced Security 试用版”。

关于 secret scanning 的自定义模式

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

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

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

自定义模式的正则表达式语法

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

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

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

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

定义仓库的自定义模式

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

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

  2. 在存储库名称下，单击 “设置”。 如果看不到“设置”选项卡，请选择“”下拉菜单，然后单击“设置”********。 存储库标头的屏幕截图，其中显示了选项卡。 “设置”选项卡以深橙色边框突出显示。

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

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

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

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

    1. 在“模式名称”字段中，键入模式的名称。
    2. 在“机密格式”字段中，键入机密模式格式的正则表达式。
    3. 可以单击“更多选项”来提供密钥格式的其他周围内容或额外匹配要求。
    4. 提供一个示例测试字符串，用于确保配置与预期模式匹配。

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

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

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

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

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

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

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

    有关推送保护的详细信息，请参阅“存储库和组织的推送保护”。

模式创建后，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。 要启用组织中所有存储库上的 secret scanning，请参阅“管理组织的安全和分析设置”。

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

    @octocat 的个人资料图片下的下拉菜单的屏幕截图。 “你的组织”以深橙色标出。

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

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

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

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

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

    1. 在“模式名称”字段中，键入模式的名称。
    2. 在“机密格式”字段中，键入机密模式格式的正则表达式。
    3. 可以单击“更多选项”来提供密钥格式的其他周围内容或额外匹配要求。
    4. 提供一个示例测试字符串，用于确保配置与预期模式匹配。

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

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

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

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

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

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

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

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

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

    注意：

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

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

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

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

注意：

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

  1. 在 GitHub.com 的右上角，单击你的个人资料照片，然后单击“你的企业”。

  2. 在企业列表中，单击您想要查看的企业。

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

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

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

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

    1. 在“模式名称”字段中，键入模式的名称。
    2. 在“机密格式”字段中，键入机密模式格式的正则表达式。
    3. 可以单击“更多选项”来提供密钥格式的其他周围内容或额外匹配要求。
    4. 提供一个示例测试字符串，用于确保配置与预期模式匹配。

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

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

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

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

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

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

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

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

    注意：

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

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

编辑自定义模式

将更改保存到自定义模式时，这将关闭使用该模式的先前版本创建的所有 机密扫描警报 警报。

  1. 导航到创建自定义模式的位置。 可以在存储库、组织或企业帐户中创建自定义模式。

  2. 在“Secret scanning”下要编辑的自定义模式的右侧，单击“”。

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

  4. 查看并测试更改后，单击“发布更改”。

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

    注意：

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

    自定义模式页的屏幕截图，其中突出显示用于启用推送保护的按钮。

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

    自定义模式页面的屏幕截图，其中“禁用推送保护”按钮以深橙色边框突出显示。

删除自定义模式

  1. 导航到创建自定义模式的位置。 可以在存储库、组织或企业帐户中创建自定义模式。
  2. 在要删除的自定义模式的右侧，单击“”。
  3. 查看确认，并选择一种方法来处理与自定义模式相关的任何打开的警报。
  4. 单击“是，删除此模式”。

自定义模式的指标

组织所有者和具有管理员权限的人员可以查看自定义模式活动的概述。 概述包括过去 30 天内自定义模式的警报和推送保护活动。

注意：自定义模式的指标为公共 beta 版，可能随时会进行更改。

查看自定义模式的指标

  1. 导航到创建自定义模式的位置。 可以在存储库、组织或企业帐户中创建自定义模式。
  2. 在“Secret scanning”下，单击要查看的自定义模式。

指标显示在自定义模式的名称下。