KeyHog：面向代码、云和 CI 的 GPU 加速密钥扫描器

KeyHog 是一款用 Rust 编写的开源密钥扫描器，可跨源代码、Git 历史、容器、云存储、浏览器资产、协作内容以及运行中的系统，发现并验证泄露的 API 密钥、令牌、密码和凭据。

大多数密钥扫描器仅止步于仓库检出中的 CPU 正则匹配。KeyHog 结合了 926 个服务特定检测器、针对隐藏凭据的穿透式解码、上下文感知的置信度与抑制、实时供应商验证，以及通过 Vyre 提供的 一流的 CUDA、Metal 和 WGPU 执行。校准会衡量每个符合条件的纯 Rust CPU、Hyperscan/SIMD 和 GPU 后端。随后，自动路由会针对确切的主机和工作负载类别，选择经过等价性验证的最快路径。

GPU 是真正的后端	扫描真正的攻击面	区分信号与噪声	根据结果采取行动
CUDA、原生 Metal 和 WGPU 是经过实测的对等后端，而非静默的回退链。	扫描 Git 历史、Docker 层、归档、云存储桶、源映射、WASM、HAR 捕获、托管的 Git 集合以及整个系统。	在应用置信度、示例抑制和基线之前，先解码 base64、hex、URL、protobuf、多行及结构化配置。	通过供应商 API 验证符合条件的凭据，发出 SARIF 或结构化信封，并保留确切的覆盖范围与退出语义。
cargo install --locked keyhog
keyhog scan .

<p align="center">
  <img src="https://assets.kitploit.com/production/public/readmes/7654/dfb768a9b8e8fa64082992f11d0b284d5ec6a199fc1eac85e0352fb20452186f.gif" alt="KeyHog 扫描显示严重性、置信度、文件与行号、修复建议、结果和覆盖率状态" width="900" />
</p>

## 围绕 GPU 构建的机密扫描器

KeyHog 不会将几个正则表达式交给一个通用的计算着色器。
它的 GPU 路径基于 [Vyre](https://github.com/santhreal/vyre) 构建，这是一个 Rust GPU
计算基座，与 KeyHog 同步开发。检测器触发条件会编译为
驻留在 GPU 中的不可变表。有界的源批次会生成完整的匹配
位置，供与 CPU 和 Hyperscan 路径相同的确认、抑制、置信度及
报告流水线使用。

- **三个物理 GPU 通道。** CUDA、原生 Metal 和可移植 WGPU 会
  被独立获取、测量并报告。
- **精确的结果一致性。** 校准会拒绝检测结果标识与参考路径
  不同的候选结果。更快的错误答案永远不会进入
  路由表。
- **持久化的路径证据。** KeyHog 会记录二进制文件、检测器语料库、
  配置、工作负载类型、主机、加速器、驱动程序以及实测时序
  证据。普通扫描不会在热路径中进行基准测试。
- **常驻执行。** 守护进程工作线程会让已编译的检测器与加速器
  状态保持预热，以便重复处理文件、归档、历史、远程及云端批次。
- **没有隐藏的 CPU 逃生通道。** 明确选择的加速器若无法
  初始化或调度，会以可见方式失败，而不会在 GPU 标签下返回
  CPU 检测结果。

默认的 crates.io 安装使用可移植的纯 Rust CPU 路径，因此可以在
干净的 Rust 主机上运行。无需引入 Hyperscan 即可启用三个 GPU 通道：```sh
cargo install --locked keyhog --no-default-features --features portable,gpu

运行生产后端诊断，然后检查测量到的路由：```sh keyhog backend --self-test keyhog calibrate-autoroute --policy all keyhog backend --autoroute --json

The [backend guide](https://santhreal.github.io/keyhog/backends.html) documents
the resident tables, bounded dispatch model, parity contract, and reproducible
crossover evidence.

## 快速开始

### 安装并运行你的第一次扫描

上面的两条命令会安装最新的 crates.io 版本，并使用可移植的纯 Rust 路由扫描当前目录树。

要将 CI 环境固定到某个精确版本，请使用
`cargo install --locked --version '=0.5.75' keyhog`。KeyHog 需要 Rust 1.89
或更新版本。请参阅[安装指南](https://santhreal.github.io/keyhog/install.html)
了解 GPU、Hyperscan、CI、可移植和源码构建配置。

当扫描干净时 KeyHog 退出 `0`；当报告了高于你的严重性阈值的发现时退出 `1`。
退出 `1` 表示扫描器正常工作。请审查每条发现的文件、行号、检测器和修复建议，
再决定是删除、轮换还是抑制该凭据。其他非零代码表示输入、系统、验证或覆盖失败；
请参阅[退出码参考](https://santhreal.github.io/keyhog/reference/exit-codes.html)。

完整的进程契约如下：

| 退出码 | 含义 |
|---|---|
| `0` 干净 | 扫描已完成，没有可报告的发现或覆盖失败。 |
| `1` 发现 | 存在发现，但没有一条被确认为存活。 |
| `2` 操作员错误 | 修复参数、配置、检测器语料库或可由操作员修正的输入。 |
| `3` 系统错误 | 修复或重试运行器。这包括低级 I/O、致命的守护进程服务、增量缓存以及显式选择的 SIMD 失败。 |
| `4` `backend --self-test` 或维护失败 | 请求的安装、修复、后端或自动路由健康检查不健康。 |
| `10` 存活凭据 | 至少有一条凭据被确认为存活。当存在更新版本时，`update --check` 也使用此退出码。 |
| `11` 扫描器恐慌 | 丢弃扫描结果，因为扫描器状态不可信。 |
| `12` 必需 GPU 失败 | 显式选择或必需的 GPU 路径无法执行。 |
| `13` 覆盖不完整 | 请求的源失败或输入覆盖不完整，且没有发现结果优先。 |
| `130` 已中断 | SIGINT 或 Ctrl-C 中断了进程。 |

**筛选、格式化、门控：**

在将其用作筛选器之前，请先创建基线：```sh
keyhog scan . --create-baseline .keyhog-baseline.json
keyhog scan . --baseline .keyhog-baseline.json --format json-envelope --output keyhog.json

第一个命令对已审核的发现进行快照，并以 0 退出，而不打印它们。提交该文件，然后使用第二个命令仅报告新的发现身份。基线条目按检测器和凭据值匹配，而不是按文件路径，因此移动已记录的机密不会导致门禁失败，但轮换它就会失败。更改的凭据和不完整的覆盖范围仍然可见。完整路径（包括 monorepo 分区）是仅对新的机密失败。

对于下一次扫描，请使用配方手册或选择正确的工作流程中的可复制命令。你可以扫描 Git 历史、容器镜像、云存储桶、仓库集合、 URL 以及整个机器，而无需更换工具。

将其添加到 GitHub Actions

创建 .github/workflows/keyhog.yml:```yaml name: keyhog on: push: branches: [main] pull_request: permissions: contents: read security-events: write jobs: scan: runs-on: ubuntu-latest steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - uses: santhreal/keyhog@v0 with: path: . severity: high

该 Action 扫描已检出的工作树，在存在 `high` 或 `critical` 级别发现时失败，将 SARIF 上传到 Code Scanning，并将报告保留为工作流构件。安装、覆盖范围、后端和报告发布失败同样会使作业失败。

有关输入、输出、基线采用、monorepo 分区、验证和失败行为，请参阅 [GitHub Action 指南](https://santhreal.github.io/keyhog/workflows/github-action.html)。有关 GitLab、CircleCI、Jenkins、Buildkite 和通用 shell 作业，请参阅 [CI 指南](https://santhreal.github.io/keyhog/workflows/ci.html)。有关仓库组织、托管的 Git 组、云存储桶和分区清单，请参阅 [大规模扫描指南](https://santhreal.github.io/keyhog/guides/mass-scanning.html)。

## 其他工具视为独立产品的扫描面

KeyHog 扫描的是可能发生泄露的边界处的字节，而不仅仅是受跟踪的源文件。每个边界使用一份报告，以便 CI 保留精确的覆盖范围和失败状态。

| 暴露面 | 示例 |
|---|---|
| 最终包构件 | 运行 `npm pack`，然后用 `keyhog scan package.tgz` 扫描生成的 `.tgz`。归档展开会检查预期源代码树中不存在的生成文件、source map、fixtures 和元数据。 |
| 已部署的浏览器应用 | `keyhog scan --url https://app.example.com/assets/app.js` 遵循有界的 JavaScript、source map、WASM 和响应解码，而不会将扫描器变成无界的爬虫。 |
| GitHub issues、pull request、讨论、wiki 和 gist | `keyhog scan --github-collaboration owner/repo --github-all` 扫描检出之外的所有协作面。 |
| AI agent 和 MCP 配置 | `keyhog scan ~/.config ~/.claude ~/.codex` 将相同的检测器、解码、置信度和报告流水线应用于本地工具配置。 |
| 容器镜像层 | `keyhog scan --docker-image registry.example.com/team/app:v1` 扫描将要运行的镜像内容，包括构建期间引入的文件。 |
| 云对象清单 | `keyhog scan --s3-bucket BUCKET`、`--gcs-bucket BUCKET` 或 `--azure-container-url URL` 在终端报告中保留提供程序分页、对象和字节限制覆盖范围。 |
| 整个开发主机 | `sudo keyhog scan-system --space 50G` 在严格的存储预算下发现已挂载的文件系统和可达的 Git 历史。 |

这些路由共享同一个检测和报告契约。特定来源的失败不会无声地变成范围更窄的本地扫描。

## 选择正确的工作流

首先选择来源边界。预设会改变检测工作，而后端会改变执行方式。两者都不会将工作树扫描扩展为 Git 历史、提供程序清单、云存储或主机审计。

没有真正的 `scan everything` 捷径。完整的资产审查会将下面的相关边界作为独立作业运行，并保留每个 `json-envelope` 报告及其原始退出代码。

| 需求 | 起始命令 | 吞吐量与复用 | 覆盖边界 |
|---|---|---|---|
| 快速本地反馈 | `keyhog scan . --fast --incremental` | 复用未更改文件的哈希。fast 预设跳过解码、熵和 ML 工作。 | 在合并前运行默认策略，因为 fast 有意地范围更窄。 |
| 完整仓库扫描 | `keyhog scan .` | 校准后的 `auto` 和 CPU 核心工作线程默认值。对同一可信树的重复扫描添加 `--incremental`。 | 仅当前文件。不会添加 Git 历史。 |
| 暂存提交门禁 | `keyhog scan --git-staged` 或 `keyhog hook install` | 读取精确的索引 blob，因此未暂存的编辑无法改变结果。 | 仅暂存内容。当本地未暂存字节很重要时，请单独运行工作树扫描。 |
| 永久仓库守护 | `keyhog guard add . --mode repo`，然后 `keyhog guard status .` | 常驻守护进程的根注册表，具有 7 状态机、干净证明缓存和策略身份跟踪。 | 需要运行中的守护进程。守护是对暂存和工作树扫描的补充，而非替代。 |
| GitHub pull request 门禁 | `santhreal/keyhog@v0` | 该 Action 安装、扫描、发布 SARIF 和构件，然后保留 KeyHog 的状态。 | 一个检出路径。对组织使用提供程序清单扫描。 |
| GitLab、Jenkins、Buildkite 或 shell CI | `keyhog scan . --format json-envelope --output keyhog.json` | 在成功、发现和错误时持久化报告和退出代码。仅对明确更窄的变更行门禁使用 `--git-diff <base>`。 | 检出中存在的字节，或选定的 diff。 |
| 接入存在已知发现的仓库 | 创建 `.keyhog-baseline.json`，提交它，然后使用 `--baseline .keyhog-baseline.json` 扫描。 | 现有身份在基线中保持可见，只有新发现才会使门禁失败。 | 基线不会抑制已更改的凭据或不完整的覆盖范围。 |
| 递归 Git 恢复 | `keyhog scan --deep --git-history . --git-blobs . --daemon=off` | 每个工作线程类别校准一次 deep 策略。在进程内运行。 | 一个仓库。`--git-history` 仅覆盖当前检出的祖先，因此从未检出的分支会被遗漏且没有覆盖缺口；`--git-blobs` 还能触及悬空 blob、被 amend 掉的提交、stash、notes、带注释的标签消息和打包引用。 |
| 容器或归档检查 | `keyhog scan --docker-image registry/app:v1` 或 `keyhog scan incoming/` | 保留信封报告，使跳过的、损坏的、加密的、不安全的或超大的成员保持可见。 | 仅选定的镜像或文件系统路径以及受支持的嵌套格式。 |
| URL、响应或 HAR 检查 | `keyhog scan --url https://api.example.com/config` 或 `keyhog scan capture.har` | 使用有界来源限制并保留终端信封。 | 仅获取的响应或捕获条目。这不是爬虫。 |
| 组织或云清单 | `keyhog scan --daemon=off --github-org acme --format json-envelope --output acme.json` | 按提供程序、所有者或存储桶分区。并发运行独立分区，每个分区一份报告和状态。 | 每个作业一个选定的提供程序清单。分页或对象限制仍然是覆盖边界。 |
| 确认符合条件的发现是否仍然有效 | `keyhog scan . --verify` | 提供程序并发和速率控制与扫描器工作线程分开。 | 向声明的提供程序端点发送凭据派生的请求。并非每个检测器都支持验证。 |
| 全主机健康扫描 | `sudo keyhog scan-system --space 50G` | 默认使用所有 CPU 核心，并在文件系统数据之后扫描发现的 Git 历史。 | 本地挂载的文件系统。网络挂载是选择加入的，空间上限是硬性的。 |
| Unix 上 GPU 支持的目录、历史、归档、远程或云清单 | 校准 autoroute，启动 `keyhog daemon start --mass`，然后运行 `keyhog scan --daemon=mass <SOURCE>`。 | 通过一个编译后的 CPU、Hyperscan、CUDA、Metal 或 WGPU 工作线程流式传输有界批次。为已预热的未更改文件系统树添加 `--incremental`。终端收据报告精确的总数和 GPU 批次、块、字节、GPU 份额和吞吐量。 | 基线、验证、锁定、预设、叠加和其他扫描器策略更改在采集前被拒绝。增量状态仅适用于守护程序本地的文件系统根。 |

### 扫描每个受支持的来源边界

每个边界使用一条命令。为每个清单分区保留 `json-envelope` 报告和原始退出状态。

| 来源或用例 | 命令 |
|---|---|
| 多个本地根 | `keyhog scan services/api services/web deploy/` |
| 持续变化的文件 | `keyhog watch services/api deploy/` |
| 暂存字节、变更行、可达历史或 blob | `keyhog scan --git-staged`、`--git-diff main`、`--git-history .` 或 `--git-blobs .` |
| 原生二进制和固件字符串 | `keyhog scan --binary firmware.bin`（普通目录扫描会跳过二进制文件，仍然退出 `0`） |
| 归档和压缩来源 | `keyhog scan incoming/`（受支持的成员自动展开） |
| Docker 镜像层 | `keyhog scan --docker-image registry/app:v1` |
| JavaScript、source map、WASM 或端点响应 | `keyhog scan --url https://api.example.com/config` |
| HTTP 请求和响应捕获 | `keyhog scan capture.har` |
| GitHub issues、pull request、讨论、wiki 和 gist | `keyhog scan --github-collaboration owner/repo --github-all` |
| GitHub、GitLab 或 Bitbucket 清单 | `--github-org ORG`、`--gitlab-group GROUP` 或 `--bitbucket-workspace WORKSPACE` |
| S3、GCS 或 Azure Blob 清单 | `--s3-bucket BUCKET`、`--gcs-bucket BUCKET` 或 `--azure-container-url URL` |
| 来自另一个工具的有界流 | `producer \| keyhog scan --stdin`（使用 `set -o pipefail`，以便失败的制作者呈现自己的错误，而不是零字节扫描） |

普通目录扫描不读取原生二进制文件。每个二进制文件都会成为 `binary (extension or content sniff)` 覆盖缺口，扫描仍然退出 `0`，而 `--no-default-excludes` 不会改变这一点，因此当编译产物在范围内时，请传递 `--binary`。该标志需要带有 `binary` 功能的构建，默认的 crates.io 安装具有此功能，而精简的 `ci` 功能则没有。

原生二进制提取报告满足命名检测器显式形状契约的完整凭据。它会抑制来自编译数据段的短前缀片段和通用赋值形状字符串，因为这些字节不保留来源上下文。

端点获取是有界的并经过 SSRF 筛查。它不是爬虫。私有云端点和凭据转发需要各自的显式信任标志。提供程序令牌应放在文档记录的环境变量中，而不是进程参数中。

有关来源和策略详情，请参阅 [工作流选择器](https://santhreal.github.io/keyhog/capabilities.html)；有关持续维护的仓库门禁，请参阅 [GitHub Action 指南](https://santhreal.github.io/keyhog/workflows/github-action.html)；有关持久化报告和退出处理，请参阅 [直接 CI 指南](https://santhreal.github.io/keyhog/workflows/ci.html)；有关分区和聚合，请参阅 [大规模扫描指南](https://santhreal.github.io/keyhog/guides/mass-scanning.html)。[配方手册](https://santhreal.github.io/keyhog/recipes.html) 涵盖容器、归档、URL、GitHub 协作内容和云来源。

### 无需猜测的速度与并发

从默认值开始。经过历史验证的二进制资产安装程序会自行运行校准。Cargo 在 `cargo install` 后无法执行 KeyHog，因此在安装多后端 Cargo 构建后运行一次以下命令，并在主机、二进制、检测器语料库、驱动程序或工作负载类别更改后再次运行：```sh
keyhog calibrate-autoroute --policy all
keyhog backend --autoroute --json

控件	用途	需保持不变的不变量
校准后的 `--backend auto`	常规 CPU、Hyperscan 或 GPU 选择。	显式后端是诊断性覆盖，而不是更快的默认值。
`--threads <N>`	在共享运行器上预留 CPU 容量。专用主机通常应保持未设置，以便 KeyHog 使用可用核心。	每个值都必须为正数。多个并发的 KeyHog 进程各自拥有一个工作线程池，因此应在分区之间划分主机预算。
`--reader-threads <N>`	已测量的存储管线，其中读取工作（而非扫描）是瓶颈。	默认值派生自扫描工作线程池。在性能分析显示读取瓶颈之前，请保持未设置。
`--incremental` 和 `--incremental-cache <PATH>`	对同一可信目录树进行重复扫描。	不要在无关的仓库或不可信任务之间共享同一个索引。
提供方或仓库分区	并发资产扫描和独立重试。	每个分区保留一个最终信封和原始退出码。不要将发现项拼接在一起并丢弃覆盖状态。
`--verify-concurrency`、`--verify-rate` 和 `--verify-batch`	独立于文件扫描来限制实时提供方检查。	验证会发送由凭据派生的请求。决定该并发的是提供方速率限制，而不是 CPU 数量。
大规模守护进程	在单个 Unix 工作器上处理 TB 级目录、历史、归档、远程或云流。	每个帧限制为 8 MiB 和 1,024 个块。守护进程序列化分片状态，并返回精确的 CPU/GPU 执行回执。
`--fast`、默认、`--deep` 或 `--precision`	用于选择明确的检测成本与召回率策略。	这些预设互斥，并且会改变覆盖范围。它们不是可互换的速度调节旋钮。

使用 keyhog config --effective 检查已解析的策略。在更改读取器、批次或通道深度控制之前，使用 --profile 测量固定的扫描器阶段和完整的操作员运行。低开销报告记录：源、后端、缓存、工作负载、线程、输入、状态转换、CPU 时间、峰值内存、精确二进制 SHA-256、已启用特性 SHA-256、目标三元组、构建配置、编译器、分配器、链接后端 SHA-256、检测器语料库 SHA-256、已启用检测器 BLAKE3、已编译计划 BLAKE3、哈希检测器来源、完整解析配置 BLAKE3、性能策略 BLAKE3、预设、已应用的保护状态、源适配器、哈希源目标 BLAKE3、哈希源分区 BLAKE3、原始源字节、源单元扇出、解码派生字节、已完成的后端分发字节，以及稳定的大小/扇出桶。对于其源适配器尚无法区分的字节域，会显式保持不可用，而不是变成测量到的零值。报告不会记录源内容、凭据值、原始路径、原始 URL 或原始配置值。仅将 --perf-trace 用于昂贵的逐模式和后端诊断计数器。除非在目标工作器上进行的可重现测量显示出改进，否则请保持高级管线控制不设置。```sh keyhog scan . --incremental
--format json-envelope --output keyhog.json

对于共享运行器，其中作业分配了四个扫描器工作进程和一个
读取器工作进程：```sh
keyhog scan . --threads 4 --reader-threads 1 \
  --format json-envelope --output keyhog.json

第二个命令是资源预算，而非普适最优值。在选择显式工作线程数量之前，请先测量目标主机。

对于深度恢复和全系统分类，请使用它们专门的指南，因为其覆盖范围和完成规则与常规仓库扫描不同。

密钥扫描器基准测试

这些面板比较检测策略、CPU 与 GPU 执行请求、增量缓存行为以及热守护进程请求。每个值都源自经过校验的基准测试快照。该快照绑定了扫描器版本、可执行文件摘要、检测器摘要、语料库、主机和运行时间戳。请使用完整基准测试证据获取竞争对手来源和各类别召回率。

检测准确率

KeyHog KeyHog v0.5.70 扫描了 mirror 语料库：15,000 个测试样本、3,000 个标记正例，以及 2,431,242 个输入字节。答案密钥清单已从扫描树中排除。该行数据在 AMD Ryzen 9 9950X 16-Core Processor 上使用显式 Hyperscan/SIMD 路线的默认策略。

精确率	召回率	F1	真阳性	假阳性	假阴性
0.9651	0.9027	0.9328	2,708	98	292

被跟踪的源树是干净的。

执行路线、预设与缓存

在配备 NVIDIA GeForce RTX 5090 的 AMD Ryzen 9 9950X 16-Core Processor 上测量，32 个逻辑核心，15,000 个测试样本、3,000 个标记正例，以及 2,431,242 个输入字节。扫描器：KeyHog v0.5.70。被跟踪的源树是干净的。

按执行路线的完整扫描

所有行均使用默认检测策略，且关闭增量缓存和守护进程。自动行记录所请求的策略，但基准测试结果不会绑定所选定的持久化路线，因此它不能作为路线选择的证明。GPU 行包含在此小语料库上的采集和完整扫描器启动过程；它们不是 GPU 内核交叉测量。

请求路线	墙钟时间	吞吐量	峰值 RSS	F1
Hyperscan/SIMD	860 ms	2.70 MB/s	416 MiB	0.9328
Pure-Rust CPU	903 ms	2.57 MB/s	509 MiB	0.9328
CUDA	2.03 s	1.14 MB/s	963 MiB	0.9328
WGPU	1.97 s	1.18 MB/s	1264 MiB	0.9328
Automatic	1.46 s	1.59 MB/s	634 MiB	0.9328

Hyperscan/SIMD 上的检测策略

路线、缓存、守护进程状态、语料库和主机保持不变。预设会改变检测工作量，因此除了时间之外，还应比较精确率和召回率。

策略	墙钟时间	精确率	召回率	F1	发现数
Fast	737 ms	0.9700	0.8837	0.9248	2,738
Default	860 ms	0.9651	0.9027	0.9328	2,816
Deep	861 ms	0.9645	0.9067	0.9347	2,845
Precision	849 ms	0.9590	0.6397	0.7674	2,001

增量热重跑

该基准测试先填充 BLAKE3 Merkle 索引，然后对第二次相同扫描计时。由于扫描器启动占主导地位，小型合成树变化不大；在声称提速之前，请先测量您的仓库。

Hyperscan/SIMD 默认策略	墙钟时间	吞吐量	峰值 RSS
关闭缓存	860 ms	2.70 MB/s	416 MiB
热增量缓存	617 ms	3.76 MB/s	457 MiB

热守护进程请求

一个确定性的 8 MiB 普通文件（sha256:afafbe7b6487fd62866f510e7c281a9e7bfeaa8dc585d7b0478c92ee6c4f5ef5）在一次预热请求后，分别在进程内和通过自有守护进程各扫描一次。守护进程时间指客户端请求时间；守护进程 RSS 归属于常驻服务器。

显式路线	进程内	热守护进程	热/单次	进程内 RSS	守护进程 RSS
Hyperscan/SIMD	323 ms	106 ms	0.33×	63 MiB	74 MiB
Pure-Rust CPU	278 ms	109 ms	0.39×	62 MiB	66 MiB
CUDA	1.65 s	232 ms	0.14×	674 MiB	666 MiB
WGPU	1.33 s	237 ms	0.18×	596 MiB	600 MiB

这些行涵盖热单文件路线。mass 路线还接受有边界的目录和远程源批次；其增量文件系统路径另行测量。

CPU、读取器、存储、大小与分区扩展

由 make -C benchmarks readme-scaling 从 benchmarks/reports/readme-scaling.json 生成。测试框架在 1 次预热后运行了 3 次测量试验，使用显式 simd 且关闭守护进程路由。工作线程扩展使用热客户端页缓存来隔离 CPU 工作。读取器、语料库大小、存储和分区行在平台支持的情况下使用 posix_fadvise 请求清理页驱逐；快照在每一行上记录该策略。每个工作负载都是字节确定性的且无发现。

主机：AMD Ryzen 9 9950X 16-Core Processor，32 个有效逻辑核心，94,140 MiB 内存，Linux 6.17.0-19-generic。证据：clean，二进制 274b045489c4。

扫描工作线程扩展

工作线程数	读取线程数	中位墙钟时间	p95 墙钟时间	吞吐量	加速比	效率	中位峰值 RSS
1	auto	8,134.4 ms	8,135.4 ms	7.9 MiB/s	1.00x	100.0%	47.0 MiB
2	auto	4,398.2 ms	6,906.7 ms	14.6 MiB/s	1.85x	92.5%	50.3 MiB
4	auto	2,392.6 ms	6,245.2 ms	26.7 MiB/s	3.40x	85.0%	57.2 MiB
8	auto	1,816.3 ms	6,117.6 ms	35.2 MiB/s	4.48x	56.0%	63.4 MiB
16	auto	1,428.5 ms	6,867.7 ms	44.8 MiB/s	5.69x	35.6%	78.4 MiB
32	auto	1,862.8 ms	5,939.1 ms	34.4 MiB/s	4.37x	13.6%	126.7 MiB

文件系统读取器扩展

扫描工作线程数	读取线程数	中位墙钟时间	p95 墙钟时间	吞吐量	相对 1 个读取器	中位峰值 RSS
32	1	1,898.7 ms	1,922.1 ms	33.7 MiB/s	1.00x	121.3 MiB
32	2	1,881.7 ms	1,887.5 ms	34.0 MiB/s	1.01x	122.8 MiB
32	4	1,874.2 ms	1,891.2 ms	34.1 MiB/s	1.01x	126.6 MiB
32	8	1,873.2 ms	1,885.7 ms	34.2 MiB/s	1.01x	133.4 MiB
32	16	1,856.8 ms	1,868.5 ms	34.5 MiB/s	1.02x	153.9 MiB
32	32	1,877.3 ms	1,880.4 ms	34.1 MiB/s	1.01x	179.5 MiB

语料库大小扩展

语料库	文件数	精确字节数	中位墙钟时间	p95 墙钟时间	吞吐量	中位峰值 RSS
small	256	8 MiB	869.9 ms	886.1 ms	9.2 MiB/s	111.1 MiB
medium	1,024	64 MiB	1,859.9 ms	1,874.8 ms	34.4 MiB/s	126.3 MiB
large	2,048	256 MiB	5,214.9 ms	5,321.7 ms	49.1 MiB/s	137.1 MiB

存储扩展

存储类别	文件系统	设备 ID	中位墙钟时间	p95 墙钟时间	吞吐量	相对首个存储	中位峰值 RSS
workspace	`ext4`	`66305`	1,847.4 ms	1,863.4 ms	34.6 MiB/s	1.00x	127.0 MiB
local-temp	`tmpfs`	`116`	1,870.8 ms	1,887.3 ms	34.2 MiB/s	0.99x	124.9 MiB

并发分区扩展

进程数	每进程工作线程数	合计工作线程数	文件总数	总字节数	中位墙钟时间	合计吞吐量	加速比	中位合计峰值 RSS
1	32	32	256	8 MiB	871.9 ms	9.2 MiB/s	1.00x	111.5 MiB
2	16	32	512	16 MiB	404.6 ms	39.5 MiB/s	4.31x	134.0 MiB
4	8	32	1,024	32 MiB	571.1 ms	56.0 MiB/s	6.11x	227.2 MiB

这些行是测量结果，而非通用调优常量。请在目标主机和存储上运行生成器。使用吞吐量停止提升的拐点，然后为 CI 运行器或编排层预留 CPU 和内存。

使用 make -C benchmarks readme-matrix 重现全部四组基准测试。该命令会测量所需矩阵，如果任何请求的 CPU、Hyperscan、CUDA、Metal、WGPU、预设、缓存、守护进程、线程、读取器、存储、语料库大小或分区行不可用，则会失败。使用 make -C benchmarks readme-matrix-check 验证两个快照、报告和 README 是否一致。

选择扫描配置

从默认策略和经过校准的自动路由开始。仅在工作流需要时更改单个维度：

工作流	检测策略	执行与复用	额外控制
首次仓库扫描	Default	已校准的 `auto`；`--daemon=auto`	在添加抑制规则之前审查所有发现。
重复的本地树或 CI 扫描	Default	已校准的 `auto`；`--incremental`	仅在相同可信树的扫描之间持久化增量缓存。
短反馈循环	`--fast`	已校准的 `auto`；可选 `--incremental`	接受降低的解码、熵和 ML 覆盖率。合并前请运行默认策略。
最高召回率恢复	`--deep`	进程内	Deep 与 fast 和 precision 互斥，且不符合守护进程条件。
低噪声大型资产清单	`--precision`	仓库集合、历史和云源在进程内	该预设提高置信度下限并禁用熵发现。它可能会漏掉置信度较低的凭据。
Unix 上的 TB 级目录、历史、归档、远程或云资产清单	Default	`keyhog daemon start --mass`，然后 `--daemon=mass`	批次保持限制在 8 MiB 和 1,024 个块。保留终端覆盖报告和 GPU 执行凭证。
实时凭据验证	Default	进程内	显式添加 `--verify`。验证会向提供商发送基于凭据的请求。
Linux 无交换扫描	默认加上 `--lockdown`	进程内；禁用增量缓存	Lockdown 拒绝验证、明文机密、快速模式以及降低完整性的开关。

--fast、--deep 和 --precision 是互斥的检测预设。--lockdown 是一种故障关闭执行模式，而非第四种预设。显式 --backend 值是诊断和基准测试覆盖项。它们不会取代自动路由使用的持久化最快正确证据。有关完整契约，请参阅配置、自动路由校准、守护进程与热扫描和加固。

KeyHog 的工作原理

KeyHog 将其 926 个检测器编译为共享的触发与提取计划，在匹配前解码嵌套编码，并应用每个检测器的置信度和抑制规则。纯 Rust CPU（cpu-fallback）始终可用。Hyperscan 路线（simd-regex）在启用该特性时使用 Hyperscan；便携式构建使用 CPU 路线。CUDA（gpu-cuda-region-presence）、Metal（gpu-metal-region-presence）和 WGPU（gpu-wgpu-region-presence）是基于证据的自动路由选择器中的对等项，而非回退链。校准会测量每个符合条件的对等项，并持久化最快且完整发现与参考路线匹配的路线，针对确切的二进制、检测器和配置状态、主机、加速器和工作负载类别。缺失、过期、无效或不完整的决策会在执行前停止自动扫描，并报告如何重新校准。它绝不会静默替换另一个后端。

请参阅架构了解仓库地图、依赖方向、从字节到发现的流水线以及性能分析入口点。请参阅后端与路由了解执行契约，以及自动路由校准了解一致性、工作负载标识、缓存生命周期和修复流程。

完整文档： santhreal.github.io/keyhog - 安装、首次扫描、输出格式、检测内部机制、抑制规则、验证、pre-commit + CI 集成、CLI 参考、自动路由、退出码、环境变量和贡献指南。源代码位于 docs/ 下。

安装 KeyHog

安装当前的 crates.io 版本：```sh cargo install keyhog --locked

当你需要未发布的更改时，请构建仓库检出：```sh
cargo install --path crates/cli --locked

确认已安装的构建版本：```sh keyhog --version --full keyhog doctor

关于 Rust 工具链要求、功能配置和平台特定的运行时依赖，请参阅[安装指南](https://santhreal.github.io/keyhog/install.html)。


## 它能检测到什么

926 个内置检测器，具备检测器自有的离线验证和伴生凭据：

- **云服务商：** AWS（access key + secret + STS 验证）、Azure（subscription key、storage account key、SAS）、GCP（service account、API key）、Cloudflare、Heroku、Vercel、Supabase。
- **支付处理器：** Stripe、Braintree、Razorpay、Paddle、Plaid、Square 和 PayPal，附带检测器自有的校验以及可选或必需的伴生凭据。Razorpay 的 key secret 需要其相邻的 key ID。
- **代码托管平台：** GitHub PAT（含 CRC32 校验和）、GitLab tokens、Bitbucket 应用密码、npm tokens（含校验和）、Gitea / Forgejo / Codeberg。
- **认证 / SSO：** Okta、Auth0、Clerk、JumpCloud、Kinde。
- **通信：** Slack、Discord、Twilio、SendGrid、Postmark、Mailgun、Resend、Loops。
- **AI / ML：** OpenAI（sk-/sk-proj-）、Anthropic、Google AI Studio、Cohere、Mistral、HuggingFace、Replicate。HuggingFace 组织凭据同时包含当前的 `hf_` 形式和旧版 `api_org_` tokens。
- **密码管理器：** 1Password 账户 secret key（`A3-` 后跟五或六段分段的大写字母数字组件）。
- **数据库：** Postgres 连接字符串、MongoDB Atlas、Supabase service-role、PlanetScale、Neon、Turso、MySQL、Redis URLs。
- **通用 + 熵发现：** `API_KEY=<high-entropy-blob>` 可捕获没有命名检测器的凭据，并通过按上下文区分的熵阈值 + ML 评分进行门控。
- **加密材料：** RSA / EC / SSH 私钥、PGP 私钥块、JWT 签名密钥。

每个检测器都以 [TOML 文件](https://github.com/santhreal/keyhog/blob/HEAD/detectors/)（数据，而非代码）的形式发布：服务元数据、正则模式、关键词、离线验证器、熵与 ML 策略、伴生字段以及验证处理器。添加新检测器只需一次可审查的 TOML 变更；[贡献者指南](https://github.com/santhreal/keyhog/blob/HEAD/CONTRIBUTING.md) 会逐步介绍该过程。

`keyhog explain <id>` 可导出任意检测器的完整规格：模式、关键词、验证端点，以及按服务区分的轮换指南和逐步修复指南，因此任何发现都不会是黑盒：

<p align="center">
  <img src="https://assets.kitploit.com/production/public/readmes/7654/0fc64959950abfa39c0ba81a1f5fbde3fe17a57169d2edca38cb0f248c834470.gif" alt="keyhog explain github-classic-pat: detector spec dump (pattern ghp_[A-Za-z0-9]{36}, keyword, verification URL) followed by the github rotation guide and step-by-step remediation" width="860" />
</p>

可在[检测器参考文档](https://github.com/santhreal/keyhog/blob/HEAD/docs/src/detectors.md)中浏览检测器的编写与检查，或使用 `keyhog detectors --search <term> --verbose` 查询已安装的检测器语料库。

## 为什么召回率更高、误报更少

- **解码穿透扫描。** 覆盖 Kubernetes `Secret` 清单、Jupyter notebooks、JWT payloads、base64 包装的环境变量、Helm values 以及 docker-config 的 `auth:` blobs。结构化预处理器将平衡的 Helm 动作视为惰性的渲染期值，并在文件末尾闭合缺失的 Jupyter 分隔符，从而保证字面字节和完整代码单元始终被覆盖。它会就地解码结构化值，并将明文馈送给每个下游检测器，各检测器无需自行重新实现解码。启用解码的扫描还能在恢复材料全部内嵌的情况下，恢复无副作用的 JavaScript 字节数组 XOR 和 AES-256-CBC 表达式，包括严格的 CryptoJS/OpenSSL 加盐口令包装。KeyHog 从不执行源代码。
- **多行重组。** JavaScript 中的 `"sk-proj-" + \` 续行、YAML 多行字符串、Makefile 反斜杠续行、Helm / Jinja 模板化输出，都会在正则匹配前重新组装。
- **伴生验证。** 必需的伴生凭据会对高噪声检测器进行门控。没有对应 API secret 的 Twilio API key 会被跳过。可选的伴生凭据可增强置信度或验证。AWS access-key 检测不要求其 secret，但实时验证需要该 secret。
- **跨检测器解析。** 检测器 TOML 可以要求、拒绝或吸收来自另一检测器的有界发现。解析结果在输入顺序变化时保持确定性；无效目标、矛盾或依赖循环都会导致语料库编译失败。
- **置信度评分。** 每个发现都带有 `[0.0, 1.0]` 的分数，其来源包括 Shannon 熵、周围上下文、伴生匹配、检测器自有的离线证明（GitHub/npm CRC32 和 PyPI payload 解码）、结构证据以及一个小型 ML 分类器（约 30k 参数）。默认阈值 `0.40`（即标准 `ScanConfig::default()` 下限；与 `--min-confidence` 默认值及下方 `[scan].min_confidence` 示例相同）可过滤低质量匹配，同时不会掩盖真实密钥。
- **贝叶斯逐检测器校准。** `keyhog calibrate --fp generic-api-key` 会写入 Beta(α,β) 后验分布。仅当 `--calibration-cache` 或 `[system].calibration_cache` 指向该文件时，扫描才会使用它，因此置信度调优是显式且可复现的，而非依赖主机上零散的缓存状态。

## 性能

使用 [`benchmarks/`](https://github.com/santhreal/keyhog/blob/HEAD/benchmarks/) 中的可复现基准框架，在统一的评分契约下比较 KeyHog、Betterleaks、Kingfisher、Nosey Parker、TruffleHog 和 Titus。该框架会将真值清单从每个扫描树中排除。在存在当前 schema 的运行结果前，生成的表格保持为空。测量后运行 `make -C benchmarks report`。请勿手动编辑生成的表格。

### 检测排行榜

<!-- BENCH:leaderboard:start -->
语料库：**mirror** - 15000 个测试样本，3000 个带标签的正样本。每个扫描器都采用相同评分（SecretBench 重叠规则）；答案清单被排除在扫描树之外。

| 排名 | 扫描器 | F1 | 精确率 | 召回率 | 发现数 | 耗时 | 峰值 RSS |
|---|---|---|---|---|---|---|---|
| 1 | **KeyHog** | **0.9328** | 0.9651 | 0.9027 | 2816 | 1.05s | 416 MB |
| 2 | TruffleHog | 0.5294 | 1.0000 | 0.3600 | 1080 | 1.59s | 300 MB |
| 3 | Kingfisher | 0.4683 | 0.3877 | 0.5913 | 5255 | 4.81s | 402 MB |
| 4 | Titus | 0.4207 | 0.3381 | 0.5567 | 5151 | 2.86s | 115 MB |
| 5 | Nosey Parker | 0.4186 | 0.3511 | 0.5183 | 4529 | 0.82s | 285 MB |
| 6 | Betterleaks | 0.3498 | 0.2241 | 0.7970 | 11113 | 0.74s | 198 MB |

### 结果溯源

| 扫描器 | 扫描器版本 / 可执行文件摘要 | 语料库标识 | 主机标识 | 运行日期 |
|---|---|---|---|---|
| KeyHog | version: KeyHog v0.5.70<br>Commit: d1eb2e09eb2c289181d93d719ce3f62411aeaf2c<br>Detector Set: 926 (926-4168e2c6c93a16ca)<br>Build Target: x86_64-linux<br>ML Model Version: moe-v1-246a05b92bec9aa3<br>ML Model Card: recorded 2026-07-15; features 55; synthetic F1 0.971 / P 0.945 / R 0.999; real F1 0.832 / P 0.753 / R 0.931 / [email protected] 0.938; zero-recall detectors 2/32; six-scanner differential unavailable<br>executable SHA-256: `2899ee53789bff9c531f72645f6c8380a7c873230dfb2b6857079467bc8d2dcd` | mirror; 15,000 fixtures; 3,000 labeled positives; 2,431,242 bytes | hostname SHA-256/12: `82fcd9288623`<br>Linux 6.17.0-19-generic<br>AMD Ryzen 9 9950X 16-Core Processor | 2026-08-11T01:29:39Z |
| TruffleHog | version: trufflehog 3.96.0<br>executable SHA-256: `6eb1f98fb890bf9361d8833c061e122dcb4f14fb7b71c65e603b7c096153c724` | mirror; 15,000 fixtures; 3,000 labeled positives; 2,431,242 bytes | hostname SHA-256/12: `82fcd9288623`<br>Linux 6.17.0-19-generic<br>AMD Ryzen 9 9950X 16-Core Processor | 2026-08-11T01:29:58Z |
| Kingfisher | version: kingfisher 1.94.0<br>executable SHA-256: `a49f8e9838d7f1da1e9f328a4dbc45a16996bce5078cde3ff1b8ad422d8ab07a` | mirror; 15,000 fixtures; 3,000 labeled positives; 2,431,242 bytes | hostname SHA-256/12: `82fcd9288623`<br>Linux 6.17.0-19-generic<br>AMD Ryzen 9 9950X 16-Core Processor | 2026-08-11T01:29:50Z |
| Titus | version: Titus v1.1.20 (Go port of NoseyParker)<br>executable SHA-256: `0b9c126a6c280ba28c6ed8795f88bf9bd793164c15959a34921f47a7ed276bcf` | mirror; 15,000 fixtures; 3,000 labeled positives; 2,431,242 bytes | hostname SHA-256/12: `82fcd9288623`<br>Linux 6.17.0-19-generic<br>AMD Ryzen 9 9950X 16-Core Processor | 2026-08-11T01:30:03Z |
| Nosey Parker | version: noseyparker 0.24.0 Build Configuration: Build Timestamp:    2025-05-08T21:11:15.600909923Z Commit Timestamp:   2025-05-08T17:04:47.000000000-04:00 Commit Branch:      HEAD Commit SHA:         61fa4ca67e4ded1b47b3b9ecce618ae91f1ff2fe Cargo Features:     color_backtrace,default,disable_trace,github,log,mimalloc,parquet,release Debug:              true Optimization:       3 Target Triple:      x86_64-unknown-linux-gnu Build System: OS:                 Ubuntu OS Version:         Linux (Ubuntu 22.04) CPU Vendor:         AuthenticAMD CPU Brand:          AMD EPYC 7763 64-Core Processor CPU Cores:          2 rustc Version:      1.86.0 rustc Channel:      stable rustc Host Triple:  x86_64-unknown-linux-gnu rustc Commit Date:  2025-03-31 rustc Commit SHA:   05f9846f893b09a1be1fc8560e33fc3c815cfecb rustc LLVM Version: 19.1<br>executable SHA-256: `42d6e88bf77904866a9dda49d7cf333501e76b62e9054b112e67f81dc88e2b71` | mirror; 15,000 fixtures; 3,000 labeled positives; 2,431,242 bytes | hostname SHA-256/12: `82fcd9288623`<br>Linux 6.17.0-19-generic<br>AMD Ryzen 9 9950X 16-Core Processor | 2026-08-11T01:29:53Z |
| Betterleaks | version: betterleaks version dev<br>executable SHA-256: `466f7d34e1ebcf12ecd5939494f509c17125e54416226976fced2f046da56ba4` | mirror; 15,000 fixtures; 3,000 labeled positives; 2,431,242 bytes | hostname SHA-256/12: `82fcd9288623`<br>Linux 6.17.0-19-generic<br>AMD Ryzen 9 9950X 16-Core Processor | 2026-08-11T01:29:43Z |
<!-- BENCH:leaderboard:end -->

### 速度与内存

<!-- BENCH:perf:start -->
| 扫描器 | 配置 | 语料库 | 耗时 | 吞吐量 | 峰值 RSS |
|---|---|---|---|---|---|
| Betterleaks | `default-nocache-nodaemon-no-validate` | mirror | 0.74s | 3.1 MB/s | 198 MB |
| Nosey Parker | `default-nocache-nodaemon-no-git-history` | mirror | 0.82s | 2.8 MB/s | 285 MB |
| KeyHog | `simd-nocache-nodaemon-full` | mirror | 1.05s | 2.2 MB/s | 416 MB |
| TruffleHog | `default-nocache-nodaemon-no-verify` | mirror | 1.59s | 1.5 MB/s | 300 MB |
| Titus | `default-nocache-nodaemon-no-validate` | mirror | 2.86s | 0.8 MB/s | 115 MB |
| Kingfisher | `default-nocache-nodaemon-low-no-validate` | mirror | 4.81s | 0.5 MB/s | 402 MB |
<!-- BENCH:perf:end -->

### 各类别召回率对比

<!-- BENCH:gaps:start -->
_仅为诊断性召回率切片。总体精确率与 F1 仍是对比契约；误报计入其所属的评分类别。_

| 类别 | KeyHog P/R/F1 | KeyHog TP/FN | 最佳竞品 P/R/F1 | 召回率差距 |
|---|---|---|---|---|
| `generic-high-entropy-string` | 1.000 / 0.434 / 0.606 | 73/95 | Betterleaks 1.000 / 0.798 / 0.887 | +0.363 |
<!-- BENCH:gaps:end -->

### 有界静态恢复遥测

<!-- BENCH:recovery:start -->
所选运行：扫描器 **KeyHog** `KeyHog v0.5.70<br>Commit: d1eb2e09eb2c289181d93d719ce3f62411aeaf2c<br>Detector Set: 926 (926-4168e2c6c93a16ca)<br>Build Target: x86_64-linux<br>ML Model Version: moe-v1-246a05b92bec9aa3<br>ML Model Card: recorded 2026-07-15; features 55; synthetic F1 0.971 / P 0.945 / R 0.999; real F1 0.832 / P 0.753 / R 0.931 / [email protected] 0.938; zero-recall detectors 2/32; six-scanner differential unavailable`；语料库 **mirror**（15,000 个测试样本，2,431,242 字节）；生成于 `2026-08-11T01:29:39Z`；产物 `mirror-keyhog-simd-nocache-nodaemon-full.json`。

遥测 schema：`static-recovery-v1`。

| 处置 | 精确数量 |
|---|---:|
| 支持 | 0 |
| 不支持 | 0 |
| 错误 | 0 |

| 拒绝原因 | 精确数量 |
|---|---:|
| _无_ | 0 |
<!-- BENCH:recovery:end -->

### Bigram Bloom 证据

<!-- BENCH:bloom:start -->
证据 schema：`bloom-evidence-v1`。

| 字段 | 精确结果 |
|---|---|
| 语料库 | `samsung-creddata-fx-record-spans-v1` |
| 语料库修订版本 | `f1de3f85dbdf42bf7b3467c0d273a4dfe44d56ee` |
| 语料库 SHA-256 | `4f2de506f334521121bb5b4aef8a37bf0b8153a4f9115e7ba9392d0eed1757b9` |
| 测试样本 SHA-256 | `a0ff018dc0a64b2cc78b25999043d1a441afa0087070f4cd8d73ae82408a59b4` |
| 可执行文件 SHA-256 | `2899ee53789bff9c531f72645f6c8380a7c873230dfb2b6857079467bc8d2dcd` |
| 工作区检测器语料库 SHA-256 | `d87e8b3d086e9ffa4c8a94f35a717ec710d5224e52e5b4fc7e71db30677609c9` |
| 扫描器检测器摘要 | `8d789251e092959f` |
| 检测器语料库 SHA-256 | `3729bd72df768187420f37e08ab64cd2b5a8bac558002d8b0844f465e9a75711` |
| Bloom 拒绝 | **110/51794 (0.21%)**；51684 个被接受 |
| 外部可用性 | 51794 个已测量；51794 个声明中有 0 个明确不可用；原因：  |
| 启用与绕过的发现 | **完全一致**；977/977 个发现 |
| 发现身份 SHA-256 | `1517bad01ab5228e85b7f4fd44e72226aa3f195bc18a67d58b7a6364b6bf6e0e` / `1517bad01ab5228e85b7f4fd44e72226aa3f195bc18a67d58b7a6364b6bf6e0e` |
| Bloom 密度/状态 | 1793/65536 个槽位；`healthy`；饱和点 39322 |

发现身份会绑定检测器、文件、行、字节跨度以及凭据的 SHA-256；明文凭据永远不会被记录。
<!-- BENCH:bloom:end -->

复现：`make -C benchmarks canonical KEYHOG_BIN=/absolute/path/to/keyhog` 会重新运行完整的 KeyHog、Betterleaks、Kingfisher、Nosey Parker、TruffleHog 和 Titus mirror 运行集，包括与可执行文件绑定的 CredData Bloom 差分；`make -C benchmarks report` 会重新生成上述表格及 `benchmarks/reports/`。语料库（mirror、竞品主场、Samsung/CredData）以及后端/缓存/守护进程/OS/GPU 矩阵，请参阅 [`benchmarks/README.md`](https://github.com/santhreal/keyhog/blob/HEAD/benchmarks/README.md)。

## GPU 支撑的大规模守护进程工作器

可选的 Unix 大规模守护进程会让一个已编译的扫描器及其校准后的后端状态保持热状态。本地文件系统扫描仅发送规范根路径与来源策略元数据；守护进程会在自身进程中读取并批量处理这些文件。需要客户端凭据的 Git、二进制、远程和云来源，则使用受保护的有界分块帧。```sh
# Terminal 1
keyhog calibrate-autoroute --policy default
keyhog daemon start --mass

# Terminal 2, after the daemon prints its ready line
keyhog scan --daemon=mass /srv/inventory/team-a \
  --format json-envelope --output team-a.json
keyhog daemon stop

--daemon=mass 是必需的路由。它永远不会在进程内重试。每个批次限制为 8 MiB 和 1,024 个块，与总输入大小无关。为每个清单分区保留覆盖范围、退出状态和终端执行回执。

参见守护进程生命周期、路由和回执和清单分区。

全系统凭证分类```sh

sudo keyhog scan-system --space 50G sudo keyhog scan-system --include-network --output system-findings.json

`scan-system` 是一种有界本地主机审计，不能替代仓库或云清单分区。它通过扫描的总字节数而非路径来约束自身：`--space` 是上限，除非传入 `--include-network`，否则会跳过网络挂载的文件系统。运行前请审视挂载、网络文件系统、空间上限和权限行为。参见
[system-wide triage](https://santhreal.github.io/keyhog/guides/system-wide-triage.html)。

## 锁定敏感本地扫描

Linux `--lockdown` 是一种默认拒绝（fail-closed）的进程保护模式：```sh
keyhog scan . --daemon=off --lockdown

它锁定当前和未来的内存，禁用核心转储和增量缓存，保持在进程中，并拒绝验证、明文输出、快速模式以及会降低完整性的开关。它在不支持的平台或锁定内存容量不足时会失败。参见加固与数据处理。

将 KeyHog 用作 Rust 库```rust

use keyhog_core::{Chunk, ChunkMetadata, RawMatch}; use keyhog_scanner::CompiledScanner;

let detectors = keyhog_core::load_embedded_detectors_or_fail()?; let scanner = CompiledScanner::compile(detectors)?; let findings = scanner.scan(&Chunk { data: "TOKEN=sk_live_EXAMPLE…".into(), metadata: ChunkMetadata::default(), })?; let report_safe: Vec<_> = findings.iter().map(RawMatch::to_redacted).collect();

默认的库方法是确定性的可移植 CPU 参考实现。显式的
后端方法会返回类型化错误，而不是终止进程或
静默替换另一个引擎。原始块和匹配项可能包含
明文。请通过 `RawMatch::to_redacted` 转换它们，或在跨越
JSON、日志、磁盘或网络边界之前使用最终的
`VerifiedFinding` 值。

[架构指南](https://github.com/santhreal/keyhog/blob/HEAD/docs/src/architecture.md) 定义了 crate 所有权、
后端契约、恢复收据、源辅助工具以及安全的报告
边界。完整的 API 由 crate 级别的 Rust 文档负责。

## 使用显式优先级配置策略

仓库策略位于 `.keyhog.toml` 中：```toml
verify = false

[scan]
severity = "high"
incremental = true

[system]
gpu = "auto"

解析顺序为内置默认值、用户配置、仓库配置、文档中记载的环境变量，最后是显式 CLI 覆盖。未知键和无效组合会在扫描前失败。运行 keyhog config --effective 可检查解析后的策略，而不会暴露代理凭据。超过 expires 的条目会在扫描前导致允许列表加载失败。

有关每个键的说明，请参阅配置与优先级；有关凭据和运行时输入，请参阅环境变量。

架构

KeyHog 将编排逻辑置于边缘层，而将领域行为放在库中：```text sources -> scanner -> suppression/confidence -> reporting -> optional verifier CLI and Action own process, transport, and exit semantics.

检测器定义仍然是 `detectors/` 下的数据。`keyhog-core` 拥有检测器和发现项类型，`keyhog-scanner` 拥有匹配与执行后端，`keyhog-sources` 拥有输入采集，`keyhog-verifier` 拥有实时检查，`keyhog-cli` 拥有操作员工作流。

从[架构指南](https://github.com/santhreal/keyhog/blob/HEAD/docs/src/architecture.md)开始，了解仓库地图、依赖方向、从字节到发现项的流水线、路由归属以及性能分析入口点。

## 检查并扩展安装```sh
keyhog detectors --search aws --verbose
keyhog explain aws-access-key
keyhog backend --autoroute --json
keyhog completion zsh

CLI 参考文档列出了每个命令、标志、生成的默认值和退出状态。使用 keyhog --help 和 keyhog <command> --help 可查看已安装版本的确切信息。

贡献

新的检测器？ 在 detectors/ 中放置一个 TOML 文件，然后打开 PR。贡献者指南（CONTRIBUTING.md）包含模式和一个完整的示例。
Bug / 漏报的密钥 / 误报？ 请提交 issue，附上脱敏后的凭据形态和检测器 ID；每份报告都会成为 crates/scanner/tests/contracts/ 下的永久测试夹具。
发布行为？ 每次成功的 main CI 运行都会递增补丁版本号、生成变更日志，并将全部六个 crate 发布到 crates.io。如需精确的说明，可在 changes/ 下添加可选的 fragment。发布指南涵盖了自动事务和上传失败恢复。
KeyHog 本身存在安全问题？ 请不要提交公开 issue；请使用 GitHub 私有漏洞报告。如果该表单不可用，请发送邮件至 [email protected]；无需 PGP。

变更日志。开放问题。

致谢

KeyHog 建立在先前密钥扫描工作的基础之上。借鉴了以下项目的思路：

TruffleHog：检测器的广度和验证语义
Betterleaks：token 效率和误报抑制
Titus： 扫描易用性和严重性校准

感谢这些项目及其贡献者。

许可证

许可证：MIT OR Apache-2.0。

条款：MIT 和 Apache-2.0。此双重许可证涵盖代码和检测器 TOML。商业使用、嵌入、分叉和托管服务在任一许可证下均被允许。

Star 历史

_{由 GitHub 公开 Star 计数的 UTC 观测数据生成。仓库存储第一个数据点以及之后的每次计数变化。当日重新运行会替换当天的数据点，计数未变化时不会产生提交。}