GuthL/KeyClaw
GitHub: GuthL/KeyClaw
本地 MITM 代理，在机密信息发送到 LLM API 之前实时检测并替换，防止凭证泄露。
Stars: 3 | Forks: 0
一个本地 MITM 代理，可在机密信息离开你的设备之前将其从 LLM 流量中剥离。
在设备本地保留 API keys、云凭证和私有 token，同时让 Claude Code、Codex 以及兼容代理感知的 API 客户端继续正常工作。
快速入门
·
工作原理
·
为什么选择 KeyClaw？
·
文档
·
贡献指南
KeyClaw 位于你的 AI 工具和上游 API 之间，检测出站 payload 中的机密信息，将其替换为确定性占位符，将映射关系存储在加密的本地 vault 中，并在响应返回时重新注入真实值。模型永远不会看到原始机密，但你的工作流表现依然如常。
## 为什么它很重要
- AI 编码工具非常擅长读取那些你希望它们忽略的文件。
- 机密扫描器只能在事后捕获泄露；KeyClaw 则在实时请求穿越网络之前对其进行保护。
- 你不需要封装 SDK、提示词纪律或单独的托管服务即可将凭证排除在模型提示之外。
## 架构
```
+-----------------------------------+
| Claude Code / Codex / Client |
+-----------------+-----------------+
| outbound request
v
+-----------------------------------+
| KeyClaw local proxy |
| |
| 1. Detect secrets in body |
| 2. Replace with placeholders |
| 3. Store mapping in vault --+ |
| | |
+-----------------+------------+----+
| sanitized |
v request |
+-----------------------------------+
| OpenAI / Anthropic / API |
+-----------------+-----------------+
| response |
v |
+-----------------------------------+
| Resolve placeholders back <----+
| (HTTP, SSE, WebSocket) |
+-----------------+-----------------+
|
v
+-----------------------------------+
| Claude Code / Codex / Client |
+-----------------------------------+
```
## 适用工具
KeyClaw 首要构建用于与 OpenAI 或 Anthropic 风格的 HTTPS API 通信的本地开发者工具。目前验证通过的路径包括：
| 工具 | 路径 | 备注 |
|------|------|-------|
| Claude Code | `keyclaw claude ...` 封装器或 `source ~/.keyclaw/env.sh` | 一流 CLI 路径 |
| Codex | `keyclaw codex ...` 封装器或 `source ~/.keyclaw/env.sh` | 一流 CLI 路径 |
| ChatGPT / OpenAI web 流量 | 本地代理 + 受信任 CA | 在主机层面对 `chatgpt.com` / `chat.openai.com` 在流量真正经过代理时纳入范围 |
| 直接 API 客户端 | `HTTP_PROXY` / `HTTPS_PROXY` + KeyClaw CA | 已针对实际经过代理的支持主机进行验证 |
其他工具（如 Cursor、aider 和 Continue）如果通过 `HTTP_PROXY` / `HTTPS_PROXY` 路由流量并信任 KeyClaw CA，可能在通用代理模式下工作，但它们不是一流集成，目前不在测试套件覆盖范围内。
## 60 秒快速入门
KeyClaw 尚未发布到 crates.io，因此目前最快的 `cargo install` 路径是通过 Git：
```
cargo install --git https://github.com/GuthL/KeyClaw keyclaw
keyclaw init
keyclaw proxy
source ~/.keyclaw/env.sh
```
这将安装 CLI，生成本地 CA 和 vault 密钥，启动分离代理，并配置当前 shell 信任并使用它。
### Claude Code
```
keyclaw claude --resume latest
```
或全局使用代理：
```
claude
```
### 通用代理感知客户端
```
source ~/.keyclaw/env.sh
your-client-here
```
对于内置 `claude` / `codex` 封装器之外的工具：
1. 运行一次 `keyclaw init` 以确保 `~/.keyclaw/ca.crt` 存在。
2. 在你的 OS 钥匙串或证书存储中信任 `~/.keyclaw/ca.crt`。
3. 通过 shell 环境变量或应用/OS 代理设置，将客户端路由至 `http://127.0.0.1:8877`。
4. 使用 `keyclaw doctor` 和真实请求验证流量确实被拦截。
### 单终端：
```
keyclaw proxy
source ~/.keyclaw/env.sh
claude "scan this repo for AWS credentials"
```
### 双终端：
```
# 终端 1
keyclaw proxy
# 终端 2
source ~/.keyclaw/env.sh
claude
```
`keyclaw proxy` 分离并在后台持续运行。它在 stdout 打印 `source ~/.keyclaw/env.sh`，该脚本导出 `HTTP_PROXY`、`HTTPS_PROXY`、`SSL_CERT_FILE` 及相关变量，使 CLI 工具通过 KeyClaw 路由并信任本地 CA。
启动 daemon 不会自动重新配置当前 shell。子进程无法改变其父 shell 环境，因此只有在 `source ~/.keyclaw/env.sh` 之后，当前 shell 才会通过 KeyClaw 路由。
使用以下命令管理代理生命周期：
```
keyclaw proxy status # check if the proxy is running
keyclaw proxy stop # graceful shutdown
```
在带有 `systemd --user` 的 Linux 上，你还可以让 daemon 在登录或重启后自动恢复：
```
keyclaw proxy autostart enable
keyclaw proxy autostart status
keyclaw proxy autostart disable
```
自动启动仅保持 daemon 存活。Shell 仍需 `source ~/.keyclaw/env.sh` 才能将 CLI 流量路由通过它。
如果你希望代理附加到当前终端，请使用 `keyclaw proxy start --foreground`。
## 工作原理
### 之前：包含泄露 AWS key 的真实请求
```
{
"model": "claude-sonnet-4",
"messages": [
{
"role": "user",
"content": "Deploy the staging stack with AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE and AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
}
]
}
```
### 之后：经 KeyClaw 处理后的同一请求
```
{
"model": "claude-sonnet-4",
"messages": [
{
"role": "developer",
"content": "KeyClaw notice: 2 secrets were redacted before this request left the machine."
},
{
"role": "user",
"content": "Deploy the staging stack with AWS_ACCESS_KEY_ID={{KEYCLAW_SECRET_AKIAI_77dc0005c514277d}} and AWS_SECRET_ACCESS_KEY={{KEYCLAW_SECRET_wJalr_8b4f0f2d14a8b2c1}}"
}
],
"x-keyclaw-contract": "placeholder:v1"
}
```
当模型在响应中回显或操作这些占位符时，KeyClaw 会在本地客户端看到最终 payload 之前将其解析回真实值。
## 为什么选择 KeyClaw？
| 方法 | 擅长 | KeyClaw 的不同之处 |
|----------|----------|----------------------------|
| `llm-interceptor` | 检查、分析和记录 AI 流量 | KeyClaw 旨在主动重写实时请求，通过占位符重新注入保持工作流，并在保护失效时“失败关闭” |
| `gitleaks` / `trufflehog` | 扫描仓库、历史、镜像或已泄露材料以查找机密 | KeyClaw 在实时流量上内联操作，而不仅是审计文件或先前泄露的数据 |
| 手动提示词卫生 | 减少明显的复制/粘贴错误 | KeyClaw 是自动化的，仍能捕获隐藏在 payload、配置或生成的请求体中的机密 |
如果你想检查 LLM 流量，`llm-interceptor` 是一个有用的邻居。如果你想从一开始就阻止原始凭证到达上游 API，KeyClaw 是更紧凑的方案。
## 内置检测规则
KeyClaw 附带 [`gitleaks.toml`](gitleaks.toml) 中的**内置检测规则**，在启动时原生编译为 Rust 正则表达式。无需子进程或外部 `gitleaks` 二进制文件。
内置规则覆盖：
- 提供商凭证，如 AWS、OpenAI、Anthropic、GitHub、GitLab、Slack、Stripe、GCP 等
- 通用赋值模式，如 `api_key=...`、`secret_key=...`、`access_token=...`
- 私钥材料，如 RSA、EC、OpenSSH、PGP 和 age
- 通过内置熵检测器的高熵 token
可以通过 `KEYCLAW_GITLEAKS_CONFIG` 从文件加载自定义规则。
KeyClaw 不使用或不需要 `KEYCLAW_GITLEAKS_BIN`。机密检测使用原生编译到二进制中的内置 gitleaks 规则；仅当想用你自己的 TOML 文件覆盖这些规则时才设置 `KEYCLAW_GITLEAKS_CONFIG`。
内置检测的事实来源是 `gitleaks.toml`；`src/gitleaks_rules.rs` 是这些规则的加载器/编译器。
## 验证是否工作
```
keyclaw doctor
```
`keyclaw doctor` 是在调试客户端本身之前，最快发现损坏的 CA 文件、代理绕过、无效的 `~/.keyclaw/config.toml`、损坏的允许列表条目、自定义规则集问题和缺失 vault 密钥材料的方法。
按以下方式解读输出：
- `PASS` 表示检查已准备好正常使用
- `WARN` 表示 KeyClaw 仍可运行，但配置有风险或非标准
- `FAIL` 表示在依赖代理之前修复此项；`doctor` 以非零状态退出
- `hint:` 指向该特定检查的下一步操作者行动
## 配置
KeyClaw 读取 `~/.keyclaw/config.toml`（如果存在），然后在其之上应用环境变量覆盖。优先级为：
```
env vars > ~/.keyclaw/config.toml > built-in defaults
```
缺少 `~/.keyclaw/config.toml` 没问题；KeyClaw 会静默回退到环境变量和默认值。无效 TOML 被视为阻塞配置错误，`keyclaw doctor` 会明确报告。
完整配置参考请参阅 [docs/configuration.md](docs/configuration.md)。
### 配置文件
示例 `~/.keyclaw/config.toml`：
```
[proxy]
addr = "127.0.0.1:8877"
[logging]
level = "info"
[notice]
mode = "minimal"
[detection]
dry_run = false
entropy_enabled = true
entropy_threshold = 3.5
[audit]
path = "~/.keyclaw/audit.log"
[hosts]
codex = ["api.openai.com", "chat.openai.com", "chatgpt.com"]
claude = ["api.anthropic.com", "claude.ai"]
[allowlist]
rule_ids = ["generic-api-key"]
patterns = ["^sk-test-"]
secret_sha256 = ["0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"]
```
目前支持的文件节包括 `proxy`、`vault`、`logging`、`notice`、`detection`、`audit`、`hosts` 和 `allowlist`。将文件用于稳定的本地设置，然后在需要一次性覆盖时使用环境变量。
允许列表条目让你有意跳过对已知安全匹配的修订：
- `rule_ids`：跳过特定 gitleaks 规则 ID 产生的每个匹配
- `patterns`：跳过匹配值满足正则表达式的机密
- `secret_sha256`：通过 SHA-256 摘要跳过一个精确机密值，无需在配置中存储明文
在本地计算 `secret_sha256` 条目：
```
printf '%s' 'your-known-safe-secret' | sha256sum
```
禁用持久审计日志：
```
[audit]
path = "off"
```
### 环境变量
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `KEYCLAW_PROXY_ADDR` | `127.0.0.1:8877` | 代理监听地址 |
| `KEYCLAW_PROXY_URL` | `http://127.0.0.1:8877` | 导出给子进程的代理 URL |
| `KEYCLAW_CA_CERT` | `~/.keyclaw/ca.crt` | 传递给客户端的覆盖 CA 证书路径 |
| `KEYCLAW_VAULT_PATH` | `~/.keyclaw/vault.enc` | 加密 vault 位置 |
| `KEYCLAW_VAULT_PASSPHRASE` | 未设置 | 显式 vault 口令覆盖 |
| `KEYCLAW_CODEX_HOSTS` | `api.openai.com,chat.openai.com,chatgpt.com` | 要拦截的 Codex/OpenAI 主机 |
| `KEYCLAW_CLAUDE_HOSTS` | `api.anthropic.com,claude.ai` | 要拦截的 Claude/Anthropic 主机 |
| `KEYCLAW_MAX_BODY_BYTES` | `2097152` | 最大请求体大小 |
| `KEYCLAW_DETECTOR_TIMEOUT` | `4s` | 请求体检查和流式 body 读取的超时时间 |
| `KEYCLAW_GITLEAKS_CONFIG` | 内置规则 | 自定义 `gitleaks.toml` 路径 |
| `KEYCLAW_AUDIT_LOG` | `~/.keyclaw/audit.log` | 仅追加 JSONL 审计日志路径，或 `off` 禁用 |
| `KEYCLAW_LOG_LEVEL` | `info` | 运行时 stderr 详细程度：`error`、`warn`、`info`、`debug` |
| `KEYCLAW_NOTICE_MODE` | `verbose` | 修订通知模式：`verbose`、`minimal`、`off` |
| `KEYCLAW_DRY_RUN` | `false` | 扫描并记录将被修订的内容而不修改流量 |
| `KEYCLAW_UNSAFE_LOG` | `false` | 仅用于调试，禁用正常日志清理 |
| `KEYCLAW_FAIL_CLOSED` | `true` | 在重写或检测失败时阻止请求 |
| `KEYCLAW_REQUIRE_MITM_EFFECTIVE` | `true` | 如果检测到代理绕过则失败 |
| `KEYCLAW_ENTROPY_ENABLED` | `true` | 启用高熵机密检测 |
| `KEYCLAW_ENTROPY_THRESHOLD` | `3.5` | 基于熵的匹配的最小熵分数 |
| `KEYCLAW_ENTROPY_MIN_LEN` | `20` | 基于熵的匹配的最小 token 长度 |
### 设置变量
当配置文件和环境变量都设置时，环境变量优先。
单命令内联：
```
KEYCLAW_LOG_LEVEL=debug KEYCLAW_NOTICE_MODE=minimal keyclaw claude --resume latest
KEYCLAW_GITLEAKS_CONFIG="$PWD/gitleaks.toml" keyclaw doctor
```
当前 shell 会话持久：
```
export KEYCLAW_LOG_LEVEL=debug
export KEYCLAW_NOTICE_MODE=minimal
keyclaw codex exec --model gpt-5
```
跨新 shell 持久：
```
# ~/.bashrc 或 ~/.zshrc
export KEYCLAW_LOG_LEVEL=debug
export KEYCLAW_NOTICE_MODE=minimal
export KEYCLAW_GITLEAKS_CONFIG="$HOME/.config/keyclaw/gitleaks.toml"
```
如果你将 `keyclaw proxy` 用作分离 daemon，或启用 `keyclaw proxy autostart`，daemon 端设置在该代理进程启动时读取。在更改 `~/.keyclaw/config.toml` 或 `KEYCLAW_PROXY_ADDR`、`KEYCLAW_LOG_LEVEL`、`KEYCLAW_GITLEAKS_CONFIG`、`KEYCLAW_NOTICE_MODE`、`KEYCLAW_REQUIRE_MITM_EFFECTIVE` 等变量后，重启代理以便运行中的 daemon 采纳。
默认情况下，KeyClaw 在加密 vault 旁边创建一个机器本地 vault 密钥，并在后续运行中重用。仅在需要显式覆盖该密钥材料时设置 `KEYCLAW_VAULT_PASSPHRASE`。使用已移除内置默认值写入的现有 vault 将在下一次成功写入时迁移到生成的本地密钥。如果现有 vault 无法解密或其密钥材料缺失，KeyClaw 将失败关闭并告诉你如何恢复。
`KEYCLAW_NOTICE_MODE=verbose` 保持当前完整确认指引，`minimal` 注入较短通知，`off` 完全抑制通知注入，但仍正常修订和重新注入机密。
在不更改实时量的情况下调整检测时使用 dry-run：设置 `[detection] dry_run = true`，导出 `KEYCLAW_DRY_RUN=true`，或向 `keyclaw rewrite-json`、`keyclaw mitm ...`、`keyclaw codex ...`、`keyclaw claude ...` 或 `keyclaw proxy start` 传递 `--dry-run`。
唯一故意例外清理后运行时日志的是 `KEYCLAW_UNSAFE_LOG=true`。启用时，KeyClaw 可能将原始请求片段写入 stderr 或 `~/.keyclaw/mitm.log` 以帮助调试拦截问题。正常使用时请保持未设置。
## 审计日志
默认情况下，KeyClaw 将每个修订机密的一行 JSON 追加到 `~/.keyclaw/audit.log`。每个条目包括 UTC 时间戳、`rule_id`、占位符、请求主机和操作，但绝不包含原始机密值本身。
设置 `KEYCLAW_AUDIT_LOG=off` 或 `[audit] path = "off"` 以禁用持久审计日志。设置 `KEYCLAW_AUDIT_LOG=/path/to/audit.log` 或 `[audit] path = "/path/to/audit.log"` 将其移动到其他位置。
KeyClaw 本身不轮换审计日志；它总是追加。对于大小管理，将其指向由 `logrotate`、`newsyslog` 或你平台的等效轮换工具管理的路径。
## 日志
面向操作者的运行时消息使用分级 stderr 前缀：
- `keyclaw info:` 启动、关闭、CA/规则集初始化和生命周期摘要
- `keyclaw debug:` 每请求代理活动，如拦截、重写和占位符解析
- `keyclaw warn:` 有风险但非致命的条件，如不安全日志或绕过风险
- `keyclaw error:` 退出前的致命 CLI 错误
设置 `KEYCLAW_LOG_LEVEL=error`、`warn`、`info` 或 `debug` 以减少或扩展 stderr 详细程度。默认值为 `info`，保持关注生命周期并避免为每个代理请求发出一行。在排查实时流量时使用 `debug`。`doctor` 子命令故意独立：它将其 `doctor: PASS|WARN|FAIL ...` 报告写入 stdout，以便干净地管道传输或解析。
## 错误码
KeyClaw 使用确定性错误码进行程序化处理：
| 代码 | 含义 |
|------|---------|
| `mitm_not_effective` | 检测到代理绕过 |
| `body_too_large` | 请求体超过 `KEYCLAW_MAX_BODY_BYTES` |
| `invalid_json` | 解析或重写请求 JSON 失败 |
| `request_timeout` | 请求体读取在检查完成前超时 |
| `strict_resolve_failed` | 在严格模式下占位符解析失败 |
## 安全模型
完整威胁模型请参阅 [docs/threat-model.md](docs/threat-model.md)。
### KeyClaw 防范的内容
- 代码库中的机密被发送到 AI API
- API keys、token 和凭证通过 CLI 或 IDE 流量泄露
- `.env` 文件、配置文件和硬编码凭证的意外暴露
### 非目标与限制
- 被入侵的本地机器
- 从未使用 KeyClaw 代理或针对配置拦截列表之外主机的流量
- 跨每个提供商、凭证格式或提示措辞的完美机密检测
- 侧信道泄露，如精确机密长度保留
### 信任边界
信任边界是你的机器。KeyClaw 仅保护受支持客户端实际通过本地代理路由的流量。CA 证书在本地生成，绝不离开你的机器。加密 vault 及其机器本地密钥保留在本地磁盘，除非你通过 `KEYCLAW_VAULT_PASSPHRASE` 显式覆盖密钥。机密检测、占位符生成和重新注入都在进程内发生。
## 项目结构
```
src/
├── main.rs # Entry point
├── lib.rs # Module declarations
├── allowlist.rs # Operator-controlled allowlist logic
├── audit.rs # Persistent JSONL audit log writes
├── certgen.rs # Runtime CA certificate generation
├── config.rs # Env + TOML configuration
├── entropy.rs # High-entropy token detection
├── gitleaks_rules.rs # Bundled gitleaks rule loading + native regex compilation
├── pipeline.rs # Request rewrite pipeline
├── placeholder.rs # Placeholder parsing, generation, and resolution
├── redaction.rs # JSON walker + notice injection
├── vault.rs # AES-GCM encrypted secret storage
├── proxy.rs # Proxy server entrypoint + handler wiring
├── proxy/
│ ├── common.rs # Shared host checks, response helpers, and logging
│ ├── http.rs # HTTP request/response interception
│ ├── streaming.rs # SSE frame resolution and buffering
│ └── websocket.rs # WebSocket message redaction and resolution
├── launcher.rs # CLI surface and subcommand dispatch
├── launcher/
│ ├── bootstrap.rs # Processor/bootstrap setup and launched-tool wiring
│ └── doctor.rs # Operator health checks
├── logscrub.rs # Log sanitization
└── errors.rs # Error types and codes
gitleaks.toml # Bundled detection rules compiled by gitleaks_rules.rs
```
## 更多文档
| 文档 | 目的 |
|-----|---------|
| [docs/README.md](docs/README.md) | 深入文档的入口 |
| [docs/architecture.md](docs/architecture.md) | 请求/响应流、模块映射和设计决策 |
| [docs/configuration.md](docs/configuration.md) | 完整配置文件和环境变量参考 |
| [docs/secret-patterns.md](docs/secret-patterns.md) | 支持的机密类别和自定义规则指南 |
| [docs/threat-model.md](docs/threat-model.md) | 威胁模型、信任边界和非目标 |
| [CLAUDE.md](CLAUDE.md) | Claude Code 的 Agent 指南 |
| [AGENTS.md](AGENTS.md) | Codex 的 Agent 指南 |
## 贡献
本地开发、验证、发布和文档期望请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
## 许可证
[MIT](LICENSE)
标签：API密钥保护, API网关, Cloud Credentials, DLL 劫持, DLL注入, DLP, MITM, Rust, Zero Trust, 中间人代理, 代码分析, 凭证管理, 可视化界面, 大语言模型, 威胁情报, 开发者工具, 提示词注入防御, 敏感信息过滤, 本地代理, 流量审计, 私有化部署, 秘密扫描, 网络安全, 网络安全, 网络流量审计, 通知系统, 防御规避, 隐私保护, 隐私保护