Skip to content

Commit 4c556ca

Browse files
mchammer01mchammer01
authored
Create a tutorial on assessing the impact of GHSP (#60829)
1 parent 31c784e commit 4c556ca

2 files changed

Lines changed: 150 additions & 1 deletion

File tree

‎content/code-security/tutorials/remediate-leaked-secrets/assessing-ghsp-impact.md‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
---
2+
title: Assessing the impact of GitHub Secret Protection
3+
intro: 'Measure how {% data variables.product.prodname_GH_secret_protection_always %} reduces secret exposure across your organization, so you can demonstrate value and identify areas to strengthen your security posture.'
4+
allowTitleToDifferFromFilename: true
5+
shortTitle: Assess GHSP impact
6+
versions:
7+
fpt: '*'
8+
ghec: '*'
9+
ghes: '*'
10+
contentType: tutorials
11+
category:
12+
- Protect your secrets
13+
---
14+
15+
## Introduction
16+
17+
After enabling {% data variables.product.prodname_GH_secret_protection_always %} (GHSP) for your organization, you'll want to assess its impact and understand how it's protecting your organization. This tutorial walks you through accessing secret-related data and interpreting the results to measure GHSP performance.
18+
19+
In this tutorial, you'll learn how to:
20+
* Access your organization's security overview to view {% data variables.product.prodname_secret_scanning %} data
21+
* Review the {% data variables.product.prodname_secret_risk_assessment %} (SRA) report
22+
* Compare and analyze the data to assess GHSP's impact
23+
24+
If you don't have a historic SRA report from before your GHSP rollout, you can still assess GHSP's effectiveness. Skip ahead to [Step 4: Analyze security overview data trends](#step-4-analyze-security-overview-data-trends).
25+
26+
## Prerequisites
27+
28+
* You need to have the organization owner or security manager role.
29+
* {% data variables.product.prodname_secret_protection %} must be enabled for your organization.
30+
31+
## Step 1: Access the organization-level security overview
32+
33+
The security overview provides real-time data about {% data variables.secret-scanning.alerts %} across your organization.
34+
35+
{% data reusables.organizations.navigate-to-org %}
36+
{% data reusables.organizations.security-overview %}
37+
1. On the security overview page, click the **Risk** tab to view secret scanning data.
38+
The overview shows:
39+
* Total number of open {% data variables.secret-scanning.alerts %}
40+
* Alert trends over time
41+
* Breakdown by repository
42+
* Alert severity distribution
43+
44+
## Step 2: View your {% data variables.product.prodname_secret_risk_assessment %} report
45+
46+
If you previously ran a SRA report, you can access the report to establish a baseline.
47+
48+
{% data reusables.organizations.navigate-to-org %}
49+
{% data reusables.organizations.security-overview %}
50+
{% data reusables.security-overview.open-assessments-view %}
51+
1. Review the key metrics from the assessment, including:
52+
* Number of exposed secrets detected
53+
* Types of secrets found
54+
* Repositories with the highest risk
55+
* Recommended remediation actions
56+
57+
> [!NOTE] The SRA report represents a point-in-time snapshot of your secret exposure before or during your GHSP implementation.
58+
59+
## Step 3: Compare SRA data with current security overview
60+
61+
The SRA report is a **point-in-time** snapshot taken before or during your GHSP rollout, while the security overview shows **real-time** data that updates as alerts are opened and resolved. To make a meaningful comparison, you need to ensure both datasets cover the same secret types.
62+
63+
### Filter to comparable pattern types
64+
65+
The SRA report only detects **provider patterns** and **generic patterns**. The security overview, however, may also include results from custom patterns you've configured since enabling GHSP. To ensure an accurate comparison, filter the security overview to the same pattern types the SRA covers.
66+
67+
#### Using the UI
68+
69+
In the security overview **Risk** tab, use the filter bar to narrow results to provider and generic patterns only, excluding any custom patterns.
70+
71+
#### Using the API
72+
73+
Alternatively, you can use the REST API to programmatically retrieve alerts filtered by secret type. For example, to list only default (provider) {% data variables.secret-scanning.alerts %} for a repository:
74+
75+
```shell copy
76+
gh api \
77+
-H "Accept: application/vnd.github+json" \
78+
/orgs/ORG/secret-scanning/alerts --paginate
79+
```
80+
81+
This returns alerts for default patterns only. To also include generic patterns in your results, pass the specific token names using the `secret_type` parameter.
82+
83+
For more information, see [AUTOTITLE](/rest/secret-scanning/secret-scanning).
84+
85+
### Build your comparison
86+
87+
1. Using the filtered data, create a comparison table with these key metrics:
88+
89+
| Metric | SRA report (Baseline) | Current security overview (Filtered) | Change |
90+
|--------|----------------------|--------------------------------------|--------|
91+
| Total exposed secrets | [SRA number] | [Current number] | [Difference] |
92+
| Critical alerts | [SRA number] | [Current number] | [Difference] |
93+
| Affected repositories | [SRA number] | [Current number] | [Difference] |
94+
95+
1. Calculate the percentage change for each metric:
96+
* **Positive impact indicators:** Reduction in total exposed secrets, fewer critical alerts
97+
* **Areas for improvement:** New alerts appearing, specific repositories with increasing trends
98+
99+
1. Note any significant differences in:
100+
* Secret types being detected
101+
* Repository coverage
102+
* Alert resolution rates
103+
104+
## Step 4: Analyze security overview data trends
105+
106+
Even without an SRA report, you can assess GHSP effectiveness by analyzing trends in the security overview.
107+
108+
{% data reusables.organizations.navigate-to-org %}
109+
{% data reusables.organizations.security-overview %}
110+
1. In the security overview **Risk** tab, look at the trend graph showing {% data variables.secret-scanning.alerts %} over time.
111+
1. Identify patterns:
112+
* **Declining trend:** Indicates successful remediation and prevention
113+
* **Plateau:** May suggest steady state or need for increased awareness
114+
* **Rising trend:** May indicate increased detection coverage or new secret introduction
115+
116+
1. Click on individual repositories to drill down into specific alert details.
117+
1. Review the alert resolution rate:
118+
* Navigate to the **{% data variables.product.prodname_security_and_quality_tab %}** tab for your organization.
119+
* Under "Findings", Click **{% data variables.product.prodname_secret_scanning_caps %}**.
120+
* Check how many alerts have been closed versus the number of alerts that remain open.
121+
* Select the alert type you're interested in.
122+
* Assess average time to resolution.
123+
124+
## Step 5: Interpret the results and take action
125+
126+
Based on your analysis, determine the next steps.
127+
128+
### If you're seeing positive trends
129+
130+
* Document the improvement to demonstrate GHSP value
131+
* Identify successful practices to replicate across other repositories
132+
* Consider expanding GHSP coverage to additional repositories or organizations
133+
134+
### If you're seeing areas for improvement
135+
136+
* Review repositories with increasing alerts or slow resolution times
137+
* Provide additional training to development teams
138+
* Assess whether custom patterns need to be configured
139+
* Check if push protection is enabled to prevent new secrets from being introduced
140+
141+
### Ongoing monitoring
142+
143+
* Schedule regular reviews (weekly or monthly) of the security overview
144+
* Set up notifications for new {% data variables.secret-scanning.alerts %}
145+
* Track metrics over time to demonstrate continuous improvement
146+
147+
## Further reading
148+
149+
* To understand {% data variables.product.prodname_secret_scanning %} metrics in detail, see [AUTOTITLE](/code-security/security-overview/viewing-security-insights).

‎content/code-security/tutorials/remediate-leaked-secrets/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ versions:
88
contentType: tutorials
99
children:
1010
- /calculating-the-cost-savings-of-push-protection
11+
- /assessing-ghsp-impact
1112
- /evaluating-alerts
1213
- /remediating-a-leaked-secret
1314
---
14-

0 commit comments

Comments
 (0)