AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

secret-scanning

Guide for configuring and managing GitHub secret scanning, push protection, custom patterns, and secret alert remediation. For pre-commit secret scanning in AI coding agents via the GitHub MCP Server, this skill references the Advanced Security plugin (`advanced-security@copilot-plugins`). Use this skill when enabling secret scanning, setting up push protection, defining custom patterns, triaging alerts, resolving blocked pushes, or when an agent needs to scan code for secrets before committing.

Original source
github
License
MIT
Pinned revision
5269f7ea2d6c3a9bfda5ed878b6726cf509121fd

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

Ask your assistant

Use Agentic Memory skills to read github--secret-scanning at revision 5269f7ea2d6c3a9bfda5ed878b6726cf509121fd, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 4

references/alerts-and-remediation.md

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 removing the secret from Git history.

Step-by-Step Remediation

  1. Receive alert — via Security tab, email notification, or webhook
  2. Assess severity — check validity status (active = urgent)
  3. Rotate the credential — revoke the old credential and generate a new one
  4. Update references — update all code/config that used the old credential
  5. Investigate impact — check logs for unauthorized use during the exposure window
  6. Close the alert — mark as resolved with appropriate reason
  7. Optionally clean Git history — remove from commit history (time-intensive)

Removing Secrets from Git History

If needed, use git filter-repo (recommended) or BFG Repo-Cleaner:

# Install git-filter-repo
pip install git-filter-repo

# Remove a specific file from all history
git filter-repo --path secrets.env --invert-paths

# Force push the cleaned history
git push --force --all

Note: Rewriting history is disruptive — it invalidates existing clones and PRs. Only do this when absolutely necessary and after rotating the credential.

Dismissing Alerts

Choose the appropriate reason:

| Reason | When to Use | |---|---| | False positive | Detected string is not a real secret | | Revoked | Credential has already been revoked/rotated | | Used in tests | Secret is only in test code with acceptable risk |

Add a dismissal comment for audit trail.

Alert Notifications

Alerts generate notifications via:

  • Email — to repository admins, organization owners, security managers
  • Webhooks — secret_scanning_alert event
  • GitHub Actions — secret_scanning_alert event trigger
  • Security overview — aggregated view at organization level

REST API

List Alerts

GET /repos/{owner}/{repo}/secret-scanning/alerts

Query parameters: state (open/resolved), secret_type, resolution, sort, direction

Get Alert Details

GET /repos/{owner}/{repo}/secret-scanning/alerts/{alert_number}

Returns: secret type, secret value (if permitted), locations, validity, resolution status, dismissed_comment

Update Alert

PATCH /repos/{owner}/{repo}/secret-scanning/alerts/{alert_number}

Body: state (open/resolved), resolution (false_positive/revoked/used_in_tests/wont_fix), resolution_comment

List Alert Locations

GET /repos/{owner}/{repo}/secret-scanning/alerts/{alert_number}/locations

Returns: file path, line numbers, commit SHA, blob SHA

Organization-Level Endpoints

GET /orgs/{org}/secret-scanning/alerts

Lists alerts across all repositories in the organization.

Webhook Events

secret_scanning_alert

Triggered when a secret scanning alert is:

  • Created
  • Resolved
  • Reopened
  • Validated (validity status changes)

Payload includes: alert number, secret type, resolution, commit SHA, and location details.

Exclusion Configuration

secret_scanning.yml

Place at .github/secret_scanning.yml to auto-close alerts for specific paths:

paths-ignore:
  - "docs/**"              # Documentation with example secrets
  - "test/fixtures/**"     # Test fixture data
  - "**/*.example"         # Example configuration files
  - "samples/credentials"  # Sample credential files

Limits:

  • Maximum 1,000 entries
  • File must be under 1 MB
  • Excluded paths are also excluded from push protection

Alerts for excluded paths are closed as "ignored by configuration."