Skip to main content

Defining custom patterns for secret scanning

You can define custom patterns for secret scanning in organizations and private repositories.

Secret scanning is available for organization-owned repositories in GitHub Enterprise Server if your enterprise has a license for GitHub Advanced Security. For more information, see "GitHub's products."

Note: Custom patterns for secret scanning is currently in beta and is subject to change.

About custom patterns for secret scanning

GitHub performs secret scanning on repositories for secret patterns provided by GitHub and GitHub partners. To find out about our partner program, see "Secret scanning partner program" in the GitHub Enterprise Cloud documentation For details of the supported secrets and service providers, see "Secret scanning partners."

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

Note: During the beta, there are some limitations when using custom patterns for secret scanning:

  • There is no dry-run functionality.
  • You cannot edit custom patterns after they're created. To change a pattern, you must delete it and recreate it.
  • There is no API for creating, editing, or deleting custom patterns. However, results for custom patterns are returned in the secret scanning alerts API.

Regular expression syntax for custom patterns

Custom patterns for secret scanning 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.

Secret scanning 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 secret scanning is enabled on your repository. For more information, see "Configuring secret scanning for your repositories."

  1. On your GitHub Enterprise Server instance, navigate to the main page of the repository.

  2. Under your repository name, click Settings. Repository settings button

  3. In the left sidebar, click Security & analysis. "Security & analysis" tab in repository settings

  4. Under "Configure security and analysis features", find "GitHub Advanced Security."

  5. Under "Secret scanning", under "Custom patterns", click New custom pattern.

  6. Enter the details for your new custom pattern:

    1. You must at least provide the name for your pattern, and a regular expression for the format of your secret pattern.
    2. You can click More options to provide other surrounding content or additional match requirements for the secret format.
    3. Provide a sample test string to make sure your configuration is matching the patterns you expect.

    Create a custom secret scanning pattern form

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

After your pattern is created, secret scanning scans for any secrets in your entire Git history on all branches present in your GitHub repository. For more information on viewing secret scanning alerts, see "Managing alerts from secret scanning."

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 secret scanning for the repositories that you want to scan in your organization. To enable secret scanning on all 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 secret scanning alerts.

  1. In the top right corner of GitHub Enterprise Server, click your profile photo, then click Your organizations. Your organizations in the profile menu

  2. Next to the organization, click Settings. The settings button

  3. In the left sidebar, click Security & analysis. "Security & analysis" tab in organization settings

  4. Under "Configure security and analysis features", find "GitHub Advanced Security."

  5. Under "Secret scanning", under "Custom patterns", click New custom pattern.

  6. Enter the details for your new custom pattern:

    1. You must at least provide the name for your pattern, and a regular expression for the format of your secret pattern.
    2. You can click More options to provide other surrounding content or additional match requirements for the secret format.
    3. Provide a sample test string to make sure your configuration is matching the patterns you expect.

    Create a custom secret scanning pattern form

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

After your pattern is created, secret scanning scans for any secrets in 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 secret scanning alerts, see "Managing alerts from secret scanning."

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 secret scanning alerts.

  1. In the top-right corner of GitHub Enterprise Server, click your profile photo, then click Enterprise settings. "Enterprise settings" in drop-down menu for profile photo on GitHub Enterprise Server

  2. In the enterprise sidebar, click Policies. Policies tab in the enterprise account sidebar

  3. Under Policies, click "Advanced Security." "Advanced Security" policies in sidebar

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

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

  6. Enter the details for your new custom pattern:

    1. You must at least provide the name for your pattern, and a regular expression for the format of your secret pattern.
    2. You can click More options to provide other surrounding content or additional match requirements for the secret format.
    3. Provide a sample test string to make sure your configuration is matching the patterns you expect.

    Create a custom secret scanning pattern form

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

After your pattern is created, secret scanning scans for any secrets in 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 secret scanning alerts, see "Managing alerts from secret scanning."

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.

  2. To the right of the custom pattern you want to remove, click Remove.

  3. Review the confirmation, and click Remove custom pattern.