Installation Guide¶

This guide covers all installation methods for Kingfisher, including pre-commit hook setup.

Table of Contents¶

Pre-built Releases
Verifying Release Artifacts
Linux Packages (RPM and DEB)
Homebrew
mise
Linux and macOS
Windows
Pre-commit Hooks
macOS and Linux
Windows PowerShell
Using the pre-commit Framework
Using Husky (Node.js projects)
Cargo
Native Scan Wizard
Compile from Source
PyPI Wheels
Run Kingfisher in Docker

Pre-built Releases¶

Pre-built binaries are available from the Releases section.

Verifying Release Artifacts¶

Verify a downloaded release before extracting or running it. This checks that the file matches a signed artifact from Kingfisher's release workflow and the exact version you requested. It prevents a modified download or an older genuine release from silently replacing your pinned version in CI.

Install a current GitHub CLI and authenticate with gh auth login. In a fresh directory, run these Bash commands, replacing vX.Y.Z with your pinned release tag:

set -euo pipefail
VERSION=vX.Y.Z
ASSET=kingfisher-linux-x64.tgz

gh release download "$VERSION" --repo mongodb/kingfisher \
  --pattern "$ASSET" --pattern multiple.intoto.jsonl

gh attestation verify "$ASSET" \
  --repo mongodb/kingfisher \
  --signer-workflow mongodb/kingfisher/.github/workflows/release.yml \
  --source-ref "refs/tags/$VERSION" \
  --bundle multiple.intoto.jsonl

Change ASSET for your platform: kingfisher-linux-arm64.tgz, kingfisher-darwin-x64.tgz, kingfisher-darwin-arm64.tgz, kingfisher-windows-x64.zip, or kingfisher-windows-arm64.zip. The same verification command works for release .deb and .rpm packages and kingfisher-rule-bundle.tgz.

Only install the file if verification succeeds. Keep --source-ref: verifying just the repository or workflow accepts genuine artifacts from other versions too. Renaming an older archive does not bypass the tag check. In CI, let a failed verification stop the install.

The downloaded multiple.intoto.jsonl contains the SLSA build-provenance attestation. The GitHub CLI verifies the signature and artifact digest, then enforces the workflow and tag. See the verification options. This verifies release provenance; it does not guarantee that the software has no vulnerabilities.

Older releases attested from refs/heads/main cannot pass this version-specific check. Do not remove --source-ref to make them pass: use a release attested from its version tag, or independently pin a trusted artifact SHA-256 for a legacy release.

Linux Packages (RPM and DEB)¶

The native Linux package name is kingfisher, and the command is kingfisher. This is separate from the intentional crates.io and PyPI name kingfisher-bin.

Download the .rpm or .deb for your architecture from Releases, then verify it before installing. These examples use x64; substitute arm64 in the filename for ARM64:

# RPM: install or upgrade.
sudo dnf install ./kingfisher-linux-x64.rpm
# DEB: install or upgrade.
sudo apt install ./kingfisher-linux-x64.deb

For updates, download and verify the newer release and run the corresponding local-file install command again. A repository upgrade command alone does not fetch GitHub release assets. Do not use kingfisher self-update to overwrite a package-managed binary.

To uninstall:

sudo dnf remove kingfisher  # RPM; use yum instead of dnf where applicable.
sudo apt remove kingfisher # DEB

Homebrew¶

Homebrew Formula Version

brew install kingfisher

mise¶

Install the latest release globally with the mise GitHub backend:

mise use --global github:mongodb/kingfisher

Append a version to install a specific release:

mise use --global github:mongodb/kingfisher@2.10.0

Linux and macOS¶

Use the bundled installer script to fetch the latest release and place it in ~/.local/bin (or a directory of your choice):

# Linux, macOS
curl --silent --location \
  https://raw.githubusercontent.com/mongodb/kingfisher/main/scripts/install-kingfisher.sh | \
  bash

To install into a custom location, pass the desired directory as an argument:

curl --silent --location \
  https://raw.githubusercontent.com/mongodb/kingfisher/main/scripts/install-kingfisher.sh | \
  bash -s -- /opt/kingfisher

To install a specific tag:

curl --silent --location \
  https://raw.githubusercontent.com/mongodb/kingfisher/main/scripts/install-kingfisher.sh | \
  bash -s -- --tag v2.10.0

Windows¶

Remote repository scans and --staged scans require Git for Windows. Install it with command-line access enabled and verify git --version in PowerShell. If Git is installed outside PATH, or MSYS2 supplies a different Git, select the executable:

$env:KF_GIT_BINARY = 'C:\Program Files\Git\cmd\git.exe'

Download and run the PowerShell installer to place the binary in $env:USERPROFILE\bin (or another directory you specify):

# Windows
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force
Invoke-WebRequest -Uri 'https://raw.githubusercontent.com/mongodb/kingfisher/main/scripts/install-kingfisher.ps1' -OutFile install-kingfisher.ps1
./install-kingfisher.ps1

The installer auto-detects your Windows architecture and downloads the matching release artifact (windows-x64 or windows-arm64).

You can provide a custom destination using the -InstallDir parameter:

./install-kingfisher.ps1 -InstallDir 'C:\Tools\Kingfisher'

To install a specific tag:

./install-kingfisher.ps1 -Tag v2.10.0

To explicitly override architecture selection:

./install-kingfisher.ps1 -Arch arm64

Pre-commit Hooks¶

Install a Git pre-commit hook to block commits that introduce new secrets.

The installer:

Preserves any existing pre-commit hook by chaining it before Kingfisher.
Supports custom hook directories via --hooks-path (or Git's core.hooksPath).
Can be installed either per-repository or as a global hook.

macOS and Linux¶

Install a per-repository hook from the root of the repo you want to protect:

curl --silent --location \
  https://raw.githubusercontent.com/mongodb/kingfisher/main/scripts/install-kingfisher-pre-commit.sh | \
  bash

Uninstall from that repository:

curl --silent --location \
  https://raw.githubusercontent.com/mongodb/kingfisher/main/scripts/install-kingfisher-pre-commit.sh | \
  bash -s -- --uninstall

Install as a global pre-commit hook (using core.hooksPath):

curl --silent --location \
  https://raw.githubusercontent.com/mongodb/kingfisher/main/scripts/install-kingfisher-pre-commit.sh | \
  bash -s -- --global

Uninstall the global hook:

curl --silent --location \
  https://raw.githubusercontent.com/mongodb/kingfisher/main/scripts/install-kingfisher-pre-commit.sh | \
  bash -s -- --global --uninstall

Windows PowerShell¶

Install a per-repository hook from the root of the target repo:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force
Invoke-WebRequest -Uri 'https://raw.githubusercontent.com/mongodb/kingfisher/main/scripts/install-kingfisher-pre-commit.ps1' -OutFile install-kingfisher-pre-commit.ps1
./install-kingfisher-pre-commit.ps1

Uninstall from that repository:

./install-kingfisher-pre-commit.ps1 -Uninstall

Install as a global hook (using core.hooksPath):

./install-kingfisher-pre-commit.ps1 -Global

Uninstall the global hook:

./install-kingfisher-pre-commit.ps1 -Global -Uninstall

The installer automatically runs any existing pre-commit hook first, then executes kingfisher scan . --staged --quiet --no-update-check against the staged diff (anchored to HEAD when no commits exist yet).

Using the `pre-commit` Framework¶

Add Kingfisher as a hook in your .pre-commit-config.yaml:

repos:
  - repo: https://github.com/mongodb/kingfisher
    rev: <version-or-commit>
    hooks:
      # Recommended: Auto-downloads and caches the binary - no manual install or Docker required
      - id: kingfisher-auto

      # Alternative: Runs Kingfisher from Docker (requires Docker)
      - id: kingfisher-docker

      # Alternative: Uses locally installed Kingfisher (fastest, requires manual install)
      - id: kingfisher

Available hooks:

Hook ID	Description	Requirements
`kingfisher-auto`	Automatically downloads and caches the appropriate binary for your platform	curl, tar (or unzip on Windows)
`kingfisher-docker`	Runs Kingfisher in Docker	Docker
`kingfisher`	Uses locally installed Kingfisher binary	Manual installation

The kingfisher-auto hook is recommended for most users as it:

Automatically downloads the correct binary for your OS and architecture
Caches the binary in ~/.cache/kingfisher (Linux/macOS) or %LOCALAPPDATA%\kingfisher (Windows)
Works across Linux, macOS, and Windows (via Git Bash which comes with Git for Windows)
Requires no Docker or manual installation

Windows users: The kingfisher-auto hook uses a bash script that runs via Git Bash (included with Git for Windows). For native PowerShell, a kingfisher-pre-commit-auto.ps1 script is also available in the scripts/ directory.

The PowerShell auto-hook script also auto-detects Windows architecture and downloads the matching windows-x64 or windows-arm64 binary.

Then install the hook via pre-commit install. Every hook now drives Kingfisher directly with the built-in --staged flag:

kingfisher scan . --staged --quiet --no-update-check

When --staged is set, Kingfisher snapshots the staged index into a temporary commit, diffs it against HEAD (or an empty tree if no commits exist yet), and scans only those staged changes.

Exit codes: Kingfisher exits 0 when no findings are present and returns 205 when validated credentials are discovered (other findings use codes in the 200 range). The hook surfaces those exit codes directly to pre-commit, so no extra handling is required—the commit will fail automatically on non-zero exits.

To trigger a hook in CI without installing to .git/hooks, run (for example):

pre-commit run kingfisher-auto --all-files

Pin to a specific version:

To use a specific Kingfisher version with the kingfisher-auto hook, set the KINGFISHER_VERSION environment variable:

repos:
  - repo: https://github.com/mongodb/kingfisher
    rev: v1.76.0
    hooks:
      - id: kingfisher-auto
        # Optional: pin to a specific kingfisher binary version
        # env:
        #   KINGFISHER_VERSION: "1.76.0"

Using Husky (Node.js projects)¶

For Node.js projects using Husky, you can add Kingfisher to your pre-commit hooks:

Quick setup (recommended):

# Initialize Husky if you haven't already
npx husky init

# Add Kingfisher to the pre-commit hook (auto-downloads binary)
echo 'curl -fsSL https://raw.githubusercontent.com/mongodb/kingfisher/main/scripts/kingfisher-pre-commit-auto.sh | bash' >> .husky/pre-commit

Or use the helper script:

curl -fsSL https://raw.githubusercontent.com/mongodb/kingfisher/main/scripts/install-husky.sh | bash -s -- --auto-install

Available options:

# Use auto-download (recommended - no pre-installation needed)
./scripts/install-husky.sh --auto-install

# Use Docker (requires Docker, no binary installation)
./scripts/install-husky.sh --use-docker

# Use local binary (requires kingfisher to be installed)
./scripts/install-husky.sh

# Uninstall
./scripts/install-husky.sh --uninstall

Manual setup:

If you prefer to configure Husky manually, add one of these to your .husky/pre-commit:

# Option 1: Auto-download binary (recommended)
curl -fsSL https://raw.githubusercontent.com/mongodb/kingfisher/main/scripts/kingfisher-pre-commit-auto.sh | bash

# Option 2: Use Docker
docker run --rm -v "$(pwd)":/src ghcr.io/mongodb/kingfisher:latest scan /src --staged --quiet --no-update-check

# Option 3: Use locally installed binary
kingfisher scan . --staged --quiet --no-update-check

For faster repeated hook runs, pre-warm the compiled rule cache:

kingfisher rules compile-cache
kingfisher scan . --staged --quiet --no-update-check

Kingfisher caches compiled rules by default and uses a platform default cache directory when --rule-cache-dir is omitted. See ADVANCED.md for cache locations, custom-rule behavior, and the --no-rule-cache opt-out.

For long-lived developer machines or shared CI cache volumes, prune old compiled rule databases explicitly:

kingfisher rules prune-cache --dry-run
kingfisher rules prune-cache

Windows with PowerShell:

For Windows users preferring native PowerShell over Git Bash, create a .husky/pre-commit.ps1 or add to your hook:

# Download and run the PowerShell auto-install script
Invoke-WebRequest -Uri 'https://raw.githubusercontent.com/mongodb/kingfisher/main/scripts/kingfisher-pre-commit-auto.ps1' -OutFile "$env:TEMP\kf-scan.ps1"
& "$env:TEMP\kf-scan.ps1"

If needed, you can override architecture explicitly:

& "$env:TEMP\kf-scan.ps1" -Arch arm64

Or if Kingfisher is already installed:

kingfisher scan . --staged --quiet --no-update-check

Cargo¶

The crates.io package is named kingfisher-bin, matching PyPI; the installed command is kingfisher. Once the release is published to crates.io:

cargo install --locked kingfisher-bin
kingfisher --version

This compiles from source and requires Rust 1.99 or newer and the platform's native build prerequisites described below. The rule catalog is bundled; installation does not fetch Betterleaks or Veles sources.

Native Scan Wizard¶

The native GPUI workspace is built into the CLI with the optional gui feature:

cargo build --release --features gui --bin kingfisher
./target/release/kingfisher wizard
# Equivalent alias:
./target/release/kingfisher gui

On Windows, run target\release\kingfisher.exe wizard. You can supply a scan target or open an existing report with kingfisher wizard --report report.json. Scans run the same binary; no separate desktop executable or CLI installation is needed. Ordinary headless builds do not compile GPUI. Current pre-built releases do not include this optional feature.

See the wizard guide for controls, native report views, shell command copying, and platform prerequisites.

Compile from Source¶

Source builds embed the prepared catalog of 488 rules; they do not download Betterleaks or Veles sources. Cargo dependencies and native build prerequisites must still be available. The repository preserves license texts, source headers, and provenance under crates/kingfisher-rules/generated/; the source archive includes those files.

You may compile for your platform via make:

# NOTE: Requires Docker
make linux

# macOS --- must build from a macOS host
make darwin

# Windows x64 --- run from an MSYS2 MINGW64 shell
make windows-x64

# Windows ARM64 --- run from an MSYS2 CLANGARM64 shell
make windows-arm64

These Windows targets use the published GNU/LLVM Vectorscan archives. The Vectorscan crate does not support MSVC targets; use the matching MSYS2 target environment when building Kingfisher from source.

# Build all targets
make linux-all # builds both x64 and arm64
make darwin-all # builds both x64 and arm64
make all # builds for every OS and architecture supported

Run Kingfisher in Docker¶

Run the dockerized Kingfisher container:

# GitHub Container Registry 
docker run --rm ghcr.io/mongodb/kingfisher:latest --version

# Scan the current working directory
# (mounts your code at /src and scans it)
docker run --rm \
  -v "$PWD":/src \
  ghcr.io/mongodb/kingfisher:latest scan /src

# Reuse the compiled rule cache across disposable containers:
# mount a host cache directory and set KF_RULE_CACHE_DIR.
docker run --rm \
  -v "$PWD":/src \
  -v "$HOME/.cache/kingfisher-rule-cache":/kf-cache \
  -e KF_RULE_CACHE_DIR=/kf-cache \
  ghcr.io/mongodb/kingfisher:latest scan /src

# Optionally prune old mounted cache entries during the scan.
docker run --rm \
  -v "$PWD":/src \
  -v "$HOME/.cache/kingfisher-rule-cache":/kf-cache \
  -e KF_RULE_CACHE_DIR=/kf-cache \
  ghcr.io/mongodb/kingfisher:latest scan /src --prune-rule-cache


# Scan while providing a GitHub token
# Mounts your working dir at /proj and passes in the token:
docker run --rm \
  -e KF_GITHUB_TOKEN=ghp_… \
  -v "$PWD":/proj \
  ghcr.io/mongodb/kingfisher:latest \
    scan https://github.com/org/private_repo.git

# Scan an S3 bucket
# Credentials can come from KF_AWS_KEY/KF_AWS_SECRET, --role-arn, or --profile
docker run --rm \
  -e KF_AWS_KEY=AKIA... \
  -e KF_AWS_SECRET=g5nYW... \
  ghcr.io/mongodb/kingfisher:latest \
    scan s3 bucket-name


# Scan and write a JSON report locally
# Here we:
#    1. Mount $PWD → /proj
#    2. Tell Kingfisher to write findings.json inside /proj/reports
#   3. Ensure ./reports exists on your host so Docker can mount it
mkdir -p reports

# run and output into host's ./reports directory
docker run --rm \
  -v "$PWD":/proj \
  ghcr.io/mongodb/kingfisher:latest \
    scan /proj \
    --format json \
    --output /proj/reports/findings.json


# Tip: you can combine multiple mounts if you prefer separating source vs. output:
# Here /src is read‑only, and /out holds your generated reports
docker run --rm \
  -v "$PWD":/src:ro \
  -v "$PWD/reports":/out \
  ghcr.io/mongodb/kingfisher:latest \
    scan /src \
    --format json \
    --output /out/findings.json

# Scan and view the HTML report in your browser (Docker)
# Use --view-report-address 0.0.0.0 and -p to expose the report server to the host
docker run --rm \
  -v "$PWD":/src \
  -p 7890:7890 \
  ghcr.io/mongodb/kingfisher:latest \
  scan /src --blast-radius --view-report --view-report-address 0.0.0.0
# Then open http://localhost:7890 in your browser

PyPI Wheels¶

If you want to run Kingfisher from PyPI, you can install it using uv, pip, or run it directly with uvx:

# Install with uv (recommended)
uv tool install kingfisher-bin

# Or install with pip
pip install kingfisher-bin

# Then run Kingfisher
kingfisher --help

Or run it without installation using uvx:

uvx kingfisher-bin --help

For in-process Python embedding, install kingfisher-secret-scanner and import kingfisher_sdk; kingfisher-bin installs the CLI command. See the Python SDK and wheel guide for SDK examples and publishing.