## 概述
**Entropy** 是一个开源的、生产级 **LLM 安全防火墙**，位于您的应用程序和任何 LLM 提供商之间。它拦截每个请求和响应，应用多层防御管道来实时检测和阻止提示注入、越狱、数据泄露、PII 泄露和间接注入攻击。
Entropy 暴露了一个 **OpenAI 兼容的 REST API**，这意味着您可以将其指向现有应用程序，而无需更改任何客户端代码。
## 目录
- [主要功能](#key-features)
- [架构](#architecture)
- [快速开始](#quick-start)
- [配置](#configuration)
- [API 参考](#api-reference)
- [SDK 使用](#sdk-usage)
- [CLI 参考](#cli-reference)
- [检测引擎](#detection-engine)
- [测试](#testing)
- [贡献](#contributing)
- [许可证](#license)
## 主要功能
| 功能 | 详情 |
|---|---|
| 🛡️ **基于模式的检测** | 跨 8 个 OWASP 对齐威胁类别的 28+ 个手动调整的正则表达式模式 |
| 🧠 **语义分析** | ONNX 驱动的本地 ML 模型 — 无外部 API，< 5ms 开销 |
| 🔄 **多轮上下文分析** | 检测对话历史中的升级、探测和渐进式攻击 |
| 🧹 **输入清理器** | 递归解码 8 层混淆（Base64、URL、HTML、ROT13、Leetspeak、全角、十六进制、字符分割） |
| 🕵️ **间接注入检测器** | 扫描工具输出和检索的文档中的嵌入注入和不可见 Unicode |
| 🔒 **输出过滤器** | 从响应中剥离电子邮件、SSN、信用卡、API 密钥、私钥和机密信息 |
| 🔍 **输入验证** | 结构化门控 — 长度、空字节、编码、字符密度 |
| 🔑 **API 密钥认证** | bcrypt 哈希密钥管理、基于前缀的查找、主密钥引导 |
| ⚡ **速率限制** | Redis 支持的全局、每 IP 和每用户速率限制 |
| 📊 **Prometheus 指标** | 请求计数、威胁速率和延迟直方图，位于 `/metrics` |
| 🌐 **多提供商** | 按模型名称路由到 OpenAI、Anthropic、Gemini、Groq 或 OpenRouter |
| 🐳 **Docker 就绪** | 多阶段 Dockerfile，包含 Postgres + Redis compose 堆栈 |
| ☸️ **Kubernetes 就绪** | 完整的 K8s 清单：Deployment、Service、HPA、Secrets |
| 🤖 **CI/CD** | GitHub Actions 管道，包含 linting、类型检查和自动化测试 |
| 📦 **Python SDK** | 同步 + 异步客户端、流式支持、OpenAI 兼容命名空间 |
| 🖥️ **CLI** | 离线扫描、服务器管理、健康检查、密钥生成 |
## 架构
```
┌──────────────────────────────────────────────────────────┐
│ Client Application │
└───────────────────────────┬──────────────────────────────┘
│ POST /v1/chat/completions
▼
┌──────────────────────────────────────────────────────────┐
│ 🔥 ENTROPY FIREWALL │
│ │
│ ┌──────────┐ ┌──────────────┐ ┌────────────────────┐ │
│ │ Auth │→ │ Rate Limiter │→ │ Input Validator │ │
│ │ (X-API- │ │ (Redis) │ │ (length, encoding) │ │
│ │ Key) │ └──────────────┘ └─────────┬──────────┘ │
│ └──────────┘ │ │
│ ▼ │
│ ┌───────────────────────────────────────────────────┐ │
│ │ Entropy Engine │ │
│ │ │ │
│ │ ┌─────────────────┐ ┌──────────────────────────┐ │ │
│ │ │ Input Sanitizer │ │ Indirect Injection │ │ │
│ │ │ (8 decoders, │ │ Detector (tool outputs, │ │ │
│ │ │ fixed-point) │ │ HTML, invisible Unicode) │ │ │
│ │ └─────────────────┘ └──────────────────────────┘ │ │
│ │ ┌─────────────────┐ ┌──────────────────────────┐ │ │
│ │ │ Pattern Matcher │ │ Context Analyzer │ │ │
│ │ │ (28+ patterns, │ │ (multi-turn escalation, │ │ │
│ │ │ 8 categories) │ │ probing detection) │ │ │
│ │ └─────────────────┘ └──────────────────────────┘ │ │
│ │ ┌─────────────────┐ │ │
│ │ │ Semantic Analyzer│ (ONNX local model, offline) │ │
│ │ └─────────────────┘ │ │
│ └───────────────────────────┬───────────────────────┘ │
│ │ ALLOWED / BLOCKED │
│ ▼ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ LLM Provider (OpenAI · Anthropic · Gemini ···) │ │
│ └────────────────────────┬────────────────────────────┘ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Output Filter (PII · Secrets · Leaks) │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────┐ ┌─────────────────┐ │
│ │ Audit Logger │ │ Prometheus │ │
│ │ (PostgreSQL) │ │ Metrics │ │
│ └──────────────┘ └─────────────────┘ │
└──────────────────────────────────────────────────────────┘
```
## 快速开始
### 选项 1：Docker Compose（推荐）
```
git clone https://github.com/paarthbhatt/entropy-firewall.git
cd entropy-firewall
cp .env.example .env
# 编辑 .env — 设置您的 API key(s)
docker-compose up -d
curl http://localhost:8000/health
```
### 选项 2：本地使用 uv
```
git clone https://github.com/paarthbhatt/entropy-firewall.git
cd entropy-firewall
uv sync
uv run uvicorn entropy.api.app:app --reload
```
### 选项 3：pip
```
pip install -e ".[dev]"
cp .env.example .env
entropy server --port 8000
```
### 选项 4：Kubernetes
```
kubectl apply -f deployments/k8s/secrets.yaml
kubectl apply -f deployments/k8s/deployment.yaml
```
## 配置
Entropy 使用**三层配置系统**（最高优先级优先）：
1. **环境变量** — 前缀为 `ENTROPY_*`
2. **YAML 配置文件** — `config.yaml`
3. **内置默认值**
```
# 核心
ENTROPY_MASTER_API_KEY=ent-change-this-in-production
ENTROPY_DATABASE_URL=postgresql://entropy:entropy@localhost:5432/entropy
ENTROPY_REDIS_URL=redis://localhost:6379/0
# Provider keys（仅设置您使用的）
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_API_KEY=AIza...
GROQ_API_KEY=gsk_...
OPENROUTER_API_KEY=sk-or-...
```
请参阅 [`.env.example`](
标签：AI安全, AMSI绕过, Chat Copilot, CNCF毕业项目, Docker, Jailbreak检测, ONNX, OpenAI兼容API, PII保护, Python, REST API, Web安全, 个人信息泄露检测, 人工智能安全, 合规性, 威胁检测, 子域名突变, 安全防御评估, 实时检测, 对抗性攻击, 搜索引擎查询, 数据泄露防护, 无后门, 测试用例, 网络安全, 网络探测, 蓝队分析, 请求拦截, 越狱检测, 逆向工具, 间接注入攻击, 防火墙, 隐私保护, 零日漏洞检测
