security

Security: Secret Detection

This skill activates when performing secret detection, credential scanning, or implementing security checks for leaked sensitive data in code repositories.

Pre-Commit Hook (Automatic)

When this skill is loaded, a pre-commit hook automatically scans staged files for secrets before every git commit command, providing defense-in-depth by catching secrets before they enter git history. Only staged files are scanned (not the entire working tree); .gitleaks-baseline.json and .gitleaks.toml, when present, are honored for known false positives and custom rules.

If the hook detects secrets, the commit is blocked (exit code 2) with guidance to remove the secret, switch to an environment variable, or add it to the baseline if it's a false positive.

The hook requires a container runtime (Apple Container, Docker, or Colima via mise) to run gitleaks. If no runtime is available, the hook logs a warning and allows the commit — it fails open, not closed.

See references/gitleaks-usage.md for the hook's exact flow diagram and block-message text.

Agent Secret Safety

When agents interact with secrets (1Password, environment variables, keychains):

• Never print secret values in output, logs, or reports
• Confirm existence only: test -n "$VAR" && echo "set" || echo "empty"
• Never use --reveal in agent scripts — use it only in launcher scripts that don't capture output
• If a secret value is accidentally exposed in conversation context, the user must rotate it immediately

This applies to all agent tiers. A leaked secret in agent output forces credential rotation.

Commands that leak environments

"Never print secret values" is not enough on its own — some commands leak the full environment as a side effect of an unrelated-looking diagnostic. The command reads as "get a bit more context on this process," not "dump every credential this process can see," so the guidance above does not visibly apply and the leak happens anyway.