Phase 6: Rollout and scale secret scanning

You can enable secret scanning for individual repositories or for all repositories in an organization or enterprise. For more information, see "Managing security and analysis settings for your repository", "Managing security and analysis settings for your organization", or "Managing GitHub Advanced Security features for your enterprise."

This article explains a high-level process focusing on enabling secret scanning for all repositories in an organization. The principles described in this article can still be applied even if you take a more staggered approach of enabling secret scanning for individual repositories.

1. Focus on newly committed secrets

When you enable secret scanning, you should focus on remediating any newly committed credentials detected by secret scanning. If you focus on cleaning up committed credentials, developers could continue to accidentally push new credentials, which means your total secret count will stay around the same level, not decrease as intended. This is why it is essential to stop new credentials being leaked before focusing on revoking any current secrets.

There are a few approaches for tackling newly committed credentials, but one example approach would be:

1. Notify: Use webhooks to ensure that any new secret alerts are seen by the right teams as quickly as possible. A webhook fires when a secret alert is either created, resolved, or reopened. You can then parse the webhook payload, and integrate it into any tools you and your team use such Slack, Teams, Splunk, or email. For more information, see "About webhooks" and "Webhook events and payloads."

2. Follow Up: Create a high-level remediation process that works for all secret types. For example, you could contact the developer who committed the secret and their technical lead on that project, highlighting the dangers of committing secrets to GitHub, and asking the them to revoke, and update the detected secret.

   Note

   You can automate this step. For large enterprises and organizations with hundreds of repositories, manually following up is unsustainable. You could incorporate automation into the webhook process defined in the first step. The webhook payload contains repository and organization information about the leaked secret. Using this information, you can contact the current maintainers on the repository and create an email/message to the responsible people or open an issue.

3. Educate: Create an internal training document assigned to the developer who committed the secret. Within this training document, you can explain the risks created by committing secrets and direct them to your best practice information about using secrets securely in development. If a developer doesn't learn from the experience and continues to commit secrets, you could create an escalation process, but education usually works well.

Repeat the last two steps for any new secrets leaked. This process encourages developers to take responsibility for managing the secrets used in their code securely, and allows you to measure the reduction in newly committed secrets.

2. Enable push protection

Once you have enabled secret scanning, you should also enable push protection. With push protection, secret scanning checks pushes for supported secrets and blocks pushes to GitHub before the secrets are exposed to other users. For information on how to enable push protection, see "Enabling push protection for your repository."

Once enabled, you can do the following:

1. Provide guidance: Configure a custom link in the message that contributors will see if their push is blocked by secret scanning. The linked resource can provide guidance for contributors on how to resolve the blocked push. For more information, see "Enabling push protection for your repository."

2. Notify: Define a webhook that specifically tracks secret scanning alerts created when someone bypasses push protection by using the alert property "push_protection_bypassed": true. Or, use the API to get updates on which secret scanning alerts were the result of a push protection bypass by filtering the list of results for "push_protection_bypassed": true. For more information, see "Auditing security alerts."

3. Monitor: Use security overview to view metrics on how push protection is performing in repositories across your organization, so you can quickly identify any repositories where you might need to take action. For more information, see "Viewing metrics for secret scanning push protection."

3. Remediate previously committed secrets, starting with the most critical

After you have established a process to reduce the addition of secrets to your codebases, you are ready to start work remediating secrets that were committed before you introduced GitHub Advanced Security.

How you define your most critical secrets will depend on your organization's processes and integrations. For example, a company likely isn’t worried about a Slack Incoming Webhook secret if they don’t use Slack. You may find it useful to start by focusing on the top five most critical credential types for your organization.

Once you have decided on the secret types, you can do the following:

1. Define a process for remediating each type of secret. The actual procedure for each secret type is often drastically different. Write down the process for each type of secret in a document or internal knowledge base.

   Note

   When you create the process for revoking secrets, try and give the responsibility for revoking secrets to the team maintaining the repository instead of a central team. One of the principles of GHAS is developers taking ownership of security and having the responsibility of fixing security issues, especially if they have created them.

2. When you have created the process that teams will follow for revoking credentials, you can collate information about the types of secrets and other metadata associated with the leaked secrets so you can discern who to communicate the new process to.

   You can use security overview to collect this information. For more information about using security overview, see "Filtering alerts in security overview."

   Some information you may want to collect includes:

   • Organization

   • Repository

   • Secret type

   • Secret value

   • Maintainers on repository to contact

   Note

   Use the UI if you have few secrets leaked of that type. If you have hundreds of leaked secrets, use the API to collect information. For more information, see "REST API endpoints for secret scanning."

3. After you collect information about leaked secrets, create a targeted communication plan for the users who maintain the repositories affected by each secret type. You could use email, messaging, or even create GitHub issues in the affected repositories. If you can use APIs provided by these tools to send out the communications in an automated manner, this will make it easier for you to scale across multiple secret types.

4. Expand the program to include more secret types and custom patterns

You can now expand beyond the five most critical secret types into a more comprehensive list, with an additional focus on education. You can repeat the previous step, remediating previously committed secrets, for the different secret types you have targeted.

You can also include more of the custom patterns collated in the earlier phases and invite security teams and developer teams to submit more patterns, establishing a process for submitting new patterns as new secret types are created. For more information, see "Defining custom patterns for secret scanning."

As you continue to build your remediation processes for other secret types, start to create proactive training material that can be shared with all developers of GitHub in your organization. Until this point, a lot of the focus has been reactive. It is an excellent idea to shift focus to being proactive and encourage developers not to push credentials to GitHub in the first place. This can be achieved in multiple ways but creating a short document explaining the risks and reasons would be a great place to start.