Redact MCP

Redact MCP — Claude Code 的自动 PII 混淆

一个 MCP 服务（也是 Claude Code 插件），可在 Claude 看到敏感数据之前自动检测并混淆这些数据。使用 正则表达式模式匹配 和 AI 驱动的命名实体识别（NER），检测 IP、主机名、电子邮件、API 密钥、人名、组织名称、地点、私钥、连接字符串等。

专为需要借助 Claude 的分析能力、又不想向第三方暴露客户数据的渗透测试人员打造。

工作原理

Raw data with real PII ──► Regex + NER detection ──► Claude sees only fake values
                                                              │
Final report for client ◄── Real values restored ◄── /redact:export

服务会维护一个双向映射表。每个敏感值都会被替换为一致且确定性的虚假值，并在整个会话期间保持不变：

真实值	混淆为	检测方式
10.50.1.100	198.51.100.1	正则表达式
api.clientcorp.com	target-1.example.com	正则表达式
[email protected]	[email protected]	正则表达式
AKIA3EXAMPLE...	[REDACTED_AWS_KEY_1]	正则表达式
James Wilson	Person_A Person_B	NER
Microsoft	Org_A	NER
Seattle	City_A	NER
postgres://admin:pw@host/db	[REDACTED_CONN_STRING_1]	正则表达式
-----BEGIN RSA PRIVATE KEY...	[REDACTED_PRIVATE_KEY_1]	正则表达式

相同的真实值始终映射到相同的虚假值。保证 obfuscate(text) -> deobfuscate(result) === text 成立。

安装

通过 npx 快速安装（推荐）

claude mcp add @mattzam/redact-mcp -- npx @mattzam/redact-mcp

就这么简单。Claude Code 会在每个会话中通过 npx 启动服务。NER 模型（约 110MB）会在首次使用时自动下载，并缓存以供后续运行使用。

要启用审计日志：

claude mcp add @mattzam/redact-mcp -e REDACT_AUDIT_LOG=true -- npx @mattzam/redact-mcp

作为 Claude Code 插件安装（完整功能：钩子 + 技能）

git clone https://github.com/r3352/redact-mcp.git redact
cd redact/server
npm install
npm run build
cd ../..

# Load as a plugin (includes hooks for leak detection + slash commands)
claude --plugin-dir ./redact

插件模式在 MCP 服务的基础上增加了钩子（自动检测原始工具输出中的数据泄漏）和技能（/redact:status、/redact:add、/redact:export）。

手动配置 MCP

在 Claude Code MCP 配置文件（~/.claude/mcp.json 或项目的 .mcp.json）中添加：

{
  "mcpServers": {
    "redact-server": {
      "command": "npx",
      "args": ["redact-mcp"],
      "env": {
        "REDACT_DATA_DIR": "/path/to/data/directory",
        "REDACT_AUDIT_LOG": "true"
      }
    }
  }
}

环境变量

变量	默认值	说明
REDACT_DATA_DIR	./data	映射状态和审计日志的目录
REDACT_AUDIT_LOG	false	设置为 true 以启用 JSONL 审计日志

检测内容

正则表达式模式（19 种类型）

无需配置。自动检测：

类别	类型
网络	IPv4（私有 + 公共）、IPv6、带有效 TLD 的主机名、MAC 地址
身份信息	电子邮件、人员姓名（JSON 上下文）、电话号码（美国 + 国际）、SSN
机密信息	AWS 访问密钥、JWT、Bearer 令牌、API 密钥（结合上下文检测）、通用机密（password=、secret=）、私钥（PEM 格式）、连接字符串（postgres/mysql/redis/mongodb/amqp/mssql URI）
财务信息	信用卡号（经 Luhn 算法验证）
物理地址	街道地址（例如 123 Main Street、456 Oak Ave）

NER 检测（AI 驱动）

安装 @huggingface/transformers 后（默认已包含），服务会加载 Xenova/bert-base-NER（约 110MB 的 ONNX 模型，首次使用时下载），以检测：

实体类型	示例	混淆为
人名	James Wilson	Person_A Person_B
组织	Microsoft、Acme Corp	Org_A、Org_B
地点	Seattle、New York	City_A、City_B

NER 可以检测正则表达式遗漏的实体，例如 JSON 上下文之外的人名和组织名称、任意地点名称等。如果两种方式检测到相同文本片段，始终优先采用正则表达式的结果（正则表达式对结构化模式的检测更精确）。

平稳降级： 如果模型加载失败或缺少相应的软件包，服务会继续以仅使用正则表达式的模式运行，不会报错。

智能透传

以下值永远不会被混淆：

• 回环／保留地址： localhost、127.0.0.1、::1、0.0.0.0
• RFC 文档地址段： 192.0.2.x（TEST-NET-1）、198.51.100.x（TEST-NET-2）、203.0.113.x（TEST-NET-3）、2001:db8::（IPv6 文档地址）
• 示例域名： example.com、example.org、example.net
• 开发域名： github.com、npmjs.com、nodejs.org、googleapis.com 等
• 安全测试： burpcollaborator.net、oastify.com
• 代码模式： console.log、process.env、package.json、webpack.config、jest.config、tailwind.config 以及另外 30 多种常见误报
• 广播 MAC 地址： FF:FF:FF:FF:FF:FF、00:00:00:00:00:00

MCP 工具

此服务通过 MCP 注册了 8 个工具：

工具	描述
redact_obfuscate	自动检测并替换文本中的所有个人身份信息（PII）（正则表达式 + NER）
redact_deobfuscate	撤销所有替换，还原为真实值
redact_proxy_request	HTTP 代理 — 对请求反混淆、发起真实调用、对响应混淆
redact_read_file	读取文件并返回混淆后的内容
redact_add_mapping	手动添加真实值到虚假值的映射
redact_remove_mapping	移除映射（修正误报）
redact_show_mappings	按类型分组显示所有当前映射
redact_audit_log	查看最近的审计日志条目（需要 REDACT_AUDIT_LOG=true）

redact_proxy_request — 核心工具

对于渗透测试工作流，这是关键工具。Claude 会调用它，而不是 curl/fetch：

1. Claude 提供 URL／标头／请求体（可能包含已混淆的值）
2. 服务对请求进行反混淆（还原真实主机名／IP／令牌）
3. 向目标发起真实 HTTP 请求
4. 对整个响应（标头 + 请求体）进行混淆
5. 将经过清理的响应返回给 Claude

Claude 永远不会看到真实的响应数据。所有反混淆和混淆步骤都会记录到审计日志。

redact_audit_log — 合规审计跟踪

启用 REDACT_AUDIT_LOG=true 后，每次混淆和反混淆操作都会记录到 ${REDACT_DATA_DIR}/audit.jsonl。每条记录包含：

• 时间戳和操作类型（obfuscate、deobfuscate、proxy_request、file_read）
• 完整输入文本（转换前的原始数据）
• 所有检测结果，包括类型、真实值、虚假替换值和来源（regex 或 ner）
• 完整输出文本（转换后的结果）

这会提供完整的审计跟踪：输入了什么、修改了什么，以及输出了什么。

通过 redact_audit_log 工具查看条目，或直接读取 audit.jsonl：

# Last 5 entries, pretty-printed
tail -5 data/audit.jsonl | python3 -m json.tool

安全提示： 审计日志会按设计包含真实的敏感数据（这正是它的用途 — 证明哪些内容已被编辑）。请妥善保护日志。

技能（斜杠命令）

命令	描述
/redact:status	按类型分组显示当前的脱敏映射
/redact:add <real> <fake>	手动添加映射（例如，/redact:add clientcorp.com target.example.com）
/redact:export <file> [output]	为交付客户而对文件进行反混淆（默认为 ~/Desktop/）

钩子

此插件使用两个钩子（自动运行，无需用户交互）：

• SessionStart — 注入指令，告知 Claude 通过 redact 工具处理所有数据
• PostToolUse — 如果 Claude 使用原始 Bash／Read／Grep／WebFetch 且输出包含已知敏感值，则发出警告（泄漏检测）

管道的工作原理

检测

1. 正则表达式扫描 — 通过编译后的 RegExp 同步扫描 19 种模式
2. NER 扫描 — Xenova/bert-base-NER 并行运行（异步），识别人名／组织／地点实体
3. 合并 — 合并结果；对于重叠区域，优先采用正则表达式匹配（对结构化数据更精确）
4. 去重 — 如果重叠的 NER 结果与正则表达式匹配覆盖相同区域，则将其丢弃

映射

1. 每个唯一的真实值都会通过基于计数器的生成方式获得一个确定性的伪造值
2. 伪造值使用安全范围：IPv4 使用 TEST-NET-2，IPv6 使用 RFC 3849，域名使用 example.com，电话号码使用 555 前缀，MAC 地址使用本地管理范围
3. 映射会持久化到 ${REDACT_DATA_DIR}/mappings.json，并采用防抖写入（500ms）
4. 按长度从长到短替换可避免部分匹配导致的错误（例如，先替换 10.50.1.100，再替换 10.50.1.10）

往返保证

对于所有输入，deobfuscate(obfuscate(text)) === text。双向映射表可确保无损还原。

架构

redact/
├── .claude-plugin/plugin.json     # Plugin manifest
├── .mcp.json                      # MCP server config (stdio transport)
├── hooks/
│   ├── hooks.json                 # Hook definitions
│   └── scripts/
│       ├── session-start.sh       # Injects redaction context on session start
│       └── post-tool-scan.py      # Leak detection on raw tool output
├── skills/
│   ├── status/SKILL.md            # /redact:status
│   ├── add/SKILL.md               # /redact:add
│   └── export/SKILL.md            # /redact:export
└── server/
    ├── package.json               # v2.0.0, deps: @modelcontextprotocol/sdk, @huggingface/transformers
    ├── tsconfig.json              # ES2022, Node16 modules, strict
    └── src/
        ├── index.ts               # MCP server — 8 tools, server instructions
        ├── mapping-engine.ts      # Bidirectional mapping, async obfuscate/deobfuscate, audit integration
        ├── pattern-detector.ts    # 19 regex patterns + async NER merge
        ├── fake-generator.ts      # Deterministic counter-based fake value generation
        ├── ner-detector.ts        # Lazy-loaded HuggingFace NER with graceful fallback
        ├── audit-logger.ts        # JSONL append logger, serialized write queue
        └── persistence.ts         # JSON state file with debounced writes

运行时流程

Claude Code ──stdio──► MCP Server (index.ts)
                            │
                     CallToolRequest
                            │
                    ┌───────┴───────┐
                    │ MappingEngine │
                    └───────┬───────┘
                            │
              ┌─────────────┼─────────────┐
              │             │             │
        detectPatterns   NER detect   AuditLogger
        (regex, sync)   (async)      (JSONL, async)
              │             │             │
              └─────────────┼─────────────┘
                            │
                     merge + dedupe
                            │
                     apply mappings
                     (longest-first)
                            │
                     return to Claude

开发

cd server

# Install dependencies (~110MB for NER model on first run)
npm install

# Build TypeScript
npm run build

# Test MCP server starts and lists tools
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | node dist/index.js

# Quick obfuscation test
node -e '
const { MappingEngine } = await import("./dist/mapping-engine.js");
const engine = new MappingEngine("/tmp/redact-dev");
await engine.init();
console.log(await engine.obfuscate("Email [email protected] from 10.0.0.1"));
'

更新日志

v2.0.0

• NER 检测 — 通过 @huggingface/transformers + Xenova/bert-base-NER 实现 AI 驱动的实体识别。可在结构化 JSON 上下文之外识别人名、组织和地点。
• 审计日志 — 选择启用的 JSONL 审计记录（REDACT_AUDIT_LOG=true）会记录每次混淆和去混淆操作的完整输入/输出文本、所有检测结果及其来源，以及时间戳。
• 新增 7 种模式类型 — organization、location、private_key、connection_string、generic_secret、mac_address、street_address
• 第 8 个工具 — 用于查看审计条目的 redact_audit_log
• 改进电话号码检测 — 支持国际格式（+CC-XXXX-XXXX）
• 扩展误报列表 — 新增 webpack.config、jest.config、tailwind.config 及其他 9 种配置文件模式

v1.0.0

• 初始版本，采用仅基于正则表达式的检测（12 种模式类型），包含 7 个 MCP 工具、双向映射、持久化、钩子和技能。

许可证

MIT