Secret Scanning

# Alerts and Remediation Reference

Detailed reference for secret scanning alert types, validity checks, remediation workflows, and API access.

## Alert Types

### User Alerts

Generated when secret scanning detects a supported secret in the repository.

- Displayed in the repository **Security** tab
- Created for provider patterns, non-provider patterns, custom patterns, and AI-detected secrets
- Scanning covers entire Git history on all branches

### Push Protection Alerts

Generated when a contributor bypasses push protection to push a secret.

- Displayed in the Security tab (filter: `bypassed: true`)
- Record the bypass reason chosen by the contributor
- Include the commit and file where the secret was pushed

**Bypass reasons and their alert behavior:**

| Bypass Reason | Alert Status |
|---|---|
| It's used in tests | Closed (resolved as "used in tests") |
| It's a false positive | Closed (resolved as "false positive") |
| I'll fix it later | Open |

### Partner Alerts

Generated when GitHub detects a leaked secret matching a partner's pattern.

- Sent directly to the service provider (e.g., AWS, Stripe, GitHub)
- **Not** displayed in the repository Security tab
- Provider may automatically revoke the credential
- No action required by the repository owner

## Alert Lists

### Default Alerts List

The primary view showing alerts for:
- Supported provider patterns (e.g., GitHub PATs, AWS keys, Stripe keys)
- Custom patterns defined at repo/org/enterprise level

### Generic Alerts List

Separate view (toggle from default list) showing:
- Non-provider patterns (private keys, connection strings)
- AI-detected generic secrets (passwords)

**Limitations:**
- Maximum 5,000 alerts per repository (open + closed)
- Only first 5 detected locations shown for non-provider patterns
- Only first detected location shown for AI-detected secrets
- Not shown in security overview summary views

## Paired Credentials

When a resource requires paired credentials (e.g., access key + secret key):
- Alert is only created when BOTH parts are detected in the same file
- Prevents noise from partial leaks
- Reduces false positives

## Validity Checks

Validity checks verify whether a detected secret is still active.

### How It Works

1. Enable validity checks in repository/organization settings
2. GitHub periodically sends the secret to the issuer's API
3. Validation result is displayed on the alert

### Validation Statuses

| Status | Meaning | Priority |
|---|---|---|
| `Active` | Secret is confirmed to be valid and exploitable | 🔴 Immediate |
| `Inactive` | Secret has been revoked or expired | 🟡 Lower priority |
| `Unknown` | GitHub cannot determine validity | 🟠 Investigate |

### On-Demand Validation

Click the validation button on an individual alert to trigger an immediate check.

### Privacy

GitHub makes minimal API calls (typically GET requests) to the least intrusive endpoints, selecting endpoints that don't return personal information.

## Extended Metadata Checks

Provides additional context about detected secrets when validity checks are enabled.

### Available Metadata

Depends on what the service provider shares:
- Secret owner information
- Scope and permissions of the secret
- Creation date and expiration
- Associated account or project

### Benefits

- **Deeper insight** — know who owns a secret
- **Prioritize remediation** — understand scope and impact
- **Improve incident response** — quickly identify responsible teams
- **Enhance compliance** — ensure secrets align with governance policies
- **Reduce false positives** — additional context helps determine if action is needed

### Enabling

- Requires validity checks to be enabled first
- Can be enabled at repository, organization, or enterprise level
- Available via security configurations for bulk enablement

## Remediation Workflow

### Priority: Rotate the Credential

**Always rotate (revoke and reissue) the exposed credential first.** This is more important than removin