Independent Rust engine · Offline detection
Keyspoor is a secret scanner for repositories, CI and AI coding agents. Scan files, Git history and archives with 225 rules, precise locations and redacted results.
Current version 0.1.3 · Apache-2.0 · Rust APIs may change before 1.0
Install the CLI with Rust 1.96 or newer.
cargo install keyspoor --version 0.1.3 --locked
keyspoor scan . --format jsonlRun the native Rust CLI with Node.js 20+.
npm install -g keyspoor@0.1.3
keyspoor scan . --format jsonlInstall on macOS or supported Linux GNU systems.
brew install majiayu000/tap/keyspoorThe npm package bundles binaries for macOS ARM64/x64, Linux GNU ARM64/x64 and Windows x64. Linux builds use Ubuntu 24.04; older glibc and Alpine/musl are not supported targets. No install hooks or runtime binary downloads. This is a CLI launcher, not a JavaScript SDK. Standalone releases are available through GitHub.
With Node.js 20+, run this made-up example in a macOS/Linux terminal.
printf 'password=KspDemo_7zQ2mX9pL4vN6sR8\n' | npx -y keyspoor@0.1.3 scan - --format jsonExpected: one finding with redacted: [REDACTED] and exit code 1. Clean scans return 0; errors or incomplete scans return 2. First installation needs npm access; detection runs locally.
Read the staged index, inspect locally reachable Git history, respect ignore files and track existing findings with fingerprint baselines. History scanning reuses unique Git blobs while preserving commit and path occurrences.
keyspoor staged .
keyspoor history . --range main..HEADUse JSON, streaming JSONL or SARIF. The read-only MCP server exposes scan_text and scan_paths, with progress, cancellation and bounded previews. Errors and incomplete scans remain explicit.
keyspoor mcp --root /path/to/project
keyspoor scan . --format sarifCompile rules once and reuse an Engine across requests and threads. Custom JSON rules can define capture groups, keyword gates, entropy thresholds, path filters and allowlists.
use keyspoor::{Engine, EngineConfig};
let engine = Engine::new(EngineConfig::default())?;
let findings = engine.scan_bytes("config.env", input)?;Reports contain rules, byte locations, fingerprints and explanations, without raw secrets or source snippets. Scan UTF-16 and single-layer Base64, or expand ZIP/tar/gzip archives within depth and byte budgets.
No provider requests, credential validation or revocation. Archive members are never written to disk.
CLI exit codes distinguish a complete scan without reported findings (0), a complete scan with findings (1) and errors or incomplete scans (2). Baselines and ignores affect what is reported.
Add a scanner step after checkout. The Action saves a redacted report and fails on findings or incomplete scans.
- uses: majiayu000/keyspoor@v1
with:
path: .
format: sarifCopy the complete PR/push workflow · Reports, Git hooks and existing findings
The repository includes research on 22 external projects, including detect-secrets, Gitleaks, TruffleHog and Kingfisher. A format rule, an offline detector and a live credential validator have different boundaries. Start with those boundaries before comparing timing.
| Decision | Keyspoor today | Evidence and limits |
|---|---|---|
| Embed a Rust scanner | Independent engine with reusable byte-scanning and streaming APIs. | Implementation decisions. Uses general-purpose libraries; no other scanner SDK. |
| Audit rule coverage | 225 default rules: 221 adapted MIT-licensed Gitleaks rules and four independently written rules. | Rule provenance. Rule count is not provider count or accuracy; not a Gitleaks-compatible engine. |
| Connect a coding agent | Read-only MCP, persistent JSONL requests and redacted structured output. | Interface contracts. MCP previews are bounded; root checks are not an OS sandbox. |
| Scan cloud sources or validate credentials | No cloud connectors, provider verification or revocation. | Feature matrix and alternatives. No GPU/ML, cross-function analysis or Python/JS in-process bindings. |
The v6 metadata-sharing optimization was measured against the previous version using 20 alternating pairs on Apple M2 Max/macOS. These are within-project comparisons, not claims to outperform every scanner.
| Synthetic workload | Median scanner peak RSS | Scanner CPU change |
|---|---|---|
| One file, 100,000 findings | 99.86 → 59.59 MiB | −8.74% |
| 16 files, four workers, 100,000 findings | 118.85 → 76.38 MiB | −8.55% |
Regular throughput and Git workloads were broadly unchanged; some sparse workloads had slightly higher RSS. Previously observed synthetic regression sets retained 600 true positives, 25 false positives and zero false negatives. These results do not establish real-world precision or production-wide recall.
Historical evidence uses the former project name secret-scan. Recorded commands and binary hashes are preserved. Offline benchmarks do not measure live verification; unsupported tools and modes are not scored as zero.
使用自研 Rust 扫描引擎，支持文件、Git 暂存区、历史记录和归档，默认提供 225 条规则。可通过 Cargo 或 npm 安装原生 CLI，也可作为 Rust 库或只读 MCP 服务接入工具链。
报告默认脱敏，保留规则、位置、指纹和解释；扫描错误不会伪装成干净结果。目前没有云连接器、凭据活性验证、GPU/ML 或跨函数分析。Benchmark 保留硬件、参数、原始数据与适用边界。