prompt-injection-defense

用途

Prompt Injection Defense 用于保护智能体的指令与上下文表面，使其免受一类特殊文本的攻击：人类审查者看到的内容与模型读取的内容并不一致。其载体是不可见、改变方向或视觉误导的 Unicode 字符，可能隐藏在智能体当作权威来源的文件中（CLAUDE.md、AGENTS.md、SKILL.md、.cursorrules）、MCP 工具描述中，以及运行时被拉入的内容里（网页抓取、issue 正文、依赖 README）。

该威胁的定义性特征是：人类审查者看到的内容不等于模型读取的内容。技能中的所有控制手段都在弥合这一差距——要么检测这种偏差（扫描），要么消除它（净化 / 审查原始字节）。

主要能力

检测隐藏或危险的码点，包括双向控制（bidi）、Trojan Source、标签字符 ASCII 走私、零宽字符、行分隔符、C0/C1 控制字符、同形异义字符等。
净化和净化不受信内容：以字节保真的方式过滤，UTF-8 输入、UTF-8 输出，除被移除或展平的码点外完全一致。
提供原始字节审查方式，避免依赖渲染后的视图。
审计 MCP 工具描述，将其视为不受信任的指令文件。
通过边界钩子（SessionStart、git pre-commit）和规则在内容进入信任边界时触发扫描，而非每次读取都扫描。

使用方式

路径相对该技能文件夹。脚本通过 scripts/run-python.sh 启动，下文 ... 代表 bash scripts/run-python.sh scripts/。

扫描指令文件：

bash scripts/run-python.sh scripts/scan-hidden-unicode.py CLAUDE.md AGENTS.md
bash scripts/run-python.sh scripts/scan-hidden-unicode.py .
bash scripts/run-python.sh scripts/scan-hidden-unicode.py --json . | jq '.data[] | select(.severity=="critical")'

净化不受信内容：

curl -s https://r.jina.ai/https://example.com | bash scripts/run-python.sh scripts/sanitize-content.py > clean.md
bash scripts/run-python.sh scripts/sanitize-content.py untrusted.md --strip-level minimal -o clean.md
bash scripts/run-python.sh scripts/sanitize-content.py notes.txt --json 2> removal-report.json

审查原始字节：

bat --show-all CLAUDE.md
cat -A CLAUDE.md
bash scripts/run-python.sh scripts/scan-hidden-unicode.py CLAUDE.md

审计 MCP 工具描述：

bash scripts/run-python.sh scripts/scan-hidden-unicode.py path/to/mcp-server/manifest.json --strict

主要模式

模式 1：扫描受信任的指令文件中的隐藏码点。 在信任任何指令/配置文件前运行。它会遍历 .md/.mdc 及已知指令文件名，读取可调目录，并对 emoji 放行。返回 0 表示干净，命中返回 10（最严重级别输出到 stderr）。默认在 critical 与 high 级别失败；--strict 增加 medium、low 以及混合脚本同形异义 token。非 UTF-8 文件算作 high 级别发现，而非跳过。

模式 2：在不受信内容进入上下文前净化。 以字节保真过滤，stdout 输出干净结果，stderr 输出移除报告。--strip-level 可选 minimal（仅 bidi 覆盖与标签块）、standard（默认；增加零宽、隔离符、标记、文件中部 BOM、软连字符、行分隔符、C0/C1 控制，保留 emoji 与波斯/阿拉伯/印度语连接符）、aggressive（增加 ZWNJ、蒙古文与 Duployan 格式控制、PUA、变体选择符）。换行码点与空白渲染的 Hangul 填充符被展平为空格而非删除。

模式 3：审查原始字节，而非渲染视图。 在 GUI 中批准 CLAUDE.md 编辑时，审查者看到的是 bidi 重排后的字形，而不是模型所服从的逻辑字节。

模式 4：审计 MCP 工具描述。 工具描述会作为指令注入模型上下文，而用户很少阅读。把服务器清单当作不受信的指令文件处理；扫描干净仍可能包含可见的对抗性文字，需要阅读散文内容。

模式 5：作为静默守护者部署（钩子 + 规则），而非每次读取扫描。 扫描本身便宜（约 20 ms），但进程生成不便宜（约 140 ms），因此应只在不受信内容进入信任的少数边界时刻扫描。claude-mods 提供三个配套：SessionStart 钩子（启动时扫描一次项目指令文件）、git pre-commit 门禁（拒绝向指令文件添加隐藏 Unicode 的提交）、rules/prompt-injection.md（让智能体在进入不熟悉仓库及摄取抓取/MCP 内容时自动扫描和净化）。不要把扫描器放在 PreToolUse Read 钩子上，因为匹配器匹配工具名而非路径。

摄取面风险排序（由高到低）

MCP 工具描述：面向模型，极少被审查。控制：扫描清单并阅读散文。
抓取到的网页/issue/PR 正文：攻击者可控，运行时拉取。控制：摄取前净化。
依赖 README/changelog：随供应链防御影响到达。控制：扫描 + 净化。
CLAUDE.md / SKILL.md / .cursorrules：最高权威，PR 引入的编辑。控制：扫描 + 原始字节审查。
提交信息、代码注释：被概括历史的智能体读取。控制：整体摄取时扫描。

适用场景

收到非自己编写的指令文件（PR、模板、依赖）。
进入不熟悉的仓库。
将不受信内容拉入上下文（WebFetch、r.jina.ai、issue/PR 正文、changelog）。
添加或审查 MCP 服务器。
怀疑某个文件看似干净但感觉不对。

限制与说明

脚本化的覆盖范围是隐藏 Unicode 与同形异义检测加净化，即机械、确定性的部分。可见文本是否对抗属于判断问题，作为准则覆盖，而非检测器。
退出码：0 正常；2 用法错误；3 未找到；4 校验；5 缺少目录（扫描时或文件不可读）；10 发现指标（仅扫描）。
通过 run-python.sh 启动，在 Windows 上 python3 常是 Microsoft Store 别名，会退出 49 且什么都不运行。启动器退出 5 表示 PATH 上没有 Python 3.8+。
两个脚本读取 assets/dangerous-codepoints.json（可用 --catalog 覆盖），强制 UTF-8 stdio，共享退出码。
bash tests/run.sh 是离线自测。该文件夹可单独复制运行，脚本、启动器、目录、参考和测试都在其中。模式 5 的钩子和规则是 claude-mods 中的可选配套。

脚本

scripts/scan-hidden-unicode.py：检测文件或 stdin 中隐藏/危险码点；命中退出 10。关键参数：--strict、--json、--stdin、--no-emoji-whitelist、--include。
scripts/sanitize-content.py：从不受信内容中剥离危险码点（字节保真过滤）。关键参数：--strip-level、--nfkc、-o、--json。
scripts/run-python.sh：用 python3 / python / py 中第一个真正是 Python 3.8+ 的来运行上述脚本。参数：--which、--help。

验证清单

指令文件（CLAUDE.md/AGENTS.md/SKILL.md/.cursorrules）扫描干净（scan-hidden-unicode.py，退出 0）。
任何地方都没有 critical 级别：bidi 覆盖（U+202A-U+202E）或标签块（U+E0000-U+E007F）。
不受信/抓取内容在进入上下文前经过 sanitize-content.py。
MCP 工具描述已扫描并阅读可见对抗散文。
任何被标记的文件以原始字节而非渲染字形审查。
emoji 密集文件未误报（白名单工作正常）。
对同形异义冒充重要的文件考虑运行 --strict。

技能介绍

用途