secret-scanner

# secret-scanner skill

## What this tool does

secret-scanner is a Node.js CLI that recursively scans files for secrets (API keys, tokens, private keys, connection strings) using regex patterns with optional Shannon entropy filtering. It exits 0 (no findings), 1 (findings), or 2 (error).

## Installation and build

```bash
cd secret-scanner
pnpm install
pnpm run build   # outputs to dist/
```

After building, run as:
```bash
node dist/cli.js [options] [path]
# or after npm link / pnpm link:
secret-scanner [options] [path]
```

## Common usage

Scan current directory:
```bash
secret-scanner .
```

Scan and only show critical findings:
```bash
secret-scanner . --severity critical
```

Scan a specific file:
```bash
secret-scanner src/config.ts
```

Write JSON report:
```bash
secret-scanner . --format json --output report.json
```

Write SARIF for GitHub Advanced Security:
```bash
secret-scanner . --format sarif --output results.sarif
```

Suppress progress, use in scripts:
```bash
secret-scanner . --severity high -q
if [ $? -eq 1 ]; then
  echo "Secrets found - aborting deployment"
  exit 1
fi
```

## Exit codes

| Code | Meaning |
|------|---------|
| 0 | No findings (or all findings below min severity) |
| 1 | At least one finding at or above min severity |
| 2 | Error (bad arguments, path not found, invalid config) |

## Built-in patterns

| ID | Severity | Description |
|----|----------|-------------|
| AWS_ACCESS_KEY | critical | AWS Access Key ID (AKIA...) |
| AWS_SECRET_KEY | critical | AWS Secret Access Key (40-char base64, entropy >= 4.5) |
| GITHUB_TOKEN | critical | GitHub PAT (ghp_... or github_pat_...) |
| SLACK_TOKEN | high | Slack Bot/User Token (xox[baprs]-...) |
| PRIVATE_KEY_HEADER | critical | PEM Private Key header |
| CONNECTION_STRING | high | Database connection string |
| GENERIC_API_KEY | medium | api_key= assignment (entropy >= 3.5) |
| JWT_TOKEN | high | JSON Web Token (eyJ...three-part base64url) |
| HIGH_ENTROPY_STRING | low | Quoted string >= 20 chars, entropy >= 4.5 |

## Configuration file (.secretscanrc.json)

Place in the directory being scanned or specify with `--config`:

```json
{
  "severity": "high",
  "excludePatterns": ["JWT_TOKEN", "HIGH_ENTROPY_STRING"],
  "excludePaths": ["tests/fixtures/", "*.test.ts"],
  "customPatterns": [
    {
      "id": "MY_TOKEN",
      "name": "My Company Token",
      "regex": "myco_[A-Za-z0-9]{32}",
      "severity": "critical"
    }
  ]
}
```

## Ignore file (.secretscanignore)

Gitignore-style patterns, one per line:
```
dist/
build/
coverage/
tests/fixtures/
*.generated.ts
```

## Pre-commit hook setup

```bash
cat > .git/hooks/pre-commit << 'EOF'
#!/usr/bin/env bash
STAGED=$(git diff --cached --name-only --diff-filter=ACM)
if [ -z "$STAGED" ]; then exit 0; fi
echo "$STAGED" | xargs secret-scanner --severity high -q
if [ $? -ne 0 ]; then
  echo "[secret-scanner] Commit blocked: secrets detected."
  exit 1
fi
EOF
chmod +x .git/hooks/pre-commit
```

## Environment variables

| Variable | Values | Description |
|----------|--------|-------------|
| SS_NO_COLOR | 0 / 1 | Disable ANSI color output |
| SS_QUIET | 0 / 1 | Suppress non-finding output |

## Redaction format

All matched values in output are redacted: first 4 chars + `***...***` + last 4 chars.
Example: `AKIAIOSFODNN7EXAMPLE` becomes `AKIA***...***MPLE`.

The full value is never written to stdout, stderr, or report files.

## Shannon entropy

Patterns with an `entropy` field only fire when the matched string's Shannon entropy exceeds the threshold. This reduces false positives on low-entropy strings like `version-1.0.0` that happen to match a generic pattern.

Formula: `H = -sum(p(c) * log2(p(c)))` where `p(c)` is the frequency of character `c`.

Typical values:
- All same character ("aaaa..."): 0.0
- Version string: ~2.8
- Real API key: 4.5-5.5

## Behavior notes

- Files larger than `--max-file-size` (default 1 MB) are skipped
- `node_modules/`, `.git/`, and binary files are always skipped
- Unreadable files emit a warning but do not cause exit code 2
- Pattern regexes are applied line-by-line, not to the whole file content
- Custom `regex` strings in config are compiled with `new RegExp(string)`. Invalid regex strings produce exit code 2 at startup.