Secret scanning validity checks for partner patterns - [Public Beta] …

…(#37289) Co-authored-by: mc <[email protected]> Co-authored-by: github-actions <[email protected]> Co-authored-by: Courtney Claessens <[email protected]> Co-authored-by: Sophie <[email protected]> Co-authored-by: Siara <[email protected]>
binhle113 · Aug 11, 2023 · 1267748 · 1267748
1 parent 54f11c8
commit 1267748
Show file tree

Hide file tree

Showing 12 changed files with 108 additions and 19 deletions.
diff --git a/.../enterprise-security-and-analysis-disable-or-enable-all-with-validity-check.png b/.../enterprise-security-and-analysis-disable-or-enable-all-with-validity-check.png
diff --git a/...ur-enterprise/managing-github-advanced-security-features-for-your-enterprise.md b/...ur-enterprise/managing-github-advanced-security-features-for-your-enterprise.md
@@ -39,19 +39,25 @@ When you enable one or more security and analysis features for existing reposito
 
    - To the right of the feature, click **Disable all** or **Enable all**. {% ifversion ghes or ghec %}If the control for "{% data variables.product.prodname_GH_advanced_security %}" is disabled, you have no available {% ifversion ghas-billing-UI-update %}licenses{% else %}seats{% endif %} for {% data variables.product.prodname_GH_advanced_security %}.{% endif %}
 
-   ![Screenshot of the "Configure security and analysis features" section of the enterprise settings. To the right of each setting are "Enable all" and "Disable all" buttons, which are outlined in dark orange.](/assets/images/enterprise/security/enterprise-security-and-analysis-disable-or-enable-all.png)
+     {% ifversion secret-scanning-validity-check-partner-patterns %}
+     ![Screenshot of the "Configure security and analysis features" section of the enterprise settings. To the right of each setting are "Enable all" and "Disable all" buttons, which are outlined in dark orange.](/assets/images/enterprise/security/enterprise-security-and-analysis-disable-or-enable-all-with-validity-check.png)
 
+     {% else %}
+     ![Screenshot of the "Configure security and analysis features" section of the enterprise settings. To the right of each setting are "Enable all" and "Disable all" buttons, which are outlined in dark orange.](/assets/images/enterprise/security/enterprise-security-and-analysis-disable-or-enable-all.png){% endif %}
    - To confirm the change, click the **Enable/Disable all** or **Enable/Disable for eligible repositories** button in the dialog that is displayed.
-
 1. Optionally, to enable or disable a feature automatically when new repositories are added, select the checkbox below the feature.
+{% ifversion secret-scanning-validity-check-partner-patterns %}
+1. Optionally, to automatically allow {% data variables.product.prodname_secret_scanning %} to check the validity of a secret by sending it to the relevant partner, select the relevant checkbox under "{% data variables.product.prodname_secret_scanning_caps %}". You can also enable the validity check for a single repository or organization. For more information, see "[Allowing validity checks for partner patterns in a repository](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-security-and-analysis-settings-for-your-repository#allowing-validity-checks-for-partner-patterns-in-a-repository)," and "[Allowing validity checks for partner patterns in an organization](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-security-and-analysis-settings-for-your-organization#allowing-validity-checks-for-partner-patterns-in-an-organization)." <br><br>
 
-{% ifversion secret-scanning-custom-link-on-block %}
+   {% indented_data_reference reusables.secret-scanning.validity-check-partner-patterns-beta spaces=3 %}
 
+{%- endif %}
+{% ifversion secret-scanning-custom-link-on-block %}
 1. Optionally, to include a resource 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 %}
 
-  **Note**: When a custom link is configured for an organization, the organization-level value overrides the custom link set for the enterprise. For more information, see "[AUTOTITLE](/code-security/secret-scanning/protecting-pushes-with-secret-scanning)".
+  **Note**: When a custom link is configured for an organization, the organization-level value overrides the custom link set for the enterprise. For more information, see "[AUTOTITLE](/code-security/secret-scanning/protecting-pushes-with-secret-scanning)."
 
   {% endnote %}
 

diff --git a/content/code-security/secret-scanning/managing-alerts-from-secret-scanning.md b/content/code-security/secret-scanning/managing-alerts-from-secret-scanning.md
@@ -35,39 +35,59 @@ shortTitle: Manage secret alerts
 {% data reusables.repositories.navigate-to-repo %}
 {% data reusables.repositories.sidebar-security %}
 1. In the left sidebar, under "Vulnerability alerts", click **{% data variables.product.prodname_secret_scanning_caps %}**.
-1. Under "{% data variables.product.prodname_secret_scanning_caps %}" click the alert you want to view.{% ifversion secret-scanning-validity-check %}
-1. Optionally, if the leaked secret is a {% data variables.product.company_short %} token, check the validity of the secret and follow the remediation steps. {% ifversion secret-scanning-github-token-metadata %}If the {% data variables.product.company_short %} token is currently active, you can also review the token metadata. For more information on reviewing token metadata, see "[Reviewing {% data variables.product.company_short %} token metadata](#reviewing-github-token-metadata)."{% endif %}
+1. Under "{% data variables.product.prodname_secret_scanning_caps %}" click the alert you want to view. {% ifversion secret-scanning-validity-check-partner-patterns %}
+1. Optionally, to perform a validity check on the token, on the top right-hand side of the alert, click {% octicon "sync" aria-label="Send token to partner for verification" %}. For more information, see "[Validating partner patterns](#validating-partner-patterns)." <br><br>
+  {% note %}
 
-   ![Screenshot of the UI for a {% data variables.product.company_short %} token, showing the validity check and suggested remediation steps.](/assets/images/help/repository/secret-scanning-validity-check.png)
+  **Note:** You can only perform on-demand validity checks for patterns detected in the repository if automatic validity checks have been enabled for the repository. For more information, see "[Allowing validity checks for partner patterns in a repository](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-security-and-analysis-settings-for-your-repository#allowing-validity-checks-for-partner-patterns-in-a-repository)."
+
+  {% endnote %}
+  {% endif %}{% ifversion ghes = 3.9 or ghes = 3.10 or ghes = 3.11 %}
+1. Optionally, if the leaked secret is a {% data variables.product.company_short %} token, check the validity of the secret and follow the remediation steps.
 
    {% note %}
 
-   **Note:** Validity check for {% data variables.product.company_short %} tokens is currently in public beta and subject to change.
+   **Note:**  Validity check for {% data variables.product.company_short %} tokens is currently in public beta and subject to change.
 
    {% endnote %}
 
    {% data variables.product.company_short %} provides information about the validity of the secret, for {% data variables.product.company_short %} tokens only.
 
-   | Validity                |     Result                                                                           |
-   |-------------------------|--------------------------------------------------------------------------------|
-   | Active secret           | {% data variables.product.company_short %} confirmed this secret is active                                         |
-   | Active secret           | {% data variables.product.company_short %} checked with this secret's provider and found that the secret is active |
-   | Possibly active secret  | {% data variables.product.company_short %} does not support validation checks for this token type yet               |
-   | Possibly active secret  | {% data variables.product.company_short %} could not verify this secret                                            |
-   | Secret appears inactive | You should make sure no unauthorized access has already occurred                 |
-{% endif %}{% ifversion secret-scanning-partner-documentation-link-UI %}
+   {% data reusables.secret-scanning.validity-check-table %}{% endif %}{% ifversion secret-scanning-github-token-metadata %}
+1. Optionally, if the leaked secret is a {% data variables.product.company_short %} token, you can also review the token metadata. For more information on reviewing token metadata, see "[Reviewing {% data variables.product.company_short %} token metadata](#reviewing-github-token-metadata)."{% endif %}{% ifversion secret-scanning-partner-documentation-link-UI %}
 1. To dismiss an alert, select the "Close as" dropdown menu and click a reason for resolving an alert.
 
    ![Screenshot of a {% data variables.product.prodname_secret_scanning %} alert. A dropdown menu, titled "Close as", is expanded and highlighted in a dark orange outline.](/assets/images/help/repository/secret-scanning-dismiss-alert-web-ui-link-partner-documentation.png)
 
    {% else %}
-
-1 To dismiss an alert, select the "Mark as" dropdown menu and click a reason for resolving an alert.
+1. To dismiss an alert, select the "Mark as" dropdown menu and click a reason for resolving an alert.
    {% endif %}{% ifversion secret-scanning-dismissal-comment %}
 1. 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 {% data variables.product.prodname_secret_scanning_caps %} API. The comment is contained in the `resolution_comment` field. For more information, see "[AUTOTITLE](/rest/secret-scanning#update-a-secret-scanning-alert)" in the REST API documentation.
 1. Click **Close alert**.
 {% endif %}
 
+{% ifversion secret-scanning-validity-check-partner-patterns %}
+## Validating partner patterns
+
+{% data reusables.secret-scanning.validity-check-partner-patterns-beta %}
+{% data reusables.gated-features.partner-pattern-validity-check-ghas %}
+
+You can allow {% data variables.product.prodname_secret_scanning %} to check the validity of a secret found in your repository by sending it to the relevant partner.
+
+You can enable automatic validity checks for supported partner patterns in the code security settings for your repository, organization, or enterprise. {% data variables.product.company_short %} will periodically send the pattern to the relevant partner to check the secret's validity and display the validation status of the secret in the alert view. 
+
+ For more information on enabling automatic validation checks for partner patterns in your repository, organization, or enterprise, see "[Allowing validity checks for partner patterns in a repository](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-security-and-analysis-settings-for-your-repository#allowing-validity-checks-for-partner-patterns-in-a-repository)," "[Allowing validity checks for partner patterns in an organization](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-security-and-analysis-settings-for-your-organization#allowing-validity-checks-for-partner-patterns-in-an-organization)," and "[Managing Advanced Security features](/admin/code-security/managing-github-advanced-security-for-your-enterprise/managing-github-advanced-security-features-for-your-enterprise#managing-advanced-security-features)."
+
+If your repository has validity checks enabled, you can also perform an on-demand validity check for a secret by clicking {% octicon "sync" aria-label="Send token to partner for verification" %} in the alert view. {% data variables.product.company_short %} will send the pattern to the relevant partner and display the validation status of the secret in the alert view.
+
+You can use the validation status of a leaked secret to help prioritize the secrets needing remediation steps.
+
+{% data reusables.secret-scanning.validity-check-table %}
+
+For more information on which partners support validity checks, see "[Supported secrets](/code-security/secret-scanning/secret-scanning-patterns#supported-secrets)."
+
+{% endif %}
+
 {% ifversion secret-scanning-github-token-metadata %}
 
 ## Reviewing {% data variables.product.company_short %} token metadata

diff --git a/content/code-security/secret-scanning/secret-scanning-patterns.md b/content/code-security/secret-scanning/secret-scanning-patterns.md
@@ -85,7 +85,7 @@ This table lists the secrets supported by {% data variables.product.prodname_sec
 - **User**—token for which leaks are reported to users on {% data variables.product.prodname_dotcom %}. Applies to public repositories, and to private repositories where {% data variables.product.prodname_GH_advanced_security %} is enabled.{% endif %}{% ifversion ghes or ghae %}
 - **{% data variables.product.prodname_secret_scanning_caps %} alert**—token for which leaks are reported to users on {% data variables.product.prodname_dotcom %}. Applies to private repositories where {% data variables.product.prodname_GH_advanced_security %} and {% data variables.product.prodname_secret_scanning %} enabled.{% endif %}{% ifversion secret-scanning-push-protection %}
 - **Push protection**—token for which leaks are reported to users on {% data variables.product.prodname_dotcom %}. Applies to repositories with {% data variables.product.prodname_secret_scanning %} and push protection enabled.{% endif %}{% ifversion secret-scanning-validity-check %}
-- **Validity check**—token for which a validity check is implemented. For partner tokens, the token is sent to the relevant partner. Currently only applies to {% data variables.product.prodname_dotcom %} tokens.{% endif %}
+- **Validity check**—token for which a validity check is implemented. {% ifversion secret-scanning-validity-check-partner-patterns %}For partner tokens, {% data variables.product.prodname_dotcom %} sends the token to the relevant partner. Note that not all partners are based in the United States. For more information, see "[{% data variables.product.prodname_advanced_security %}](/free-pro-team@latest/site-policy/github-terms/github-terms-for-additional-products-and-features#advanced-security)" in the Site Policy documentation.{% else %} Currently only applies to {% data variables.product.prodname_dotcom %} tokens.{% endif %}{% endif %}
 
 <!-- FPT version of table -->
 {% ifversion fpt %}

diff --git a/...r-organization/managing-security-and-analysis-settings-for-your-organization.md b/...r-organization/managing-security-and-analysis-settings-for-your-organization.md
@@ -129,6 +129,20 @@ To allow {% data variables.product.prodname_dependabot %} to access a private {%
 
 {% endif %}
 
+{% ifversion secret-scanning-validity-check-partner-patterns %}
+
+## Allowing validity checks for partner patterns in an organization
+
+{% data reusables.secret-scanning.validity-check-partner-patterns-beta %}
+{% data reusables.gated-features.partner-pattern-validity-check-ghas %}
+
+You can allow {% data variables.product.prodname_secret_scanning %} to automatically check the validity of a secret by sending it to the relevant partner. When you select the checkbox in the organization settings, the feature is enabled for all repositories in the organization. Alternatively, you can enable the validity check for a single repository, or at the enterprise level. For more information, see "[Allowing validity checks for partner patterns in a repository](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-security-and-analysis-settings-for-your-repository#allowing-validity-checks-for-partner-patterns-in-a-repository)" and "[AUTOTITLE](/admin/code-security/managing-github-advanced-security-for-your-enterprise/managing-github-advanced-security-features-for-your-enterprise)."
+
+1. Go to the security and analysis settings for your organization. For more information, see "[Displaying the security and analysis settings](#displaying-the-security-and-analysis-settings)."
+{% data reusables.secret-scanning.validity-check-auto-enable %}
+
+{% endif %}
+
 {% ifversion ghes or ghec %}
 
 ## Removing access to {% data variables.product.prodname_GH_advanced_security %} from individual repositories in an organization

diff --git a/...-your-repository/managing-security-and-analysis-settings-for-your-repository.md b/...-your-repository/managing-security-and-analysis-settings-for-your-repository.md
@@ -94,6 +94,28 @@ Organization owners and repository administrators can only grant access to view
      ![Screenshot of the list of users with access to alerts. To the right of @octocat, an x icon is outlined in dark orange.](/assets/images/help/repository/security-and-analysis-security-alerts-username-x.png)
 1. Click **Save changes**.
 
+{% ifversion secret-scanning-validity-check-partner-patterns %}
+
+## Allowing validity checks for partner patterns in a repository
+
+{% data reusables.secret-scanning.validity-check-partner-patterns-beta %}
+{% data reusables.gated-features.partner-pattern-validity-check-ghas %}
+
+You can allow {% data variables.product.prodname_secret_scanning %} to automatically check the validity of a secret found in your repository by sending it to the relevant partner. Alternatively, organization owners and enterprise administrators can enable the feature for all repositories in the organization or enterprise settings. For more information, see "[Allowing validity checks for partner patterns in an organization](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-security-and-analysis-settings-for-your-organization#allowing-validity-checks-for-partner-patterns-in-an-organization)" and "[AUTOTITLE](/admin/code-security/managing-github-advanced-security-for-your-enterprise/managing-github-advanced-security-features-for-your-enterprise)."
+
+{% note %}
+
+**Note:** When you enable automatic validity checks for a repository, you also allow on-demand validity checks to be performed for patterns detected in that repository. 
+
+{% endnote %}
+
+{% data reusables.repositories.navigate-to-repo %}
+{% data reusables.repositories.sidebar-settings %}
+{% data reusables.repositories.navigate-to-code-security-and-analysis %}
+{% data reusables.secret-scanning.validity-check-auto-enable %}
+
+{% endif %}
+
 ## Further reading
 
 - "[AUTOTITLE](/code-security/getting-started/securing-your-repository)"

diff --git a/...t/site-policy/github-terms/github-terms-for-additional-products-and-features.md b/...t/site-policy/github-terms/github-terms-for-additional-products-and-features.md
@@ -62,6 +62,8 @@ GitHub makes extra security features available to customers under an Advanced Se
 
 Advanced Security is licensed on a "Unique Committer" basis. A "Unique Committer" is a licensed user of GitHub Enterprise, GitHub Enterprise Cloud, GitHub Enterprise Server, or GitHub AE, who has made a commit in the last 90 days to any repository with any GitHub Advanced Security functionality activated. You must acquire a GitHub Advanced Security User license for each of your Unique Committers. You may only use GitHub Advanced Security on codebases that are developed by or for you. For GitHub Enterprise Cloud users, some Advanced Security features also require the use of GitHub Actions.
 
+For secret scanning with GitHub Advanced Security, when you opt-in to automatic validity checks for partner patterns, exposed third-party tokens may be shared with the relevant partner, in order to provide you with more information about the validity of the token. Not all partners are based in the United States. The [Secret scanning patterns documentation](/enterprise-cloud@latest/code-security/secret-scanning/secret-scanning-patterns) provides more details on which partners support the validity check.
+
 ## Advisory Database
 
 The GitHub Advisory Database allows you to browse or search for vulnerabilities that affect open source projects on GitHub.

diff --git a/data/features/secret-scanning-validity-check-partner-patterns.yml b/data/features/secret-scanning-validity-check-partner-patterns.yml
@@ -0,0 +1,5 @@
+# Reference: #9861.
+# Documentation for secret scanning: validity check for partner patterns (GHAS).
+versions:
+  ghec: '*'
+  ghes: '>=3.12'
diff --git a/data/reusables/gated-features/partner-pattern-validity-check-ghas.md b/data/reusables/gated-features/partner-pattern-validity-check-ghas.md
@@ -0,0 +1,7 @@
+{% ifversion ghec %}
+Validity checks for partner patterns is available on all types of repositories on {% data variables.product.prodname_dotcom_the_website %}. To use this feature, you must have a license for {% data variables.product.prodname_GH_advanced_security %}.
+
+{% elsif ghes %}
+Validity checks for partner patterns is available on all types of repositories in {% data variables.product.product_name %}. This feature requires a license for {% data variables.product.prodname_GH_advanced_security %}.
+
+{% endif %} 
diff --git a/data/reusables/secret-scanning/validity-check-auto-enable.md b/data/reusables/secret-scanning/validity-check-auto-enable.md
@@ -0,0 +1 @@
+1. Under {% data variables.product.prodname_secret_scanning_caps %}, select the checkbox next to "Automatically verify if a secret is valid by sending it to the relevant partner".
diff --git a/data/reusables/secret-scanning/validity-check-partner-patterns-beta.md b/data/reusables/secret-scanning/validity-check-partner-patterns-beta.md
@@ -0,0 +1,5 @@
+{% note %}
+
+**Note:** Validity checks for partner patterns is currently in beta and subject to change.
+
+{% endnote %}
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		1. Under {% data variables.product.prodname_secret_scanning_caps %}, select the checkbox next to "Automatically verify if a secret is valid by sending it to the relevant partner".