From 2808ffd450327abfa971f904f15f96708c911d0a Mon Sep 17 00:00:00 2001
From: Erich Blume <blume.erich@gmail.com>
Date: Sat, 28 Mar 2026 21:47:37 -0700
Subject: [PATCH] Document Kingfisher secret scanner service

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 docs/changelog.d/+kingfisher-docs.doc.md |  1 +
 docs/reference/operations/security.md    |  1 +
 docs/reference/services/kingfisher.md    | 55 ++++++++++++++++++++++++
 3 files changed, 57 insertions(+)
 create mode 100644 docs/changelog.d/+kingfisher-docs.doc.md
 create mode 100644 docs/reference/services/kingfisher.md

diff --git a/docs/changelog.d/+kingfisher-docs.doc.md b/docs/changelog.d/+kingfisher-docs.doc.md
new file mode 100644
index 0000000..42fe085
--- /dev/null
+++ b/docs/changelog.d/+kingfisher-docs.doc.md
@@ -0,0 +1 @@
+Add service reference documentation for Kingfisher secret scanner.
diff --git a/docs/reference/operations/security.md b/docs/reference/operations/security.md
index d66efe1..17a6ff6 100644
--- a/docs/reference/operations/security.md
+++ b/docs/reference/operations/security.md
@@ -24,6 +24,7 @@ Security posture and compliance scanning for BlumeOps infrastructure.
 - [[prowler]] — CIS Kubernetes Benchmark scanner (weekly CronJob)
   - [[deploy-prowler]] — deployment and ad-hoc scan how-to
   - [[read-compliance-reports]] — accessing and interpreting reports
+- [[kingfisher]] — Secret detection and live validation for Forgejo repos (weekly CronJob + prek hook)
 
 ## Identity & access
 
diff --git a/docs/reference/services/kingfisher.md b/docs/reference/services/kingfisher.md
new file mode 100644
index 0000000..dea47f1
--- /dev/null
+++ b/docs/reference/services/kingfisher.md
@@ -0,0 +1,55 @@
+---
+title: Kingfisher
+modified: 2026-03-28
+last-reviewed: 2026-03-28
+tags:
+  - service
+  - security
+---
+
+# Kingfisher
+
+Secret detection and live validation scanner for Forgejo repositories, using MongoDB's open-source [Kingfisher](https://github.com/mongodb/kingfisher) tool.
+
+## Quick Reference
+
+| Property | Value |
+|----------|-------|
+| **Namespace** | `kingfisher` |
+| **Image** | `ghcr.io/mongodb/kingfisher` (see `argocd/manifests/kingfisher/kustomization.yaml` for current tag) |
+| **Schedule** | Sunday 4am (after Prowler k8s scan at 3am) |
+| **Reports** | `sifaka:/volume1/reports/kingfisher/` (NFS) |
+| **Manifests** | `argocd/manifests/kingfisher/` |
+| **Upstream** | `forge.eblu.me/mirrors/kingfisher` (GitHub mirror) |
+
+## What it does
+
+Runs as a weekly CronJob that scans all repositories in the `eblume` user on Forgejo for leaked secrets, API keys, and credentials. Produces timestamped HTML and JSON reports on the sifaka NFS share.
+
+Uses the Forgejo/Gitea API to enumerate repos, then clones and scans each one. Validation is enabled (secrets are tested against their respective APIs to confirm they're live).
+
+## Pre-commit hook
+
+Kingfisher also runs as a prek hook alongside TruffleHog for comparative secret detection coverage. The hook uses `--staged` mode (only checks staged files) with validation disabled for fast, offline-safe commits.
+
+## Known false positives
+
+- **Postgres URL with `op://` template** — 1Password External Secrets template references match the postgres connection string pattern. Not a real credential.
+- **GitHub legacy secret key in `.git/`** — git commit SHAs are 40-char hex strings matching the old GitHub PAT format. Only appears in full-repo scans, not `--staged` mode.
+
+## Ad-hoc scan
+
+```fish
+kubectl create job --from=cronjob/kingfisher kingfisher-manual -n kingfisher --context=minikube-indri
+kubectl logs -f job/kingfisher-manual -n kingfisher --context=minikube-indri
+```
+
+## Limitations
+
+- Clone URLs come from Forgejo's API response using the instance's public `ROOT_URL` (`forge.eblu.me`), so clones roundtrip through Fly.io. Mirror/org scanning is excluded for now to avoid unnecessary external bandwidth. A clone URL rewrite option would need an upstream contribution.
+- Only one output format per invocation, so the CronJob runs Kingfisher twice (HTML then JSON).
+
+## See also
+
+- [[prowler]] — CIS Kubernetes, image, and IaC compliance scanning
+- [[read-compliance-reports]] — how to access and interpret reports