daniel-omari/llm-blue-team-guardrail

# Prompt Guardrail 一个分层防护服务，可在 prompt 到达生产环境的 LLM 之前，对其进行 injection、jailbreak 和 social-engineering 尝试的筛查。它将快速的启发式检查与托管的 LLM 判别器相结合，返回完全可解释的判定结果，并作为一个可部署的全栈应用交付（React + TypeScript 前端，FastAPI 后端，PostgreSQL，Docker，CI）。 [](https://github.com/daniel-omari/llm-blue-team-guardrail/actions/workflows/ci.yml) ## 背景 这个项目源于我在兰卡斯特大学 SCC353 安全 AI 课程作业中的防护组件部分 ([ml-security-redteaming-guardrails](https://github.com/daniel-omari/ml-security-redteaming-guardrails))， 在那里我对一个 LLM 进行了红队测试，并构建了一个单模型的 SAFE/UNSAFE 分类器来防御它。那个分类器在 notebook 中可以运行，但并不是一个你能直接运行、部署或调用的东西。Prompt Guardrail 是它的产品化版本：相同的防御理念，被重新构建为一个真正的服务，在模型之前添加了快速检测层、可解释的 API、请求日志记录和一个 UI。 简而言之，课程作业是红队（寻找破坏模型的方法）；而这个项目是蓝队（构建阻止它们的防御）。这两者应该结合在一起来看。 ## 工作原理 传入的 prompt 会经过两层处理，最廉价的优先（纵深防御）： 1. **Heuristic layer（启发式层）。** 用于已知攻击系列的已编译 regex 签名：指令覆盖（“忽略所有之前的指令”）、system-prompt 和机密提取、jailbreak 角色设定（DAN / 开发者模式）、基于紧迫感的 social engineering、输出格式劫持以及 prompt 中间的多语言 injection。这一层的运行时间远低于一毫秒，并且无需消耗 API 调用即可捕获明显的攻击。如果它发现了高置信度的签名，prompt 将被拦截，请求也会直接短路。 2. **Hosted-LLM judge（托管 LLM 判别器）。** 只有那些在 Heuristic layer 存留下来的模糊 prompt 才会被提交给一个小型托管模型，该模型将返回结构化的 SAFE/UNSAFE 判定结果，并附带置信度分数和单行原因。该判别器通过 HTTP 实现了与提供商无关的特性，并能优雅降级：在未配置 API key 的情况下，服务将仅运行启发式检查，并将决策标记为降级状态，因此无论有无凭证，演示都能保持实时可用。 每一个响应都是可解释的。它会报告最终判定结果、由哪一层做出的决定、每一层发现了什么，以及端到端的延迟： ``` { "verdict": "UNSAFE", "confidence": 0.95, "reason": "Attempts to make the model ignore its previous instructions.", "decided_by": "heuristics", "latency_ms": 0.21, "layers": [ { "name": "heuristics", "ran": true, "verdict": "UNSAFE", "findings": [ { "category": "instruction_override", "pattern": "Ignore all previous instructions", "reason": "Attempts to make the model ignore its previous instructions." } ] }, { "name": "llm_judge", "ran": false, "verdict": "SKIPPED" } ] } ``` ## API | 方法 | 路径 | 描述 | | ------ | ----------- | -------------------------------------------------- | | POST | `/classify` | 筛查单个 prompt 并返回分层判定结果 | | GET | `/history` | 最近的分类记录（需要数据库） | | GET | `/health` | 存活状态及已启用的可选功能 | 交互式 API 文档位于 `/docs` (FastAPI / OpenAPI)。 ## 快速开始 ### 使用 Docker（全栈） ``` # 可选：启用 LLM judge export LLM_API_KEY=sk-... docker compose up --build # 前端：http://localhost:8080 # API： http://localhost:8000/docs ``` ### 本地开发 后端： ``` cd backend pip install -r requirements-dev.txt uvicorn app.main:app --reload # http://localhost:8000 ``` 前端： ``` cd frontend npm install npm run dev # http://localhost:5173 (proxies /api -> :8000) ``` 配置通过环境变量进行（参见 `backend/.env.example`）。每一个外部依赖都是可选的：如果没有配置 `DATABASE_URL`，将跳过请求日志记录；如果没有配置 `LLM_API_KEY`，服务将仅运行启发式检查。 ## 测试 ``` cd backend pytest -q # unit tests for the heuristic layer + API integration tests ruff check . # lint ``` 前端在 CI 环境中会进行类型检查和构建（`npm run lint && npm run build`）。 ## 基准测试 `benchmark/run_benchmark.py` 会使用带标签的 SAFE/UNSAFE prompt 对防护机制进行评分，将攻击（UNSAFE）视为正类，并报告每个数据集划分及整体的混淆矩阵。该数据集结合了 SCC353 安全 AI 课程作业中的带标签案例，以及未用于编写启发式规则的新 prompt 的保留划分集，因此保留集的数据可以评估泛化能力。 ``` cd backend python -m benchmark.run_benchmark ``` 仅使用启发式规则的基线（无 LLM 判别器），34 个案例： | 划分 | precision | recall | F1 | false-positive rate | | ---------- | --------- | ------ | ---- | ------------------- | | coursework | 100% | 40% | 0.57 | 0% | | held-out | 100% | 75% | 0.86 | 0% | | overall | 100% | 56% | 0.71 | 0% | 快速的 Heuristic layer 被刻意设计为高 precision：它对良性 prompt 不会产生任何 false alarms，但单独使用时只能捕获公然的攻击。它遗漏的那些隐蔽的、多语言和编码的 injection 正是设计时要提交给 LLM 判别器处理的案例。设置 `LLM_API_KEY` 以对完整 pipeline 进行基准测试，预计将恢复其中的大部分 recall。 ## 技术栈 后端：Python, FastAPI, Pydantic, SQLAlchemy, PostgreSQL, httpx。 前端：React, TypeScript, Vite。 基础设施：Docker, docker-compose, GitHub Actions。 ## 路线图 - 基于 `/history` 数据的持久化分析仪表板。 - 针对每个攻击类别的可配置策略阈值。 - 调整 Heuristic layer 以提高基准测试中出现的多语言和角色扮演攻击的 recall。 - 使用公开的 jailbreak 数据集和完整 pipeline 运行来扩展基准测试。 - 速率限制和用于多租户场景的 API-key 认证层。 ## 许可证 MIT，详见 [LICENSE](LICENSE)。

标签：AI安全, AV绕过, Chat Copilot, FastAPI, React, Syscalls, 提示词注入检测, 测试用例, 混合加密, 蓝队防御, 请求拦截, 运行时操纵, 逆向工具