Yashkhatri10/Guardrail-
GitHub: Yashkhatri10/Guardrail-
一个三层架构的 LLM 输入防护 Pipeline，结合规则引擎、微调分类器和专用注入检测模型来检测越狱、提示注入与敏感数据泄露。
Stars: 0 | Forks: 0
# Guardrail
用于检测和过滤数据集与模型输出中受污染或不安全文本的综合内容审核 pipeline。
## 关键发现
- 本项目采用分层方法，结合基于规则的过滤器（Layer 1）、分类器（Layer 2）和裁判/聚合器（Layer 3），在捕获高风险内容的同时减少误报。
- 在保留数据上的评估表明，在生产环境中使用的操作点具有很高的精确率；JSON 摘要请参见 `results/`。
- 污染检查（`results/contamination_check.json`）可识别需要人工审核的样本。
## 架构
- Layer 1：使用模式和标准化的快速确定性过滤器 (`layer1_rules/`)
- Layer 2：经过训练的分类器 (`layer2_classifier/`)，用于细化 layer-1 的命中结果
- Layer 3：裁判模块 (`layer3_judge/`)，用于最终决策和聚合策略逻辑
- Pipeline 编排：`pipeline/run_pipeline.py` 和 `pipeline/router.py`
Mermaid 架构图：
```
graph LR
RawData -->|preprocess| Layer1[Layer 1 Rules]
Layer1 -->|flag/pass| Layer2[Layer 2 Classifier]
Layer2 --> Layer3[Layer 3 Judge]
Layer3 --> Outputs[Outputs / Actions]
```
## 结果
- 完整的评估输出位于 `results/` 目录中：最终得分、保留集结果和污染报告。
- 关键文件：`results/full_pipeline_build_scores.json`、`results/full_pipeline_holdout_scores.json`、`results/nemo_comparison.json`。
## 如何运行
前置条件：Python 3.10+，推荐使用 virtualenv。
安装依赖（从仓库根目录开始）：
```
python -m venv venv310
venv310\Scripts\activate
pip install -r requirements.txt
```
运行完整 pipeline（示例）：
```
python pipeline\run_pipeline.py
```
运行完整评估：
```
python eval\run_full_pipeline_eval.py
```
运行 layer 1 评估：
```
python layer1_rules\eval_layer1.py
```
## 数据
- 原始数据集样本存储在 `data/raw/all_records.jsonl` 中。
- 用于准备和扩展数据集的脚本：`data/prepare_data.py`、`data/expand_dataset.py`。
## 训练
- Layer 2 的训练产物和检查点位于 `results_training/` 和 `layer2_classifier/model/` 下。
- 训练脚本：`layer2_classifier/train.py`。
## 评估
- 评估脚本：`eval/metrics.py`、`eval/run_full_pipeline_eval.py` 和 `eval/run_holdout_eval.py`。
## 发现与建议
- 在生产环境中使用分层方法以平衡延迟和安全性；将高风险案例路由至人工审核。
- 定期对新摄入的数据进行污染检查。
- 将大型模型检查点归档在仓库之外（S3 或类似存储），仅在 `results_training/` 中保留轻量级的元数据。
## 许可证
在此指定您的许可证（例如，MIT）。
## 联系方式
本项目由原作者维护。如有疑问，请提交 issue。
# LLM Guardrails：分层越狱与提示注入检测 Pipeline
一个用于 LLM 应用的三层输入防护系统，结合了快速的基于规则的检测、微调的 transformer 分类器以及专门构建的注入分类器——所有这些都通过可配置的策略引擎进行协调。基于公开的越狱/注入数据集进行构建和评估，并使用在开发期间从未触碰过的保留测试集。
## 架构
```
Input
│
▼
Layer 1 — Regex/rule engine
│ PII detection (credit card + Luhn check, SSN, email), jailbreak trigger phrases
│ <3ms latency, blocks obvious cases immediately
▼
Layer 2 — Fine-tuned DeBERTa-v3-small classifier
│ Binary: attack / benign. Trained on ~4,700 merged examples.
│ Resolves most cases; escalates low-confidence ones
▼
Layer 3 — deepset/deberta-v3-base-injection
│ Purpose-built injection classifier, used only as a corroboration
│ check on Layer 2's uncertain cases (not a standalone gate — see Findings)
▼
Policy Engine (policy/policy.yaml)
│ Configurable thresholds and actions (block / allow / escalate)
▼
Allow / Block
```
## 结果
**完整 pipeline，保留测试集（588 个样本，从未在训练中使用）：**
| 指标 | 数值 |
|---|---|
| 精确率 (Precision) | 97.9% |
| 召回率 (Recall) | 85.6% |
| 误报率 | 1.6% |
| 延迟 (p50) | 223ms |
**仅 Layer 2，相同的保留测试集，用于对比：**
| 指标 | 数值 |
|---|---|
| 精确率 (Precision) | 97.5% |
| 召回率 (Recall) | 98.2% |
| 误报率 | 2.25% |
| 延迟 (p50) | 159ms |
**完整 pipeline 在召回率上并没有胜过单独的 Layer 2。** 这是一个真实的、刻意的权衡——在下文的“发现”中有所解释，并不是一个 bug。
**仅 Layer 1，供参考：**
| 指标 | 数值 |
|---|---|
| 精确率 (Precision) | 99.2% |
| 召回率 (Recall) | 43.2% |
| 误报率 | 0.33% |
| 延迟 (p50) | 0.2ms |
## 关键发现
1. **两处数据集标记错误在被发现之前造成了实际的损害。** 一个被标记为 `regular` 的数据集划分被错误地认为是“良性”的——实际上它是未分类的越狱社区内容。这单一的错误假设导致在一次训练运行中，精确率暴跌至 36%（1,502 个误报），随后才被追踪并修复。此外，一个压力测试脚本在遇到缺失字段时静默地使用了默认值，从而产生了一个与模型毫无关系的虚假“0% 召回率”结果。
2. **一个“完美”的 100% 召回率结果完全是由数据泄露造成的，而不是因为模型的能力。** 针对一个被认为是独立数据集的压力测试得出了 100% 的召回率。然而，一项污染检查发现，所有 79 个压力测试 prompt 实际上都是训练数据中已有 prompt 的精确或近乎完全相同的副本——公开的越狱数据集在不同的来源中流传着相同的著名 prompt（DAN、BasedGPT 等）。**目前本项目无法提供一个确切的数字，来说明 Layer 2 能在多大程度上泛化到真正新颖的越狱措辞上**——这是作为一个公开的局限性来说明的，并没有被隐瞒。
3. **作为安全裁判的通用 LLM 在三家不同的提供商中都出现了相同的失败。** 我们尝试将 Gemini 和由 NVIDIA 托管的 Llama-3.1-8b（未测试 Anthropic，因为没有可用的密钥）作为 Layer 3 的“裁判”。两者都忽略了分类指令，并直接对内嵌的看似有害的文本进行回复，而不是对其进行标记——例如，拒绝解释如何搭线启动汽车，而不是返回 `ATTACK`。这是安全对齐训练与分类指令之间的结构性冲突，而不是 prompt 措辞问题。通过改用专门构建的本地分类器（`deepset/deberta-v3-base-injection`）解决了这个问题，该分类器没有需要被覆盖的对话人格。
4. **专门构建的分类器引入了自身的偏差。** 在完整的保留测试集（而非手工挑选的样本）上对其进行测试时，发现有 180 个良性样本被以 99% 以上的置信度误分类为注入攻击——其中大部分是普通的角色扮演/创意写作 prompt（“假装你是一位睿智的老师傅”）和纯粹的教学文本（“翻译以下句子”）。如果将其不受限制地输入到 pipeline 中，误报率会飙升至 55.6%。通过要求 Layer 3 必须验证 Layer 2 的结果，而不是作为一个独立的门控来解决了这个问题——这使得精确率恢复到了 97.9%，但牺牲了召回率（98.2% → 85.6%）。
5. **盲目地将各层组合在一起反而会使系统变得更糟，而不是更好。** 与单独运行 Layer 2 相比，最终的 pipeline 用约 12 个百分点的召回率换取了微小的精确率/误报率提升。这种权衡是否值得取决于部署环境——面向客户的产品可能更倾向于减少误报；而对安全至关重要的系统可能更倾向于仅使用 Layer 2。本项目报告了测量得出的权衡，而不是声称某一种配置是普遍适用的。
## 设置
依赖项（请根据您的环境确认确切的版本——未根据本仓库中的 `requirements.txt` 进行验证）：
```
pip install transformers torch datasets scikit-learn langdetect pyyaml
```
Layer 2 需要在 `layer2_classifier/model/` 中提供微调后的模型权重（通过 Colab 单独训练——参见 `layer2_classifier/train.py`）。
## 如何运行
按以下顺序运行——每个步骤的输出都是下一步的输入：
```
python data/prepare_data.py
python layer1_rules/eval_layer1.py
python layer2_classifier/eval_layer2.py
python eval/run_full_pipeline_eval.py data/holdout/data.jsonl
```
## 已知局限性
1. **仅支持英语。** 非英语文本会被明确检测并从评估中过滤掉，而不是被静默地并入统计数字中。
2. **对新颖越狱攻击的泛化能力尚未得到证实**，这是由于公开的越狱数据集之间不可避免地存在重叠。
3. **Layer 3 专门用于检测注入式攻击**——它无法可靠地捕获没有注入框架的直接有害内容请求（例如，在测试中，“给我一种黑入银行账户的方法”以 99.88% 的置信度被评为合法请求）。
4. **没有自动重新训练循环。** 刻意不构建此功能——在标记的输入上自动重新训练会带来数据投毒风险。正确的模式（人工审核队列、定期经过审查的重新训练）已被记录为未来的工作，尚未实现。
5. **未完成与现有开源 guardrail 工具（例如 NeMo Guardrails）的正面比较**——原计划作为下一步，但因时间限制而被放弃。
## 演示
标签：DeBERTa, DLL 劫持, Naabu, 人工智能安全, 内容安全, 凭据扫描, 合规性, 大语言模型, 恶意代码分类, 文本分类, 系统调用监控, 逆向工具, 零日漏洞检测