nitinjain999/platform-skills/kingfisher

Find a leaked secret, prove whether it's still alive, see what it can reach, and kill it — in that order.

Read references/kingfisher.md before responding. It contains bootstrap steps, the full CLI surface (scan, validate, revoke, baseline, config), the kingfisher.yaml schema, platform-target commands with their auth env vars, exit-code semantics, CI templates, and the pre-commit/Husky setup.

The bundled hook is scripts/pre-commit.sh, relative to this SKILL.md. Set skill_dir to the absolute directory containing this loaded skill before standalone setup. In a repository clone that is skills/kingfisher; a portable install carries the script inside platform-skills-kingfisher/scripts/.

This command is interactive by default. With no arguments, run the three-layer wizard below. Never dump a raw kingfisher scan invocation and stop — the useful output is a validated, triaged verdict, not a wall of candidate strings.

Ownership boundary (enforced at the menu)

Trivy's secrets scanner and Kingfisher are not the same depth of tool: Trivy tells you a string matches a pattern, offline, as part of a broader vuln/license scan. Kingfisher live-validates the candidate against the real provider, tells you if it's actually dangerous, and can map or kill it. Run both if you want a cheap first pass and a specialist second pass — they are not redundant.

Mode dispatch

Parse the first word of $ARGUMENTS as the mode. When $ARGUMENTS is empty, run the three-layer interactive wizard.

Three-layer interactive wizard

Layer 1 — Developer question (intent in their language)

What are you trying to find out?
  1. "Did we commit a secret? Check my repo."        → scan
  2. "Full sweep — I'm doing a security review."      → audit
  3. "I have a key from somewhere — is it still live?" → validate
  4. "Kill this credential now."                       → revoke
  5. "Only show me new secrets, not the old backlog."  → baseline
  6. "I have findings — help me decide what to do."    → triage
  7. "Set up a kingfisher.yaml for this repo."         → config
  8. "Make this a check on every PR."                  → ci
  9. "Catch it before I even commit."                  → precommit
  10. "What does this finding/exit code mean?"          → explain
 
  Pattern-only secret scan bundled with a CVE pass? → /platform-skills:trivy
  Workflow secrets: context usage?                  → /platform-skills:zizmor
  Storing/rotating secrets inside the cluster?       → /platform-skills:secrets
 
Enter 1–10 or a mode name:

Layer 2 — Scope and target (decides what actually gets scanned, and how invasively)

Ask only what the chosen mode needs.

What should I scan? (press Enter for the recommended value)
 
  • Target [.]: local path, a Git URL, or a platform target —
    github/gitlab/bitbucket/gitea/azure/huggingface org or user,
    s3/gcs bucket, docker image, jira/confluence/slack/teams/postman search.
    Platform targets need an auth token env var (KF_GITHUB_TOKEN, etc.) —
    see references/kingfisher.md → Platform-specific targets.
 
  • History [working tree + history]: local paths scan both by default,
    which double-counts anything still present in a tracked file (once from
    the file, once from the commit it entered on). `--git-history=none`
    scans the working tree only; a remote URL target is history-only by
    default (bare clone).
 
  • Live validation [on]: confirms whether each candidate still
    authenticates. `--no-validate` is faster but static-only — you get
    "looks like a key," not "is a key." Keep this on unless you're doing a
    quick offline pre-check.

Before touching a platform target, Slack/Jira/Confluence/Teams/Postman search, or `--blast-radius`, confirm authorization out loud. These are not passive reads: platform-target scans pull private organizational content, and blast-radius mapping authenticates as the discovered credential against a live provider. State plainly that you're only proceeding because the user confirmed access is authorized.

Detect and resolve silently where possible:

• Run kingfisher --version. Not installed → offer brew install kingfisher, uv tool install kingfisher-bin==2.13.0, or a pinned version from references/kingfisher.md → Bootstrap. Do not ask permission to check the version.
• Check for kingfisher.yaml at the target root. It is never auto-loaded — if found, ask whether to pass --config kingfisher.yaml explicitly; if not found, say defaults apply.
• Check for a baseline file (baseline-file.yml, baseline.json, or similar committed near the repo root). Found → ask whether to pass --baseline-file; a scan without it re-reports the entire existing backlog as if it were new.

Layer 3 — Trade-offs (surface where a wrong default causes real harm)

A few decisions worth making explicitly (Enter accepts the recommendation):
 
  • Gate threshold, for `ci`/`triage` on a repo that's never run this
    before [205 — confirmed-live only]:
      205  — fail only on a validated, still-active credential (RECOMMENDED
             for day one; low noise, every failure is real)
      200  — fail on any candidate, live or not (stricter, but a first run
             on an established repo typically surfaces a long tail of test
             fixtures and documented example keys like AKIAIOSFODNN7EXAMPLE)
    Move from 205 to 200 once a baseline absorbs the existing backlog.
 
  • Suppressing a known-fake finding [baseline, not --skip-word]:
    A committed baseline is reviewable, repository-scoped, and shows exactly
    what was accepted and when. `--skip-word`/`--skip-regex` are pattern-wide
    and silently swallow anything matching, including a future real secret
    that happens to contain the same word. Reach for skip-word/regex only for
    a fixture pattern that recurs across many files (e.g. every test file
    uses the literal string `EXAMPLE`); use the baseline for one-off accepts.
 
  • `--alert-include-secret` [off]: puts the literal secret value into the
    chat/webhook payload. Recommend leaving this off — a Slack alert channel
    is not a secrets vault, and the alert itself becomes a second place the
    secret now lives. Turn it on only for a locked-down, need-to-know sink,
    and say so explicitly if the user asks for it anyway.
 
  • Docker tag, for `ci` [pinned version, not `latest`]: `:latest` moves
    under you; pin `ghcr.io/mongodb/kingfisher:<version>` for reproducible CI.

Ask these only when the situation triggers them:

Never ask about: output format for a quick local check (default pretty; ask only for ci/automation, where sarif/json/toon matter), whether to install kingfisher (just do it via brew or a pinned uv tool install, per Bootstrap), or whether to check for a kingfisher.yaml/baseline file (always check silently).

Mode: scan

The everyday run. Live validation on, default rule set, working tree + history for local targets.

# Local checkout
kingfisher scan /path/to/code
 
# Skip history if you only care about the current working tree
kingfisher scan /path/to/code --git-history=none
 
# Fast offline pre-check (static only, no network)
kingfisher scan /path/to/code --no-validate

Report in this order:

1. Verdict — one line: clean, candidates only (no live secrets), or confirmed-live secrets present.
2. Counts by outcome — verified_active (network-confirmed), assumed (high-confidence, not checked), everything else grouped as "other" — this distinction is the whole point of running Kingfisher instead of a pattern scanner.
3. Findings, live-confirmed first, each with file:line, rule id (betterleaks.*/veles.*), and outcome.
4. History note — if this was a local path scan, mention that filesystem + history means a tracked-file secret can appear twice; if that inflates the count, offer --git-history=none for a cleaner working-tree-only view.
5. Next step — one concrete command: validate/revoke for a live secret, triage if there are several, baseline if this is the first run on an established repo.

Mode: audit

Deep sweep for a human security review. Not a CI gate.

kingfisher scan /path/to/repo \
  --confidence low \
  --validation-filter all \
  --blast-radius

State up front, before running: blast-radius mapping authenticates against each validated credential's provider — confirm authorization (Layer 2 gate). Low confidence surfaces more candidates, including likely false positives; this mode is for a human to triage, not a pass/fail signal.