Skill: Secret Scan

Purpose

Detect accidentally committed secrets, API keys, passwords, and other sensitive credentials in code repositories.

When to Use

• Pre-commit verification
• Pull request checks
• Repository audits
• Security incident response
• Compliance verification
• New repository onboarding

---

Secret Categories

API Keys & Tokens

Provider	Pattern	Example Format
AWS Access Key	AKIA[0-9A-Z]{16}	AKIAIOSFODNN7EXAMPLE
AWS Secret Key	40-char base64	wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
GitHub Token	ghp_[a-zA-Z0-9]{36}	ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
GitLab Token	glpat-[a-zA-Z0-9-]{20}	glpat-xxxxxxxxxxxxxxxxxxxx
Google API Key	AIza[0-9A-Za-z-_]{35}	AIzaSyxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Stripe Key	sk_live_[a-zA-Z0-9]{24}	sk_live_[EXAMPLE_KEY_HERE]
OpenAI Key	sk-[a-zA-Z0-9]{48}	sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Slack Token	xox[baprs]-[0-9-]+	xoxb-123456789-123456789-xxxxx

Credentials

Type	Pattern	Risk Level
Password in code	password\s*=\s*["'][^"']+["']	Critical
Private key	-----BEGIN.*PRIVATE KEY-----	Critical
Database URL	`(mysql	postgres
Connection string	Server=.*;Password=.*	Critical
Basic auth	Authorization.*Basic\s+[A-Za-z0-9+/=]+	High
Bearer token	Bearer\s+[A-Za-z0-9._-]+	High

Cloud Provider Secrets

Provider	Secret Type	Pattern
Azure	Connection String	DefaultEndpointsProtocol=.*AccountKey=.*
Azure	Service Principal	"clientSecret":\s*"[^"]+"
GCP	Service Account	"private_key":\s*"-----BEGIN
Firebase	Config	apiKey.*firebase

---

Detection Methods

Pattern Matching

## Pattern-Based Detection

### High-Confidence Patterns
- Provider-specific key formats (e.g., AWS AKIA prefix)
- Known secret variable names
- Base64 with sufficient length
- Private key headers/footers

### Context Patterns
- Assignment to secret-named variables
- Configuration file formats
- Environment variable references

Entropy Analysis

## Entropy-Based Detection

### High-Entropy String Detection
- Shannon entropy calculation
- Threshold: >4.5 bits per character
- Length: >20 characters
- Context: assignment or config

### Entropy Calibration
| String Type | Typical Entropy |
|-------------|-----------------|
| English text | 3.5-4.0 |
| Base64 encoded | 5.5-6.0 |
| Random hex | 4.0 |
| API keys | 5.0-6.0 |

---

Scan Report Template

## Secret Scan Report

**Scan Date:** {{date}}
**Repository:** {{repo}}
**Branch:** {{branch}}
**Commit Range:** {{commit_range}}

### Summary
| Severity | Count |
|----------|-------|
| Critical | {{critical}} |
| High | {{high}} |
| Medium | {{medium}} |
| Low | {{low}} |

---

### Critical Findings

#### SECRET-001: AWS Access Key Exposed
**Severity:** Critical
**Type:** AWS Access Key ID
**Confidence:** High (pattern match)

**Location:**
- File: `src/config/aws.ts`
- Line: 12
- Commit: `abc1234`
- Author: `developer@example.com`

**Finding:**
```typescript
const AWS_ACCESS_KEY = "AKIAIOSFODNN7EXAMPLE";

Git History:

• First introduced: 2024-01-10
• Still present: Yes
• In git history: Yes (requires history rewrite)

Remediation:

1. Immediate: Rotate key in AWS Console
2. Code fix: Replace with environment variable

   const AWS_ACCESS_KEY = process.env.AWS_ACCESS_KEY_ID;
   

3. History: Consider git-filter-repo to remove from history
4. Prevention: Add to .gitignore, use pre-commit hooks

---

Files to Add to .gitignore

# Recommended additions
.env
.env.*
*.pem
*.key
config/local.*
secrets/

Git History Cleanup Required

The following secrets exist in git history and should be rotated even after removal:

• AWS Access Key (commit abc1234)
• Database password (commit def5678)

Pre-commit Hook Recommendation

#!/bin/bash
# .git/hooks/pre-commit

echo "Running secret scan on staged files..."
# Run scan
if [ $? -ne 0 ]; then
  echo "ERROR: Secrets detected in staged files!"
  echo "Please remove secrets before committing."
  exit 1
fi

---

## Allowlist Management

### Legitimate Exceptions

```yaml
# .secret-scan-allowlist.yml
allowed:
  # Test/example keys (not real)
  - pattern: "AKIAIOSFODNN7EXAMPLE"
    reason: "AWS documentation example key"

  # False positives
  - file: "docs/examples/config.md"
    reason: "Documentation with placeholder values"

  # Encrypted secrets
  - pattern: "ENC\\[.*\\]"
    reason: "SOPS encrypted values"

Allowlist Best Practices

1. Document every exception with clear reason
2. Review allowlist quarterly
3. Never allowlist actual secrets
4. Use hash of secret for allowlist (not secret itself)

---

Integration Points

CI/CD Pipeline

# Block PR if secrets detected
secret-scan:
  stage: security
  script:
    - run-secret-scan
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request"
  allow_failure: false

Pre-commit Hook

#!/bin/bash
# Scan only staged changes
git diff --cached --name-only | xargs secret-scan

IDE Integration

• VS Code: Highlight secrets in real-time
• JetBrains: Inspection warnings
• vim/neovim: Syntax highlighting

---

Response Procedures

When Secrets Are Found

## Incident Response

### Immediate Actions (< 1 hour)
1. Assess scope and impact
2. Rotate/revoke exposed credentials
3. Check access logs for unauthorized use
4. Remove from code (create PR)

### Follow-up Actions (< 24 hours)
1. Clean git history if needed
2. Audit for related exposures
3. Update secret management practices
4. Add to pre-commit hooks

### Documentation
1. Create incident report
2. Update security runbook
3. Conduct team briefing

---

Agents Using This Skill

• DevOps Engineer - CI/CD integration, response
• Senior Developer - Code review, prevention
• Software Architect - Secret management architecture

Related Skills

• security-vulnerability-scan - General security scanning
• security-compliance-check - Compliance verification
• security-dependency-audit - Dependency checking

MCP Tools Used

• None (analysis skill - no external tools required)
• Incidents logged via jira-bug-management