SHUBHAGYTA24/contextduty

# ContextDuty [](https://pypi.org/project/contextduty/) [](https://www.python.org/) [](LICENSE) [](https://github.com/SHUBHAGYTA24/contextduty/actions/workflows/ci.yml) [](https://modelcontextprotocol.io) ## 为什么选择 ContextDuty AI 编程助手和代理（agent）工作流正在迅速普及。随之而来的还有意外的数据泄露——API 密钥、电子邮件和 PII（个人身份信息）流入提示、日志和追踪中，并可能被存储或发送给第三方服务。 ContextDuty 是一个**本地优先、策略分层的防火墙**，它在数据从您的环境移动到 LLM 的确切时刻介入——在为时已晚之前。 - **CLI** — 在 CI 或预提交钩子中通过管道传输文件 - **MCP server** — Cursor、VS Code 以及任何 MCP 客户端都可获得自动拦截 - **策略继承** — 团队可以在不复制规则的情况下扩展组织范围的基线 ## 为什么不使用 Presidio？ Presidio 是一个数据处理管道工具——它在事后处理文档，并且其 MCP 包装器[明确警告](https://github.com/Szowesgad/mcp-server-presidio)，当它运行时，LLM 已经看到了您的数据。ContextDuty 是一个**在提示边界处**的执行原语，这正是实际发生泄露的地方。 | | ContextDuty | Presidio | |---|---|---| | 在 LLM 看到数据之前拦截 | ✅ | ❌ (LLM 将其作为工具调用 — 数据已发送) | | 人名、地点 (NLP) | ❌ | ✅ | | 结构化秘密和 API 密钥 | ✅ | ✅ | | MCP 执行层 | ✅ | ❌ | | 策略分层 + `block` 模式 | ✅ | ❌ | | 零依赖，即时启动 | ✅ | ❌ (需要下载 spaCy 模型) | | 确定性的、可审计的掩码 | ✅ | ❌ (ML 置信度得分会有所不同) | 对于结构化秘密和 API 密钥——最常见的 AI 工作流泄露——ContextDuty 以零延迟和完全可审计性捕获它们。对于姓名和地点等非结构化 PII，Presidio 的 ML 识别器是合适的工具。它们是互补的，而不是竞争的，并且 Presidio 集成已在路线图中。 ## 检测覆盖范围 | 检测器 | 示例输入 | 掩码结果 | |---|---|---| | `email` | `jane@corp.com` | `` | | `phone` | `+1 415-555-1212` | `` | | `api_key` | `sk_live_ABC123...` | `` | | `aws_key` | `AKIA1234567890ABCDEF` | `` | | `bearer_token` | `Bearer eyJhbGci...` | `` | 掩码是**确定性的**——相同的值总是产生相同的掩码，因此您可以跨日志行关联而不暴露原始值。 ## 快速开始 ``` pip install contextduty contextduty init ``` 立即尝试： ``` cat > /tmp/test.txt << 'EOF' From: priya@healthtech.com Auth: Bearer eyJhbGciOiJIUzI1NiJ9.payload.sig AWS Key: AKIA1234567890ABCDEF API: sk_live_9Xk2mPqRvL8nJwTdYcBe3F Phone: +1 415-555-1212 Error: SMTP timeout on port 587 EOF contextduty scan /tmp/test.txt contextduty redact --in /tmp/test.txt --out /tmp/clean.txt cat /tmp/clean.txt ``` 或运行完整演示： ``` git clone https://github.com/SHUBHAGYTA24/contextduty cd contextduty && bash demo/demo.sh ``` ## 命令 | 命令 | 描述 | |---|---| | `contextduty init` | 在当前目录创建 `.contextduty.json` | | `contextduty scan ` | 扫描文件，打印 JSON 发现报告 | | `contextduty redact --in --out ` | 编辑匹配项，写入清理后的文件 | | `contextduty policy validate --policy [--strict]` | 验证并解析分层策略 | | `contextduty --version` | 打印已安装的版本 | ## MCP server (Cursor / VS Code / 任何 MCP 客户端) ContextDuty 作为 MCP stdio 服务器运行——将其放入您的编辑器配置中，您的代理触及的每个文件都会在到达 LLM **之前**被扫描。 ``` contextduty-mcp ``` **Cursor** — 添加至 `~/.cursor/mcp.json`： ``` { "mcpServers": { "contextduty": { "command": "contextduty-mcp" } } } ``` 暴露的工具： | 工具 | 参数 | 用例 | |---|---|---| | `contextduty_scan_text` | `text`，可选 `policyPath` | 扫描内存中的字符串 — **用于提示拦截** | | `contextduty_scan` | `path`，可选 `policyPath` | 扫描磁盘上的文件 | | `contextduty_redact` | `inputPath`，`outputPath`，可选 `policyPath` | 编辑磁盘上的文件 | ## 策略文件 默认 `.contextduty.json`： ``` { "mode": "redact", "detectors": ["email", "phone", "api_key", "aws_key", "bearer_token"], "custom_detectors": {} } ``` **无需修改代码即可添加自定义检测器：** ``` { "mode": "redact", "detectors": ["email"], "custom_detectors": { "employee_id": "\\bEMP-[0-9]{6}\\b", "internal_ticket": "\\bTICKET-[A-Z]{3}-[0-9]{4}\\b" } } ``` `custom_detectors` 会自动启用——只需添加正则表达式条目。 **面向团队和企业的策略分层：** ``` { "extends": "../../policies/org-baseline.json", "mode": "block", "detectors": ["internal_ticket"], "custom_detectors": { "internal_ticket": "\\bTICKET-[A-Z]{3}-[0-9]{4}\\b" } } ``` 规则： - `extends` 可以是字符串或列表（相对文件路径） - `detectors` 会被合并（父级 + 子级） - `custom_detectors` 会被合并（子级覆盖同名键） - `mode` 会被子策略覆盖 - `extends` 中的循环会被拒绝并显示明确的错误 **模式：** | 模式 | 行为 | |---|---| | `redact` | 用确定性掩码替换匹配的值 | | `warn` | 报告发现，不更改内容 | | `block` | 如果存在发现则以非零状态退出（CI 强制执行） | ## 合规策略包 适用于 SOC 2 和 HIPAA 的现成基线——在您自己的策略文件中扩展它们： | 包 | 文件 | 包含的检测器 | |---|---|---| | SOC 2 | `policies/soc2-baseline.json` | email, phone, api_key, aws_key, bearer_token | | HIPAA | `policies/hipaa-baseline.json` | email, phone + SSN, NPI, DEA, ICD-10, MRN | 用法： ``` { "extends": "policies/soc2-baseline.json", "mode": "block" } ``` ## CI 集成 如果在特定文件中发现秘密，请使用 `block` 模式使流水线失败： ``` # .github/workflows/contextduty.yml - name: Scan for secrets run: | pip install contextduty contextduty scan src/my_module.py --policy .contextduty.json ``` ## 本地开发 ``` git clone https://github.com/SHUBHAGYTA24/contextduty cd contextduty make install # pip install -e ".[dev]" make check # fmt + lint + tests — run before every push bash demo/demo.sh ``` ## 路线图 - [x] PyPI 发布 (`pip install contextduty`) - [ ] 目录扫描 (`contextduty scan src/`) - [ ] Presidio 集成作为可选 NLP 后端 有想法吗？[提出问题](https://github.com/SHUBHAGYTA24/contextduty/issues)。 ## 开源 | 文件 | 目的 | |---|---| | `LICENSE` | MIT | | `SECURITY.md` | 漏洞报告 | | `CONTRIBUTING.md` | 如何贡献 | | `CODE_OF_CONDUCT.md` | 社区标准 | | `CHANGELOG.md` | 版本历史 | 欢迎提交问题、PR 和策略包贡献。请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 开始。

标签：AI安全, API密钥, Chat Copilot, CISA项目, Cursor, DevSecOps, DLP, IP 地址批量处理, LLM防火墙, MCP兼容, MCP服务器, Model Context Protocol, PII脱敏, Python, VS Code, 上游代理, 个人隐私信息, 代码助手, 前置拦截, 密钥保护, 提示词工程, 敏感数据, 数据合规, 文档结构分析, 无后门, 本地优先, 策略决策点, 策略引擎, 网络安全, 网络安全挑战, 隐私保护, 零依赖