# desensitize **Repository Path**: gzalex78/desensitize ## Basic Information - **Project Name**: desensitize - **Description**: No description available - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-10-26 - **Last Updated**: 2026-10-26 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # desensitize · 敏感信息扫描与脱敏技能 面向支持 `SKILL.md` 的智能体及独立命令行用户:在分享日志、配置、代码、交易记录或项目目录前,先扫描再脱敏,生成一份**仍需人工复核**的副本。规则复检是安全辅助,不等于匿名化或绝对无遗漏。 检测和替换由确定性脚本完成,智能体只负责按退出码执行流程并转述类型与占位符。 - **零依赖**:Python 3.8+ 标准库,无联网、无遥测 - **原文件不动**:映射表不能指向输入或源目录;输出先写临时位置,复检通过才提交 - **报告不显示命中行上下文**:只转述规则类型和占位符,路径命中也会打码 - **路径脱敏**:检查文件与目录名称,使用跨平台安全占位符,冲突时拒绝输出 - **可还原**:placeholder 模式可选明文映射表;mask 模式不可逆,不能与映射表同用 - **交付前复检**:内容与路径覆盖 medium 及以上,失败返回 4 且不生成最终输出 - **面向中文场景**:身份证、银行卡、手机号、资金/股东账号、常见机器人 webhook、中文密码赋值、GBK 文本 - **Office 深度检查**:支持 `.docx .xlsx .pptx` 已知文本部件及 Excel 批注,其他 XML 参与残留复检;宏和嵌入对象拒绝处理,内嵌图片列为人工检查项 ## 安装与运行 ### 独立命令行 安装 Python 3.8+ 后,直接运行 `scripts/desensitize.py`,不需要安装第三方包或接入 AI 模型。Windows 下把示例中的 `python3` 换成 `python`。 本轮未在 macOS / Linux 上实测;在其他平台使用前,请先运行文末测试并用虚构数据试用。 ### 智能体技能 `SKILL.md` 只含 `name` 和 `description` 两个 frontmatter 字段,不依赖宿主专用元数据。若宿主支持 `.skill` 导入,可使用发布包中的 `desensitize.skill`;否则解压 `desensitize.zip`,按目标宿主的技能目录约定放置整个 `desensitize` 目录。 OpenClaw 的目录约定示例: - 所有智能体共享:`~/.openclaw/skills/desensitize` - 只给某个工作区:`/skills/desensitize` 不同宿主的目录发现、触发和权限机制不同,本轮未逐一实测安装兼容性;导入后请先用虚构数据验证完整流程。 **Windows 映射表警告**:`--map` 生成的是含原文的明文 JSON,且 `chmod 600` 在 Windows 上不能提供 POSIX 权限保护。请把映射表放在本机用户目录的专用位置,不要放进同步盘、源目录或项目目录。 ## 快速上手 ```bash # 1. 扫描(只读) python3 scripts/desensitize.py scan ./my-project # 2. 生成脱敏副本(默认输出到 ./my-project_redacted) python3 scripts/desensitize.py redact ./my-project --db-schema # 3. 一段日志:标准输入 → 标准输出,不把原文写进命令行 python3 scripts/desensitize.py redact - < app.log > app.redacted.log # 4. 发给外部模型前脱敏,拿到回答后再还原 python3 scripts/desensitize.py redact trades.csv -o trades.redacted.csv --map ~/.openclaw/desensitize/maps/trades.json --enable amount python3 scripts/desensitize.py restore answer.md --map ~/.openclaw/desensitize/maps/trades.json -o answer.restored.md ``` 不常用命令行的 Windows 用户可以把文件或文件夹拖到 `scan.bat` / `redact.bat` 上运行。 ## 同类文件批量脱敏(跨文件保持一致) 多次脱敏时共用同一个映射表,同一个敏感值可跨文件保持同一个占位符: ```bash python3 scripts/desensitize.py redact 5月工资表.xlsx -o 5月_脱敏.xlsx --map <本机私密目录>/工资映射.json --terms 词表.txt python3 scripts/desensitize.py redact 6月工资表.xlsx -o 6月_脱敏.xlsx --map <本机私密目录>/工资映射.json --terms 词表.txt python3 scripts/desensitize.py restore 模型回答.md --map <本机私密目录>/工资映射.json -o 回答_还原.md ``` 注意: - **映射表是占位符 ↔ 原文的明文对照,等于全部秘密本身**:只留本机私密目录,绝不发给外部模型、不进同步盘、不进 git。脚本会拒绝让映射表等于输入文件或位于源目录内。 - 发给外部模型的只有脱敏后的文件;模型不需要、也不应看到映射表、词表或放行值文件。 - 稳定占位符便于跨文件处理和还原,但也可能让接收者关联同一主体;这不等于匿名化。 - 人名等规则无法自动覆盖的词可用 `--terms 词表.txt` 补充,词表同样只留本机。 - 映射表丢失后无法 restore;备份也只能保存在本机私密位置。 - `--style mask` 不可逆,不能与 `--map` 同用;密钥即使在 mask 模式下也使用完整占位符。 脱敏效果示意: | 原文类型 | `--style placeholder`(默认) | `--style mask` | |---|---|---| | 手机号 | `` | `138****5678` | | 邮箱 | `` | `z***@domain.cn` | | 资金账号 | `` | `********5678` | | API Key / 令牌 / 私钥 | `` / `` / `` | 同左(密钥永不部分显示) | | `C:\Users\<名字>\...` | `C:\Users\\...` | 同左 | ## 规则 运行 `python3 scripts/desensitize.py rules` 查看完整列表。 | 类别 | 默认 | 内容 | |---|---|---| | secret | 开 | PEM 私钥、AWS / 阿里云 / 腾讯云 AccessKey、GitHub / Slack / Telegram 令牌、`sk-` 开头的大模型 Key、Google API Key、JWT、机器人 webhook、URL 内嵌密码、Bearer / Basic 认证、密钥类赋值、中文“密码:” | | pii | 开 | 身份证号、银行卡号、手机号、邮箱 | | finance | 开 | 资金账号 / 股东账号 / 客户号(关键词识别)、上交所股东账号 | | env | 开 | 用户目录中的用户名、内网 IP;公网 IP 默认关 | | amount | **关** | 持仓市值、成本、余额、盈亏、持股数量(`--enable amount` 打开) | | custom | 视词表 | 自定义词表与自定义规则 | | file | 开 | `.env*`、私钥/证书/令牌文件、数据库/pickle、超大文件、二进制文件、PDF 与旧版 Office 文档 | ## 目录与文档处理边界 - 文件、子目录和目录根名称都参与扫描与脱敏;改名后冲突会停止,且不生成最终输出。 - `.git` 等目录跳过;凭据文件、数据文件、PDF 与旧版 Office 文档默认不复制。 - `.env*` 不复制,生成只含键名且删除注释的模板。 - `.docx .xlsx .pptx` 改写已知文本部件(含 Excel 批注),并深度复检其他 XML 文本和属性;发现不能安全改写的残留会拒绝交付。 - `.docm .xlsm .pptm`、VBA、嵌入对象和可执行内容不支持:单文件拒绝,目录中不复制。 - Office 内嵌图片等二进制默认原样复制并列为人工检查项;可用 `--drop-binary` 改为不复制。工具不识别图片文字。 - SQLite 可用 `--db-schema` 导出不含行数据的表结构,但默认值、视图等仍需检查。 - 文本文件保持原编码与换行符;输出先在临时位置复检,失败时不留下最终文件或目录。 ## 定制 - **词表**(真实姓名、券商、公司名等):`~/.openclaw/desensitize/terms.txt`,格式见 [`examples/terms.example.txt`](examples/terms.example.txt)。词表本身是敏感清单,不要放进要分享的目录。 - **自定义规则**:`--rules my_rules.json`,格式见 [`examples/rules.example.json`](examples/rules.example.json)。 - **放行误报**:优先让用户自行准备本机私密文件,每行一个精确值,再使用 `--allow-value-file <路径>`;也可使用 `--allow-value <值>`,但原值会进入命令行记录。 - **其他放行方式**:行尾注释 `desensitize:allow`,或目录根部 `.desensitizeallow`(见 [`examples/desensitizeallow.example`](examples/desensitizeallow.example))。 - 私钥、超大文件、宏和嵌入对象等不安全 Office 内容不可豁免。不要读取或外发放行值文件。 ## 退出码 | 码 | scan | redact | |---|---|---| | 0 | 无已启用规则命中 | 成功,medium 及以上内容与路径复检通过 | | 1 | 参数 / 运行错误 | 参数 / 运行错误 | | 2 | 有 high 命中 | — | | 3 | 最高为 medium | — | | 4 | — | 复检仍有残留,未生成最终输出 | | 5 | 最高为 low,含未扫描项 | — | `scan` 返回 5,或较高等级命中同时伴随 low 项时,都要先列出并处理人工检查项。`redact` 返回 0 也不代表可以跳过这些人工检查。 ## 局限 - 规则和词表无法覆盖所有人名、地址、公司名及未知秘密格式;脱敏不等于匿名化。 - Excel 数字单元格不直接改写;深度扫描若发现命中,会拒绝交付。 - 图片、截图和扫描件中的文字不会被识别;数据库行数据默认不扫描、不复制。 - 仅识别 UTF-8 / GBK 文本;UTF-16 文件需先转码,否则按二进制处理。 - 数字签名可能因改写失效;外部链接和文档实际打开效果需用对应 Office 应用人工复核。 - medium 可能误报,所以放行值必须由用户确认。 - 密钥一旦外泄,应先吊销或更换;脱敏不能补救已经发生的泄露。 ## 测试 ```bash python3 tests/test_desensitize.py ``` 测试离线运行,敏感样例均为运行时拼接的虚构数据,包含扫描本仓库自身的自动规则自检;自检不能替代人工复核。 ## 许可 MIT