GitHub Secret Scanning and Push Protection: How to Deploy and Tune It So Developers Are Not Blocked by False Positives

Secret scanning and push protection require GitHub Advanced Security licenses (included in GitHub Enterprise Cloud/Server). Enable at the organization level to apply to all repositories:

Via GitHub API:

# Enable secret scanning for all repos in an org
curl -X PATCH \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "Accept: application/vnd.github+json" \
  https://api.github.com/orgs/your-org \
  -d '{"secret_scanning_enabled_for_new_repositories": true}'

# Enable push protection for all repos in an org
curl -X PATCH \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "Accept: application/vnd.github+json" \
  https://api.github.com/orgs/your-org \
  -d '{"secret_scanning_push_protection_enabled_for_new_repositories": true}'

For existing repositories, use the GitHub REST API to enable on each:

# Enable on a specific repository
curl -X PATCH \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "Accept: application/vnd.github+json" \
  https://api.github.com/repos/your-org/your-repo \
  -d '{"security_and_analysis": {"secret_scanning": {"status": "enabled"}, "secret_scanning_push_protection": {"status": "enabled"}}}'

Or via GitHub CLI for bulk enablement:

# Enable on all repos in an org using gh CLI
gh api /orgs/your-org/repos --paginate | \
  jq '.[].name' -r | \
  while read repo; do
    gh api --method PATCH /repos/your-org/$repo \
      -f 'security_and_analysis[secret_scanning][status]=enabled' \
      -f 'security_and_analysis[secret_scanning_push_protection][status]=enabled'
    echo "Enabled: $repo"
  done

Built-in patterns cover major third-party services but not internal systems. Create custom patterns for:

• Internal API gateway tokens
• Service-to-service authentication tokens
• Internal PKI certificate patterns
• Database connection strings with internal domain patterns

Create a custom pattern via the GitHub API:

# Create an org-level custom pattern
curl -X POST \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "Accept: application/vnd.github+json" \
  https://api.github.com/orgs/your-org/secret-scanning/patterns \
  -d '{
    "name": "Internal API Key",
    "pattern": "INTERNAL-[A-Z0-9]{32}",
    "secret_type": "internal_api_key",
    "keywords": ["INTERNAL-"],
    "description": "Internal API gateway authentication key"
  }'

Pattern design principles for low false-positive rates:

1. Require a keyword prefix: Patterns without a keyword anchor (like [A-Za-z0-9]{40}) match too broadly. Require a distinguishing prefix: apikey_, sk_live_, INTERNAL-, etc.
2. Specify minimum entropy: High-entropy random strings are more likely to be real secrets. Use character class ranges to enforce entropy: [A-Za-z0-9!@#$%]{32,64}
3. Test against false positive samples before deployment: GitHub allows dry-run testing of custom patterns against a sample of recent commits before activating them
4. Use the test functionality: Settings > Security > Code security and analysis > Custom patterns > [pattern] > Test -- paste sample content and verify the pattern matches real secrets but not example values in documentation

Push protection can be bypassed by developers when they have a legitimate reason (test credentials, example values, already-rotated secrets). Track and review bypass events:

# List all push protection bypass events in an org via API
curl -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "Accept: application/vnd.github+json" \
  "https://api.github.com/orgs/your-org/secret-scanning/alerts?state=open&resolution=used_in_tests" \
  | jq '.[] | {repo: .repository.full_name, secret_type: .secret_type, created_at: .created_at, resolution: .resolution}'

Bypass reasons developers can select:

• It's used in tests: The secret is a test/example value with no real access
• It's a false positive: The pattern matched something that is not actually a secret
• I'll fix it later: The developer acknowledges it is a real secret but will rotate it

"I'll fix it later" is the high-risk bypass reason. Configure a workflow that:

1. Sends an immediate Slack/Teams notification to the security team when this reason is selected
2. Creates a JIRA ticket with a 48-hour SLA for the developer to confirm the secret has been rotated
3. Follows up after 48 hours if the secret has not been rotated and the alert remains open

Configure this via GitHub Actions on the secret_scanning_alert webhook event:

# .github/workflows/secret-alert-webhook.yml
on:
  secret_scanning_alert:
    types: [created]
jobs:
  notify-security:
    runs-on: ubuntu-latest
    steps:
      - name: Notify on push protection bypass
        if: github.event.alert.push_protection_bypassed == true
        run: |
          curl -X POST ${{ secrets.SLACK_WEBHOOK }} \
            -H 'Content-type: application/json' \
            --data '{"text":"Push protection bypassed: ${{ github.event.alert.secret_type }} in ${{ github.event.repository.full_name }}"}'

Secret scanning generates alerts for secrets found in repository content. Triage alerts by severity:

Immediate response (within 1 hour):

• AWS access keys, Azure client secrets, GCP service account keys
• Database connection strings with production credentials
• Active OAuth tokens for production applications

For each high-severity alert:

1. Verify the secret is still active (check the provider's API for key validity)
2. Revoke the secret immediately at the source (AWS IAM, Azure portal, GCP IAM)
3. Generate a replacement credential
4. Update the application using the credential (via Secrets Manager or environment variable injection)
5. Remove the secret from git history (if it was committed, git history rewrite is required)

Removing a secret from git history:

# Use BFG Repo Cleaner (faster than git filter-branch)
bfg --replace-text secrets-to-remove.txt your-repo.git
git reflog expire --expire=now --all
git gc --prune=now --aggressive
git push --force --all
git push --force --tags

Note: git history rewrite requires force push and affects all forks. Notify all contributors to re-clone after history rewrite.

Lower priority (within 48 hours):

• Test credentials with no production access
• Internal system credentials for dev/staging environments
• Credentials that are already rotated

For lower-priority alerts, verify the credential is no longer active and close the alert with the appropriate resolution.

Track key metrics to demonstrate secret scanning program value and identify gaps:

# Count open secret scanning alerts by secret type
curl -H "Authorization: Bearer $GITHUB_TOKEN" \
  "https://api.github.com/orgs/your-org/secret-scanning/alerts?state=open&per_page=100" \
  | jq 'group_by(.secret_type) | map({type: .[0].secret_type, count: length}) | sort_by(.count) | reverse'

# Count alerts resolved in the last 30 days
curl -H "Authorization: Bearer $GITHUB_TOKEN" \
  "https://api.github.com/orgs/your-org/secret-scanning/alerts?state=resolved&per_page=100" \
  | jq '[.[] | select(.resolved_at > "'$(date -v-30d +%Y-%m-%d)'")] | length'

# Track bypass rate (bypasses as % of push protection blocks)
curl -H "Authorization: Bearer $GITHUB_TOKEN" \
  "https://api.github.com/orgs/your-org/secret-scanning/alerts?state=open" \
  | jq '[.[] | select(.push_protection_bypassed == true)] | length'

Monthly security metrics to report:

• Total alerts generated vs. resolved
• Mean time to remediation (MTTR) for critical secret types
• Push protection block rate (pushes blocked / total push protection evaluations)
• Bypass rate by reason category
• Custom pattern coverage vs. internal credential format inventory