Secret Scan

---
name: secret-scan
description: 'Hardcoded-secret detection — AWS keys, GitHub PATs, Slack tokens, Stripe keys, generic high-entropy strings. Pre-commit (`--staged-only`), explicit paths, or full repo. Use when guarding `git commit`, auditing a repo for leaked credentials, validating no secrets entered the diff before push, or producing a rotation list for an exposed-secret incident.'
license: Apache-2.0
allowed-tools: Bash(vulnetix:*) Read Grep Glob
argument-hint: "[--paths file1 file2] [--staged-only]"
user-invocable: true
model: sonnet
metadata:
  outputBudget: short
  cooldown: per-session
  chain: "verify-fix"
---
# Vulnetix Secret Scan Skill

## Use when

- Pre-commit: confirm no secrets in staged files (`--staged-only`).
- Pre-push: scan diff vs `origin/HEAD` for high-confidence leaks.
- Audit: full-repo scan for an exposed-secret incident.
- Producing a rotation list — which provider keys need to be revoked NOW.
- CI gate: block merge if any high-confidence secret detected.

## Don't use for

- Vulnerability detection — use `sast-scan` or `vulnetix scan --sca`.
- Validating an already-fixed leak — use git filter-repo or BFG to remove from history.

## Conventions

Follows `skills/_lib/contract.md`. In short: use the `vulnetix_*` MCP tools when the agent has them and the CLI otherwise — both shape their own output, so there is no jq step any more. Independent calls go out as concurrent Bash tool calls in one message. One trailing suggestion, not a playbook. See the contract for surface selection, output style and memory writes.

## Step 1: Load capabilities

Read `.vulnetix/capabilities.yaml`. Note `binaries.git` (required for `--staged-only`).

## Step 2: Decide scope

- `--staged-only`: `git diff --cached --name-only` for the file list.
- `--paths`: explicit list.
- Default: changed files vs. main branch, fallback to whole repo.

## Step 3: Run scan

```bash
vulnetix secrets --paths "$PATHS" -o json > .vulnetix/secrets.${TIMESTAMP}.json
```

Or via integrated scan:

```bash
vulnetix scan --evaluate-secrets --paths "$PATHS" -o json
```

## Step 4: Render

```
Secret findings: N (high-confidence: M)

| Type | File:Line | Snippet (redacted) | Confidence |
```

For each finding, emit a redacted snippet (replace 60% of the secret with `*`). Never print the full secret.

## Step 5: Remediation guidance

For each unique secret type, surface the standard rotation/revocation steps (AWS, GCP, GitHub PAT, Slack, Stripe, etc.). Do not auto-rotate.

If a secret is found in a committed file (not just staged):
- Suggest `git filter-repo` or BFG repo-cleaner
- Strongly recommend rotating the credential since it's in git history

## Memory update

Append a sanitized record to `.vulnetix/secrets/${TIMESTAMP}.summary.yaml` (counts by type, file paths, no values).

## Edge cases & gotchas

- Output redacts 60% of each detected secret. Never re-print the un-redacted value.
- High-confidence findings include AWS / GitHub PAT / Slack / Stripe patterns. Generic high-entropy strings are medium-confidence; tune your CI gate accordingly.
- `--staged-only` reads `git diff --cached --name-only` — files not yet staged are skipped. Run AFTER `git add`.
- Detection is regex-based; obfuscated secrets (split across vars, base64-wrapped) may be missed. Pair with a hand review for high-stakes audits.
- For secrets ALREADY in git history, this skill detects them on next change only. Use `gitleaks --log-opts="--all"` for full history scan, then BFG / filter-repo to remove.
- False-positive suppression uses inline comments (`# pix-ignore-secret`) on the next line; the suppression is per-line, not per-pattern.