Protecting pushes with secret scanning

About push protection for secrets

Up to now, secret scanning for advanced security checks for secrets after a push and alerts users to exposed secrets. 启用推送保护时，secret scanning 还会检查推送中是否存在高置信度机密（经识别误报率低的机密）。 Secret scanning 列出了它检测到的所有机密，便于作者进行查看和删除，或者根据需要允许推送这些机密。

If a contributor bypasses a push protection block for a secret, GitHub:

• generates an alert.
• creates an alert in the "Security" tab of the repository.
• adds the bypass event to the audit log.
• sends an email alert to organization owners, security managers, and repository administrators, with a link to the related secret and the reason why it was allowed.

For information on the secrets and service providers supported for push protection, see "Secret scanning patterns."

Enabling secret scanning as a push protection

For you to use secret scanning as a push protection, the organization or repository needs to have both GitHub Advanced Security and secret scanning enabled. For more information, see "Managing security and analysis settings for your organization," "Managing security and analysis settings for your repository," and "About GitHub Advanced Security."

Organization owners, security managers, and repository administrators can enable push protection for secret scanning via the UI and API. For more information, see "Repositories" and expand the "Properties of the security_and_analysis object" section in the REST API documentation.

Enabling secret scanning as a push protection for an organization

1. 在 GitHub.com 上，导航到组织的主页。

2. 在组织名称下，单击“设置”。

3. In the "Security" section of the sidebar, click Code security and analysis.

4. 在“代码安全性和分析”下，查找“GitHub Advanced Security”。

5. Under "Secret scanning", under "Push protection", click Enable all.

6. Optionally, click "Automatically enable for private repositories added to secret scanning."

7. Optionally, to include a custom link in the message that members will see when they attempt to push a secret, select Add a resource link in the CLI and web UI when a commit is blocked, then type a URL, and click Save link.

   Note: The ability to add resource links to blocked push messages is currently in public beta and subject to change.

   

Enabling secret scanning as a push protection for a repository

1. 在 GitHub.com 上，导航到存储库的主页。

2. 在存储库名称下，单击 “设置”。

3. In the "Security" section of the sidebar, click Code security and analysis.

4. 在“代码安全性和分析”下，查找“GitHub Advanced Security”。

5. 在“Secret scanning”下的“推送保护”下，单击“启用”。

Using secret scanning as a push protection from the command line

尝试在 secret scanning 作为推送保护启用的情况下将受支持的机密推送到存储库或组织时，GitHub 将组织推送。 可以从分支中删除该机密，或遵循提供的 URL 来允许推送。

Up to five detected secrets will be displayed at a time on the command line. If a particular secret has already been detected in the repository and an alert already exists, GitHub will not block that secret.

Organization admins can provide a custom link that will be displayed when a push is blocked. This custom link can contain organization-specific resources and advice, such as directions on using a recommended secrets vault or who to contact for questions relating to the blocked secret.

如果确认机密是真实的，则需要将机密从分支和出现机密的所有提交中删除，然后再次推送。 For more information about remediating blocked secrets, see "Pushing a branch blocked by push protection."

If you confirm a secret is real and that you intend to fix it later, you should aim to remediate the secret as soon as possible. For example, you might revoke the secret and remove the secret from the repository's commit history. Real secrets that have been exposed must be revoked to avoid unauthorized access. You might consider first rotating the secret before revoking it. For more information, see "Removing sensitive data from a repository."

Allowing a blocked secret to be pushed

If GitHub blocks a secret that you believe is safe to push, you can allow the secret and specify the reason why it should be allowed.

允许推送机密时，将在“安全”选项卡中创建警报。如果指定机密为误报或仅在测试中使用，则 GitHub 会关闭警报，且不会发送通知。 如果指定机密是真实的并且稍后将修复它，GitHub 会将安全警报保持打开状态，并向提交的作者以及存储库管理员发送通知。 有关详细信息，请参阅管理来自机密扫描的警报。

当参与者绕过机密的推送保护块时，GitHub 还会向选择接收电子邮件通知的组织所有者、安全管理员和存储库管理员发送电子邮件警报。

1. Visit the URL returned by GitHub when your push was blocked.
2. 选择最能描述为何应该能够推送机密的选项。
   • 如果机密仅在测试中使用，并且不会构成任何威胁，请单击“它在测试中使用”。
   • 如果检测到的字符串不是机密，请单击“它是误报”。
   • 如果机密是真实的，但你打算稍后修复它，请单击“稍后修复”。
3. Click Allow me to push this secret.
4. Reattempt the push on the command line within three hours. If you have not pushed within three hours, you will need to repeat this process.

Using secret scanning as a push protection from the web UI

When you use the web UI to attempt to commit a supported secret to a repository or organization with secret scanning as a push protection enabled, GitHub will block the commit.

You will see a banner at the top of the page with information about the secret's location, and the secret will also be underlined in the file so you can easily find it.

GitHub will only display one detected secret at a time in the web UI. If a particular secret has already been detected in the repository and an alert already exists, GitHub will not block that secret.

Organization admins can provide a custom link that will be displayed when a push is blocked. This custom link can contain resources and advice specific to your organization. For example, the custom link can point to a README file with information about the organization's secret vault, which teams and individuals to escalate questions to, or the organization's approved policy for working with secrets and rewriting commit history.

You can remove the secret from the file using the web UI. Once you remove the secret, the banner at the top of the page will change and tell you that you can now commit your changes.

Bypassing push protection for a secret

如果确认机密是真实的，则需要将机密从分支和出现机密的所有提交中删除，然后再次推送。 For more information about remediating blocked secrets, see "Pushing a branch blocked by push protection."

If you confirm a secret is real and that you intend to fix it later, you should aim to remediate the secret as soon as possible. For more information, see "Removing sensitive data from a repository."

If GitHub blocks a secret that you believe is safe to push, you can allow the secret and specify the reason why it should be allowed.

允许推送机密时，将在“安全”选项卡中创建警报。如果指定机密为误报或仅在测试中使用，则 GitHub 会关闭警报，且不会发送通知。 如果指定机密是真实的并且稍后将修复它，GitHub 会将安全警报保持打开状态，并向提交的作者以及存储库管理员发送通知。 有关详细信息，请参阅管理来自机密扫描的警报。

当参与者绕过机密的推送保护块时，GitHub 还会向选择接收电子邮件通知的组织所有者、安全管理员和存储库管理员发送电子邮件警报。

If you confirm a secret is real and that you intend to fix it later, you should aim to remediate the secret as soon as possible.

1. In the banner that appeared at the top of the page when GitHub blocked your commit, click Bypass protection.

2. 选择最能描述为何应该能够推送机密的选项。

   • 如果机密仅在测试中使用，并且不会构成任何威胁，请单击“它在测试中使用”。
   • 如果检测到的字符串不是机密，请单击“它是误报”。
   • 如果机密是真实的，但你打算稍后修复它，请单击“稍后修复”。

   

3. Click Allow secret.