Skip to main content

Managing alerts from secret scanning

You can view, evaluate and resolve alerts for secrets checked in to your repository.

Who can use this feature?

People with admin access to a public repository can view and dismiss secret scanning alerts for the repository.

Secret scanning alerts for partners runs automatically on public repositories and public npm packages to notify service providers about leaked secrets on GitHub.com.

Secret scanning alerts for users are available for public repositories for free. Organizations using GitHub Enterprise Cloud with a license for GitHub Advanced Security can also enable secret scanning alerts for users on their private and internal repositories. For more information, see "About secret scanning" and "About GitHub Advanced Security."

For information about how you can try GitHub Enterprise with GitHub Advanced Security for free, see "Setting up a trial of GitHub Enterprise Cloud" and "Setting up a trial of GitHub Advanced Security" in the GitHub Enterprise Cloud documentation.

About the secret scanning alerts page

When you enable secret scanning for a repository or push commits to a repository with secret scanning enabled, GitHub scans the contents for secrets that match patterns defined by service providers.

When secret scanning detects a secret, GitHub generates an alert. GitHub displays an alert in the Security tab of the repository.

Viewing alerts

  1. On GitHub.com, navigate to the main page of the repository.
  2. Under the repository name, click Security. If you cannot see the "Security" tab, select the dropdown menu, and then click Security. Screenshot of a repository header showing the tabs. The "Security" tab is highlighted by a dark orange outline.
  3. In the left sidebar, under "Vulnerability alerts", click Secret scanning.
  4. Under "Secret scanning", click the alert you want to view.

Filtering alerts

You can apply various filters to the alerts list to help you find the alerts you're interested in. You can use the dropdown menus above the alerts list, or input the qualifiers listed in the table into the search bar.

QualifierDescription
is:openDisplays open alerts.
is:closedDisplays closed alerts.
bypassed: trueDisplays alerts for secrets where push protection has been bypassed. For more information, see "Push protection for repositories and organizations."
validity:activeDisplays alerts for secrets that are still active. Applies to GitHub tokens only. For more information about validity statuses, see "Checking a secret's validity."
validity:inactiveDisplays alerts for secrets that are no longer active.
validity:unknownDisplays alerts for secrets where the validity status of the secret is unknown.
secret-type:SECRET-NAMEDisplays alerts for a specific secret type, for example, secret-type:github_personal_access_token. For a list of supported secret types, see "Secret scanning patterns."
provider:PROVIDER-NAMEDisplays alerts for a specific provider, for example, provider:github. For a list of supported partners, see "Secret scanning patterns."

Evaluating alerts

There are some additional features that can help you to evaluate alerts in order to better prioritize and manage them. You can:

  • Check the validity of a secret, to see if the secret is still active. Applies to GitHub tokens only. For more information, see "Checking a secret's validity."
  • Review a token's metadata. Applies to GitHub tokens only. For example, to see when the token was last used. For more information, see "Reviewing GitHub token metadata."

Checking a secret's validity

Validity checks help you prioritize alerts by telling you which secrets are active or inactive. An active secret is one that could still be exploited, so these alerts should be reviewed and remediated as a priority.

By default, GitHub checks the validity of GitHub tokens and displays the validitation status of the token in the alert view.

Organizations using GitHub Enterprise Cloud with a license for GitHub Advanced Security can also enable validity checks for partner patterns. For more information, see "Checking a secret's validity" in the GitHub Enterprise Cloud documentation.

ValidityStatusResult
Active secretactiveGitHub checked with this secret's provider and found that the secret is active
Possibly active secretunknownGitHub does not support validation checks for this token type yet
Possibly active secretunknownGitHub could not verify this secret
Secret inactiveinactiveYou should make sure no unauthorized access has already occurred

You can use the REST API to retrieve a list of the most recent validation status for each of your tokens. For more information, see "REST API endpoints for secret scanning" in the REST API documentation. You can also use webhooks to be notified of activity relating to a secret scanning alert. For more information, see the secret_scanning_alert event in "Webhook events and payloads."

Reviewing GitHub token metadata

Note: Metadata for GitHub tokens is currently in public beta and subject to change.

In the view for an active GitHub token alert, you can review certain metadata about the token. This metadata may help you identify the token and decide what remediation steps to take.

Tokens, like personal access token and other credentials, are considered personal information. For more information about using GitHub tokens, see GitHub's Privacy Statement and Acceptable Use Policies.

Screenshot of the UI for a GitHub token, showing the token metadata.

Metadata for GitHub tokens is available for active tokens in any repository with secret scanning enabled. If a token has been revoked or its status cannot be validated, metadata will not be available. GitHub auto-revokes GitHub tokens in public repositories, so metadata for GitHub tokens in public repositories is unlikely to be available. The following metadata is available for active GitHub tokens:

MetadataDescription
Secret nameThe name given to the GitHub token by its creator
Secret ownerThe GitHub handle of the token's owner
Created onDate the token was created
Expired onDate the token expired
Last used onDate the token was last used
AccessWhether the token has organization access

Fixing alerts

Once a secret has been committed to a repository, you should consider the secret compromised. GitHub recommends the following actions for compromised secrets:

  • For a compromised GitHub personal access token, delete the compromised token, create a new token, and update any services that use the old token. For more information, see "Managing your personal access tokens."
  • For all other secrets, first verify that the secret committed to GitHub is valid. If so, create a new secret, update any services that use the old secret, and then delete the old secret.

Note: If a secret is detected in a public repository on GitHub.com and the secret also matches a partner pattern, an alert is generated and the potential secret is reported to the service provider. For details of partner patterns, see "Secret scanning patterns."

Closing alerts

  1. On GitHub.com, navigate to the main page of the repository.

  2. Under the repository name, click Security. If you cannot see the "Security" tab, select the dropdown menu, and then click Security. Screenshot of a repository header showing the tabs. The "Security" tab is highlighted by a dark orange outline.

  3. In the left sidebar, under "Vulnerability alerts", click Secret scanning.

  4. Under "Secret scanning", click the alert you want to view.

  5. To dismiss an alert, select the "Close as" dropdown menu and click a reason for resolving an alert.

    Screenshot of a secret scanning alert. A dropdown menu, titled "Close as", is expanded and highlighted in a dark orange outline.

  6. Optionally, in the "Comment" field, add a dismissal comment. The dismissal comment will be added to the alert timeline and can be used as justification during auditing and reporting. You can view the history of all dismissed alerts and dismissal comments in the alert timeline. You can also retrieve or set a comment by using the Secret scanning API. The comment is contained in the resolution_comment field. For more information, see "REST API endpoints for secret scanning" in the REST API documentation.

  7. Click Close alert.

Configuring notifications for secret scanning alerts

Notifications are different for incremental scans and historical scans.

Incremental scans

When a new secret is detected, GitHub notifies all users with access to security alerts for the repository according to their notification preferences. These users include:

  • Repository administrators
  • Security managers
  • Users with custom roles with read/write access
  • Organization owners and enterprise owners, if they are administrators of repositories where secrets were leaked

Note: Commit authors who've accidentally committed secrets will be notified, regardless of their notification preferences.

You will receive an email notification if:

  • You are watching the repository.
  • You have enabled notifications for "All Activity", or for custom "Security alerts" on the repository.
  • In your notification settings, under "Subscriptions", then under "Watching", you have selected to receive notifications by email.
  1. On GitHub.com, navigate to the main page of the repository.

  2. To start watching the repository, select Watch.

    Screenshot of the repository's main page. A dropdown menu, titled "Watch", is highlighted with an orange outline.

  3. In the dropdown menu, click All Activity. Alternatively, to only subscribe to security alerts, click Custom, then click Security alerts.

  4. Navigate to the notification settings for your personal account. These are available at https://github.com/settings/notifications.

  5. On your notification settings page, under "Subscriptions", then under "Watching", select the Notify me dropdown.

  6. Select "Email" as a notification option, then click Save.

    Screenshot of the notification settings for a user account. An element header, titled "Subscriptions", and a sub-header, titled "Watching", are shown. A checkbox, titled "Email", is highlighted with an orange outline.

For more information about setting up notification preferences, see "Managing security and analysis settings for your repository" and "Configuring your watch settings for an individual repository."

Historical scans

For historical scans, GitHub notifies the following users:

  • Organization owners, enterprise owners, and security managers—whenever a historical scan is complete, even if no secrets are found.
  • Repository administrators, security managers, and users with custom roles with read/write access—whenever a historical scan detects a secret, and according to their notification preferences.

We do not notify commit authors.

For more information about setting up notification preferences, see "Managing security and analysis settings for your repository" and "Configuring your watch settings for an individual repository."

Auditing responses to secret scanning alerts

You can audit the actions taken in response to secret scanning alerts using GitHub tools. For more information, see "Auditing security alerts."