Defining custom patterns for secret scanning

About custom patterns for secret scanning

GitHub performs secret scanning on public and private repositories for secret patterns provided by GitHub and GitHub partners. For more information on the secret scanning partner program, see "Secret scanning partner program."

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 secret scanning patterns in your enterprise, organization, or private repository on GitHub. 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 secret scanning are specified as regular expressions. 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 GitHub.com, navigate to the main page of the repository.

2. Under your repository name, click Settings.

3. In the left sidebar, click Security & analysis.

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

5. Under "Secret scanning", under "Custom patterns", click New 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.

   

7. When you are satisfied with your new custom pattern, click Create 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."

Defining a custom pattern for an organization

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

1. In the top right corner of GitHub.com, click your profile photo, then click Your organizations.

2. Next to the organization, click Settings.

3. In the left sidebar, click Security & analysis.

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

5. Under "Secret scanning", under "Custom patterns", click New 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.

   

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

After your pattern is created, secret scanning 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 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."

1. In the enterprise sidebar, click Policies.

2. Under Policies, click "Advanced Security."

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

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

5. 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.

   

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

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

Editing a custom pattern

When you save a change to a custom pattern, this closes all the secret scanning 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.
   • For a repository or organization, display the "Security & analysis" settings for the repository or organization where the custom pattern was created. For more information, see "Defining a custom pattern for a repository" or "Defining a custom pattern for an organization" above.
   • For an enterprise, under "Policies" display the "Advanced Security" area, and then click Security features. For more information, see "Defining a custom pattern for an enterprise account" above.
2. Under "Secret scanning", 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.

   • For a repository or organization, display the "Security & analysis" settings for the repository or organization where the custom pattern was created. For more information, see "Defining a custom pattern for a repository" or "Defining a custom pattern for an organization" above.
   • For an enterprise, under "Policies" display the "Advanced Security" area, and then click Security features. For more information, see "Defining a custom pattern for an enterprise account" above.

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

3. Review the confirmation, and select a method for dealing with any open alerts relating to the custom pattern.

4. Click Yes, delete this pattern.