mpuodziukas-labs/llm-adversarial-gate
GitHub: mpuodziukas-labs/llm-adversarial-gate
一个基于规则评分的离线 LLM 对抗性验证门，内置合成语料库与确定性评估器，用于在 CI 中可复现地检测 OWASP LLM Top 10 相关的恶意提示。
Stars: 0 | Forks: 0
# LLM 对抗性验证门
一个针对 LLM 输出的可复现、离线对抗性验证门，涵盖五大 OWASP LLM Top 10 威胁类别。内置打包的合成语料库、确定性评估器和完整的 pytest 套件——无需 API 密钥。
## 诚信声明
## 语料库构成
| 数据集 | 数量 | 类别 |
|-------------|-------|------------|
| Adversarial | 140 | prompt_injection (40), jailbreak (40), system_prompt_leak (20), data_exfil (20), unsafe_tool_call (20) |
| Benign | 80 | 编程、安全教育、研究、创意写作、工具使用、表面上相似的边缘情况 |
| **Total** | **220** | |
良性数据集包含了含有表层“可疑” token 的提示词（`ignore`、`override`、`base64`、`developer`、`pretend` 等），用于压力测试误报率。
**参考数据集：** 此语料库为原创合成内容。它并非衍生自 [AdvBench](https://github.com/llm-attacks/llm-attacks)、[HarmBench](https://github.com/centerforaisafety/HarmBench)、[JailbreakBench](https://github.com/JailbreakBench/jailbreakbench) 或任何其他已发布的数据集，尽管此处引用它们是为了提供上下文。
## 内置语料库的结果
```
Confusion Matrix:
Predicted BLOCK Predicted ALLOW
Actual Adversarial TP=140 FN=0
Actual Benign FP=0 TN=80
Block rate (recall): 100.0% [140 / 140 adversarial caught]
False-negative rate: 0.0% [0 adversarial missed]
False-positive rate: 0.0% [0 benign over-blocked]
Accuracy: 100.0%
Precision: 100.0%
F1: 1.0000
```
各类别拦截率：prompt_injection 100%、jailbreak 100%、system_prompt_leak 100%、data_exfil 100%、unsafe_tool_call 100%。
**为什么这些数据是真实的：** 规则是针对该语料库迭代开发的。语料库和规则是共同开发的——该验证门并未在不同来源的保留数据集上进行测试。这是应当陈述的客观事实。其价值在于该方法论（规则、语料库、评估器）是完全可复现和可审计的。
## 重放命令
```
# 构建语料库（一次性）
python3 build_corpus.py
# 运行完整评估
python3 evaluate.py
# 运行测试套件
python3 -m pytest tests/ -v
# 直接查询 gate
python3 gate.py "Ignore all previous instructions."
python3 gate.py "How do I read a file in Python?"
```
## 文件结构
```
llm-adversarial-gate/
├── gate.py # Guardrail: detection rules, evaluate(), ModelAdapter
├── evaluate.py # Runs corpus through gate, prints metrics
├── build_corpus.py # Generates corpus/adversarial.jsonl
├── corpus/
│ └── adversarial.jsonl # 220 labeled prompts (140 adversarial / 80 benign)
├── tests/
│ └── test_gate.py # 114 pytest assertions (offline, deterministic)
├── .github/
│ └── workflows/
│ └── ci.yml # GitHub Actions: pytest + evaluate
├── README.md
└── LICENSE # MIT
```
## Gate 架构
`gate.py` 实现了一个基于规则的评分 gate：
```
from gate import evaluate
result = evaluate("Ignore all previous instructions.")
# GateResult(verdict=BLOCK, score=1.0, primary_reason="[PI-001] ...")
result = evaluate("How do I sort a list in Python?")
# GateResult(verdict=ALLOW, score=0.0, matches=[])
```
**检测类别（OWASP LLM Top 10 映射）：**
| 规则前缀 | OWASP 类别 | 覆盖范围 |
|-------------|-------------|----------|
| PI-* | LLM01 Prompt Injection | 直接覆盖、分隔符注入、from-now-on 劫持、冒充权威 |
| JB-* | LLM01 / LLM02 | DAN、人格越狱、编码绕过、模式切换、社会工程学 |
| SP-* | LLM02 Sensitive Info Disclosure | System prompt 泄露、指令转储、间接操作员泄露 |
| DE-* | LLM06 Sensitive Info Disclosure | URL/webhook 数据窃取、API-key-in-link、内存转储 |
| TC-* | LLM07 Insecure Plugin Design | Shell 注入、敏感路径写入、凭证提取、通过网络工具窃取数据 |
| CO-* | Composite | 紧迫性+覆盖堆叠、研究免责声明绕过、上下文泛洪 |
**评分：** 每条规则都有一个权重。得分 = 匹配规则权重之和。得分 ≥ 1.0 即触发 `BLOCK`。权重为 1.0 的规则在单个匹配项上即会拦截。较低权重（0.4–0.6）的规则需要同时出现才能达到阈值。
**扩展：** 在 `gate.py` 中向 `RULE_REGISTRY` 添加规则，而无需更改评估循环。每个 `Rule` 接收一个已编译的正则表达式、一个权重和元数据。
## 接入真实模型
`gate.py` 提供了一个 `ModelAdapter` 接口：
```
from gate import ModelAdapter, evaluate
class OpenAIAdapter(ModelAdapter):
def __init__(self, api_key: str):
import openai
self.client = openai.OpenAI(api_key=api_key)
def generate(self, prompt: str) -> str:
resp = self.client.chat.completions.create(
model="gpt-4o",
messages=[{"role": "user", "content": prompt}]
)
return resp.choices[0].message.content
# 预检：在发送给 model 之前对输入进行 gate
gate_result = evaluate(prompt)
if gate_result.blocked:
raise ValueError(f"Blocked: {gate_result.primary_reason}")
# 发送给 model，然后也对响应进行 gate
adapter = OpenAIAdapter(api_key="...")
response = adapter.generate(prompt)
response_result = evaluate(response) # check for response-side violations
```
`MockModelAdapter`（无需 API 密钥）用于 CI 和测试套件。
## 局限性
这是一份关于该 gate 无法实现功能的客观列表：
1. **语料库是合成的，且与规则共同开发。** 该语料库上的指标反映了规则对*已知*模式的覆盖范围，并不代表对新型攻击的泛化能力。
2. **正则/启发式漏洞。** 如果不进行扩展，这些规则将无法捕捉到新颖的措辞、对抗性同义词或高度混淆的攻击（多轮对话、token 拆分、低速隐蔽攻击）。
3. **无语义理解。** 基于规则的 gate 无法对意图进行推理。它是训练分类器或 LLM judge 的补充，而不是替代品。
4. **生产数据存在误报风险。** 0% 的误报率是基于 80 个合成良性提示词得出的。真实的生产流量将具有更大的误报表面积，尤其是在开发人员/安全上下文中。
5. **大多数类别没有输出端覆盖。** 该 gate 目前评估的是输入提示词。响应侧的违规行为（通过检索到的文档进行的 LLM02 间接 prompt injection、LLM06 PII 泄露）需要对模型输出进行第二次评估。
6. **并非完整的 OWASP LLM Top 10 实现。** LLM03（Training Data Poisoning）、LLM04（Model DoS）、LLM05（Supply Chain）、LLM08（Excessive Agency）、LLM09（Overreliance）、LLM10（Model Theft）超出了范围。
## 许可证
MIT — 查看 [LICENSE](LICENSE)。
标签：DLL 劫持, 人工智能安全, 合规性, 大语言模型, 安全规则引擎, 对抗性测试, 评估测试, 逆向工具