alihamzazaka/prompt-injection-guardrail

# 提示注入 / 越狱 Guardrail 分类器 ## 客观定位 这个领域**并非空白**。目前已经存在强大的开源基线 —— Meta 的 **Llama Prompt Guard 2** (22M/86M)、**ProtectAI / PIGuard**、**Deepset**、**NVIDIA NeMo Guard**、**Vijil**，以及特定于 Agent 的工具如 **StackOne Defender**。因此，我们的目标**不是**“首个小型开源 Guardrail”。一个可信且站得住脚的结果应当是**在特定指标上取得可量化的胜利**：在匹配指定基线的攻击召回率的同时，大幅降低**在无害且与攻击相近的查询上的假阳性率**（即 InjecGuard / NotInject 的过度防御问题），并且/或者在**间接/Agent 注入**检测上取得显著改善。 ## 核心目标（指标 + 约束） 胜利的定义非常明确：**相同或更高的攻击召回率，并且大幅降低假阳性率**（或者在间接/Agent 检测上有显著提升），且必须明确说明具体的衡量指标。参见 [docs/05-evaluation-metrics.md](docs/05-evaluation-metrics.md)。 **目前测得的数据**（参见 [reports/results.md](reports/results.md)）：在攻击召回率为 0.948、F1 为 0.939、AUROC 为 0.994 的情况下，NotInject 的假阳性率（FPR）为 **0.354**，而 ProtectAI v2 为 0.428，Deepset 为 0.705。*Prompt Guard 2 的数据尚在等待受限代码库的访问权限。* 推理服务采用的是 **fp32 ONNX**（在 CPU 上单条数据处理约为 19 毫秒，批处理约为 11 毫秒/条；在 GPU 上低于 1 毫秒）—— 动态 INT8 量化在 DeBERTa-v3 上被测出存在问题因此被移除（[reports/onnx_export.md](reports/onnx_export.md)）；要实现小于 10 毫秒的单条数据 CPU 推理路径，将需要使用 static-QDQ/QAT 或采用其他的基础编码器。 ## 文档 完整的文档套件位于 [`docs/`](docs/)： | 文档 | 涵盖内容 | |---|---| | [docs/01-overview.md](docs/01-overview.md) | 从问题到解决方案的框架、与 SOTA 相比的客观定位、为何稀缺/具有防御性，以及单一的核心成功标准。 | | [docs/02-architecture.md](docs/02-architecture.md) | 系统架构、Mermaid 图表、数据/推理流程、部署路径以及关键设计决策。 | | [docs/03-requirements.md](docs/03-requirements.md) | 功能性与非功能性需求、范围内/范围外内容、假设、依赖项、交付物清单。 | | [docs/04-data-and-datasets.md](docs/04-data-and-datasets.md) | 数据计划：要拉取的数据集、自行整理/生成的数据、数据标注、数据划分（留出集 + NotInject）、规模目标、授权许可。 | | [docs/05-evaluation-metrics.md](docs/05-evaluation-metrics.md) | 指标定义、要击败的指定基线、“核心数据表”、评估测试工具，以及确切证明取得胜利的方式。 | | [docs/06-environment-setup.md](docs/06-environment-setup.md) | 技术栈表格、前置条件、安装步骤、硬件适配（RTX 5080 16GB）、环境配置、验证安装的冒烟测试。 | | [docs/07-build-roadmap.md](docs/07-build-roadmap.md) | 分阶段构建计划（阶段 0..4），包含目标、任务、完成标准以及逐周的里程碑表格。 | | [docs/08-risks-pitfalls.md](docs/08-risks-pitfalls.md) | 将所有常见的陷阱扩展为风险/原因/缓解措施，并提供一个核心条目风险登记表。 | | [docs/09-references.md](docs/09-references.md) | 规范中引用的所有模型、基准测试、数据集、论文和工具，并附带规范标识符。 | | [docs/10-glossary.md](docs/10-glossary.md) | 每个领域术语（过度防御、NotInject、ECE、间接注入、LoRA/QLoRA 等）的一句话定义。 | 权威源规范：[SPEC.md](SPEC.md)。 ## 技术栈（精简版） **基础编码器** DeBERTa-v3-base (184M) / mDeBERTa-v3 / ModernBERT · **微调** 🤗 Transformers `Trainer` (序列分类) · **校准** 温度缩放 / Platt 缩放 (scikit-learn)，报告 ECE · **服务** FastAPI + ONNX Runtime / CTranslate2，INT8 量化，目标 < 10 毫秒 · **打包** `pip` 包 + Docker 微服务 (`guard.score(text) -> 0..1`) · **追踪** Weights & Biases / TensorBoard · **对抗性探测** NVIDIA garak。 ## 为何具有防御性 任何人都可以微调一个分类器。但通过**经过校准的评估，在特定指标上击败指定的 SOTA** —— 并且解决过度防御问题 —— 正是极少有作品集能展现的安全 ML 严谨性。它与信息安全教学以及 Agent 工作（LangGraph / CrewAI）直接相关。它也是路线图上**计算量需求最低**的项目：一个 184M 参数的编码器微调可以轻松在 RTX 5080 (16GB) 上运行，几小时内即可完成训练，使其成为一个快速且极具参考价值的成果。 ## 仓库布局 ``` pi-guard/ ├── SPEC.md # authoritative source spec ├── README.md # this file ├── RUNBOOK.md # GPU-machine setup + Phase 0→4 exact commands ├── pyproject.toml # pip package (pi-guard) + extras + pytest config ├── requirements.txt # full train/eval env (GPU box) ├── requirements-serve.txt # lean serving env (ONNX Runtime, no torch) ├── docs/ # 01–10 design docs (architecture, data, eval, …) ├── src/pi_guard/ # the installable package (dependency-light core) │ ├── labels.py # binary taxonomy + normalize/template_hash (dedup) │ ├── metrics.py # AUROC, PR-AUC, ECE, recall/FPR/F1, latency (pure) │ ├── calibrate.py # temperature scaling from scratch + ECE (pure) │ ├── data.py # dataset registry, dedup, balance, counterfactuals, │ │ # leakage-safe split builder (HF import is lazy) │ ├── api.py # Guard: score()/classify(); ONNX & torch backends │ │ # are LAZY-imported so the core stays pure │ └── cli.py # `pi-guard score|classify|serve` ├── scripts/ # phased pipeline (GPU box) │ ├── 01_build_dataset.py # Phase 1 — assemble/balance/augment/lock splits │ ├── 00_baselines.py # Phase 0 — score named baselines on common test set │ ├── train.py # Phase 2 — fine-tune the encoder │ ├── 02_calibrate.py # Phase 2 — temperature-scale on dev (ECE before/after) │ ├── evaluate.py # Phase 3 — money table + novel-attack slice + gate │ └── export_onnx.py # Phase 4 — ONNX export + INT8 + parity + latency ├── serve/ # FastAPI microservice + lean Docker image │ ├── app.py # /v1/score, /v1/batch, /metrics, /healthz │ ├── Dockerfile # ~300 MB, model mounted at runtime │ └── docker-compose.yml └── tests/ # pure-Python pytest suite (no torch/transformers/numpy) ├── conftest.py # puts src/ on sys.path ├── test_metrics.py # AUROC & ECE math with hand-computed answers ├── test_calibrate.py # recovers a known T; ECE improves after calibration ├── test_data.py # cross-split template dedup; counterfactual labels └── test_api.py # Guard validation + classify() shape (stub backend) ``` ## 状态 / 下一步 **包和工具脚手架已完成；模型尚未训练。** 可安装的 `pi_guard` 包（指标、校准、标签/去重逻辑、数据集流水线、 可直接调用的 `Guard` API 和 CLI）、分阶段的 `scripts/`（阶段 0→4）、FastAPI + Docker 服务路径，以及**纯 Python 的 pytest 测试套件（通过，无重度依赖项）** 均已就绪。核心导入不需要 torch/transformers/onnxruntime —— 推理后端均为延迟导入 —— 因此该逻辑可以在仅配备 CPU 的笔记本电脑上进行验证。 下一步是按照 [RUNBOOK.md](RUNBOOK.md) 在 **GPU 机器 (RTX 5080)** 上运行流水线： **阶段 0 —— 基线**（在通用的留出集 + NotInject 测试集上运行 Prompt Guard 2、ProtectAI v2、 Deepset），以记录需要击败的召回率和假阳性数据，然后是阶段 1→4（数据 → 训练 + 校准 → 根据门限评估 → 导出 + 发布）。参见 [docs/07-build-roadmap.md](docs/07-build-roadmap.md)。 ### 本地（无 GPU）验证 ``` python -m pytest tests/ -q # pure-logic tests; only needs `pip install pytest` ```

标签：DeBERTa, DLL 劫持, 人工智能, 大语言模型, 安全规则引擎, 安全防护, 文本分类, 用户模式Hook绕过, 请求拦截, 逆向工具, 零日漏洞检测