Kingfisher Documentation Index¶
This page routes users, operators, LLM agents, rule authors, and library developers to the authoritative Kingfisher documentation for each task.
Start by Goal¶
| Goal | Documentation |
|---|---|
| Install or upgrade Kingfisher | Installation |
| Run a first scan or understand scan output | Usage |
| Scan a hosted service or developer platform | Integrations |
| Configure project-wide defaults | Project configuration |
| Follow detection through containment | Defender workflow |
| Validate credentials and filter by outcome | Usage: validation |
| Map credential identity, permissions, and resources | Blast radius |
| Review and prioritize findings in a browser | Viewer usage, hosted guide |
| Revoke a supported credential | Revocation providers |
| Send alerts to chat or webhook destinations | Alert webhooks |
| Deploy in CI, pre-commit, or a central service | Deployment |
| Tune performance, validation, filtering, or CI behavior | Advanced configuration |
| Track accepted findings without hiding new ones | Baseline management |
| Preserve repository coverage evidence | Repository audit log |
| Write, import, or verify detection rules | Rule authoring |
| Embed Kingfisher in Rust | Library API |
| Install or maintain the Python distribution | Python/PyPI |
Response Workflow¶
- Defender workflow — end-to-end detection, validation, notification, blast-radius analysis, triage, and revocation.
- Blast radius — provider coverage, evidence fields, safety boundaries, and standalone or scan-integrated commands.
- Revocation providers — supported provider actions and operational safeguards.
- Multi-step revocation — authoring lookup-then-revoke HTTP flows.
- Token revocation support — how imported detectors connect to Kingfisher-specific containment capabilities.
- Alert webhooks — summary and finding notifications.
- Repository audit log — scan coverage, lifecycle events, and evidence semantics.
Detection and Finding Semantics¶
- Rule authoring — Betterleaks TOML, private Kingfisher YAML, regex constraints, components, validation, filters, and checksums.
- Parser-based context verification — how assignment context reduces false positives.
- Source parsing — supported languages and parser pipeline.
- Finding fingerprints — stable identifiers, deduplication, and
--no-dedup. - Baseline management — suppressing accepted findings while detecting new ones.
Operations and Deployment¶
- Installation — package managers, binaries, Docker, source builds, hooks, cache, and release-attestation verification.
- Integrations — authentication and commands for every remote scan target.
- Project configuration —
kingfisher.yamlpolicy and CLI precedence. - Advanced configuration — confidence, validation tuning, CI diffs, performance, exclusions, updates, and exit codes.
- Deployment — local, CI, centralized, and embedded deployment patterns.
Development and Project Reference¶
- Architecture — crates, CLI paths, scanner pipeline, validation, and reporters.
- Rust library API — embedding the scanner and selecting validation features.
- Python/PyPI — Python installation, wheels, and publishing.
- Benchmarks — methodology, performance, network requests, and binary size.
- Project background — production use, lineage, evolution, and roadmap.
- Changelog — release history.
- Contributing — development workflow and contribution expectations.
- Security policy — vulnerability reporting.
Guidance for LLMs and Automation¶
- Read the repository AGENTS.md before changing code or documentation.
- Use
kingfisher scan --format toonfor token-efficient scan output. Add--no-update-checkin reproducible automation. - Use structured
validation.outcomevalues and finding fingerprints; do not infer state by parsing human-readable labels. - Treat USAGE.md, CONFIG.md, and command
--helpas authoritative for CLI behavior. Use ARCHITECTURE.md for source routing. - Read RULES.md before non-trivial detector or schema changes. Generally useful rules belong upstream in Betterleaks; organization-specific rules may use Kingfisher YAML.
- Live validation, blast-radius mapping, alerts, and revocation can make network requests or cause external effects. Follow the authorization and safety guidance in the relevant document.