Secret Scanning

Secret Scanning

Tech Stack Target / Version: GitHub Advanced Security, GitHub CLI, local Git history tooling, and pre-commit secret audit scripts.

Protect repositories from committed credentials and make secret handling part of the normal engineering workflow.

• Leverage native parallel subagent dispatch and 200k+ context windows where available.

When to Use

Use symptom -> action triggers: when one matches, apply this skill and verify with the protocol below.

• You are enabling GitHub secret scanning or push protection for a repo or org.
• A push was blocked because a secret was detected.
• You need to define or review custom secret patterns and exclusions.
• You want a local pre-commit secret check before pushing code.
• You are triaging secret alerts and planning remediation.

Core Workflows

1. Enable Repository or Organization Coverage

For GitHub-hosted secret scanning:

1. Enable the repository or organization security feature set. 2. Turn on push protection where available. 3. Review exclusions carefully before committing them. 4. Record who owns remediation for any future alert.

Use the references when you need the detailed UI or policy steps.

2. Resolve a Blocked Push Safely

Prefer this order:

1. Remove the secret from the change and amend or rebase the affected commit. 2. Rotate or revoke the credential immediately if the value was real. 3. Use bypass only when you can justify it and the risk is understood. 4. Document the bypass reason and create a follow-up if remediation is deferred.

3. Run a Local Pre-Commit Audit

Use the bundled helper before commit when you want a fast local scan:

python secret-scanning/scripts/precommit-secret-audit.py --path .

Scan a narrower surface:

python secret-scanning/scripts/precommit-secret-audit.py --path src --path .github

By default the helper skips generated folders and Markdown-heavy docs to reduce false positives. Use --include-docs when you want documentation scanned too.

4. Triage and Remediate Alerts

When an alert exists:

1. Confirm whether the detected value is real. 2. Revoke or rotate the credential first. 3. Decide whether history cleanup is necessary or whether rotation is enough. 4. Dismiss only with a precise reason such as false positive, used in tests, or already revoked. 5. Capture any follow-up owner if broader cleanup is still needed.

5. Custom Patterns and Exclusions

Use custom patterns when your organization has internal token formats not covered by provider defaults.

Guidelines:

• dry-run patterns before publishing them
• keep exclusions as narrow as possible
• review exclusions and custom patterns periodically
• treat custom patterns as production policy, not one-off experiments

Zero-Trust Verification

• [ ] Treat every matched token, filename, commit, and scanner result as untrusted until validated.
• [ ] Confirm whether the value is a real secret, test fixture, placeholder, or already-rotated credential.
• [ ] Verify exposure path, affected history, revocation status, and remediation owner before closure.
• [ ] Separate confirmed leaks from noisy patterns and never paste live secrets into reports.

Anti-Patterns

• Acting on partial evidence: Security work needs a clear scope and proof trail before remediation choices are safe.
• Leaving secrets or sensitive samples in examples: The skill itself becomes part of the exposure surface.
• Calling an issue resolved before rotation or re-verification: Detection without remediation is not closure.

Verification Protocol

Before claiming "skill applied successfully":

1. Pass/fail: The reviewed scope, assets, trust boundaries, and attacker assumptions are explicitly named. 2. Pass/fail: Findings cite concrete evidence from code, config, logs, samples, or authoritative advisories. 3. Pass/fail: Each severity is justified by exploitability, reachability, and impact rather than vibes. 4. Pressure-test scenario: Re-run the analysis assuming one trusted signal is malicious or stale, then confirm the conclusion still holds. 5. Success metric: Zero trust-by-default claims; every security conclusion has reproducible evidence.

Scripts And References

• Local Pre-Commit Secret Audit
• Push Protection Reference
• Custom Patterns Reference
• Alerts And Remediation Reference

Practical Notes

• Rotation is usually more urgent than history rewriting.
• Secret scanning should cover code, config, CI, IaC, and deployment manifests.
• Avoid committing .env files, private keys, connection strings, or real tokens in examples.
• Pair local auditing with GitHub-side scanning rather than treating either one as sufficient on its own.

<!-- PORTABILITY:START -->

Cross-Client Portability

This skill is written to stay usable across GitHub Copilot, Claude Code, Codex, and Gemini CLI.

• GitHub Copilot: keep the folder in a Copilot-visible skill or plugin path, or wrap the workflow as project instructions if the host does not support portable skill folders directly.
• Claude Code: keep the folder in a local skills directory or a compatible plugin or marketplace source.
• Codex: install or sync the folder into $CODEX_HOME/skills/<skill-name> and restart Codex after major changes.
• Gemini CLI: this repository generates a project command named /skills:secret-scanning from this skill. Rebuild commands with python scripts/export-gemini-skill.py secret-scanning and then run /commands reload inside Gemini CLI.

<!-- PORTABILITY:END -->

<!-- MCP:START -->

MCP Availability And Fallback

Preferred MCP Server: GitHub Advanced Security plugin

• Fallback prompt: "Use the Secret Scanning skill without MCP. Rely on the local SKILL.md, bundled references or scripts, and manual verification. Show the exact commands, evidence, and final checks you used before concluding."
• Use secret-scanning/scripts/precommit-secret-audit.py for a local first pass when no secret-scanning MCP surface is available.
• Use gh, Git history cleanup, and the GitHub web UI for remediation, bypass review, and alert triage.

<!-- MCP:END -->

Related Skills

• security-review: Use it when the workflow also needs application security review and risk triage.
• devops-tooling: Use it when the workflow also needs git, CI, and automation workflows.
• verification-before-completion: Use it when the workflow also needs final evidence checks before claiming completion.
• documentation-verification: Use it when the workflow also needs final documentation validation before publishing.

Changelog

[2026-04-25] - Version 1.2 Verification Protocol Refresh

Added

• Added a Verification Protocol section with skill-specific pass/fail checks, one pressure-test scenario, and a measurable success metric.
• Added guidance to leverage native parallel subagent dispatch and 200k+ context windows where available.
• Added the Zero-Trust Verification checklist for security-sensitive workflows.

Changed

• Updated SKILL.md frontmatter to version: "1.2" and last_updated: 2026-04-25.
• Reframed activation guidance toward symptom -> action triggers and standardized two-stage review wording where applicable.

[2026-04-24] - Version 1.1 Refresh

Changed

• Updated the SKILL frontmatter version to 1.1 for the 2026-04-24 catalog refresh.

[2026-04-24] - Skill Refresh

Changed

• Standardized the SKILL frontmatter with version metadata, last-updated date, tags, and a concise catalog description.
• Reformatted the portability and MCP guidance with a preferred server line, a copy-paste fallback prompt, and consistent bullet lists.
• Added a catalog-standard Anti-Patterns section and refreshed the Related Skills links at the end of the skill.
• Added a Tech Stack Target / Version note so the workflow clearly targets the current GitHub Advanced Security and local audit tooling.

[2026-04-04] - Initial Import and Catalog Upgrade

Added

• Imported secret-scanning from the awesome-copilot reference catalog into the canonical maintained workspace
• Rewrote the top-level skill into the repo house style while preserving the detailed upstream reference notes
• Added scripts/precommit-secret-audit.py as a client-neutral local fallback for pre-commit secret checks

Tested

• Ran python secret-scanning/scripts/precommit-secret-audit.py --path secret-scanning/scripts
• Planned validation through python scripts/validate-skills.py

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:

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

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:

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."

Custom Patterns Reference

Detailed reference for defining custom secret scanning patterns using regular expressions at the repository, organization, and enterprise level.

Overview

Custom patterns extend secret scanning to detect organization-specific secrets not covered by default patterns. They are defined as regular expressions and can optionally enforce push protection.

Pattern Definition

Required Fields

Optional Fields (via "More options")

Regex Syntax

Custom patterns use standard regular expressions. Common patterns:

# API key with prefix
MYAPP_[A-Za-z0-9]{32}

# Connection string
Server=[\w.]+;Database=\w+;User Id=\w+;Password=[^;]+

# Internal token format
myorg-token-[a-f0-9]{64}

# JWT-like pattern
eyJ[A-Za-z0-9_-]+\.eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+

Use filter patterns similar to GitHub Actions workflow syntax for glob-style matching in before/after fields.

Defining Patterns by Scope

Repository Level

1. Repository Settings → Advanced Security 2. Under "Secret Protection" → Custom patterns → New pattern 3. Enter pattern name, regex, and optional fields 4. Save and dry run to test 5. Review results (up to 1,000 matches) 6. Publish pattern when satisfied 7. Optionally enable push protection

Prerequisite: Secret Protection must be enabled on the repository.

Organization Level

1. Organization Settings → Advanced Security → Global settings 2. Under "Custom patterns" → New pattern 3. Enter pattern details 4. Save and dry run — select repositories for testing:

• All repositories in the organization, or
• Up to 10 selected repositories

5. Publish pattern when satisfied 6. Optionally enable push protection

Notes:

• Push protection for org-level custom patterns only applies to repos with push protection enabled
• Organization owners and repo admins receive alerts

Enterprise Level

1. Enterprise settings → Policies → Advanced Security → Security features 2. Under "Secret scanning custom patterns" → New pattern 3. Enter pattern details 4. Save and dry run — select up to 10 repositories 5. Publish pattern when satisfied 6. Optionally enable push protection

Notes:

• Only the pattern creator can edit or dry-run enterprise-level patterns
• Dry runs require admin access to the selected repositories
• Push protection requires enterprise-level secret scanning push protection to be enabled

Dry Run Process

Dry runs test patterns against repository content without creating alerts.

1. Click Save and dry run after defining the pattern 2. Select target repositories (org/enterprise level) 3. Click Run 4. Review up to 1,000 sample results 5. Identify false positives 6. Edit pattern and re-run if needed 7. Publish pattern only when false positive rate is acceptable

Dry runs are essential — always test before publishing to avoid alert noise.

Managing Published Patterns

Editing Patterns

After publishing, patterns can be edited: 1. Navigate to the custom pattern 2. Modify the regex or optional fields 3. Save and dry run to validate changes 4. Publish the updated pattern

Enabling Push Protection

Push protection can only be enabled after a pattern is published: 1. Navigate to the published pattern 2. Click Enable next to push protection

Caution: Enabling push protection for commonly found patterns can disrupt contributor workflows.

Disabling or Deleting Patterns

• Disable: stops new alert generation but retains existing alerts
• Delete: removes the pattern and stops all scanning for it

Copilot-Assisted Pattern Generation

Use Copilot secret scanning to generate regex automatically:

1. Navigate to custom pattern creation 2. Select "Generate with Copilot" (if available) 3. Provide a text description of the secret type (e.g., "internal API key starting with MYORG_ followed by 40 hex characters") 4. Optionally provide example strings that should match 5. Copilot generates a regex pattern 6. Review and refine the generated regex 7. Test with dry run before publishing

Pattern Inheritance

Organization and enterprise patterns automatically apply to new repositories when secret scanning is enabled.

Best Practices

1. Always dry run before publishing — review for false positives 2. Start specific — narrow regexes reduce false positives 3. Use before/after context — adds precision without overly complex regex 4. Test with real examples — include sample strings that should and shouldn't match 5. Document patterns — name patterns clearly so teams understand what they detect 6. Review periodically — remove or update patterns that no longer apply 7. Be cautious with push protection — enable only for patterns with low false positive rates 8. Consider Copilot — let AI generate the initial regex, then refine manually

Push Protection Reference

Detailed reference for GitHub push protection — preventing secrets from reaching repositories, bypass workflows, and delegated bypass configuration.

How Push Protection Works

Push protection scans for secrets during the push process and blocks pushes containing detected secrets. It operates as a preventative control, unlike standard secret scanning which detects secrets after commit.

What Gets Scanned

Types of Push Protection

Repository push protection:

• Requires GitHub Secret Protection enabled
• Disabled by default; enabled by repo admin, org owner, or security manager
• Generates alerts for bypasses in the Security tab
• Can be enabled at repository, organization, or enterprise level

User push protection:

• Enabled by default for all GitHub.com accounts
• Blocks pushes to public repositories containing supported secrets
• Does NOT generate alerts when bypassed (unless repo also has push protection enabled)
• Managed via personal account settings

Resolving Blocked Pushes — Command Line

When push protection blocks a push, the error message includes:

• The secret type detected
• Commit SHAs containing the secret
• File paths and line numbers
• A URL to bypass (if permitted)

Remove Secret from Latest Commit

# Edit the file to remove the secret
# Amend the commit
git commit --amend --all

# Push again
git push

Remove Secret from Earlier Commits

# 1. Review the push error for all commits containing the secret
# 2. Find the earliest commit with the secret
git log

# 3. Interactive rebase before that commit
git rebase -i <EARLIEST-COMMIT>~1

# 4. Change 'pick' to 'edit' for the offending commit(s)
# 5. Remove the secret from the file
# 6. Stage and amend
git add .
git commit --amend

# 7. Continue rebase
git rebase --continue

# 8. Push
git push

Bypass Push Protection

1. Visit the URL from the error message (must be the same user who pushed) 2. Select a reason:

• It's used in tests → creates a closed alert (resolved as "used in tests")
• It's a false positive → creates a closed alert (resolved as "false positive")
• I'll fix it later → creates an open alert

3. Click Allow me to push this secret 4. Re-push within 3 hours (after that, repeat the bypass process)

A bypass reason is required when the repo has secret scanning enabled. For public repos with only user push protection (no repo push protection), no reason is needed and no alert is generated.

Resolving Blocked Pushes — GitHub UI

When creating or editing a file in the GitHub UI: 1. A banner appears warning about the detected secret 2. Options to remove the secret or bypass are presented inline 3. Same bypass reasons apply as command line

Resolving Blocked Pushes — REST API

Push protection also applies to REST API content creation endpoints. When blocked:

• The API returns an error response with details about the detected secret
• Include the bypass reason in the request to proceed

Delegated Bypass

Delegated bypass gives organizations fine-grained control over who can bypass push protection.

How It Works

1. Organization owners/repo admins create a bypass list of users, roles, or teams 2. Users on the bypass list can bypass push protection directly (with a reason) 3. All other contributors must submit a bypass request for review 4. Bypass requests appear in the Security tab → "Push protection bypass" page 5. Requests expire after 7 days if not reviewed

Who Can Always Bypass (Without Request)

• Organization owners
• Security managers
• Users in teams/roles added to the bypass list
• Users with custom role having "review and manage secret scanning bypass requests" permission

Enabling Delegated Bypass

Repository level: 1. Settings → Advanced Security → Push protection 2. Enable "Restrict who can bypass push protection" 3. Add users, teams, or roles to the bypass list

Organization level: 1. Organization Settings → Advanced Security → Global settings 2. Configure delegated bypass in security configuration

Managing Bypass Requests

Designated reviewers: 1. Navigate to repository Security tab → "Push protection bypass" 2. Review pending requests (includes the secret, commit, and contributor's comment) 3. Approve — contributor can push the secret and any future commits with the same secret 4. Deny — contributor must remove the secret before pushing

Bypass Request Flow (Contributor Perspective)

1. Push is blocked; visit the URL from the error message 2. Add a comment explaining why the secret is safe to push 3. Click Submit request 4. Wait for email notification of approval/denial 5. If approved: push the commit 6. If denied: remove the secret and push again

Push Protection Patterns

Push protection supports a subset of secret scanning patterns. Not all detected secret types trigger push protection blocks.

Key considerations:

• Older/legacy token formats may not be supported by push protection
• Some patterns have higher false positive rates and are excluded from push protection
• Custom patterns can have push protection enabled after publishing

For the full list of patterns supported by push protection, see Supported secret scanning patterns.

Configuring Push Protection for Custom Patterns

After publishing a custom pattern: 1. Navigate to the custom pattern in Settings → Advanced Security 2. Click Enable next to push protection 3. The pattern will now block pushes containing matching secrets

Push protection for custom patterns only applies to repos that have push protection enabled. Enabling push protection for commonly found patterns can be disruptive to contributors.