Convert "Interpreting secret risk assessment results" into a tutorial (#58120)

Co-authored-by: Laura Coursen <[email protected]>
Co-authored-by: Sam Browning <[email protected]>

Author: 3 people

content/code-security/securing-your-organization/understanding-your-organizations-exposure-to-leaked-secrets/interpreting-secret-risk-assessment-results.md

@@ -1,44 +1,96 @@
 ---
 title: 'Interpreting secret risk assessment results'
 shortTitle: 'Interpret results'
-intro: 'Use the results from your {% data variables.product.prodname_secret_risk_assessment %} report to improve your organization''s security.'
+intro: 'Understand the results from your {% data variables.product.prodname_secret_risk_assessment %} and prioritize leak remediation.'
+permissions: 'Organization owners, security managers, and users with the **admin** role'
 allowTitleToDifferFromFilename: true
-type: how_to
 versions:
   feature: secret-risk-assessment
 topics:
-  - Code Security
-  - Secret scanning
   - Secret Protection
   - Organizations
   - Security
+contentType: tutorials
 ---
 
-The {% data variables.product.prodname_secret_risk_assessment %} dashboard displays point-in-time insights into the secrets detected in your organization. {% data reusables.secret-risk-assessment.link-conceptual-information %}
+## Introduction
+
+In this tutorial, you'll interpret your secret risk assessment results, and learn how to:
+
+* Understand risk metrics on the dashboard
+* Identify high-risk secret leaks
+* Prioritize secrets for remediation
 
 ## Prerequisites
 
-You need to generate a {% data variables.product.prodname_secret_risk_assessment %} report and wait for the scan to complete before being able to view and export the results. See [AUTOTITLE](/code-security/securing-your-organization/understanding-your-organizations-exposure-to-leaked-secrets/viewing-the-secret-risk-assessment-report-for-your-organization#generating-an-initial-secret-risk-assessment) and [Exporting the {% data variables.product.prodname_secret_risk_assessment %} to CSV](/code-security/securing-your-organization/understanding-your-organizations-exposure-to-leaked-secrets/viewing-the-secret-risk-assessment-report-for-your-organization#exporting-the-secret-risk-assessment-to-csv).
+You must generate a {% data variables.product.prodname_secret_risk_assessment %} report and wait for the scan to complete. See [AUTOTITLE](/code-security/securing-your-organization/understanding-your-organizations-exposure-to-leaked-secrets/viewing-the-secret-risk-assessment-report-for-your-organization#generating-an-initial-secret-risk-assessment).
+
+## Step 1: Understand your dashboard metrics
+
+Once your assessment completes, review the key metrics at the top of the dashboard:
+
+* **Total secrets**: Total number of secret leaks found across your organization
+* **Public leaks**: Distinct secrets found in **public** repositories
+* **Preventable leaks**: Leaks that push protection could have prevented
+
+You can also determine the number of secrets found in your **private repositories** by subtracting the number of public leaks from your total secrets. While remediating these secrets is less immediately important, they still pose risk if someone gains unauthorized access to your repositories, or if a repository is made public.
+
+## Step 2: Understand secret categories
+
+Look at the **Secret categories** section to understand **what types of secrets** were leaked.
+
+* **Provider patterns**: Specific secret formats for known services (AWS, Azure, {% data variables.product.github %} tokens)
+* **Generic patterns**: Generic secret formats like private keys, API keys, passwords
+
+Provider patterns are often easier to identify and revoke because you know exactly which service they belong to. Generic patterns may require more investigation.
+
+## Step 3: Identify how many repositories are affected
+
+Check the **Repositories with leaks** metric, which shows how many of your repositories contain secret leaks.
+
+If a **high percentage** of repositories contain leaks, this may indicate:
+* A widespread culture issue around secret management
+* A need for organization-wide training
+* Missing guardrails like push protection, which blocks secrets before they are committed
+
+If only a **few** repositories contain leaks, you can:
+* Focus remediation efforts on specific teams
+* Use the leak information to determine which repositories are high-risk areas
+
+## Step 4: Review leaked secrets by type
+
+Scroll to the bottom to see the detailed **Secret type** table, which includes:
+
+* **Secret type**: The specific kind of secret
+* **Distinct repositories**: How many different repositories contain this type
+* **Secrets found**: Total count of this secret type across all repositories
+
+The table sorts by highest count automatically, helping you identify the greatest risks.
+
+If you see **many secrets of the same type** (for example, multiple AWS keys), this indicates:
+* Developers may not be using environment variables
+* Missing documentation on secret management
+
+## Step 5: Prioritizing remediation and related actions
 
-## Prioritizing high-risk leaks for remediation
+Now that you understand the metrics, prioritize remediation based on risk.
 
-To understand your secrets' footprint and exposure to secrets leaks, review the **Total secrets**,**Public leaks** and **Secret locations** metrics.
+The highest priority secrets are **leaked provider patterns in public repositories**, because they are:
 
-Next, identify the areas in your organization where leaked secrets pose the highest threat to security.
+* Accessible to anyone on the internet
+* Often easier to identify and revoke, since you know which service they belong to
 
-* **Leaked secrets that are still active** usually present the greatest risk to security. Prioritize any active secrets for remediation ahead of inactive secrets. For more information about checking the validity of a detected credential, see [AUTOTITLE](/enterprise-cloud@latest/code-security/secret-scanning/enabling-secret-scanning-features/enabling-validity-checks-for-your-repository) in the {% data variables.product.prodname_ghe_cloud %} documentation.
-* Similarly, **secrets leaked in public repositories** are usually considered a higher risk and priority, than those secrets leaked in private {% ifversion ghec or ghes %}or internal {% endif %}repositories.
-* The **Repositories with leaks** metric can indicate how frequent, or the extent of, secret leaks across your organization. A large proportion of repositories with secret leaks may suggest that developer education and increased security awareness around secrets is important for your organization.
+Next, you can address secrets that present lower risk or require more extensive efforts to remediate. These can be:
 
-## Identifying areas of exposure
+* **Generic patterns in public repositories**, which may require investigation to identify the service or system they belong to
+* **Private repository leaks**, that represent a lower immediate risk but should still be addressed
 
-Review the **Preventable leaks** and **Secret categories** metrics to understand your current secret detection coverage, in addition to learning how {% data variables.product.github %} can help prevent future secret leaks.
+Finally, look for the following indicators, which may require additional prevention efforts beyond leak remediation:
 
-* Secret leaks that could have been prevented using {% data variables.product.prodname_GH_secret_protection %} features such as {% data variables.product.prodname_secret_scanning %} and push protection are shown by the **Preventable leaks** metric.
-* Using the **Secret categories** metric and the **Token type** table, search for patterns in the type of secrets leaked across your organization.
-  * Common areas and repeated occurrences of leaked secrets may suggest particular CI/CD workflows or development processes in your organization that are contributing to the results.
-  * You may also be able to identify specific teams, repositories, or networks that are more prone to secret leaks, and therefore require additional security measures or management to be put in place.
+* **Many repositories with leaks**: Indicates need for organization-wide training and improved security awareness
+* **Repeated secret types**: Suggests specific workflows or teams need targeted intervention
+* **Common secret categories**: May point to particular CI/CD processes requiring security improvements
 
-## Adopt {% data variables.product.prodname_GH_secret_protection %} to prevent leaks
+## Next steps
 
-We recommend purchasing {% data variables.product.prodname_GH_secret_protection %} products to improve your organization's exposure to secret leaks and optimize your secret detection rates. {% data variables.product.prodname_GH_secret_protection %} is a continuous monitoring and detection solution that is the most effective path for secure development. See [AUTOTITLE](/code-security/securing-your-organization/understanding-your-organizations-exposure-to-leaked-secrets/choosing-github-secret-protection).
+{% data variables.product.prodname_GH_secret_protection %} provides continuous monitoring and push protection to help remediate any remaining secrets and prevent future leaks. To help you evaluate whether {% data variables.product.prodname_GH_secret_protection %} is right for your organization, you can estimate the cost before enabling it. See [AUTOTITLE](/code-security/securing-your-organization/understanding-your-organizations-exposure-to-leaked-secrets/estimating-the-price-of-secret-protection).