GitHub Secret Scanning

What Is GitHub Secret Scanning?

Most GitHub projects use tokens or private keys to authenticate communication between project code and external services. Service providers often issue secrets such as private keys or tokens to control access to a project. 

However, when you add secrets to a Git repository, this creates a serious security risk, because anyone with read access to your repository can use these secrets to access privileged external services. Secrets must be stored in a dedicated secure location outside your project’s repository.

GitHub secret scanning is a set of security features that helps secure code and keep secrets safe across organizations and repositories. Some of these security features are available on all plans, while businesses using GitHub Advanced Security can take advantage of additional features. All public repositories on GitHub also have GitHub Advanced Security enabled.

GitHub secret scanning involves screening and retrieving secrets from the full Git history of every branch in a GitHub repository.

This is part of our series of articles about container security.

In this article:

• 5 GitHub Secret Scanning Capabilities
• Secret Scanning Patterns
• Custom Pattern Definitions
• Alerting
• Push Protection
• Reviews and Remediation
• Quick Tutorial: Configuring Secret Scanning for Your Repositories
• Manage Secret Scanning Alerts
• GitHub Secret Scanning Best Practices
• Prioritize New Secrets
• Address the Most Critical Committed Secrets
• Expand Your Program to Cover More Secrets and Patterns

5 GitHub Secret Scanning Capabilities

Here are some of the core features for secret scanning in GitHub.

1. Secret Scanning Patterns

There are two unique sets of patterns in GitHub secret scanning:

• Partner pattern scans—run automatically on any public repository. The system reports any string matching a pattern provided by a secret scanning partner directly to that partner.
• Advanced security scans—you can set up more advanced scans for a repository belonging to an organization using GitHub Enterprise Cloud with a GitHub Advanced Security license. The system generates alerts for strings that match a pattern defined by secret search partners, other service providers, or the organization. The alerts appear in the repository’s security tab. It also reports strings in public repositories that match a partner pattern to that partner.

GitHub automatically performs partner pattern scans on all public repositories to find secrets in any product. Advanced security scans are available in repositories owned by an organization that uses GitHub Enterprise Cloud and has an Advanced Security license.

Whenever you modify a public repository or set a repository as public, GitHub searches your code for secrets matching partner patterns. When a scan identifies a potential secret, GitHub notifies the service provider that issued the secret. The service provider should validate the string and decide whether to revoke the secret, issue a new one, or contact the client. Their actions depend on the risks to themselves and users.

2. Custom Pattern Definitions

You can set definitions for custom patterns to detect secrets not covered by default secret scanning patterns. For instance, your organization might have a unique, internal secret pattern. You can define a custom pattern for your company, repository, or GitHub organization. Secret scanning in GitHub can cover up to 500 patterns per organization or 100 for each repository.

3. Alerting

Alerts are available to view all secrets in a repository.

When the system detects a new secret, GitHub Enterprise Cloud alerts all users with access to the repository security notifications based on their alerting settings. You will receive email notifications if you monitor a repository, enable security alerts for repository activity, or are the owner of the commits containing detected secrets. 

4. Push Protection

Secret scanning in GitHub allows you to implement push protection to stop developers from pushing supported secrets to your repositories or organization.

With push protection enabled, the system checks for pushes of trusted secrets (secrets identified as having a low false-positive rate). It lists the secrets discovered, allowing authors to view and delete them or specify permission to push them as needed.

5. Reviews and Remediation

Secret scans return results containing sensitive information that should only be available to the necessary teams and stakeholders. You can enforce a security boundary by assigning predefined roles to teams and members within your organization. Even with only five predefined roles (and additional custom roles), assigning multiple individuals to the same role in multiple repositories can be tedious. 

Therefore, GitHub offers the security manager role you can assign across the organization. Any team member assigned this role has read access to every repository in the organization and management permissions to access and configure security alerts.

Related content: Read our guide to Docker secrets

Quick Tutorial: Configuring Secret Scanning for Your Repositories

Enabling secret scanning helps provide a higher level of security on any repository owned by your organization. When enabled, secret scanning will scan the entire Git history for secrets across every branch of your GitHub repositories.

1. Go to the repository’s home page on GitHub.com.
2. Click Settings under the repository name.
3. Click Code Security and Analysis in the Security section on the sidebar.
4. If you have not already enabled Advanced Security for your repository, click Enable next to the GitHub Advanced Security label.

5. Evaluate the impact of having advanced security enabled for each repository. 
6. Select Enable GitHub Advanced Security for the given repository.
7. With advanced security enabled, your organization’s settings can automatically enable secret scanning for the specified repository. Even if there is an Enable button next to the Secret Scanning option, you must click Enable to allow secret scanning. The Disable button will be present if you’ve already enabled secret scanning.

Manage Secret Scanning Alerts 

Use the following steps to view and close notifications for secrets present in a repository:

1. Go to the repository’s home page on GitHub.com.
2. Select Security under the repository’s name.
3. Select Secret Scanning Alerts in the sidebar to the left.

4. Select the alert you wish to view under Secret Scanning.

If a secret is committed to the repository, you must treat the secret as compromised. 

GitHub Secret Scanning Best Practices

Use the following best practices to ensure effective secret scanning in GitHub.

Prioritize New Secrets

Focusing on identifying recently submitted credentials helps keep the secret count low. Before revoking current secrets, you should ensure developers don’t keep pushing new credentials.

Here is an example of how to address newly committed secrets:

1. Use a webhook to get new secret notifications to the right team as soon as possible.
2. Follow up on alerts by creating an advanced remediation process for every secret type. You can contact developers who submitted secrets and highlight the dangers of this practice, ensuring they revoke and update the compromised secrets. 
3. Provide training documents to distribute to developers who commit secrets. Training is usually enough to stop developers from committing secrets.

You should repeat this process for newly detected secrets, encouraging all team members to take responsibility for secret management.

Address the Most Critical Committed Secrets

Once you’ve set up your monitoring, alerting, and remediation processes to deal with newly exposed secrets, you can start addressing older secrets (committed before deploying GitHub Advanced Security. Prioritize the most critical secret types.

After determining the relevant secrets, you can:

1. Define and document the remediation process for each secret type.
2. Aggregate information about each secret type and identify who needs to know the new process. You might want to collect information about the repository, organization, secret type and value, and repository admins. 
3. After gathering information about the exposed secrets, establish a plan to communicate the new process to users who manage each affected repository. 

Expand Your Program to Cover More Secrets and Patterns 

At this stage, you can move beyond the five basic types of secrets to a complete list that includes custom secrets. This stage should also focus more on training. You can address the previously identified custom patterns in the expanded program. Allow team members to submit new patterns. Remediate these patterns by repeating the above process.

Secret scanning supports push protection for trusted secrets; you can enable this feature to block pushes. As you expand your remediation strategy to cover more secret types, create and share the training documents with all GitHub developers in the organization. At this point, you can start adopting a more proactive approach to secret scanning and remediation.