Keyspoor

Keyspoor

Offline secret scanning for AI coding workflows. Keyspoor scans files, staged Git changes, local Git history and ZIP/tar/gzip archives, with redacted JSON, JSONL and SARIF results. Use it as a native CLI, a reusable Rust library or a read-only MCP server. Connect agents through MCP; use a staged hook or a required CI check to block commits or merges.

Website · Rust API · crates.io · npm · Releases · 简体中文

Try it in 60 seconds

With Node.js 20+, paste this into a macOS/Linux terminal. The value below is made up for this demo and is not a credential:

printf 'password=KspDemo_7zQ2mX9pL4vN6sR8\n' | npx -y keyspoor@0.1.4 scan - --format json

echo "exit=$?"

Expected: exit=1 and one finding. The relevant report fields are:

{"complete":true,"findings":[{"rule_id":"generic-credential-unquoted","path":"stdin","line":1,"column":9,"redacted":"[REDACTED]"}],"errors":[]}

This is an excerpt; the actual report also includes ranges, fingerprints, statistics and scan context. It contains neither the value nor a source snippet. On Windows PowerShell, pipe the same synthetic string to npx.cmd -y keyspoor@0.1.4 scan - --format json, then check $LASTEXITCODE.

Watch a commit get blocked, then repaired

With Git and an installed keyspoor CLI, run the complete demo from a checkout:

sh examples/first-scan.sh

It creates and deletes its own temporary repository. The recording comes from an actual 0.1.3 run with invented input: finding exit 1, blocked commit, repair exit 0, accepted commit. No agent is involved in this hook demo. MCP setup gives agents tools; it does not guarantee they call them before each commit. CI and hooks provide enforcement.

Install

# Rust toolchain (1.96 or newer)

cargo install keyspoor --version 0.1.4 --locked

Or Node.js 20+: the npm package runs the native Rust CLI

npm install -g keyspoor@0.1.4

Or Homebrew (macOS / Linux)

brew install majiayu000/tap/keyspoor

keyspoor scan . --format jsonl

Current release: 0.1.4. The Rust API is pre-1.0 and may change. The npm package bundles native binaries for macOS (Apple Silicon/Intel), Linux GNU (ARM64/x64) and Windows x64; it is a CLI launcher, not a JavaScript scanning SDK. There are no install hooks or runtime binary downloads. First-time npm/npx installation requires registry access; scanning itself is offline. Standalone binaries are also available. To build from source, run cargo build --release --locked and use target/release/keyspoor.

Why Keyspoor

• Offline by design: scanning does not call credential providers, and reports omit raw secrets and source snippets.
• Reusable Rust engine: compile rules once and share an Engine across calls and threads; no scanner SDK dependency.
• Agent interfaces: MCP scan_text / scan_paths, persistent JSONL requests, progress and cancellation, plus explicit incomplete-scan reporting.
• Repository-aware inputs: staged index contents, local Git history, bounded archive expansion, ignore files and fingerprint baselines.
• Evidence you can inspect: versioned rules, documented exclusions and reproducible quality, throughput and allocation measurements.

The matching, keyword dispatch, filtering, decoding, location mapping, Git acquisition and agent interfaces are implemented here. This project does not depend on Kingfisher or another secret scanner SDK. It uses general-purpose Rust regex, Aho–Corasick, hashing and archive libraries.

The built-in catalog contains 221 rules adapted from the MIT-licensed Gitleaks v8.30.1 catalog plus four independently written rules (three generic assignment rules and one URI-password rule), for 225 rules in the default engine. See rule provenance and exclusions and third-party notices. This is not a Gitleaks-compatible engine: rule semantics that cannot be preserved are explicitly excluded. The implementation decision records the build/adapt boundary and rejected SDK and wrapper alternatives.

CLI and repository scans

keyspoor scan /path/to/project --format json

keyspoor staged /path/to/repository keyspoor history /path/to/repository keyspoor history /path/to/repository --range main..HEAD keyspoor scan - --format jsonl keyspoor scan /path/to/project --write-baseline baseline.json keyspoor scan /path/to/project --baseline baseline.json keyspoor rules keyspoor serve keyspoor mcp --root /path/to/project

Version 0.1.4 changes credential-context matching and the engine configuration identity. Review and recreate older baselines. See the correction results and Benchmark.

Exit codes: 0 means the selected scan completed with no reported findings; 1 means it completed with findings; 2 means an error or incomplete scan. You can check both other outcomes with synthetic input:

printf 'ordinary configuration\n' | npx -y keyspoor@0.1.4 scan - --format json

echo "exit=$?" # 0: complete=true, findings=[] printf 'ordinary configuration\n' | npx -y keyspoor@0.1.4 scan - --max-bytes 4 --format json echo "exit=$?" # 2: complete=false, errors contains "input exceeds 4 byte limit"

When a finding appears, inspect its path and position locally, remove exposed credentials from tracked files and rotate any real credential that was exposed. Review known intentional findings before recording a baseline. Investigate every 2 result before treating the scan as complete.

An ignored finding is not evidence that the original input contained no secret. Baselines suppress existing fingerprints but preserve changed secret values. An incomplete scan cannot replace a baseline. Baseline schema 2 binds the scan mode, canonical roots, effective ignore policy (including Git/Jujutsu repository boundaries), size budget and engine settings (including rule content and fingerprint key identity). A different scope or policy cannot compare against or overwrite that baseline. Create a separate baseline when intentionally changing policy. Schema 1 baselines are rejected. Canonical filesystem identity makes aliases such as ./ stable; reported paths and rule path predicates remain relative to the selected source root.

Every finding is redacted and contains a rule, path, byte range, one-based line, zero-based byte column, confidence, explanation and fingerprint. No raw secret or source snippet is serialized. The default unkeyed fingerprint is a digest, not encryption and not protection against guessing low-entropy secrets. Supply --fingerprint-key-file with exactly 32 private bytes for keyed BLAKE3 identities. Keep the same private key when comparing baselines.

Exact matches at the same secret byte span within one decoded view are merged. rule_id identifies the primary rule: non-generic- IDs take precedence, then higher confidence, then lexical rule ID. Merged findings include sorted matched_rule_ids containing the primary and other matching rules; single-rule findings omit that field. Adjacent occurrences, partial overlaps and distinct positions inside one Base64 container stay separate. The primary rule determines the fingerprint. This semantic update changes the engine configuration identity, so previous baselines must be explicitly recreated rather than compared silently.

Scanning never contacts credential providers or validates whether a credential is active. Filesystem scans respect ignore files by default; --no-ignore includes ignored files, while Git metadata remains excluded. Oversized inputs are reported as incomplete, not clean. Default file and archive expansion limits are 64 MiB; --max-bytes changes the budget. Archive traversal never writes members to disk. ZIP, tar and gzip have a shared expansion budget and at most four nesting levels. Encrypted or damaged members remain visible as errors.

Staged mode reads the index version of each changed file, not the working tree. It scans whole staged files to preserve credential-pair context. History mode scans locally reachable commits, reads each unique blob once and retains commit/path occurrences. It does not fetch LFS, submodules or remote refs, and also unpacks supported archives in Git blobs, retaining commit/member paths. stats.files/bytes count unique inputs; detection_passes counts actual path-sensitive engine calls.

GitHub Action

Copy the complete pull request workflow into .github/workflows/keyspoor.yml, or follow the CI setup guide for reports, permissions, baselines and failure handling. Its scan job can be required in branch protection. The core steps are:

permissions:

contents: read steps:

• uses: actions/checkout@v7
• uses: majiayu000/keyspoor@v1 id: secrets with: path: . format: sarif
• uses: actions/upload-artifact@v7 if: always() && steps.secrets.outputs.report-path != '' with: name: keyspoor-report path: ${{ steps.secrets.outputs.report-path }}

Place these steps in a job. The Action installs the exact npm package version recorded at its source ref, scans the selected path and saves a redacted report outside the checkout. report-path points to that file; exit-code preserves 0 (clean), 1 (findings), or 2 (error/incomplete). Findings and errors fail the step; reports may be incomplete after an error. Use a full commit SHA to pin the Action immutably instead of the maintained v1 ref. Supported report formats are SARIF (default), JSON and JSONL. Installation needs npm registry access; detection itself remains offline. The Action scans files; use the CLI for staged/history modes and custom engine options.

Releases publish through GitHub Actions with npm and crates.io trusted publishing. Homebrew updates in the existing tap run hourly and may be delayed by GitHub scheduling. See the release guide for triggers and verification.

Library and custom rules

Add keyspoor = "0.1" and anyhow = "1" to your dependencies for this example.

use keyspoor::{Engine, EngineConfig};

fn main() -> anyhow::Result<()> { let engine = Engine::new(EngineConfig::default())?; let findings = engine.scan_bytes("config.env", b"ordinary configuration")?; assert!(findings.is_empty()); Ok(()) }

Reuse an engine across calls and threads to avoid repeated compilation. It does not install a global runtime, logger or executor.

Finding.path and Finding.explanation are shared Arc values. This is a breaking Rust API change from String: use .into() when assigning an owned string, .as_ref() to read &str, and replace the field to change its text. JSON still contains ordinary strings; fingerprints, scan context and baseline identity are unchanged. Generated findings share paths within one engine scan and explanations across calls using the same engine. Deserialization does not intern repeated strings.

Custom JSON rule files use {"rules": [...]} a