Securedact MCP

SecuRedact MCP

SecuRedact 是面向 AI Agent 和 AI 工作流的本地优先隐私与安全层。在数据到达模型、工具、文件或外部目的地之前，它会检测并保护敏感数据——个人数据 / PII、GDPR 敏感信息、凭据、API 密钥、令牌、机密和敏感文件。

SecuRedact MCP 是采用 Apache-2.0 开源许可的 MCP 服务和可复用 Python 隐私引擎。它会检测敏感文本、应用带版本的策略、在本地进行脱敏，并在将清理后的内容标记为已批准之前验证残留输出。

MCP 模式不会自动拦截每条提示词。宿主必须调用工具，并且仅在 status == "ok" 时发送 sanitized_text；配置错误或恶意的 MCP 宿主可以绕过常规 MCP 工作流。提供商原生强制钩子是独立的集成资产：当受支持的提供商在提示词生命周期边界调用此类钩子时，它可以在正常模型处理之前应用相同的确定性判定。请参阅 SecuRedact Enforced。

为什么选择 SecuRedact

AI Agent 正在越来越多地读取文件、调用工具，并向外部模型发送提示词。如果没有事先检查数据，这些操作就会暴露 PII、凭据和敏感文档。SecuRedact 是用于 AI 工作流的隐私与安全控制：

• 本地优先 — 所有检测、脱敏和策略评估都在你的机器上运行。默认不启动网络监听器，不收集遥测数据，也不调用提供商。
• PII / GDPR 检测 — 检测姓名、电子邮件、IBAN、标识符和特殊类别数据，并对其进行假名化或脱敏。
• 机密与凭据保护 — 检测 API 密钥、令牌和密码，并阻止它们离开你的环境。
• 文件系统保护 — 防止读取操作通过路径遍历 / 符号链接逃逸，并阻止读取 .env 等受保护路径。
• AI Agent 隐私防火墙 — Claude Code 和 Gemini CLI 的强制钩子会在提示词、模型调用或工具操作继续之前，执行相同的本地判定。
• 网络 / 出站流量感知 — 对出站工具调用进行分类（内部 / 外部 / 未知），以便策略要求审批或阻止出站流量。

SecuRedact 有助于减少敏感数据暴露，但不保证合规，也不声称能防止所有泄漏。请参阅限制。

HIPAA Safe Harbor（0.5.0）

SecuRedact 0.5.0 为 45 CFR 164.514(b)(2) 文本处理新增了 HIPAA Safe Harbor 机械式去标识化辅助功能。它基于现有的确定性检测堆栈，新增了 18 类 Safe Harbor 映射、美国特定标识符（带区域 / 组 / 序列号校验的 SSN、美国 ZIP / ZIP+4、健康计划受益人、账号、89 岁以上年龄、VIN 格式的车辆标识符、传真），以及可选的、经过验证的 Flair PERSON 专用门控，用于 A 类（姓名）。

使用 engine.hipaa_safe_harbor(text) 或 HIPAA_SAFE_HARBOR_POLICY 策略。这只是机械式辅助工具，不是合规认证：它无法满足实际知情要求（164.514(b)(2)(ii)），也不能替代专家判定（164.514(b)(1)）。请参阅 docs/hipaa-safe-harbor-profile.md 和 docs/hipaa-safe-harbor-gap-analysis.md。

快速开始

从 PyPI 安装并运行引导式设置（Windows）：

py -3.12 -m pip install "securedact-mcp[ml]"
securedact-mcp setup

Linux / macOS：

python3.12 -m pip install "securedact-mcp[ml]"
securedact-mcp setup

只需几秒即可保护一段文本（仅确定性演示，无需模型）：

import os

os.environ["SECUREDACT_REQUIRE_FLAIR"] = "0"  # deterministic detectors only
from securedact_core import RedactionRequest, SecuredactEngine

engine = SecuredactEngine.from_environment()
result = engine.prepare(
    RedactionRequest(
        text="Contact [email protected], IBAN NL91ABNA0417164300",
        policy="strict_external_ai",
    )
)
print(result.status)  # "ok"
print(result.sanitized_text)  # "Contact [EMAIL_1], IBAN [IBAN_1]"

可复现的合成安全演示：docs/distribution/security-demo.md。

安全的默认工作流

常规的外部 AI 准备工作请使用 prepare_for_external_ai：

{
  "text": "Contact [email protected]",
  "policy": "strict_external_ai",
  "language": "auto",
  "response_mode": "minimal"
}

已批准的响应：

{
  "schema_version": "1",
  "status": "ok",
  "sanitized_text": "Contact [EMAIL_1]",
  "counts": {"email": 1},
  "policy": "strict_external_ai",
  "policy_version": 1,
  "policy_digest": "...",
  "reason_codes": []
}

review_required 和 blocked 响应绝不包含已批准的 sanitized_text。除非明确选择了 restore_capable，否则最简响应不包含任何原文、原始实体值、 映射、异常正文、堆栈跟踪、模型路径或恢复句柄。

架构与信任边界

flowchart LR
    H["MCP host"] --> M["Securedact MCP"]
    M --> D["deterministic detectors"]
    M --> C["contextual detectors"]
    D --> P["policy engine"]
    C --> P
    P --> R["redactor"]
    R --> V["residual validator"]
    V --> O["approved sanitized output"]
    O --> W["host-controlled downstream workflow"]
    H -. "host may bypass MCP" .-> W

此服务不包含任何提供商客户端、OpenAI 兼容代理、反向代理、 网站、桌面聊天机器人、提供商凭据或特定于提供商的转发功能。 请参阅 ADR 0001 和 威胁模型。

工具

工具	预期用途	敏感响应行为
prepare_for_external_ai	推荐的完整安全工作流	默认采用最简响应
analyze_text	较低层级的本地分析／审查	最简响应；review 中包含偏移量；仅在启用调试模式时返回原始值
redact_text	较低层级的兼容操作	默认采用最简响应；显式启用的 legacy 模式涉及敏感信息，且已弃用
restore_text	使用本地不透明会话	默认单次使用；直接映射需要显式启用可信的旧版模式
create_safe_copy	在一个已配置的根目录下写入已批准的 .txt／.md 内容	不返回映射或绝对路径
securedact_read_file	安全读取本地文件，且仅返回已净化的文本	读取前阻止访问受保护路径；拒绝路径遍历、符号链接和二进制文件；默认采用 minimal 模式

响应模式包括 minimal、review、debug 和 restore_capable。除非进程启动时设置了 SECUREDACT_ENABLE_DEBUG_RESPONSES=1，否则调试模式处于禁用状态；MCP 请求无法启用该模式。内存中的 恢复会话使用加密安全的随机句柄，并提供容量限制、过期机制、 并发保护和单次使用限制。进程退出时会销毁所有会话。

请参阅 MCP 工具、响应隐私和 恢复会话。

安装

支持 Python >=3.12,<3.13。

从 PyPI 常规安装：

py -3.12 -m pip install "securedact-mcp[ml]"
securedact-mcp setup

在 Linux 或 macOS 上，请使用 python3.12 -m pip install "securedact-mcp[ml]"； 如果 python 已指向受支持的 3.12 环境，也可以使用 python -m pip install "securedact-mcp[ml]"。

setup 会检查软件包、Python 和机器学习依赖项，检查本地模型状态，提供现有的、基于用户同意的模型安装程序，运行现有的 离线验证程序，并在检测到相应宿主时提供打包的 Claude Code 和 Gemini CLI 集成。它使用各提供商的官方插件／扩展命令，且可安全地重复运行。它不会调用提供商的 模型 API，不会自动接受提供商信任，也不会下载上下文模型，除非用户明确选择模型设置并接受现有的 上游提示。

高级或无人值守操作仍可使用手动模型命令：

securedact-mcp install
securedact-mcp models verify
securedact-mcp

最后一条命令会启动本地 stdio 服务。标准输出专用于 MCP 协议消息。securedact-mcp setup --non-interactive 会报告状态，但不会暗示已接受上游条款，也不会配置新的提供商。交互式设置特定提供商时，请使用 --host claude、--host gemini 或 --host all。

开发者/源码安装

如需使用经过审查的源码检出版本进行开发：

git clone https://github.com/GigantesHJI/securedact-mcp.git
cd securedact-mcp
python -m pip install ".[ml]"
securedact-mcp setup

仓库或 wheel 中均不包含模型检查点，启动时也不会下载模型。Securedact 不会再分发这些模型权重。上游模型权重保留各自的许可证，不会因 Apache-2.0 而重新授权。请参阅模型安装和第三方许可证。

必须明确选择仅使用确定性功能的本地开发模式：

$env:SECUREDACT_REQUIRE_FLAIR = "0"
securedact-mcp

生产环境默认要求具备上下文能力；如果配置的模型缺失、正在加载、已损坏或不可用，系统会采用故障关闭策略。

宿主应用包

integrations/ 下提供了适用于 Codex、Cursor 和 Windsurf 的经过测试的配置资源及安全工作流说明。自动化 MCP 客户端测试框架会验证服务启动、工具列表、调用、最简响应结构、stdout 完整性和关闭流程。但这并不能证明真实宿主应用会针对每个提示词调用该工具。请参阅兼容性证据。

该仓库也是一个 Gemini CLI 扩展根目录：运行 gemini extensions install https://github.com/GigantesHJI/securedact-mcp 即可安装钩子。要使此安装方式生效，必须具备 gemini-cli-extension 主题，并且发布版本的标签树中必须包含根清单；如果没有安装 pip install "securedact-mcp[ml]"，也没有本地模型，已安装的钩子就无法执行任何防护。请参阅 SecuRedact Enforced。

策略和 Python API

内置策略包括 default、strict_external_ai、gdpr、identifiers_only 和 review_all_contextual；同时仍提供兼容性策略。组织的本地策略文件仅从受控策略目录加载，采用严格的声明式架构，且无法禁用故障关闭不变量。未知、重复、超大、格式错误或为符号链接的策略都会触发故障关闭。

from securedact_core import RedactionRequest, SecuredactEngine

engine = SecuredactEngine.from_environment()
result = engine.prepare(
    RedactionRequest(
        text="Contact [email protected]",
        policy="strict_external_ai",
    )
)

from_environment() 会保留对上下文模型的要求。独立的确定性开发需要设置 SECUREDACT_REQUIRE_FLAIR=0；应用也可以注入经过测试的检测器实现。请参阅公共 API和策略。

可复现的开发

已提交的 uv.lock 为 Python 3.12 锁定了运行时、机器学习、开发、基准测试和安全相关额外依赖。

uv sync --frozen --extra dev --extra benchmark
uv run python scripts\verify.py

测试、问题报告、截图、测试夹具或拉取请求中，切勿使用真实个人信息、私人文档、凭据、客户日志或模型权重。请参阅 CONTRIBUTING.md。

评估与性能

uv run python -m securedact_eval quality --mode deterministic --gate `
  --thresholds benchmarks\thresholds.json `
  --baseline benchmarks\baselines\quality-deterministic.json
uv run python -m securedact_eval performance --mode deterministic

带版本的合成语料会报告精确及宽松的跨度精确率、召回率、F1、假阳性率和假阴性率，以及按实体、语言、领域和数据集划分的结果、操作/类别准确率和自助法召回率区间。真负例是文档级负例，而非令牌级安全性。与 GDPR 相关的测试套件用于检测评估，并非法律合规认证。真实 Flair 和 GPU 基准测试需要明确配置本地模型，不属于常规 CI。请参阅基准测试。 基准测试框架介绍了本地数据层级和大型配置；迁移计划定义了未来的提取边界。如果 GitHub 尚未执行仓库步骤就已失败，请使用 CI 故障排查决策树。本地运行成功不能替代必需的 GitHub 检查。

安全性与限制

• 应用代码不会记录任何提示词、发现内容、映射、还原句柄、密钥、模型输入或还原后的输出。
• 确定性检测和上下文检测可能会漏掉新颖、模糊或对抗性的信息泄露；本项目不声称能够处理共指问题或抵御所有混淆手段。
• 审核偏移量允许持有原始输入的可信本地客户端重建值；请将审核响应保留在本地。
• 主机行为和下游服务商行为不在信任边界内。
• 文件中记录的代码库安全设置仍需管理员验证。

请通过 SECURITY.md 私下报告漏洞。请勿在公开议题中披露漏洞详情或真实数据。

许可证

原始代码库源代码和文档根据 Apache License 2.0 许可。版权归属信息记录在 NOTICE 中。第三方依赖项和模型权重仍受其各自许可证约束。