juanmmm21/llm-guardrails-shield
GitHub: juanmmm21/llm-guardrails-shield
一款基于正则表达式和启发式规则的大模型双向安全防护模块，拦截注入攻击、敏感信息泄露及 RAG 幻觉输出。
Stars: 0 | Forks: 0
# LLM Guardrails Shield
模块化的双向防火墙（Guardrails），旨在拦截、评估和缓解与语言模型（LLM）交互时的操作风险，涵盖输入端（用户 Prompts）和输出端（模型生成内容）。
该系统确保遵守隐私政策，防止旨在绕过指令的网络攻击（Jailbreaks），并在检索增强生成（RAG）架构中确保 LLM 返回信息的真实性，阻止幻觉和意外的机密泄露。
## 双向评估架构
该防火墙通过两个独立的自动检查层，在数据 pipeline 中进行同步操作。
```
flowchart TD
RawPrompt[Prompt del Usuario] --> InputShield[Input Safeguards]
subgraph InputShield [Guardrail de Entrada]
direction TB
InjectionCheck{¿Prompt Injection / Jailbreak?} -->|Si| BlockInput[Bloquear Entrada]
InjectionCheck -->|No| ToxicityCheck{¿Lenguaje Ofensivo?}
ToxicityCheck -->|Si| BlockInput
ToxicityCheck -->|No| PIIRedact[PII Redactor - Emails & Telefonos]
PIIRedact --> CleanPrompt[Prompt Anonimizado y Seguro]
end
CleanPrompt --> LLM[Procesamiento del LLM]
LLM --> RawOutput[Texto Generado]
RawOutput --> OutputShield[Output Safeguards]
subgraph OutputShield [Guardrail de Salida]
direction TB
SecretCheck{¿Fuga de API Keys / Credenciales?} -->|Si| BlockOutput[Bloquear Salida]
SecretCheck -->|No| RAGCheck{¿Tiene Contexto RAG?}
RAGCheck -->|No| ReturnSafe[Retornar Respuesta]
RAGCheck -->|Si| FactCheck{¿Similitud Factica >= 15%?}
FactCheck -->|No| BlockOutput
FactCheck -->|Si| ReturnSafe
end
BlockInput --> ErrorResponse[Retornar Mensaje de Seguridad]
BlockOutput --> ErrorResponse
```
### 1. 输入护栏（Input Safeguards）
在将查询发送给 LLM 或路由器之前，prompt 会通过以下启发式过滤器进行分析：
* **Prompt Injection 和 Jailbreaks 检测：** 使用编译好的正则表达式模式扫描文本，寻找经典攻击特征、系统 prompt 的覆盖行为（例如：`"ignore all previous instructions"`）、DAN 模式的调用（`"DAN mode"`）或直接覆盖系统 prompt 的命令 `[system: override]`。
* **冒犯性语言过滤器：** 在西班牙语可定制有害词汇列表中，查找词边界级别的显式匹配（`\b{termino}\b`），防止在对话界面中出现滥用行为。
* **个人身份信息（PII）脱敏：** 通过将敏感数据替换为占位符（`[EMAIL]` 和 `[PHONE]`）进行匿名化处理，以避免数据意外暴露给外部 API。
* *Emails Regex:* `\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,7}\b`
* *Telefonos Regex:* `\b(?:\+?\d{1,3}[-.\s]?)?\(?\d{2,3}\)?[-.\s]?\d{3}[-.\s]?\d{3,4}\b`（旨在捕获带或不带国际区号的西班牙语电话格式，以及空格或连字符间隔）。
### 2. 输出护栏（Output Safeguards）
一旦模型返回响应，在将其提供给客户端之前，会经过严格的安全控制：
* **防止机密泄露（Secret Leakage Block）：** 识别安全表达式，如 OpenAI 身份验证 token（`sk-...`）、Google 控制台凭据（`AIzaSy...`）或配置变量存储的通用模式（`password=...`、`apikey=...`）。如果发现匹配项，将取消传递以避免基础设施遭到破坏。
* **幻觉与事实一致性控制（Fact-Checking RAG）：** 验证响应与作为检索上下文的文档之间的一致性。
1. 分别从生成内容（$V_{\text{gen}}$）和提供的 RAG 上下文（$V_{\text{ctx}}$）中提取长度大于等于 4 个字符的唯一词集。
2. 计算事实一致性指数：
$$R = \frac{|V_{\text{gen}} \cap V_{\text{ctx}}|}{|V_{\text{gen}}|}$$
3. 如果 $R < 0.15$（即响应中不到 15% 的概念有 RAG 信息源支持），则判定模型产生了幻觉或引入了虚假数据，并立即拦截输出。
## 与生态系统的连接
此防护盾在整个生态系统中的横向集成方式如下：
1. **hybrid-search-retrieval-pipeline：** 提供事实上下文（从 NanoVectorDB 和 BM25 检索到的文档），为输出验证器提供支持并检查幻觉率。
2. **orchestra-agents / secure-tool-runtime：** 来自 agents 的输入 prompts 以及控制台中工具执行返回的结果，事先都会通过此过滤器，以确保在 ReAct 循环中不存在提权尝试或冒犯性内容。
## 项目结构
* `shield.py`：实现了 `LLMGuardrailsShield` 类，包含 PII、注入、毒性和事实核查方法。
* `test_shield.py`：单元测试套件，在极端情况（隐蔽注入、复杂的电话号码、受控幻觉以及 sk-keys 泄露）下全面验证其有效性。
* `example.py`：交互式演示脚本，运行冒犯性测试流程、RAG 注入和泄露测试，直观展示输入内容、输出内容以及防火墙介入拦截的详细原因。
## 安装与使用
### 1. 激活本地环境并安装依赖
由于该模块使用原生正则表达式和轻量级的验证结构，因此不需要硬件加速：
```
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```
### 2. 运行自动化安全测试
该测试套件验证了 PII 过滤、注入和事实一致性策略：
```
.venv/bin/python -m unittest test_shield.py
```
### 3. 运行防火墙演示
```
.venv/bin/python example.py
```
该脚本实时模拟攻击和真实场景，演示了防火墙如何在推理前净化 prompt，并在检测到暴露的机密或 RAG 幻觉时限制响应的返回。
标签：DLL 劫持, StruQ, 大语言模型, 安全网关, 插件系统, 网络安全, 逆向工具, 隐私保护