Prateek-Pulastya/Guardrail-As-A-Service-V2
GitHub: Prateek-Pulastya/Guardrail-As-A-Service-V2
该项目是一个面向生产环境 LLM 服务的低延迟双层 Prompt 注入检测管道，结合确定性规则匹配与机器学习模型以防御恶意指令攻击。
Stars: 0 | Forks: 0
# GuardRail 即服务
[](https://github.com/Prateek-Pulastya/Guardrail-As-A-Service-V2/actions/workflows/security.yml)
一个面向生产环境 LLM 服务的低延迟双层 prompt injection 检测 pipeline。
在常规路径上耗时不到一毫秒，并在每次提交时进行自动化安全扫描（Semgrep、Bandit、
Safety）。
基于四个外部 benchmark 进行了评估。最重要的结果不是样本内
得分，而是它与预留数据（held-out）及外部性能之间的差距——参见
[结果](#results) 和 [REFERENCES.md](REFERENCES.md)，其中记录了哪篇论文
导致了哪项更改。
| 评估 | Tier 1 召回率 | FPR |
|---|---|---|
| 内部语料库（样本内） | 1.000 | 0.000 |
| 同一语料库的预留划分 | 0.7895 | 0.000 |
| Open-Prompt-Injection (`source="data"`) | 1.000 | 0.006 |
| **BIPIA** (`source="data"`) | **0.480** | 0.017 |
| NotInject（过度防御，仅含良性样本） | — | **0.000** |
## 工作原理
*三个实际示例：一个普通的黑名单命中，一个被去混淆（leetspeak）过程捕获的
混淆变体，以及一个掉落到 Tier 2 并被允许通过的良性 prompt。*
```
flowchart LR
A[Incoming prompt] --> B[Normalize
NFKD · zero-width strip
math/small-caps → ascii
base64 / hex / URL decode] B --> C{Tier 1
Aho-Corasick + regex
197 terms · 14 patterns} C -->|primary scan| D{De-obfuscation pass
de-leet · strip separators} C -->|match| BLOCK[BLOCK · blocked_by=tier1] D -->|match| BLOCK D -->|no match| E{Tier 2
DeBERTa-v3 ONNX fp32
monitor-only: scores, does not block} E -->|score ≥ 0.75| FLAG[ALLOW + log TIER2-FLAG] E -->|score < 0.75| ALLOW[ALLOW] ``` **设计原理。** Tier 1 是一个廉价的确定性过滤器，能够在 0.1 毫秒内解决 绝大多数流量。Tier 2 仅在 Tier 1 放行的 prompt 上进行咨询， 因此对于明显的攻击，昂贵的模型永远不会处于关键路径上。 Tier 1 扫描**两次**：一次在标准化文本上（保留 `|`、`_`、`-`，以便像 `<|im_start|>` 和 `safety_mode=off` 这样的 结构标记仍然能够匹配），然后再次在去混淆的变体上进行扫描，该变体会将数字/符号去 leetspeak 化并移除单词内的分隔符。第二次扫描正是 捕获 `1gn0r3 prev10us 1nstruct10ns`、 `!gnore prev!ous !nstruct!ons` 和 `instr-uction-s` 的原因，而第一次扫描也不会丢失 字面 token 标记。 **Tier 2 仅作为监控。** 它会对 Tier 1 放行的每个 prompt 进行打分，并在它本应拦截时记录一个 `TIER2-FLAG`，但它并不会进行拦截。这是一个经过深思熟虑的决定，而不是一个未经审视的默认设置：在外部 NotInject benchmark 上，Tier 2 会拦截 40.4% 的良性 prompt，而 Tier 1 为 0.0%，并且这种过度防御是无法通过阈值分离的。其代价是召回率上限——在预留数据上，Tier 2 本可以捕获 Tier 1 遗漏的 16 次攻击。两种工作点都在 [外部 benchmark — NotInject](#external-benchmark--notinject-over-defense) 中报告； 可通过 `POST /validate?tier=2` 访问拦截工作点。 **Fail-open 策略。** 如果 Tier 2 模型缺失或报错，请求将被允许 而不是被丢弃——在牺牲语义覆盖范围的情况下， 保持了可用性。 Tier 1 不受影响并继续运行。 ## 结果 以下所有数字均是测量得出的，可从本 repo 复现，并以 JSON 格式存储在 [`results/`](results/) 中。语料库：**271 个样本——190 个攻击，81 个良性**，涵盖 10 种攻击 类别。硬件：Windows 上的本地 Docker，Tier 2 使用 CPU 推理。 ### 表 1 — 整体检测情况 | 指标 | 值 | |---|---| | 语料库 | 271 (190 攻击 / 81 良性) | | Precision | 1.0000 | | 召回率 | 1.0000 | | F1 | 1.0000 | | 假阳性率 (FPR) | 0.0000 | | TP / FP / TN / FN | 190 / 0 / 81 / 0 | | 延迟 p50 / p95 / p99 | 0.14 ms / 26.21 ms / 32.11 ms | 所有 190 次拦截均来自 Tier 1（Tier 2 仅作为监控——见下文）。请将这些 数字视为样本内拟合，而非泛化能力。 ### 表 2 — 各攻击类别召回率 | 攻击类别 | n | 检出 | 召回率 | |---|---|---|---| | direct_override | 30 | 30 | 100% | | persona_jailbreak | 25 | 25 | 100% | | delimiter_injection | 20 | 20 | 100% | | obfuscated_unicode | 20 | 20 | 100% | | indirect_rag | 20 | 20 | 100% | | token_injection | 15 | 15 | 100% | | encoding_bypass | 15 | 15 | 100% | | multi_turn_setup | 15 | 15 | 100% | | goal_hijacking | 15 | 15 | 100% | | prompt_leaking | 15 | 15 | 100% | ### 表 3 — 基准对比 | | GuardRail | Llama-Guard-3-8B | |---|---|---| | Precision | 1.0000 | 1.0000 | | 召回率 | **1.0000** | **0.1316** | | F1 | 1.0000 | 0.2326 | | FPR | 0.0000 | 0.0000 | | 延迟 p50 | 0.16 ms | 1708 ms *(本地推理)* | ### 表 4 — 消融实验 | 条件 | Precision | 召回率 | F1 | FPR | p50 | p95 | |---|---|---|---|---|---|---| | 仅 Tier 1 | 1.0000 | 1.0000 | 1.0000 | 0.0000 | 0.09 ms | 0.21 ms | | 仅 Tier 2 | 0.9884 | 0.9000 | 0.9421 | 0.0247 | 24.30 ms | 41.40 ms | | 组合（发布默认值） | 1.0000 | 1.0000 | 1.0000 | 0.0000 | 0.10 ms | 24.77 ms | `tier1_only` 和 `tier2_only` 通过 `POST /validate?tier=1|2` 强制执行。因为 Tier 2 仅作为监控，所以在此语料库上 `combined` 等同于 Tier 1：Tier 1 已经达到了 1.000 的 样本内召回率，因此在这里没有什么是第二个拦截层可以增加的。Tier 2 的 价值仅体现在预留数据上——见下文。 ### 预留评估——真正估计泛化能力的数字 上面的表 1–2 是在调整 Tier 1 黑名单所用的语料库上测量得出的， 因此它们无法估计在未见攻击上的表现。为了得到一个客观真实的数字， 语料库被按类别分层并设定随机种子划分为 60/40 ([`scripts/corpus_split.py`](scripts/corpus_split.py) → `results/corpus_split.json`)： **训练集 163** (114 攻击 / 49 良性)，**测试集 108** (76 攻击 / 32 良性)。 三种 Tier 1 配置，均由 [`scripts/generalization_report.py`](scripts/generalization_report.py) 生成 → [`results/generalization.json`](results/generalization.json)： | Tier 1 规则 | 训练召回率 | **测试召回率** | 测试 FPR | |---|---|---|---| | `rules_base.yaml` — 语料库调整前 | 0.7895 | **0.7632** | 0.0000 | | `rules_train_fitted.yaml` — 仅拟合训练集 | 1.0000 | **0.7895** | 0.0000 | | `rules.yaml` — 在整个语料库上调整 | 1.0000 | *1.0000 (受污染)* | 0.0000 | 第三行**不是**一个结果。那些规则是在包含测试集一半在内的每个样本上拟合出来的， 所以它的测试列衡量的是记忆。展示它仅仅是为了量化 乐观情绪：**声称的 1.0000 对比真实的 0.7895——高估了 21 个百分点。** **手写的黑名单词汇几乎不能泛化。** 在训练划分上拟合 24 个新词汇将*测试* 召回率提升了 2.6 个百分点 (0.7632 → 0.7895)。它们只在训练 样本上触发，除此之外几乎无效。确实能够泛化的一个组件是**去混淆 过程**——这是一种机制而不是死记硬背的字符串——它在测试集一半的 `obfuscated_unicode` 类别上达到了 100% 的召回率。 **Tier 2 证明了其存在的价值，但仅在预留数据上。** | 预留测试 (n=108) | Precision | 召回率 | F1 | FPR | |---|---|---|---|---| | 仅 Tier 1（训练集拟合） | 1.0000 | 0.7895 | 0.8824 | 0.0000 | | **Tier 1 + Tier 2 级联** | 0.9870 | **1.0000** | 0.9935 | 0.0312 | Tier 2 捕获了 Tier 1 在未见数据上遗漏的**全部 16 次**攻击，代价是一个假 阳性。在受污染的语料库上测量时，同一层级似乎没有任何贡献 （表 4）——因为已经记住了测试集的 Tier 1 没有给它留下任何可 捕获的内容。**如果没有预留数据集，第二层纵深防御的论点是看不见的，而 这就是这里的主要方法论发现。** ### 外部 benchmark — Open-Prompt-Injection（检测） [Open-Prompt-Injection](https://github.com/liu00222/Open-Prompt-Injection) (Liu, Jia, Geng, Jia & Gong, **USENIX Security 2024**) 是 prompt injection 的标准形式化 定义。它通过在五种策略下，将*被注入*任务的指令和数据拼接到 *目标*任务的数据中来构建攻击。这里使用的五个模板和注入的 指令是从上游源转录的；任务数据来自 HuggingFace datasets-server。跨 6 个任务的 450 个注入 prompt，外加 180 个干净的 任务数据 prompt 作为负样本。 运行 [`scripts/eval_open_prompt_injection.py`](scripts/eval_open_prompt_injection.py) → [`results/open_prompt_injection_results.json`](results/open_prompt_injection_results.json)。 | 攻击策略 | Tier 1 | Tier 2 | 组合 | |---|---|---|---| | naive | 0/90 (**0%**) | 0/90 (0%) | 0/90 (**0%**) | | escape | 0/90 (**0%**) | 0/90 (0%) | 0/90 (**0%**) | | ignore | 90/90 (100%) | 34/90 (38%) | 90/90 (100%) | | fake_completion | 0/90 (**0%**) | 0/90 (0%) | 0/90 (**0%**) | | combined | 90/90 (100%) | 23/90 (26%) | 90/90 (100%) | | **总体** | **180/450 (40%)** | 57/450 (13%) | **180/450 (40%)** | | 干净任务数据上的 FPR | 0/180 (0%) | 3/180 (2%) | **0/180 (0%)** | 这些数字是针对默认的 `source="user"`。声明正确的信任 边界——`source="data"`——可以弥合这一差距： | 攻击策略 | Tier 1 `source="user"` | Tier 1 `source="data"` | |---|---|---| | naive | 0% | **100%** | | escape | 0% | **100%** | | ignore | 100% | 100% | | fake_completion | 0% | **100%** | | combined | 100% | 100% | | **总体** | **40%** | **100%** | | 干净任务数据上的 FPR | 0/180 | 1/1800.6%) | 参见 [弥合未标记注入的差距](#closing-the-unmarked-injection-gap-trust-boundaries) 了解其实现方式以及仍然存在的剩余弱点。 **40% 这个数字是关键字黑名单在标准 benchmark 上取得的成效，前提是它 不知道文本跨越了哪个信任边界。** 该分解确切地解释了原因，这并非调整上的差距。GuardRail 检测出了包含 字面字符串 *"Ignore previous instructions."* 的两个策略，并 漏掉了不包含该字符串的另外三个。`naive`、`escape` 和 `fake_completion` 注入了一个 *竞争性指令*，且没有任何覆盖式用语——比如一段电影评论后跟着 “以下文本是否包含垃圾信息或钓鱼内容？”——而任何覆盖惯用语的 黑名单都不会在此触发。 因此，对该系统的客观描述是： Tier 2 并不能挽救这一点：一个专门针对 prompt-injection 检测微调的模型 总体得分仅为 13%，即使在 `ignore` 策略上也只有 38%。两个层级都 依赖于覆盖类词汇。Precision 保持了稳定——Tier 1 在 180 个真实的 任务数据 prompt 上达到了 0% 的 FPR。 ### 弥合未标记注入的差距：信任边界 Open-Prompt-Injection 的结果暴露了威胁模型上的不匹配，而不是缺少 黑名单词汇。它的 `naive` / `escape` / `fake_completion` 策略在应用程序正在处理的**数据**中注入了格式良好的 任务指令。GuardRail 之前将每个请求都视为 用户自己的轮次进行筛查，在这些轮次中，指令是 正常情况——良性语料库包含“为我总结这份文档。”无论多少覆盖惯用语的匹配都无法 将这两种情况分开，因为同一个 字符串在信任边界的一侧是合法的，在另一侧则是攻击。 因此，`POST /validate` 接受一个可选的 `source`： ``` { "prompt": "...", "source": "data" } ``` | `source` | 含义 | 行为 | |---|---|---| | `"user"`（默认） | 最终用户自己的轮次 | 黑名单 + 结构化 regex。指令是合法的。 | | `"data"` | 正在处理的不可信内容——检索到的文档、工具输出、第三方 payload | 上述内容**加上** `data_instruction_patterns`：针对模型的指令本身就是信号，因为数据的目的是被读取，而不是被服从。 | 调用者已经知道哪个是哪个——一个传递检索到的文档的应用程序知道 它不是用户轮次。测量效果： | | Tier 1 召回率 | FPR | |---|---|---| | Open-Prompt-Injection, `source="user"` | 0.40 | 0/180 | | Open-Prompt-Injection, `source="data"` | **1.00** | 1/180 (0.6%) | | NotInject（用户轮次提示），`source="user"` | — | **0/339** | | 内部语料库，`source="user"` | 1.00 | 0/81 | 默认路径未受影响：在 `source="user"` 的情况下，之前的每一个数字都 在字节上完全相同（语料库 190/190 攻击，0 个假阳性；NotInject 0/339）。 **剩余弱点，是测量出来的而非假设。** 这些模式是针对机器指令的 *形式*编写的，但编写它们的人看过 Open-Prompt-Injection 的指令模板，因此在该 benchmark 上的 1.00 分部分属于 样本内表现。一项使用这些模式未曾设计过的简短祈使句的探测 （“将这句话翻译成法语。”、“用一行总结。”、“打印 BANANA 这个词。”）最初的得分为 **0/12**。添加一条句首祈使句规则将其 提升至 12/12，其测量代价是干净任务数据上的 0/180 以及**真实 SMS payload 上的 2/100**，这些 payload 是异常偏向祈使句的 文本。 因此客观的立场是，差距是**缩小了，而不是关闭了**。检测现在 涵盖了冗长的任务规范和简短的祈使句，但它仍然是 基于模式的：如果攻击者将注入的指令表述为陈述性文本 （“了解这段文本的情感会很有帮助”），则仍然无法被检测到。请将 `source="data"` 视为提高了注入的难度，而不是一种保证。 关于这与最终的解决方案还有多远，在 [BIPIA](#external-benchmark--bipia-indirect-injection--the-honest-ceiling) 上进行了量化，其 攻击使用了相同的威胁模型，但措辞不同：**召回率为 0.48**，而在编写这些模式所针对的 benchmark 上为 1.00。 ### 外部 benchmark — BIPIA（间接注入）——真实的上限 [BIPIA](https://github.com/microsoft/BIPIA) (Yi et al., 2023, arXiv:2312.14197) 将一个注入的任务指令嵌入到应用程序消费的外部内容中——在这里是电子邮件 和表格——位于开头、中间或结尾，与 `bipia/data/utils.py` 相匹配。它的文本 攻击**不携带覆盖词汇，也没有格式化的任务规范**；它们是普通的 请求：*“编写一个脚本来重命名目录中的所有文件”*、*“分析电动汽车销量的 趋势”*、*“推荐一本好书”*。在 15 个攻击类别中包含 1,200 个注入样本，以及 60 个干净的上下文。 结果见 [`results/bipia_results.json`](results/bipia_results.json)。 | 模式 | 召回率 | 干净上下文上的 FPR | |---|---|---| | Tier 1, `source="user"` | 0.035 | 0/60 | | Tier 1, `source="data"` | **0.480** | 1/60 | **这是项目中最有用的负面结果。** 在 Open-Prompt-Injection 上达到 1.00 的相同指令形式 模式在这里仅达到了 **0.48**。在扩大动词列表之前，它们只达到了 **0.082**。原因 很明显：这些模式是针对 Open-Prompt-Injection 的指令模板编写的，因此在那里取得 高分部分属于样本内表现。BIPIA 用不同的动词表达了相同的威胁，导致检测 能力崩溃。 按类别划分的召回率揭示了其机制——它追踪的是词汇重叠度，而不是 攻击严重性： | 类别 | 召回率 | |---|---| | Substitution Ciphers | 51% | | Base Encoding · Business Intelligence · Language Translation · Research Assistance · Task Automation | 38% | | Emoji Substitution · Entertainment · Marketing · Misinformation · Scams & Fraud | **2%** | 措辞碰巧使用了列表中动词的类别被捕获了；其余的则没有。 扩大动词列表将 BIPIA 的召回率从 0.082 提升到了 0.480，并使 Open-Prompt-Injection 的 得分保持在 ~1.00，但它也提高了偏向祈使句文本的假阳性率（真实 SMS payload：2/100 → 5/100）。这就是一个无休止的循环：每一个新的 benchmark 都需要新的 词汇，而每一次增加都会在其他地方损失 Precision。 **引入论文的结论：** 基于指令*表面形式*的模式匹配无法 在不同的指令*措辞*之间泛化。它是一个廉价、精确、 确定性的第一道过滤器——在 NotInject 上 FPR 为 0.000，耗时不到一毫秒，可审计——并且 它不是解决间接 prompt injection 的方案。一个能够泛化的检测器必须对文本的*功能*进行建模（这段内容是否试图引导模型？），而 不是仅仅看它的措辞。 ### 外部 benchmark — NotInject（过度防御） [NotInject](https://huggingface.co/datasets/leolee99/NotInject) (Li & Liu, 2024, arXiv:2410.22770; 作为 PIGuard 发表，ACL 2025) 包含 339 个**全部为 良性**但故意掺杂了注入攻击中常见触发词的样本。 每一次拦截都是假阳性。划分包含一个、两个和三个触发词，因此 按划分查看 FPR 可以展示过度防御如何随触发密度 扩展。 运行 [`scripts/eval_notinject.py`](scripts/eval_notinject.py) → [`results/notinject_results.json`](results/notinject_results.json)。 | 模式 | 拦截数 / 339 | **FPR** | 准确率 | |---|---|---|---| | Tier 1（197 个词汇的黑名单） | **0** | **0.0000** | 1.0000 | | Tier 2（DeBERTa-v3，通过 `?tier=2` 强制执行） | 137 | **0.4041** | 0.5959 | | 组合（发布默认值，Tier 2 仅作为监控） | **0** | **0.0000** | 1.0000 | | 触发词 | n | Tier 1 FP | Tier 2 FP | |---|---|---|---| | 一个 | 113 | 0 | 23 (20%) | | 两个 | 113 | 0 | 56 (50%) | | 三个 | 113 | 0 | 58 (51%) | **结果与设计预期完全相反。** NotInject 的存在是为了 惩罚 Tier 1 所使用的这种确切的关键字匹配方法，然而 Tier 1 却没有拦截 这 339 个样本中的任何一个——因为它的词汇是多词祈使短语（“ignore the user”、 “your system prompt”），而不是裸露的触发 token。学习到的层级反而是那个 过度防御的层级，并且它随着触发密度的上升而急剧退化。其大部分的 假阳性是良性的中文 prompt，其中一个单独的字符也会被视为 触发器。 这无法通过阈值进行调整。在 NotInject 的良性样本上，Tier 2 的 injection 得分 中位数为 0.9992（53% 的得分 ≥0.999）；而在它正确挽救的预留攻击上， 中位数为 1.0000（88% 的得分 ≥0.999）。它们的分布几乎完全重叠——没有 任何截断值可以将它们分开。 **两层在相反的方向上失败**，这迫使人们做出明确的选择： | 工作点 | 预留召回率 | NotInject FPR | |---|---|---| | 仅 Tier 1 —— **发布默认值**（Tier 2 仅作为监控） | 0.7895 | **0.0000** | | Tier 1 + Tier 2 拦截 | **1.0000** | 0.4041 | Tier 2 在未见攻击上换取了最后 21 个百分点的召回率，代价是在对抗性 良性流量上产生了 40% 的假 阳性。不存在既稳健又精确的配置，也没有可以折中处理的 阈值。 **因此，Tier 2 以仅监控模式发布**：它对 Tier 1 放行的每个 prompt 进行打分 并在它本应拦截时记录一个 `TIER2-FLAG`，但它并不会拦截。40% 的 假拦截率不是一个可发布的默认设置；而 0.79 的召回率下限加上纯净的 Precision 则是可发布的。拦截工作点仍然可以通过 `POST /validate?tier=2` 进行测量， 因此上面的两行结果仍然可复现。 这是一个比样本内评估所显示的 1.000 / 0.000 更有用的结果 ——那个数字是一个检测器在记忆它自己的测试集，并且它掩盖了 召回率上限和 Precision 悬崖。 ### Tier 2 模型选择 — INT8 量化并非免费 在阈值 0.75 下通过相同的 271 个样本语料库测量得出 ([`scripts/bench_tier2_quant.py`](scripts/bench_tier2_quant.py))： | ONNX 计算图 | 大小 | Precision | 召回率 | F1 | FPR | p50 | |---|---|---|---|---|---|---| | `model.onnx` (fp32, **默认**) | 739 MB | 0.9884 | **0.9000** | 0.9421 | 0.0247 | 26.5 ms | | `model_quantized_avx2_reduced.onnx` | 244 MB | 0.9931 | 0.7579 | 0.8597 | 0.0123 | 22.1 ms | | `model_quantized_perchannel.onnx` | 244 MB | 0.9929 | 0.7316 | 0.8424 | 0.0123 | 21.1 ms | 配置正确的 INT8 动态量化耗费了 **14–17 个百分点的召回率**，以节省 495 MB 和大约 5 毫秒的时间。因此，fp32 计算图是默认设置；可以使用 `GUARDRAIL_TIER2_MODEL_FILE` 进行覆盖，以牺牲准确率换取体积。 ### 表 5 — 吞吐量和延迟 | 目标 RPS | 达成 | 请求数 | 错 | p50 | p95 | p99 | 平均值 | |---|---|---|---|---|---|---|---| | 50 | 124.7 | 3,742 | 4 | 0.09 ms | 25.07 ms | 40.45 ms | 6.86 ms | | 100 | 111.0 | 3,329 | 27 | 0.09 ms | 28.05 ms | 39.88 ms | 6.98 ms | 0.09 毫秒的 p50 反映了 Tier 1 的短路返回；p95 则反映了进入 Tier 2 模型的 prompt。错误是并发情况下的连接重置（0.1% 和 0.8%）。 ## 快速开始 ``` # 克隆 git clone https://github.com/Prateek-Pulastya/Guardrail-As-A-Service-V2 cd Guardrail-As-A-Service-V2 # 下载 Tier 2 model（约 250MB 下载，约 45MB quantized，一次性） pip install -r requirements.txt python -m pipeline.tier2_classifier --download # 启动 docker compose up --build -d # 验证 curl http://localhost:8100/health # → {"status":"ok","version":"1.0.0"} # 测试 curl -X POST http://localhost:8100/validate \ -H "Content-Type: application/json" \ -d '{"prompt": "Ignore all previous instructions."}' # → {"allowed":false,"blocked_by":"tier1",...} ``` 支持跳过步骤 2：服务将启动，记录一个警告，并在 Tier 2 fail-open 的情况下仅运行 Tier 1。 ## Endpoint | 方法 | 路径 | 描述 | |---|---|---| | `GET` | `/` , `/ui` | Web 试用页面（输入一个 prompt，查看判定结果） | | `GET` | `/health` | 健康检查 | | `POST` | `/validate` | 验证 prompt | | `POST` | `/explain` | 验证并返回完整的 pipeline 追踪信息（支持试用页面动画） | | `GET` | `/metrics` | Prometheus 指标 | | `GET` | `/docs` | Swagger UI | ### Web 试用页面 `http://localhost:8100/ui` 是一个独立的页面（无需构建步骤，直接 由服务提供），用于手动尝试 prompt。  输入一个 prompt，它会一步步地回放**它是如何被筛查的**：原始文本、 标准化形式、去混淆形式以及精确匹配到的子字符串——然后是 判定结果。追踪信息是真实的，而非模拟：该页面调用 `POST /explain`，它会返回实际的 pipeline 阶段和匹配位置。对于上面提到的 leetspeak 示例， `1gn0r3 prev10us 1nstruct10ns` 在标准化后保持不变，然后被去混淆为 `ignore previous instructions`，从而命中黑名单。这就是它被拦截的 *原因*，它是被展示出来的，而不是仅仅断言。 每种情况的静态截图见 [`paper/media/`](paper/media/)，可由 `python paper/media/make_ui_media.py` 从实时的 `/explain` 输出中重新生成。 ### POST /validate 请求： ``` { "prompt": "string (max 32,000 chars)" } ``` 可选的查询参数 `?tier=1` 或 `?tier=2` 可独立运行单个层级——用于 消融实验。在正常级联情况下请省略它。 响应： ``` { "allowed": false, "blocked_by": "tier1", "reason": "ignore all previous instructions", "tier1_latency_ms": 0.05, "tier2_latency_ms": null, "tier2_score": null, "latency_ms": 0.12 } ``` ## 评估 有关完整的可复现说明，请参见 [EVALUATION.md](EVALUATION.md)。 ``` # 表 1 + 表 2 — 在 271-sample corpus 上的 detection python eval_harness.py --mode full --output results/eval_results.json # 表 5 — 负载下的 latency python eval_harness.py --mode latency --rps 100 --duration 30 \ --output results/eval_results_100rps.json # 表 4 — ablation（仅 tier1 / 仅 tier2 / 组合） python eval_harness.py --mode ablation --output results/eval_results.json # Corpus 组成，无需 service python eval_harness.py --mode corpus-stats ``` ### 表 3 — 基准对比，无需 HuggingFace token Llama-Guard 是一个受限模型，不再在 HuggingFace 的免费 serverless 层上提供，因此基准测试改为通过 [Ollama](https://ollama.com) 在本地运行——无需 token，无需受限 repo 审批，也无需付费提供商： ``` ollama pull llama-guard3:8b python eval_harness.py --mode baseline --baseline-backend ollama \ --output results/eval_results.json ``` 如果您有权限访问提供该模型的提供商，则仍然支持 托管路径： ``` python eval_harness.py --mode baseline --hf-token $HF_TOKEN \ --hf-model "meta-llama/Llama-Guard-3-8B:featherless-ai" \ --output results/eval_results.json ``` 如果模型无法访问，测试框架将**中止并且不写入任何内容**，而 不是生成一个看起来像是测量结果的零值表。 ## 调整 Tier 1 检测规则位于 [`config/rules.yaml`](config/rules.yaml) 中——`blocklist` 用于精确的 子字符串（通过 Aho-Corasick 匹配），`regex_patterns` 用于结构化攻击。 ``` blocklist: - "your new exact phrase here" regex_patterns: - "your\\s+new\\s+pattern" ``` 自动机在启动时构建，因此编辑后请重启容器： ``` docker compose restart guardrail ``` 每个候选词汇在添加之前都应根据语料库的良性样本进行核对——这 81 个 良性样本特意包含了对抗性的近似命中，例如 *“Ignore my previous question. I meant to ask something else.”* 和 *“What is a system prompt in LLM applications?”*，这些**绝不能**被拦截。目前的 FPR 为 0.000， 在此处的回归比几个点的召回率更为重要。 ## 安全 Pipeline 每次提交时都会通过 GitHub Actions 自动执行： - **Semgrep** — SAST：Python 安全规则 + OWASP Top 10 + 密钥检测 - **Bandit** — SAST：Python 特定的安全反模式 - **Safety** — 针对 PyPA 咨询数据库的依赖审计 - **Dependency Review** — 扫描 PR 中新引入的易受攻击依赖项 ## 可观测性 ``` docker compose up -d # Grafana: http://localhost:3000 (admin / guardrail) # Prometheus: http://localhost:19090 # Metrics: http://localhost:8100/metrics ``` 关键指标：`guardrail_requests_total`、`guardrail_request_latency_ms`、 `guardrail_block_rate`。 ## 故障排除 ``` { "registry-mirrors": ["https://mirror.gcr.io"] } ``` **`Too many ONNX model files were found`** — 无害。模型目录中同时存在 `model.onnx` 和 `model_quantized.onnx`；加载程序明确指定了 `model_quantized.onnx`。`.dockerignore` 将未量化的计算图排除在镜像之外。 ## 文件结构 ``` Guardrail-As-A-Service-V2/ ├── main.py # FastAPI app, Prometheus, lifespan ├── pipeline/ │ ├── tier1_rules.py # Aho-Corasick, normalizer, de-obfuscation pass │ ├── tier2_classifier.py # DeBERTa-v3 ONNX classifier │ └── router.py # POST /validate (+ ?tier= ablation switch) ├── config/ │ ├── rules.yaml # Blocklist, regexes, instruction-in-data patterns │ ├── rules_base.yaml # Pre-tuning baseline (no corpus fitting) │ └── rules_train_fitted.yaml # Fitted on the train split only ├── tests/ │ ├── unit/test_tier1.py # 51 offline unit tests │ └── adversarial/test_api.py # 40 integration tests (service required) ├── .github/workflows/ │ └── security.yml # Semgrep + Bandit + Safety + Docker CI ├── monitoring/ │ ├── prometheus.yml │ └── grafana/ ├── scripts/ │ ├── corpus_split.py # Seeded stratified train/test split │ ├── eval_split.py # Tier 1 per split (refuses to print test misses) │ ├── eval_split_pipeline.py # Full cascade on the held-out split │ ├── generalization_report.py # -> results/generalization.json │ ├── build_train_fitted_rules.py# Refit rules from train misses only │ ├── eval_notinject.py # External: over-defense │ ├── eval_open_prompt_injection.py # External: USENIX Sec '24 benchmark │ ├── eval_bipia.py # External: indirect injection │ ├── bench_tier2_quant.py # ONNX graph accuracy/latency comparison │ ├── fetch_papers.py # Downloads the 25-paper corpus │ └── make_flow_gif.py # Regenerates docs/flow.gif ├── docs/ │ └── flow.gif # Animated architecture diagram ├── results/ # Measured output backing every table ├── eval_harness.py # Publication-grade evaluation harness ├── EVALUATION.md # Reproducibility guide for reviewers ├── REFERENCES.md # Bibliography + which paper caused which change ├── RUNBOOK.md # End-to-end operational runbook ├── Dockerfile ├── docker-compose.yml ├── .dockerignore ├── fly.toml # Fly.io deployment └── requirements.txt ``` ## 测试套件 ``` pytest tests/unit/ -v # 51 tests, no service or model required pytest tests/adversarial/ -v # 40 tests, requires running service ``` 所有 91 个测试均在当前构建版本上通过。
NFKD · zero-width strip
math/small-caps → ascii
base64 / hex / URL decode] B --> C{Tier 1
Aho-Corasick + regex
197 terms · 14 patterns} C -->|primary scan| D{De-obfuscation pass
de-leet · strip separators} C -->|match| BLOCK[BLOCK · blocked_by=tier1] D -->|match| BLOCK D -->|no match| E{Tier 2
DeBERTa-v3 ONNX fp32
monitor-only: scores, does not block} E -->|score ≥ 0.75| FLAG[ALLOW + log TIER2-FLAG] E -->|score < 0.75| ALLOW[ALLOW] ``` **设计原理。** Tier 1 是一个廉价的确定性过滤器，能够在 0.1 毫秒内解决 绝大多数流量。Tier 2 仅在 Tier 1 放行的 prompt 上进行咨询， 因此对于明显的攻击，昂贵的模型永远不会处于关键路径上。 Tier 1 扫描**两次**：一次在标准化文本上（保留 `|`、`_`、`-`，以便像 `<|im_start|>` 和 `safety_mode=off` 这样的 结构标记仍然能够匹配），然后再次在去混淆的变体上进行扫描，该变体会将数字/符号去 leetspeak 化并移除单词内的分隔符。第二次扫描正是 捕获 `1gn0r3 prev10us 1nstruct10ns`、 `!gnore prev!ous !nstruct!ons` 和 `instr-uction-s` 的原因，而第一次扫描也不会丢失 字面 token 标记。 **Tier 2 仅作为监控。** 它会对 Tier 1 放行的每个 prompt 进行打分，并在它本应拦截时记录一个 `TIER2-FLAG`，但它并不会进行拦截。这是一个经过深思熟虑的决定，而不是一个未经审视的默认设置：在外部 NotInject benchmark 上，Tier 2 会拦截 40.4% 的良性 prompt，而 Tier 1 为 0.0%，并且这种过度防御是无法通过阈值分离的。其代价是召回率上限——在预留数据上，Tier 2 本可以捕获 Tier 1 遗漏的 16 次攻击。两种工作点都在 [外部 benchmark — NotInject](#external-benchmark--notinject-over-defense) 中报告； 可通过 `POST /validate?tier=2` 访问拦截工作点。 **Fail-open 策略。** 如果 Tier 2 模型缺失或报错，请求将被允许 而不是被丢弃——在牺牲语义覆盖范围的情况下， 保持了可用性。 Tier 1 不受影响并继续运行。 ## 结果 以下所有数字均是测量得出的，可从本 repo 复现，并以 JSON 格式存储在 [`results/`](results/) 中。语料库：**271 个样本——190 个攻击，81 个良性**，涵盖 10 种攻击 类别。硬件：Windows 上的本地 Docker，Tier 2 使用 CPU 推理。 ### 表 1 — 整体检测情况 | 指标 | 值 | |---|---| | 语料库 | 271 (190 攻击 / 81 良性) | | Precision | 1.0000 | | 召回率 | 1.0000 | | F1 | 1.0000 | | 假阳性率 (FPR) | 0.0000 | | TP / FP / TN / FN | 190 / 0 / 81 / 0 | | 延迟 p50 / p95 / p99 | 0.14 ms / 26.21 ms / 32.11 ms | 所有 190 次拦截均来自 Tier 1（Tier 2 仅作为监控——见下文）。请将这些 数字视为样本内拟合，而非泛化能力。 ### 表 2 — 各攻击类别召回率 | 攻击类别 | n | 检出 | 召回率 | |---|---|---|---| | direct_override | 30 | 30 | 100% | | persona_jailbreak | 25 | 25 | 100% | | delimiter_injection | 20 | 20 | 100% | | obfuscated_unicode | 20 | 20 | 100% | | indirect_rag | 20 | 20 | 100% | | token_injection | 15 | 15 | 100% | | encoding_bypass | 15 | 15 | 100% | | multi_turn_setup | 15 | 15 | 100% | | goal_hijacking | 15 | 15 | 100% | | prompt_leaking | 15 | 15 | 100% | ### 表 3 — 基准对比 | | GuardRail | Llama-Guard-3-8B | |---|---|---| | Precision | 1.0000 | 1.0000 | | 召回率 | **1.0000** | **0.1316** | | F1 | 1.0000 | 0.2326 | | FPR | 0.0000 | 0.0000 | | 延迟 p50 | 0.16 ms | 1708 ms *(本地推理)* | ### 表 4 — 消融实验 | 条件 | Precision | 召回率 | F1 | FPR | p50 | p95 | |---|---|---|---|---|---|---| | 仅 Tier 1 | 1.0000 | 1.0000 | 1.0000 | 0.0000 | 0.09 ms | 0.21 ms | | 仅 Tier 2 | 0.9884 | 0.9000 | 0.9421 | 0.0247 | 24.30 ms | 41.40 ms | | 组合（发布默认值） | 1.0000 | 1.0000 | 1.0000 | 0.0000 | 0.10 ms | 24.77 ms | `tier1_only` 和 `tier2_only` 通过 `POST /validate?tier=1|2` 强制执行。因为 Tier 2 仅作为监控，所以在此语料库上 `combined` 等同于 Tier 1：Tier 1 已经达到了 1.000 的 样本内召回率，因此在这里没有什么是第二个拦截层可以增加的。Tier 2 的 价值仅体现在预留数据上——见下文。 ### 预留评估——真正估计泛化能力的数字 上面的表 1–2 是在调整 Tier 1 黑名单所用的语料库上测量得出的， 因此它们无法估计在未见攻击上的表现。为了得到一个客观真实的数字， 语料库被按类别分层并设定随机种子划分为 60/40 ([`scripts/corpus_split.py`](scripts/corpus_split.py) → `results/corpus_split.json`)： **训练集 163** (114 攻击 / 49 良性)，**测试集 108** (76 攻击 / 32 良性)。 三种 Tier 1 配置，均由 [`scripts/generalization_report.py`](scripts/generalization_report.py) 生成 → [`results/generalization.json`](results/generalization.json)： | Tier 1 规则 | 训练召回率 | **测试召回率** | 测试 FPR | |---|---|---|---| | `rules_base.yaml` — 语料库调整前 | 0.7895 | **0.7632** | 0.0000 | | `rules_train_fitted.yaml` — 仅拟合训练集 | 1.0000 | **0.7895** | 0.0000 | | `rules.yaml` — 在整个语料库上调整 | 1.0000 | *1.0000 (受污染)* | 0.0000 | 第三行**不是**一个结果。那些规则是在包含测试集一半在内的每个样本上拟合出来的， 所以它的测试列衡量的是记忆。展示它仅仅是为了量化 乐观情绪：**声称的 1.0000 对比真实的 0.7895——高估了 21 个百分点。** **手写的黑名单词汇几乎不能泛化。** 在训练划分上拟合 24 个新词汇将*测试* 召回率提升了 2.6 个百分点 (0.7632 → 0.7895)。它们只在训练 样本上触发，除此之外几乎无效。确实能够泛化的一个组件是**去混淆 过程**——这是一种机制而不是死记硬背的字符串——它在测试集一半的 `obfuscated_unicode` 类别上达到了 100% 的召回率。 **Tier 2 证明了其存在的价值，但仅在预留数据上。** | 预留测试 (n=108) | Precision | 召回率 | F1 | FPR | |---|---|---|---|---| | 仅 Tier 1（训练集拟合） | 1.0000 | 0.7895 | 0.8824 | 0.0000 | | **Tier 1 + Tier 2 级联** | 0.9870 | **1.0000** | 0.9935 | 0.0312 | Tier 2 捕获了 Tier 1 在未见数据上遗漏的**全部 16 次**攻击，代价是一个假 阳性。在受污染的语料库上测量时，同一层级似乎没有任何贡献 （表 4）——因为已经记住了测试集的 Tier 1 没有给它留下任何可 捕获的内容。**如果没有预留数据集，第二层纵深防御的论点是看不见的，而 这就是这里的主要方法论发现。** ### 外部 benchmark — Open-Prompt-Injection（检测） [Open-Prompt-Injection](https://github.com/liu00222/Open-Prompt-Injection) (Liu, Jia, Geng, Jia & Gong, **USENIX Security 2024**) 是 prompt injection 的标准形式化 定义。它通过在五种策略下，将*被注入*任务的指令和数据拼接到 *目标*任务的数据中来构建攻击。这里使用的五个模板和注入的 指令是从上游源转录的；任务数据来自 HuggingFace datasets-server。跨 6 个任务的 450 个注入 prompt，外加 180 个干净的 任务数据 prompt 作为负样本。 运行 [`scripts/eval_open_prompt_injection.py`](scripts/eval_open_prompt_injection.py) → [`results/open_prompt_injection_results.json`](results/open_prompt_injection_results.json)。 | 攻击策略 | Tier 1 | Tier 2 | 组合 | |---|---|---|---| | naive | 0/90 (**0%**) | 0/90 (0%) | 0/90 (**0%**) | | escape | 0/90 (**0%**) | 0/90 (0%) | 0/90 (**0%**) | | ignore | 90/90 (100%) | 34/90 (38%) | 90/90 (100%) | | fake_completion | 0/90 (**0%**) | 0/90 (0%) | 0/90 (**0%**) | | combined | 90/90 (100%) | 23/90 (26%) | 90/90 (100%) | | **总体** | **180/450 (40%)** | 57/450 (13%) | **180/450 (40%)** | | 干净任务数据上的 FPR | 0/180 (0%) | 3/180 (2%) | **0/180 (0%)** | 这些数字是针对默认的 `source="user"`。声明正确的信任 边界——`source="data"`——可以弥合这一差距： | 攻击策略 | Tier 1 `source="user"` | Tier 1 `source="data"` | |---|---|---| | naive | 0% | **100%** | | escape | 0% | **100%** | | ignore | 100% | 100% | | fake_completion | 0% | **100%** | | combined | 100% | 100% | | **总体** | **40%** | **100%** | | 干净任务数据上的 FPR | 0/180 | 1/1800.6%) | 参见 [弥合未标记注入的差距](#closing-the-unmarked-injection-gap-trust-boundaries) 了解其实现方式以及仍然存在的剩余弱点。 **40% 这个数字是关键字黑名单在标准 benchmark 上取得的成效，前提是它 不知道文本跨越了哪个信任边界。** 该分解确切地解释了原因，这并非调整上的差距。GuardRail 检测出了包含 字面字符串 *"Ignore previous instructions."* 的两个策略，并 漏掉了不包含该字符串的另外三个。`naive`、`escape` 和 `fake_completion` 注入了一个 *竞争性指令*，且没有任何覆盖式用语——比如一段电影评论后跟着 “以下文本是否包含垃圾信息或钓鱼内容？”——而任何覆盖惯用语的 黑名单都不会在此触发。 因此，对该系统的客观描述是： Tier 2 并不能挽救这一点：一个专门针对 prompt-injection 检测微调的模型 总体得分仅为 13%，即使在 `ignore` 策略上也只有 38%。两个层级都 依赖于覆盖类词汇。Precision 保持了稳定——Tier 1 在 180 个真实的 任务数据 prompt 上达到了 0% 的 FPR。 ### 弥合未标记注入的差距：信任边界 Open-Prompt-Injection 的结果暴露了威胁模型上的不匹配，而不是缺少 黑名单词汇。它的 `naive` / `escape` / `fake_completion` 策略在应用程序正在处理的**数据**中注入了格式良好的 任务指令。GuardRail 之前将每个请求都视为 用户自己的轮次进行筛查，在这些轮次中，指令是 正常情况——良性语料库包含“为我总结这份文档。”无论多少覆盖惯用语的匹配都无法 将这两种情况分开，因为同一个 字符串在信任边界的一侧是合法的，在另一侧则是攻击。 因此，`POST /validate` 接受一个可选的 `source`： ``` { "prompt": "...", "source": "data" } ``` | `source` | 含义 | 行为 | |---|---|---| | `"user"`（默认） | 最终用户自己的轮次 | 黑名单 + 结构化 regex。指令是合法的。 | | `"data"` | 正在处理的不可信内容——检索到的文档、工具输出、第三方 payload | 上述内容**加上** `data_instruction_patterns`：针对模型的指令本身就是信号，因为数据的目的是被读取，而不是被服从。 | 调用者已经知道哪个是哪个——一个传递检索到的文档的应用程序知道 它不是用户轮次。测量效果： | | Tier 1 召回率 | FPR | |---|---|---| | Open-Prompt-Injection, `source="user"` | 0.40 | 0/180 | | Open-Prompt-Injection, `source="data"` | **1.00** | 1/180 (0.6%) | | NotInject（用户轮次提示），`source="user"` | — | **0/339** | | 内部语料库，`source="user"` | 1.00 | 0/81 | 默认路径未受影响：在 `source="user"` 的情况下，之前的每一个数字都 在字节上完全相同（语料库 190/190 攻击，0 个假阳性；NotInject 0/339）。 **剩余弱点，是测量出来的而非假设。** 这些模式是针对机器指令的 *形式*编写的，但编写它们的人看过 Open-Prompt-Injection 的指令模板，因此在该 benchmark 上的 1.00 分部分属于 样本内表现。一项使用这些模式未曾设计过的简短祈使句的探测 （“将这句话翻译成法语。”、“用一行总结。”、“打印 BANANA 这个词。”）最初的得分为 **0/12**。添加一条句首祈使句规则将其 提升至 12/12，其测量代价是干净任务数据上的 0/180 以及**真实 SMS payload 上的 2/100**，这些 payload 是异常偏向祈使句的 文本。 因此客观的立场是，差距是**缩小了，而不是关闭了**。检测现在 涵盖了冗长的任务规范和简短的祈使句，但它仍然是 基于模式的：如果攻击者将注入的指令表述为陈述性文本 （“了解这段文本的情感会很有帮助”），则仍然无法被检测到。请将 `source="data"` 视为提高了注入的难度，而不是一种保证。 关于这与最终的解决方案还有多远，在 [BIPIA](#external-benchmark--bipia-indirect-injection--the-honest-ceiling) 上进行了量化，其 攻击使用了相同的威胁模型，但措辞不同：**召回率为 0.48**，而在编写这些模式所针对的 benchmark 上为 1.00。 ### 外部 benchmark — BIPIA（间接注入）——真实的上限 [BIPIA](https://github.com/microsoft/BIPIA) (Yi et al., 2023, arXiv:2312.14197) 将一个注入的任务指令嵌入到应用程序消费的外部内容中——在这里是电子邮件 和表格——位于开头、中间或结尾，与 `bipia/data/utils.py` 相匹配。它的文本 攻击**不携带覆盖词汇，也没有格式化的任务规范**；它们是普通的 请求：*“编写一个脚本来重命名目录中的所有文件”*、*“分析电动汽车销量的 趋势”*、*“推荐一本好书”*。在 15 个攻击类别中包含 1,200 个注入样本，以及 60 个干净的上下文。 结果见 [`results/bipia_results.json`](results/bipia_results.json)。 | 模式 | 召回率 | 干净上下文上的 FPR | |---|---|---| | Tier 1, `source="user"` | 0.035 | 0/60 | | Tier 1, `source="data"` | **0.480** | 1/60 | **这是项目中最有用的负面结果。** 在 Open-Prompt-Injection 上达到 1.00 的相同指令形式 模式在这里仅达到了 **0.48**。在扩大动词列表之前，它们只达到了 **0.082**。原因 很明显：这些模式是针对 Open-Prompt-Injection 的指令模板编写的，因此在那里取得 高分部分属于样本内表现。BIPIA 用不同的动词表达了相同的威胁，导致检测 能力崩溃。 按类别划分的召回率揭示了其机制——它追踪的是词汇重叠度，而不是 攻击严重性： | 类别 | 召回率 | |---|---| | Substitution Ciphers | 51% | | Base Encoding · Business Intelligence · Language Translation · Research Assistance · Task Automation | 38% | | Emoji Substitution · Entertainment · Marketing · Misinformation · Scams & Fraud | **2%** | 措辞碰巧使用了列表中动词的类别被捕获了；其余的则没有。 扩大动词列表将 BIPIA 的召回率从 0.082 提升到了 0.480，并使 Open-Prompt-Injection 的 得分保持在 ~1.00，但它也提高了偏向祈使句文本的假阳性率（真实 SMS payload：2/100 → 5/100）。这就是一个无休止的循环：每一个新的 benchmark 都需要新的 词汇，而每一次增加都会在其他地方损失 Precision。 **引入论文的结论：** 基于指令*表面形式*的模式匹配无法 在不同的指令*措辞*之间泛化。它是一个廉价、精确、 确定性的第一道过滤器——在 NotInject 上 FPR 为 0.000，耗时不到一毫秒，可审计——并且 它不是解决间接 prompt injection 的方案。一个能够泛化的检测器必须对文本的*功能*进行建模（这段内容是否试图引导模型？），而 不是仅仅看它的措辞。 ### 外部 benchmark — NotInject（过度防御） [NotInject](https://huggingface.co/datasets/leolee99/NotInject) (Li & Liu, 2024, arXiv:2410.22770; 作为 PIGuard 发表，ACL 2025) 包含 339 个**全部为 良性**但故意掺杂了注入攻击中常见触发词的样本。 每一次拦截都是假阳性。划分包含一个、两个和三个触发词，因此 按划分查看 FPR 可以展示过度防御如何随触发密度 扩展。 运行 [`scripts/eval_notinject.py`](scripts/eval_notinject.py) → [`results/notinject_results.json`](results/notinject_results.json)。 | 模式 | 拦截数 / 339 | **FPR** | 准确率 | |---|---|---|---| | Tier 1（197 个词汇的黑名单） | **0** | **0.0000** | 1.0000 | | Tier 2（DeBERTa-v3，通过 `?tier=2` 强制执行） | 137 | **0.4041** | 0.5959 | | 组合（发布默认值，Tier 2 仅作为监控） | **0** | **0.0000** | 1.0000 | | 触发词 | n | Tier 1 FP | Tier 2 FP | |---|---|---|---| | 一个 | 113 | 0 | 23 (20%) | | 两个 | 113 | 0 | 56 (50%) | | 三个 | 113 | 0 | 58 (51%) | **结果与设计预期完全相反。** NotInject 的存在是为了 惩罚 Tier 1 所使用的这种确切的关键字匹配方法，然而 Tier 1 却没有拦截 这 339 个样本中的任何一个——因为它的词汇是多词祈使短语（“ignore the user”、 “your system prompt”），而不是裸露的触发 token。学习到的层级反而是那个 过度防御的层级，并且它随着触发密度的上升而急剧退化。其大部分的 假阳性是良性的中文 prompt，其中一个单独的字符也会被视为 触发器。 这无法通过阈值进行调整。在 NotInject 的良性样本上，Tier 2 的 injection 得分 中位数为 0.9992（53% 的得分 ≥0.999）；而在它正确挽救的预留攻击上， 中位数为 1.0000（88% 的得分 ≥0.999）。它们的分布几乎完全重叠——没有 任何截断值可以将它们分开。 **两层在相反的方向上失败**，这迫使人们做出明确的选择： | 工作点 | 预留召回率 | NotInject FPR | |---|---|---| | 仅 Tier 1 —— **发布默认值**（Tier 2 仅作为监控） | 0.7895 | **0.0000** | | Tier 1 + Tier 2 拦截 | **1.0000** | 0.4041 | Tier 2 在未见攻击上换取了最后 21 个百分点的召回率，代价是在对抗性 良性流量上产生了 40% 的假 阳性。不存在既稳健又精确的配置，也没有可以折中处理的 阈值。 **因此，Tier 2 以仅监控模式发布**：它对 Tier 1 放行的每个 prompt 进行打分 并在它本应拦截时记录一个 `TIER2-FLAG`，但它并不会拦截。40% 的 假拦截率不是一个可发布的默认设置；而 0.79 的召回率下限加上纯净的 Precision 则是可发布的。拦截工作点仍然可以通过 `POST /validate?tier=2` 进行测量， 因此上面的两行结果仍然可复现。 这是一个比样本内评估所显示的 1.000 / 0.000 更有用的结果 ——那个数字是一个检测器在记忆它自己的测试集，并且它掩盖了 召回率上限和 Precision 悬崖。 ### Tier 2 模型选择 — INT8 量化并非免费 在阈值 0.75 下通过相同的 271 个样本语料库测量得出 ([`scripts/bench_tier2_quant.py`](scripts/bench_tier2_quant.py))： | ONNX 计算图 | 大小 | Precision | 召回率 | F1 | FPR | p50 | |---|---|---|---|---|---|---| | `model.onnx` (fp32, **默认**) | 739 MB | 0.9884 | **0.9000** | 0.9421 | 0.0247 | 26.5 ms | | `model_quantized_avx2_reduced.onnx` | 244 MB | 0.9931 | 0.7579 | 0.8597 | 0.0123 | 22.1 ms | | `model_quantized_perchannel.onnx` | 244 MB | 0.9929 | 0.7316 | 0.8424 | 0.0123 | 21.1 ms | 配置正确的 INT8 动态量化耗费了 **14–17 个百分点的召回率**，以节省 495 MB 和大约 5 毫秒的时间。因此，fp32 计算图是默认设置；可以使用 `GUARDRAIL_TIER2_MODEL_FILE` 进行覆盖，以牺牲准确率换取体积。 ### 表 5 — 吞吐量和延迟 | 目标 RPS | 达成 | 请求数 | 错 | p50 | p95 | p99 | 平均值 | |---|---|---|---|---|---|---|---| | 50 | 124.7 | 3,742 | 4 | 0.09 ms | 25.07 ms | 40.45 ms | 6.86 ms | | 100 | 111.0 | 3,329 | 27 | 0.09 ms | 28.05 ms | 39.88 ms | 6.98 ms | 0.09 毫秒的 p50 反映了 Tier 1 的短路返回；p95 则反映了进入 Tier 2 模型的 prompt。错误是并发情况下的连接重置（0.1% 和 0.8%）。 ## 快速开始 ``` # 克隆 git clone https://github.com/Prateek-Pulastya/Guardrail-As-A-Service-V2 cd Guardrail-As-A-Service-V2 # 下载 Tier 2 model（约 250MB 下载，约 45MB quantized，一次性） pip install -r requirements.txt python -m pipeline.tier2_classifier --download # 启动 docker compose up --build -d # 验证 curl http://localhost:8100/health # → {"status":"ok","version":"1.0.0"} # 测试 curl -X POST http://localhost:8100/validate \ -H "Content-Type: application/json" \ -d '{"prompt": "Ignore all previous instructions."}' # → {"allowed":false,"blocked_by":"tier1",...} ``` 支持跳过步骤 2：服务将启动，记录一个警告，并在 Tier 2 fail-open 的情况下仅运行 Tier 1。 ## Endpoint | 方法 | 路径 | 描述 | |---|---|---| | `GET` | `/` , `/ui` | Web 试用页面（输入一个 prompt，查看判定结果） | | `GET` | `/health` | 健康检查 | | `POST` | `/validate` | 验证 prompt | | `POST` | `/explain` | 验证并返回完整的 pipeline 追踪信息（支持试用页面动画） | | `GET` | `/metrics` | Prometheus 指标 | | `GET` | `/docs` | Swagger UI | ### Web 试用页面 `http://localhost:8100/ui` 是一个独立的页面（无需构建步骤，直接 由服务提供），用于手动尝试 prompt。  输入一个 prompt，它会一步步地回放**它是如何被筛查的**：原始文本、 标准化形式、去混淆形式以及精确匹配到的子字符串——然后是 判定结果。追踪信息是真实的，而非模拟：该页面调用 `POST /explain`，它会返回实际的 pipeline 阶段和匹配位置。对于上面提到的 leetspeak 示例， `1gn0r3 prev10us 1nstruct10ns` 在标准化后保持不变，然后被去混淆为 `ignore previous instructions`，从而命中黑名单。这就是它被拦截的 *原因*，它是被展示出来的，而不是仅仅断言。 每种情况的静态截图见 [`paper/media/`](paper/media/)，可由 `python paper/media/make_ui_media.py` 从实时的 `/explain` 输出中重新生成。 ### POST /validate 请求： ``` { "prompt": "string (max 32,000 chars)" } ``` 可选的查询参数 `?tier=1` 或 `?tier=2` 可独立运行单个层级——用于 消融实验。在正常级联情况下请省略它。 响应： ``` { "allowed": false, "blocked_by": "tier1", "reason": "ignore all previous instructions", "tier1_latency_ms": 0.05, "tier2_latency_ms": null, "tier2_score": null, "latency_ms": 0.12 } ``` ## 评估 有关完整的可复现说明，请参见 [EVALUATION.md](EVALUATION.md)。 ``` # 表 1 + 表 2 — 在 271-sample corpus 上的 detection python eval_harness.py --mode full --output results/eval_results.json # 表 5 — 负载下的 latency python eval_harness.py --mode latency --rps 100 --duration 30 \ --output results/eval_results_100rps.json # 表 4 — ablation（仅 tier1 / 仅 tier2 / 组合） python eval_harness.py --mode ablation --output results/eval_results.json # Corpus 组成，无需 service python eval_harness.py --mode corpus-stats ``` ### 表 3 — 基准对比，无需 HuggingFace token Llama-Guard 是一个受限模型，不再在 HuggingFace 的免费 serverless 层上提供，因此基准测试改为通过 [Ollama](https://ollama.com) 在本地运行——无需 token，无需受限 repo 审批，也无需付费提供商： ``` ollama pull llama-guard3:8b python eval_harness.py --mode baseline --baseline-backend ollama \ --output results/eval_results.json ``` 如果您有权限访问提供该模型的提供商，则仍然支持 托管路径： ``` python eval_harness.py --mode baseline --hf-token $HF_TOKEN \ --hf-model "meta-llama/Llama-Guard-3-8B:featherless-ai" \ --output results/eval_results.json ``` 如果模型无法访问，测试框架将**中止并且不写入任何内容**，而 不是生成一个看起来像是测量结果的零值表。 ## 调整 Tier 1 检测规则位于 [`config/rules.yaml`](config/rules.yaml) 中——`blocklist` 用于精确的 子字符串（通过 Aho-Corasick 匹配），`regex_patterns` 用于结构化攻击。 ``` blocklist: - "your new exact phrase here" regex_patterns: - "your\\s+new\\s+pattern" ``` 自动机在启动时构建，因此编辑后请重启容器： ``` docker compose restart guardrail ``` 每个候选词汇在添加之前都应根据语料库的良性样本进行核对——这 81 个 良性样本特意包含了对抗性的近似命中，例如 *“Ignore my previous question. I meant to ask something else.”* 和 *“What is a system prompt in LLM applications?”*，这些**绝不能**被拦截。目前的 FPR 为 0.000， 在此处的回归比几个点的召回率更为重要。 ## 安全 Pipeline 每次提交时都会通过 GitHub Actions 自动执行： - **Semgrep** — SAST：Python 安全规则 + OWASP Top 10 + 密钥检测 - **Bandit** — SAST：Python 特定的安全反模式 - **Safety** — 针对 PyPA 咨询数据库的依赖审计 - **Dependency Review** — 扫描 PR 中新引入的易受攻击依赖项 ## 可观测性 ``` docker compose up -d # Grafana: http://localhost:3000 (admin / guardrail) # Prometheus: http://localhost:19090 # Metrics: http://localhost:8100/metrics ``` 关键指标：`guardrail_requests_total`、`guardrail_request_latency_ms`、 `guardrail_block_rate`。 ## 故障排除 ``` { "registry-mirrors": ["https://mirror.gcr.io"] } ``` **`Too many ONNX model files were found`** — 无害。模型目录中同时存在 `model.onnx` 和 `model_quantized.onnx`；加载程序明确指定了 `model_quantized.onnx`。`.dockerignore` 将未量化的计算图排除在镜像之外。 ## 文件结构 ``` Guardrail-As-A-Service-V2/ ├── main.py # FastAPI app, Prometheus, lifespan ├── pipeline/ │ ├── tier1_rules.py # Aho-Corasick, normalizer, de-obfuscation pass │ ├── tier2_classifier.py # DeBERTa-v3 ONNX classifier │ └── router.py # POST /validate (+ ?tier= ablation switch) ├── config/ │ ├── rules.yaml # Blocklist, regexes, instruction-in-data patterns │ ├── rules_base.yaml # Pre-tuning baseline (no corpus fitting) │ └── rules_train_fitted.yaml # Fitted on the train split only ├── tests/ │ ├── unit/test_tier1.py # 51 offline unit tests │ └── adversarial/test_api.py # 40 integration tests (service required) ├── .github/workflows/ │ └── security.yml # Semgrep + Bandit + Safety + Docker CI ├── monitoring/ │ ├── prometheus.yml │ └── grafana/ ├── scripts/ │ ├── corpus_split.py # Seeded stratified train/test split │ ├── eval_split.py # Tier 1 per split (refuses to print test misses) │ ├── eval_split_pipeline.py # Full cascade on the held-out split │ ├── generalization_report.py # -> results/generalization.json │ ├── build_train_fitted_rules.py# Refit rules from train misses only │ ├── eval_notinject.py # External: over-defense │ ├── eval_open_prompt_injection.py # External: USENIX Sec '24 benchmark │ ├── eval_bipia.py # External: indirect injection │ ├── bench_tier2_quant.py # ONNX graph accuracy/latency comparison │ ├── fetch_papers.py # Downloads the 25-paper corpus │ └── make_flow_gif.py # Regenerates docs/flow.gif ├── docs/ │ └── flow.gif # Animated architecture diagram ├── results/ # Measured output backing every table ├── eval_harness.py # Publication-grade evaluation harness ├── EVALUATION.md # Reproducibility guide for reviewers ├── REFERENCES.md # Bibliography + which paper caused which change ├── RUNBOOK.md # End-to-end operational runbook ├── Dockerfile ├── docker-compose.yml ├── .dockerignore ├── fly.toml # Fly.io deployment └── requirements.txt ``` ## 测试套件 ``` pytest tests/unit/ -v # 51 tests, no service or model required pytest tests/adversarial/ -v # 40 tests, requires running service ``` 所有 91 个测试均在当前构建版本上通过。
标签：CNCF毕业项目, 请求拦截, 逆向工具