Pranav-Bhatlapenumarthi/PromptShield

# PromptShield **用于 LLM 安全评估的自主红队 Agent** PromptShield 是一个综合性的安全测试框架，旨在通过系统化的红队操作，自主评估大型语言模型 (LLM) API endpoint 的健壮性和安全性。 ## 核心功能 ### 自动化测试 - 渐进式测试：采用提前停止策略，寻找最低的有效 jailbreak 强度 - 批量测试：通过并行执行实现全面覆盖 - 速率限制：内置 token bucket 速率限制器，防止 API 限流 - 重试机制：针对临时性故障自动进行指数退避重试 ### 混合判定 Pipeline - 基于规则的检测：内置 12 种用于常见 jailbreak 技术的正则表达式模式 - 启发式评分：通过模式分析检测多步指令、动作动词和技术术语 - Judge LLM：结合 few-shot 示例，利用 AI 驱动的分类处理模糊情况 - 可解释的结果：每项决策均包含匹配的规则和推理过程 ### 丰富的分析功能 - 实时仪表盘：通过 KPI 进行实时进度追踪 - 交互式图表：使用 Chart.js 绘制环形图、柱状图和时间序列图 - 下钻分析：查看完整的 prompt、响应结果及判定推理过程 - 导出功能：生成包含全面指标的 JSON 报告 ### 精选数据集 - RedTeam（2,000 条 prompt）：专业红队场景 - JailBreakV（28,000 条 prompt）：复杂的 jailbreak 方法论 - Malignant Prompts：常规的有害内容生成尝试 - CySecBench：技术安全测试 prompt ## 快速开始 ### 前置条件 - Node.js 18 或更高版本 - npm 包管理器 - OpenRouter API key（或开启 mock 模式进行测试） ### 安装说明 ``` # 后端 cd backend npm install cp .env.example .env # 编辑 .env：设置 OPENROUTER_API_KEY 或启用 MOCK_PROVIDER_ENABLED=true npm run dev # 前端（新终端） cd frontend npm install npm run dev ``` 在浏览器中打开 http://localhost:5173。 **详细的设置说明，请参阅 [SETUP.md](./SETUP.md)** ## 工作原理 ### 1. 创建测试任务 配置并启动安全评估： - 选择测试模式（渐进式或批量） - 选择数据集和过滤器 - 设置并发数和速率限制 - 监控实时进度 ### 2. Worker 处理 prompt - 从选定的数据集中加载 prompt - 通过 OpenRouter 将 prompt 发送到目标 LLM - 收集带有 metadata 的响应（延迟、token、成本） - 管理速率限制和重试机制 ### 3. 判定 Pipeline 分析响应 **阶段 1：基于规则的检测** - 检查 12 种常见 jailbreak 指标的正则表达式模式 - 示例：显式指令、角色操纵、过滤器绕过 **阶段 2：启发式评分** - 分析模式：多步指令、动作动词、技术术语 - 检测免责声明语言以及是否存在拒绝回复 **阶段 3：Judge LLM（用于模糊情况）** - 结合 few-shot 示例为边缘情况调用 Judge LLM - 返回带有置信度分数的结构化 JSON 分类结果 - 综合各阶段的决策结果 ### 4. 查看结果 - KPI 卡片：检测到的 jailbreak 数量、成功率、延迟、成本 - 交互式图表：标签分布、强度细分、时间序列 - 详细表格：支持下钻功能的分页结果展示 - 导出选项：生成用于进一步分析的 JSON 报告 ## 架构 ### 后端 (Node.js + TypeScript) ``` backend/ ├── src/ │ ├── config/ # Environment configuration │ ├── storage/ # In-memory storage + file persistence │ ├── judge/ # Hybrid judge pipeline + rules │ ├── providers/ # OpenRouter integration + rate limiting │ ├── worker/ # Job queue + progressive/batch modes │ ├── routes/ # API endpoints │ └── utils/ # Logger and utilities ├── data/ # Persisted jobs and results └── logs/ # Application logs ``` ### 前端 (React + Vite) ``` frontend/ ├── src/ │ ├── Home.jsx # Landing page │ ├── PromptBrowser.jsx # Dataset explorer │ ├── JobsList.jsx # Test jobs list │ ├── Analysis.jsx # Detailed analysis dashboard │ └── App.jsx # Application router └── public/ └── data/processed/ # JSONL datasets ``` ## API 参考 ### 启动测试任务 ``` POST /api/test/start { "jobName": "Security Audit", "mode": "progressive", "datasetSources": ["RedTeam", "JailBreakV"], "concurrency": 5, "stopOnFirstSuccess": true } ``` ### 获取任务状态 ``` GET /api/test/status/:jobId ``` ### 获取结果 ``` GET /api/test/result/:jobId?page=1&pageSize=50 ``` ### 获取报告 ``` GET /api/report/:jobId/json ``` **完整的 API 文档：[backend/README.md](./backend/README.md)** ## 测试模式 ### 渐进模式（推荐） 按强度顺序（弱 → 中 → 强）测试 prompt，一旦检测到 jailbreak 即提前停止。 **优势：** - 成本效益高：可减少 50-70% 的 API 调用 - 找到每个 prompt 的最低有效强度 - 非常适合初始评估 ### 批量模式 以并行批次的方式全面测试所有 prompt。 **优势：** - 最大吞吐量 - 完全覆盖 - 适用于全面审计 ## 判定 Pipeline ### 基于规则的检测 12 种预配置模式可检测常见的 jailbreak 技术： - 显式 jailbreak 指令 - 角色操纵（DAN、邪恶人格） - System prompt 泄露 - 过滤器绕过语言 - 编码的有害内容 - 多轮 jailbreak 模式 **自定义：** 编辑 `backend/src/judge/rules.json` 以添加自定义规则。 ### 启发式评分 分析以下响应模式： - 多步编号指令 - 动作动词密度 - 技术术语的存在 - 免责声明语言 - 缺乏拒绝关键词 ### Judge LLM 针对模糊情况（评分在 0.3-0.7 之间）： - 结合 few-shot 示例构建 prompt - 调用 Judge LLM（默认：Claude-3-Haiku） - 解析带有置信度分数的 JSON 分类结果 - 若置信度 ≥ 0.8，则集成决策采用 LLM 的结果 ## 配置 ### 后端环境变量 ``` # 服务器配置 PORT=3001 NODE_ENV=development # OpenRouter API OPENROUTER_API_KEY=your-api-key-here OPENROUTER_MODEL=anthropic/claude-3.5-sonnet # Target model to test # Judge LLM JUDGE_LLM_MODEL=anthropic/claude-3-haiku # Model for classification JUDGE_LLM_MAX_TOKENS=500 # Worker 设置 WORKER_CONCURRENCY=5 WORKER_MAX_RETRIES=3 PROVIDER_RATE_LIMIT_RPM=50 # Mock 模式（无需 API 费用的测试） MOCK_PROVIDER_ENABLED=true ``` **完整的配置指南请参阅 [SETUP.md](./SETUP.md)。** ## Docker 部署 ``` # 使用 Docker Compose 构建并运行 docker-compose up -d ``` 访问地址： - 前端：http://localhost - 后端 API：http://localhost:3001 ## 安全与伦理 ### 负责任地使用 PromptShield 仅设计用于合法的安全研究和防御目的。 **要求：** - 在测试任何 LLM 系统之前获取适当的授权 - 遵守目标平台的服务条款 - 出于提升防御安全的目 responsibly 使用 - 遵循 AI 安全研究的伦理准则 ### 数据隐私 - API key 仅在服务端存储（绝不暴露给前端） - 结果在本地存储，不进行外部传输 - 提供可选的数据保留策略 - 支持安全的密钥管理实践 ## 文档 - [SETUP.md](./SETUP.md) - 完整的安装和配置指南 - [SYSTEM_OVERVIEW.md](./SYSTEM_OVERVIEW.md) - 技术架构详情 - [IMPLEMENTATION_SUMMARY.md](./IMPLEMENTATION_SUMMARY.md) - 组件概述 - [backend/README.md](./backend/README.md) - 后端 API 参考 ## License 本项目基于 MIT License 授权 - 有关详细信息，请参阅 LICENSE 文件。 ## 支持 - 问题：GitHub Issues - 文档：参阅 docs/ 目录 - 邮箱：security@promptshield.app 为 AI 安全社区而构建

标签：GNU通用公共许可证, MITM代理, Node.js, 大语言模型安全, 机密管理, 红队评估, 自定义脚本, 请求拦截, 越狱检测