Listen to this Post
Introduction:
Finding a leaked API key in a GitHub repository is the easy part. Any regex-based scanner can flag a string that looks like an AWS access key or a GitHub token. The real question that separates a routine cleanup task from a full-blown incident is: What can an attacker actually do with this credential? Kingfisher, an open-source secret scanner built in Rust by MongoDB, answers precisely that question. It goes beyond detection with live validation against provider APIs, blast radius mapping to visualize exactly what resources a compromised key exposes, and one-command revocation—closing the loop from discovery to remediation in a single workflow.
Learning Objectives:
- Understand how Kingfisher combines SIMD-accelerated regex, language-aware parsing, and live API validation to eliminate false positives.
- Learn to scan local directories, Git repositories, cloud storage, and developer platforms like GitHub, GitLab, Slack, and Jira.
- Master advanced features including blast radius mapping (
--access-map), direct revocation, custom rule creation, and CI/CD integration.
1. Installation: Get Kingfisher Running in Seconds
Kingfisher offers multiple installation methods across all major platforms. Choose the one that fits your environment:
Linux & macOS (Homebrew):
brew install kingfisher
Linux & macOS (Script):
curl -sSL https://raw.githubusercontent.com/mongodb/kingfisher/main/scripts/install-kingfisher.sh | bash
Windows (PowerShell):
Download and run the installer ./install-kingfisher.ps1 Specify custom directory ./install-kingfisher.ps1 -InstallDir 'C:\Tools\Kingfisher'
Docker:
docker run --rm -v "$PWD":/src ghcr.io/mongodb/kingfisher:latest scan /src
PyPI:
uv tool install kingfisher-bin or pip3 install kingfisher-bin
Pre-commit Hook (Block Secrets Before They Commit):
Install a Git pre-commit hook to automatically scan staged changes and block commits that introduce new secrets:
Per-repository hook kingfisher install-pre-commit Global hook (using core.hooksPath) kingfisher install-pre-commit --global
The installer preserves any existing pre-commit hook and chains it before Kingfisher executes.
- Basic Scanning: Find Secrets in Code, Git History, and More
Kingfisher automatically detects whether a path is a Git repository or a plain directory.
Scan a Local Directory:
kingfisher scan /path/to/your/code
Scan a Git Repository (Including Full History):
kingfisher scan /path/to/your/repo
Scan a GitHub Organization (All Repositories):
export KF_GITHUB_TOKEN="ghp_..." kingfisher scan github --organization my-org
This enumerates every repository in the organization, clones each one, and scans both the working tree and full git history.
Scan Additional Artifacts (Issues, PRs, Wikis, Gists):
kingfisher scan github --organization my-org --repo-artifacts
Secrets often live in issue descriptions and pull request comments—this flag ensures those surfaces are covered too.
View Results in Browser:
kingfisher scan /path/to/code --view-report
You can also open existing Kingfisher, Gitleaks, or TruffleHog JSON reports:
kingfisher view findings.json
3. Live Validation: Eliminate False Positives
Traditional secret scanners flag anything that looks like a secret, forcing engineers to sift through countless false positives. Kingfisher actively validates discovered credentials against the provider’s own API. If the API responds with an authorization error, the secret is confirmed as active and high-risk.
Scan and Show Only Live (Validated) Secrets:
kingfisher scan /path/to/code --only-valid
Kingfisher reports each credential as Active, Inactive, or NotAttempted. Of the 954 built-in detection rules, 489 include live validation support.
- Blast Radius Mapping: See What an Attacker Can Access
A regex hit tells you a string looks like an API key. `–access-map` tells you what that key can actually do.
Generate Blast Radius Map:
kingfisher scan /path/to/code --access-map --view-report
This feature maps leaked keys to their effective cloud identities and exposed resources. It answers critical questions:
- Which AWS account does this key belong to?
- What IAM permissions are attached?
- Which S3 buckets, EC2 instances, or databases are accessible?
- Is this a developer token with limited access or a production admin key?
Kingfisher currently supports blast radius mapping for 39 access map providers.
5. Direct Revocation: One Command, Zero Delay
Finding a live, high-impact secret is only half the battle. The other half is removing it before an attacker exploits it. Kingfisher supports direct revocation from the CLI for 29 provider families including GitHub, GitLab, Slack, AWS, GCP, Heroku, and Cloudflare.
Revoke a Compromised Secret:
kingfisher revoke <secret-id-or-value>
Of the 954 built-in rules, 50 support direct revocation. The revocation matrix covers providers like AWS, GCP, GitHub, GitLab, Slack, and many more.
6. CI/CD Integration and Automation
Kingfisher is designed for seamless integration into CI/CD pipelines, security automation, and developer workflows.
Output JSON for CI/CD:
kingfisher scan /path/to/code --format json --output findings.json
SARIF Output for Compliance:
kingfisher scan /path/to/code --format sarif --output findings.sarif
Real-time Webhook Alerts:
Configure alerts to Slack, Teams, Discord, Mattermost, or Google Chat:
kingfisher scan /path/to/code --webhook-url https://hooks.slack.com/services/...
This ensures that findings are delivered to the right people immediately—not buried in a JSON artifact that nobody opens.
Baseline Management (Detect Only New Secrets):
Use a baseline file to track known findings and only report new secrets in future scans:
kingfisher scan /path/to/code --manage-baseline
The baseline hashes the secret value together with the normalized filepath, so moving a secret around does not create a new entry.
- Custom Rules: Extend Kingfisher Without Touching Rust Code
Kingfisher ships with 954 built-in detection rules across 584 providers, but you can add custom rules using a simple YAML format.
Example Custom Rule (AWS Key Detection):
rules:
- name: "Custom AWS Secret Key"
id: "kingfisher.custom.aws.1"
pattern: |
(?x)(?i) aws (?:.|[\n\r]){0,32}? \b([A-Za-z0-9/+=]{40})\b
min_entropy: 3.5
confidence: medium
validation:
type: Http
content:
request:
method: GET
url: https://api.example.com/v1/check
headers:
X-Secret: "{{ TOKEN }}"
revocation:
type: Http
content:
request:
method: POST
url: https://api.example.com/v1/revoke
Custom rules support:
- Regular expression patterns with entropy filtering
- Live validation against external APIs
- Direct revocation via HTTP or gRPC
- Confidence scoring (low/medium/high)
- Dependency chaining (capture variables from one rule and use them in another)
8. Advanced Scanning: Platform Integrations
Kingfisher scans 15+ scan targets beyond local files and Git repositories:
| Category | Targets |
|||
| Version Control | GitHub, GitLab, Azure Repos, Bitbucket, Gitea, Hugging Face |
| Cloud Storage | AWS S3, Google Cloud Storage |
| Collaboration | Jira, Confluence, Slack, Microsoft Teams |
| APIs & Collections | Postman workspaces |
| Containers | Docker images |
Scan a Slack Export:
kingfisher scan slack --export /path/to/slack-export.zip
Scan Postman Workspaces:
kingfisher scan postman --workspace my-workspace
Postman is a prolific leak surface—CloudSEK’s December 2024 audit found over 30,000 public Postman workspaces leaking access tokens. Kingfisher scans live workspaces, not just exported collections.
Scan Docker Images:
kingfisher scan docker --image myapp:latest
What Undercode Say:
- Detection is not enough. Finding a secret is the beginning, not the end. The real security value lies in validation, impact assessment, and remediation.
- False positives kill security workflows. Teams ignore scanners that cry wolf too often. Kingfisher’s live validation ensures that every alert is a real, actionable threat.
- Blast radius mapping changes the game. Knowing what a leaked key can access transforms a vague alert into a prioritized incident response action.
- One-command revocation closes the loop. The ability to revoke directly from the terminal eliminates the friction that often delays remediation.
- On-premises operation ensures data privacy. Kingfisher runs entirely within your infrastructure—discovered secrets never leave your environment or pass through a third-party service.
- Performance at scale matters. Kingfisher scans the Linux kernel in 205 seconds and the GitLab monorepo with just 17 HTTP validation requests. Intelligent validation means minimal API calls and faster results.
- AI token detection is built-in. Kingfisher detects and validates tokens for 35+ AI/ML providers including OpenAI, Anthropic, Google Gemini, Mistral, and Cohere.
- Open source with no vendor lock-in. Apache 2.0 licensed, free to use, no usage limits, no telemetry.
Prediction:
- +1 Kingfisher represents a paradigm shift in secret management—moving from passive detection to active validation and remediation. As credential-stuffing attacks and supply-chain compromises rise, tools that close the loop from discovery to revocation will become mandatory in DevSecOps pipelines.
- +1 The open-source model, backed by MongoDB’s engineering team, ensures rapid iteration and community-driven rule expansion. With 954 built-in rules and counting, Kingfisher will likely become the industry standard for secret scanning, much like Gitleaks and TruffleHog before it.
- +1 Integration with AI/ML workflows is a strategic move. As organizations increasingly rely on LLM APIs and agent-based systems, the ability to detect and revoke AI tokens will be critical to prevent data exfiltration and unauthorized API usage.
- -1 The effectiveness of Kingfisher depends on organizations actually running it. Many security teams struggle with scanner fatigue and alert overload. Without proper integration into CI/CD and developer workflows, even the best tool can be ignored.
- -1 While Kingfisher supports 29 provider families for revocation, many organizations use custom or niche services. The reliance on built-in revocation support means that not all secrets can be automatically revoked—some will still require manual intervention.
- +1 The webhook alerting and real-time notifications feature addresses the “alert fatigue” problem by delivering findings directly to team chat platforms. This ensures that security teams see results in time to act, rather than discovering them weeks later in a forgotten artifact bucket.
- +1 Kingfisher’s ability to import and triage Gitleaks and TruffleHog JSON reports in the same browser-based viewer lowers the barrier to adoption. Teams can gradually migrate while still leveraging their existing tooling.
- -1 The tool requires a GitHub personal access token with appropriate scopes for organization-wide scans. Organizations with strict token rotation policies or air-gapped environments may face additional setup complexity.
- +1 The performance characteristics—scanning the Linux kernel in 205 seconds—make Kingfisher suitable for large-scale, enterprise-grade deployments. This addresses a key limitation of many open-source secret scanners that struggle with monorepos.
- +1 As regulatory requirements around data breach notification tighten, having a tool that can not only detect but also prove remediation (via revocation) will become a compliance necessity. Kingfisher’s audit trail—from detection to validation to revocation—provides that chain of evidence.
▶️ Related Video (70% Match):
🎯Let’s Practice For Free:
🎓 Live Courses & Certifications:
Join Undercode Academy for Verified Certifications
🚀 Request a Custom Project:
Secure, high-velocity infrastructure and disruptive technological engineering. Contact our engineering team for high-tier development and proprietary systems:
[email protected]
💎 Smart Architecture | 🛡️ Secure by Design | ⭐ Trusted by Thousands
IT/Security Reporter URL:
Reported By: Laurent Biagiotti – Hackers Feeds
Extra Hub: Undercode MoN
Basic Verification: Pass ✅
