Add troubleshooting article for secret scanning (#33684)

Co-authored-by: Mariam <15mariams@github.com>

content/code-security/guides.md

@@ -31,6 +31,7 @@ includeGuides:
   - /code-security/secret-scanning/protecting-pushes-with-secret-scanning
   - /code-security/secret-scanning/pushing-a-branch-blocked-by-push-protection
   - /code-security/secret-scanning/secret-scanning-patterns
+  - /code-security/secret-scanning/troubleshooting-secret-scanning
   - /code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/tracking-code-scanning-alerts-in-issues-using-task-lists
   - /code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-code-scanning
   - /code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-code-scanning-alerts

content/code-security/secret-scanning/index.md

@@ -22,5 +22,6 @@ children:
   - /secret-scanning-patterns
   - /protecting-pushes-with-secret-scanning
   - /pushing-a-branch-blocked-by-push-protection
+  - /troubleshooting-secret-scanning
 ---
 

content/code-security/secret-scanning/secret-scanning-patterns.md

@@ -31,6 +31,8 @@ redirect_from:
 Owners of public repositories, as well as organizations using {% data variables.product.prodname_ghe_cloud %} with {% data variables.product.prodname_GH_advanced_security %}, can enable {% data variables.secret-scanning.user_alerts %} on their repositories. For details of these patterns, see the "[Supported secrets for user alerts](#supported-secrets-for-user-alerts) section below.
 {% endif %}
 
+If you believe that {% data variables.product.prodname_secret_scanning %} should have detected a secret committed to your repository, and it has not, you first need to check that {% data variables.product.prodname_dotcom %} supports your secret. For more information, refer to the sections below. For more advanced troubleshooting information, see "[Troubleshooting {% data variables.product.prodname_secret_scanning %}](/code-security/secret-scanning/troubleshooting-secret-scanning)."
+
 ## Supported secrets for partner alerts
 
 {% data variables.product.product_name %} currently scans public repositories for secrets issued by the following service providers and alerts the relevant service provider whenever a secret is detected in a commit. For more information about {% data variables.secret-scanning.partner_alerts %}, see "[About {% data variables.secret-scanning.partner_alerts %}](/code-security/secret-scanning/about-secret-scanning#about-secret-scanning-alerts-for-partners)."
@@ -67,6 +69,8 @@ If you use the REST API for secret scanning, you can use the `Secret type` to re
 
 {% data reusables.secret-scanning.secret-scanning-pattern-pair-matches %}
 
+{% data reusables.secret-scanning.push-protection-older-tokens %} For more information about push protection limitations, see "[Troubleshooting {% data variables.product.prodname_secret_scanning %}](/code-security/secret-scanning/troubleshooting-secret-scanning#push-protection-and-pattern-versions)."
+
 {% data reusables.secret-scanning.secret-list-private-push-protection %}
 
 {% endif %}

content/code-security/secret-scanning/troubleshooting-secret-scanning.md

@@ -0,0 +1,46 @@
+---
+title: Troubleshooting secret scanning
+shortTitle: Troubleshoot secret scanning
+intro: 'If you have problems with {% data variables.product.prodname_secret_scanning %}, you can use these tips to help resolve issues.'
+product: '{% data reusables.gated-features.secret-scanning %}'
+versions:
+  fpt: '*'
+  ghes: '*'
+  ghae: '*'
+  ghec: '*'
+type: how_to
+topics:
+  - Secret scanning
+  - Advanced Security
+  - Troubleshooting
+---
+
+{% data reusables.secret-scanning.beta %}
+{% data reusables.secret-scanning.enterprise-enable-secret-scanning %}
+
+## Detection of pattern pairs
+
+{% data variables.product.prodname_secret_scanning_caps %} will only detect pattern pairs, such as AWS Access Keys and Secrets, if the ID and the secret are found in the same file, and both are pushed to the repository. Pair matching helps reduce false positives since both elements of a pair (the ID and the secret) must be used together to access the provider's resource.
+
+Pairs pushed to different files, or not pushed to the same repository, will not result in alerts. For more information about the supported pattern pairs, see the tables in "[{% data variables.product.prodname_secret_scanning_caps %} patterns](/code-security/secret-scanning/secret-scanning-patterns)."
+
+{% ifversion secret-scanning-validity-check %}
+## About legacy GitHub tokens
+
+For {% data variables.product.prodname_dotcom %} tokens, we check the validity of the secret to determine whether the secret is active or inactive. This means that for legacy tokens, {% data variables.product.prodname_secret_scanning %} won't detect a {% data variables.product.prodname_ghe_server %} {% data variables.product.pat_generic %} on {% data variables.product.prodname_ghe_cloud %}. Similarly, a {% data variables.product.prodname_ghe_cloud %} {% data variables.product.pat_generic %} won't be found on {% data variables.product.prodname_ghe_server %}.
+
+{% endif %}
+{% ifversion secret-scanning-push-protection %}
+## Push protection limitations
+
+If push protection did not detect a secret that you think should have been detected, then you should first check that push protection supports the secret type in the list of supported secrets. For further information, see "[Supported secrets for push protection](/code-security/secret-scanning/secret-scanning-patterns#supported-secrets-for-push-protection)."
+
+If your secret is in the supported list, there are various reasons why push protection may not detect it.
+
+- Push protection only blocks leaked secrets on a subset of the most identifiable user-alerted patterns. Contributors can trust security defenses when such secrets are blocked as these are the patterns that have the lowest number of false positives.
+- The version of your secret may be old. {% data reusables.secret-scanning.push-protection-older-tokens %}
+- The push may be too large, for example, if you're trying to push thousands of large files. A push protection scan may time out and not block a user if the push is too large. {% data variables.product.prodname_dotcom %} will still scan and create alerts, if needed, after the push.
+- If the push results in the detection of over five new secrets, we will only show you the first five (we will always show you a maximum of five secrets at one time).
+- If a push contains over 1,000 existing secrets (that is, secrets for which alerts have already been created), push protection will not block the push.
+
+{% endif %}

data/learning-tracks/code-security.yml

@@ -73,6 +73,7 @@ secret_scanning:
     - '/code-security/secret-scanning/secret-scanning-patterns'
     - '{% ifversion secret-scanning-push-protection %}/code-security/secret-scanning/protecting-pushes-with-secret-scanning{% endif %}'
     - '{% ifversion secret-scanning-push-protection %}/code-security/secret-scanning/pushing-a-branch-blocked-by-push-protection{% endif %}'
+    - '/code-security/secret-scanning/troubleshooting-secret-scanning'
 
 # Security overview feature available in GHEC and GHES 3.2+, so other articles hidden to hide the learning path in other versions
 security_alerts:

data/reusables/secret-scanning/push-protection-older-tokens.md

@@ -0,0 +1 @@
+Older versions of certain tokens may not be supported by push protection as these tokens may generate a higher number of false positives than their most recent version. Push protection may also not apply to legacy tokens. For tokens such as Azure Storage Keys, {% data variables.product.prodname_dotcom %} only supports _recently created_ tokens, not tokens that match the legacy patterns.

data/reusables/secret-scanning/secret-scanning-pattern-pair-matches.md

@@ -1 +1 @@
-If access to a resource requires paired credentials, then secret scanning will create an alert only when both parts of the pair are detected in the same file. This ensures that the most critical leaks are not hidden behind information about partial leaks.
+If access to a resource requires paired credentials, then secret scanning will create an alert only when both parts of the pair are detected in the same file. This ensures that the most critical leaks are not hidden behind information about partial leaks. Pair matching also helps reduce false positives since both elements of a pair must be used together to access the provider's resource.