kowshalyagp/PromptShield-AI-Security-Gateway
GitHub: kowshalyagp/PromptShield-AI-Security-Gateway
PromptShield 是一个部署在客户端与 LLM 之间的生产级反向代理安全网关，通过多引擎检测管线实时拦截 prompt 注入与越狱攻击，并提供审计日志、RBAC 权限控制和自动化红队测试能力。
Stars: 0 | Forks: 0
# PromptShield：大型语言模型 AI 安全网关
[](https://www.python.org/)
[](https://react.dev/)
[](https://fastapi.tiangolo.com/)
[](LICENSE)
**PromptShield** 是一个生产级、高性能的 AI 安全网关，旨在保护大型语言模型 (LLM) 免受现实世界中的对抗性攻击。作为反向代理部署在您的客户端和上游 LLM（例如 Google Gemini）之间，PromptShield 会执行实时检查、威胁评分、速率限制和深度审计日志记录，以确保安全、合规的 AI 交互。
## 目录
1. [项目概述与问题陈述](#project-overview--problem-statement)
2. [核心目标](#key-objectives)
3. [核心功能](#core-features)
4. [系统架构](#system-architecture)
5. [技术栈](#technology-stack)
6. [安装与本地设置](#installation--local-setup)
7. [环境变量](#environment-variables)
8. [Docker 部署指南](#docker-deployment-guide)
9. [REST API 文档](#rest-api-documentation)
10. [红队安全评估](#red-team-security-evaluation)
11. [安全配置与 RBAC](#security-configurations--rbac)
12. [Prompt 评估工作流演练](#walkthrough-of-prompt-evaluation-workflow)
13. [未来增强功能](#future-enhancements)
14. [许可证与贡献者](#license--contributors)
## 项目概述与问题陈述
随着大型语言模型 (LLM) 日益融入企业应用，它们成为新型安全威胁的主要目标。传统的 Web 应用防火墙 (WAF) 无法识别语义攻击。PromptShield 通过拦截和评估传入的 prompt 来填补这一空白，主要针对：
* **Prompt 注入：** 试图劫持模型的核心指令集。
* **越狱：** 旨在绕过安全防护措施的混淆策略。
* **系统 Prompt 提取与 Prompt 泄露：** 通过社会工程学窃取私密的开发者指南。
* **有害内容：** 生成有毒材料、恶意软件或非法化合物的指令。
* **数据渗出：** 恶意尝试将系统 token、环境配置或数据库记录 smuggling 到网络边界之外。
## 核心目标
1. **语义安全：** 使用多层启发式、regex 和基于模型的分类器来拦截并对语义威胁进行评分。
2. **速率限制：** 保护上游 LLM endpoint 免受拒绝服务 和 API 配额滥用。
3. **全面审计：** 记录每个请求的原始输入、输出、威胁风险指标和内部网关决策，以满足法律和取证合规要求。
4. **管理可观测性：** 为安全官员提供高保真控制仪表板，具备交互式分析、配置开关和用户角色管理功能。
5. **对抗性模拟：** 维护一个持续自动化的红队评估套件，对网关安全策略进行基准测试。
## 核心功能
* **多引擎防御 pipeline：**
* *规则评估器：* 对已知的注入特征进行快速的 regex 检查。
* *语义评估器：* 与已知越狱数据库进行向量相似度比较。
* *模型分类器：* 使用自定义安全启发式方法进行高级威胁类别识别。
* *响应护栏：* 对下游模型输出应用实时的屏蔽和过滤规则。
* **细粒度身份验证与 RBAC：** 安全的基于 token 的 JWT 身份验证，将管理权限（`Admin`）与标准查询用户（`User`）区分开来。
* **交互式分析控制台：** 使用 Recharts 可视化威胁分布、随时间变化的流量和延迟指标。
* **动态设置调整：** 直接在 UI 中实时调整速率限制、风险阈值和日志详细级别，无需重启服务器。
* **自动化红队模拟器：** 持续的安全基准测试工具，涵盖 9 个不同威胁类别的 200 个对抗性测试用例，并支持 CSV/JSON 导出。
## 系统架构
以下框图概述了通过 PromptShield 的数据流：
```
graph TD
User[Client Application] -->|1. Post Prompt| Gateway[API Gateway Controller]
Gateway -->|2. Check Limit| RateLimiter[InMemoryRateLimiter]
RateLimiter -->|3. Evaluate Safety| SecurityEngine[SecurityEngine]
subgraph SecurityEngine Pipeline
SecurityEngine --> Rules[RulesEvaluator regex]
SecurityEngine --> Semantic[SemanticEvaluator similarity]
SecurityEngine --> Classifier[ModelClassifier heuristics]
end
Rules --> Score[Calculate Composite Score]
Semantic --> Score
Classifier --> Score
Score -->|4. Decision: Blocked| ReturnError[Return Blocked Response + Log]
Score -->|4. Decision: Allowed| Gemini[Upstream Gemini API]
Gemini -->|5. Verify Output| ResponseGuard[ResponseGuardrail]
ResponseGuard -->|6. Save Audit Log| Audit[AuditLogger SQLite]
ResponseGuard -->|7. Return Response| User
```
## 技术栈
### 后端
* **框架：** FastAPI (Python 3.11+)
* **ASGI Server：** Uvicorn
* **数据库 ORM：** SQLAlchemy (Asyncio)
* **驱动：** aiosqlite (SQLite)
* **安全与 JWT：** Passlib (Bcrypt), PyJWT
### 前端
* **构建工具 / 框架：** Vite + React 18
* **样式：** CSS + Tailwind CSS
* **图表与可视化：** Recharts
* **图标：** Lucide React
## 安装与本地设置
### 后端设置
1. 导航至 backend 目录：
cd backend
2. 创建并激活虚拟环境：
python -m venv venv
# 在 Windows 上：
.\venv\Scripts\activate
# 在 Linux/macOS 上：
source venv/bin/activate
3. 安装依赖项：
pip install -r requirements.txt
4. 从模板创建您的 `.env` 配置文件：
cp .env.example .env
5. 初始化并启动后端开发服务器：
python -m uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload
### 前端设置
1. 导航至 frontend 目录：
cd ../frontend
2. 安装 npm 包：
npm install
3. 启动 Vite React 开发服务器：
npm run dev
4. 通过 `http://localhost:5173` 访问 Web 仪表板。
5. 使用默认管理员账户登录：
* **用户名：** `admin`
* **密码：** `adminpassword123`
## 环境变量
PromptShield 使用以下变量进行配置：
| 变量 | 描述 | 默认值 |
| :--- | :--- | :--- |
| `PROJECT_NAME` | 应用程序的显示名称 | `"PromptShield Gateway"` |
| `SECRET_KEY` | JWT 签名密钥 | `"supersecretdevelopmentkeythatisthirtytwobyteslong"` |
| `DATABASE_URL` | SQLite 数据库连接 URI | `"sqlite+aiosqlite:///./promptshield.db"` |
| `GEMINI_API_KEY` | 上游 Google Gemini API key | `""` |
| `RATE_LIMIT_WINDOW_SECONDS` | 速率限制的时间窗口（以秒为单位） | `60` |
| `RATE_LIMIT_MAX_REQUESTS` | 每个 IP 在每个时间窗口内允许的请求数 | `10` |
| `RISK_THRESHOLD_MALICIOUS` | 阻断 prompt 的最低分数 (0-100) | `70` |
| `RISK_THRESHOLD_SUSPICIOUS` | 标记 prompt 的最低分数 (0-100) | `30` |
| `LOGGING_LEVEL` | 应用程序日志详细级别 | `"INFO"` |
## Docker 部署指南
### 前置条件
确保您的主机系统上已安装 [Docker](https://www.docker.com/) 和 [Docker Compose](https://docs.docker.com/compose/)。
### 构建并启动服务
1. 转到包含 `docker-compose.yml` 的根目录。
2. 在环境 shell 中配置您的外部 Gemini 密钥：
### 配置您的 Gemini API key
**Linux/macOS**
```
export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
```
**Windows PowerShell**
```
$env:GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
```
```
3. Build and launch the containers in detached mode:
```bash
docker-compose up --build -d
```
4. 验证正在运行的容器：
docker-compose ps
### 服务映射
* **Web 控制台仪表板：** `http://localhost:80`（容器 nginx 映射到主机 80 端口）
* **FastAPI API Swagger 文档：** `http://localhost:8000/docs`
* **SQLite 卷数据：** 作为命名卷挂载在 `backend_db` 中并映射至 `/app/db_data`。
## REST API 文档
详细的 REST API 路由说明：
### 网关 Endpoint (`tags: ["AI Security Gateway"]`)
* `POST /api/v1/gateway/chat` - 提交 prompt 以进行网关验证和 Gemini 评估。
### 身份验证与用户 RBAC (`tags: ["Authentication & Admin RBAC"]`)
* `POST /api/v1/auth/login` - 验证用户凭据并签发 JWT token。
* `GET /api/v1/auth/me` - 获取当前活动用户的个人资料详情。
* `GET /api/v1/auth/users` - 列出所有已注册的用户（仅限管理员）。
* `POST /api/v1/auth/users` - 注册新用户账号（仅限管理员）。
* `PUT /api/v1/auth/users/{user_id}/role` - 更改用户角色（仅限管理员）。
* `PUT /api/v1/auth/users/{user_id}/disable` - 激活/停用用户账号（仅限管理员）。
### 红队套件 (`tags: ["Red-Teaming Suite"]`)
* `POST /api/v1/redteam/run` - 触发红队评估套件（仅限管理员）。
* `GET /api/v1/redteam/reports` - 列出所有历史评估运行记录（仅限管理员）。
* `GET /api/v1/redteam/reports/{report_id}` - 获取特定运行的详细测试日志（仅限管理员）。
* `GET /api/v1/redteam/reports/{report_id}/export` - 将运行数据导出为 CSV/JSON 格式（仅限管理员）。
### 威胁日志与系统配置
* `GET /api/v1/logs` - 查询、过滤和分页安全审计日志（仅限管理员）。
* `GET /api/v1/settings` - 查询动态配置（仅限管理员）。
* `PUT /api/v1/settings` - 更新速率限制、阈值和日志级别（仅限管理员）。
## 红队安全评估
该框架包含一个内置的自动化红队系统。测试运行程序会遍历 `redteam_dataset.json` 中的对抗性输入，并评估 `SecurityEngine` 的防御响应。
### 自动运行测试
您可以使用 pytest 执行所有系统测试套件：
```
cd backend
$env:PYTHONPATH="."
.\venv\Scripts\pytest
```
## 未来增强功能
1. **上游负载均衡：** 在多个 LLM 后端（Gemini、OpenAI、Anthropic）之间路由流量。
2. **分布式速率限制：** 从内存映射过渡到 Redis，以支持无状态集群。
3. **Active Directory / OAuth 集成：** 支持标准 OAuth2 和单点登录 (SSO) 协议。
4. **高级向量数据库：** 集成 PGVector 或 Milvus，以支持数百万个语义越狱模板。
## 许可证与贡献者
* **开发者：** Kowsalya（毕业设计项目）
* **许可证：** MIT License。有关更多详细信息，请参阅 [LICENSE](LICENSE)。
标签：AI安全网关, AV绕过, DLL 劫持, FastAPI, Python, React, Syscalls, 一键部署, 大语言模型, 提示词注入防护, 无后门, 红队评估, 自定义脚本, 请求拦截, 逆向工具