Skip to main content

Defining custom patterns for secret scanning

You can define custom patterns for 秘密扫描 in organizations and private repositories.

秘密扫描 is included in GitHub Enterprise Cloud for public repositories. To use 秘密扫描 in private repositories owned by organizations, you must have a license for GitHub Advanced Security. For more information, see "GitHub's products."

About custom patterns for 秘密扫描

GitHub performs 秘密扫描 on public and private repositories for secret patterns provided by GitHub and GitHub partners. To find out about our partner program, see "秘密扫描 partner program." For details of the supported secrets and service providers, see "秘密扫描 partners."

However, there can be situations where you want to scan for other secret patterns in your private repositories. For example, you might have a secret pattern that is internal to your organization. For these situations, you can define custom 秘密扫描 patterns in your enterprise, organization, or private repository on GitHub Enterprise Cloud. You can define up to 500 custom patterns for each organization or enterprise account, and up to 100 custom patterns per private repository.

Regular expression syntax for custom patterns

Custom patterns for 秘密扫描 are specified as one or more regular expressions.

  • Secret format: an expression that describes the format of the secret itself.
  • Before secret: an expression that describes the characters that come before the secret. By default, this is set to \A|[^0-9A-Za-z] which means that the secret must be at the start of a line or be preceded by a non-alphanumeric character.
  • After secret: an expression that describes the characters that come after the secret. By default, this is set to \z|[^0-9A-Za-z] which means that the secret must be followed by a new line or a non-alphanumeric character.
  • Additional match requirements: one or more optional expressions that the secret itself must or must not match.

For simple tokens you will usually only need to specify a secret format. The other fields provide flexibility so that you can specify more complex secrets without creating complex regular expressions. For an example of a custom pattern, see "Example of a custom pattern specified using additional requirements" below.

秘密扫描 uses the Hyperscan library and only supports Hyperscan regex constructs, which are a subset of PCRE syntax. Hyperscan option modifiers are not supported. For more information on Hyperscan pattern constructs, see "Pattern support" in the Hyperscan documentation.

Defining a custom pattern for a repository

Before defining a custom pattern, you must ensure that 秘密扫描 is enabled on your repository. For more information, see "Configuring 秘密扫描 for your repositories."

  1. 在 GitHub.com 上,导航到仓库的主页面。

  2. 在仓库名称下,单击 Settings(设置)仓库设置按钮

  3. 在左侧边栏中,单击 Security & analysis(安全和分析)仓库设置中的"Security & analysis(安全和分析)"选项卡

  4. 在“Configure security and analysis features(配置安全和分析功能)”下,查找“GitHub Advanced Security”。

  5. Under "秘密扫描", under "Custom patterns", click New pattern.

  6. 输入新自定义模式的详细信息:

    1. 您至少必须提供模式的名称,以及秘密模式格式的正则表达式。
    2. 您可以点击更多选项 来提供密钥格式的其他周围内容或额外匹配要求。
    3. Provide a sample test string to make sure your configuration is matching the patterns you expect.

    创建自定义 秘密扫描 模式表

  7. When you are satisfied with your new custom pattern, click Create pattern.

After your pattern is created, 秘密扫描 将在 GitHub 仓库中存在的所有分支上扫描整个 Git 历史记录的任何密钥。 For more information on viewing 秘密扫描 alerts, see "Managing alerts from 秘密扫描."

Example of a custom pattern specified using additional requirements

A company has an internal token with five characteristics. They use the different fields to specify how to identify tokens as follows:

CharacteristicField and regular expression
Length between 5 and 10 charactersSecret format: [$#%@AA-Za-z0-9]{5,10}
Does not end in a .After secret: [^\.]
Contains numbers and uppercase lettersAdditional requirements: secret must match [A-Z] and [0-9]
Does not include more than one lowercase letter in a rowAdditional requirements: secret must not match [a-z]{2,}
Contains one of $%@!Additional requirements: secret must match [$%@!]

These tokens would match the custom pattern described above:

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

These strings would not match the custom pattern described above:

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

Defining a custom pattern for an organization

Before defining a custom pattern, you must ensure that you enable 秘密扫描 for the private repositories that you want to scan in your organization. To enable 秘密扫描 on all private repositories in your organization, see "Managing security and analysis settings for your organization."

Note: As there is no dry-run functionality, we recommend that you test your custom patterns in a repository before defining them for your entire organization. That way, you can avoid creating excess false-positive 秘密扫描 alerts.

  1. In the top right corner of GitHub.com, click your profile photo, then click Your organizations. 个人资料菜单中的组织

  2. 在组织旁边,单击 Settings(设置)设置按钮

  3. 在左侧边栏中,单击 Security & analysis(安全和分析)组织设置中的"Security & analysis(安全和分析)"选项卡

  4. 在“Configure security and analysis features(配置安全和分析功能)”下,查找“GitHub Advanced Security”。

  5. Under "秘密扫描", under "Custom patterns", click New pattern.

  6. 输入新自定义模式的详细信息:

    1. 您至少必须提供模式的名称,以及秘密模式格式的正则表达式。
    2. 您可以点击更多选项 来提供密钥格式的其他周围内容或额外匹配要求。
    3. Provide a sample test string to make sure your configuration is matching the patterns you expect.

    创建自定义 秘密扫描 模式表

  7. When you are satisfied with your new custom pattern, click Create pattern.

After your pattern is created, 秘密扫描 scans for any secrets in private repositories in your organization, including their entire Git history on all branches. Organization owners and repository administrators will be alerted to any secrets found, and can review the alert in the repository where the secret is found. For more information on viewing 秘密扫描 alerts, see "Managing alerts from 秘密扫描."

Defining a custom pattern for an enterprise account

Before defining a custom pattern, you must ensure that you enable secret scanning for your enterprise account. For more information, see "Enabling GitHub Advanced Security for your enterprise."

Note: As there is no dry-run functionality, we recommend that you test your custom patterns in a repository before defining them for your entire enterprise. That way, you can avoid creating excess false-positive 秘密扫描 alerts.

  1. 在 GitHub.com 的右上角,单击您的个人资料照片,然后单击 Your enterprises(您的企业)GitHub Enterprise Cloud 上个人资料照片下拉菜单中的"Your enterprises(您的企业)"

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

  3. 在企业账户侧边栏中,单击 Policies(政策)企业帐户侧边栏中的 Policies(政策)选项卡

  4. 策略下,单击“Advanced Security(高级安全性)”。 侧边栏中的"高级安全性"策略

  5. Under "GitHub Advanced Security", click the Security features tab.

  6. Under "Secret scanning custom patterns", click New pattern.

  7. 输入新自定义模式的详细信息:

    1. 您至少必须提供模式的名称,以及秘密模式格式的正则表达式。
    2. 您可以点击更多选项 来提供密钥格式的其他周围内容或额外匹配要求。
    3. Provide a sample test string to make sure your configuration is matching the patterns you expect.

    创建自定义 秘密扫描 模式表

  8. When you are satisfied with your new custom pattern, click Create pattern.

After your pattern is created, 秘密扫描 scans for any secrets in private repositories within your enterprise's organizations with GitHub Advanced Security enabled, including their entire Git history on all branches. Organization owners and repository administrators will be alerted to any secrets found, and can review the alert in the repository where the secret is found. For more information on viewing 秘密扫描 alerts, see "Managing alerts from 秘密扫描."

Editing a custom pattern

When you save a change to a custom pattern, this closes all the 秘密扫描 alerts that were created using the previous version of the pattern.

  1. Navigate to where the custom pattern was created. A custom pattern can be created in a repository, organization, or enterprise account.
  2. Under "秘密扫描", to the right of the custom pattern you want to edit, click .
  3. When you have reviewed and tested your changes, click Save changes.

Removing a custom pattern

  1. Navigate to where the custom pattern was created. A custom pattern can be created in a repository, organization, or enterprise account.