wrapsec/wrapsec

# WrapSec WrapSec 是一个生产级 AI 安全网关和执行层，用于保护与 LLM 交互的应用程序。 它通过多层检测管道检查每个提示和响应，并在任何内容到达模型之前强制执行决策——ALLOW、BLOCK 或 SANITIZE。 ## 为什么选择 WrapSec 传统输入验证无法防范 AI 特定的威胁，如提示注入、越狱尝试、数据泄露和 PII 泄露。WrapSec 在 LLM 执行前提供实时强制执行，而不是事后处理。 WrapSec 在任何请求到达 LLM 之前强制执行安全决策。被阻止的请求永远不会离开您的系统。 WrapSec 支持两种执行模式： **仅扫描** - 应用程序向 WrapSec 发送提示，接收安全决策（ALLOW / BLOCK / SANITIZE），并自行处理 LLM 转发。 **代理** - WrapSec 位于完整请求路径中，检查输入，使用加密的 API 密钥转发给 LLM 提供商，检查响应，并向应用程序返回 OpenAI 兼容的响应。输入和输出决策都会被强制执行。 ## 检测管道 该管道结合了基于规则、机器学习和可选的基于 LLM 的分析，以产生最终的安全决策。每个请求都会经过四个独立的层： ``` Input ├── InputGuard PII detection, 22+ entity types, regex-based redaction ├── RuleDetector Regex and heuristic patterns, ~1ms ├── MLDetector TF-IDF + logistic regression, 7 labels, ~5ms ├── ToxicityGuard Reads ML toxicity label directly, independent threshold ├── LLMDetector Semantic analysis, full mode only, ~100–500ms additional └── PolicyEngine BLOCK / SANITIZE / ALLOW ``` 检测风险评分：`rule×0.40 + ml×0.30 + llm×0.30` Guardrails（PII、毒性）在架构上与检测分离，独立运行。无论风险评分如何，它们都可以覆盖检测决策。Guardrail 阈值与检测阈值相互独立。 ## 安全决策 | 决策 | 含义 | |---|---| | `ALLOW` | 未检测到威胁。可以安全转发到 LLM。 | | `BLOCK` | 检测到威胁。不得转发到 LLM。 | | `SANITIZE` | 敏感内容已删除。将 `sanitized_input` 转发到 LLM，而非原始内容。 | `risk_score = 0.0` 并不意味着安全。应始终以 `decision` 作为权威判断。Guardrails 可以产生 `risk_score = 0.0` 的 `BLOCK`。 `primary_reason = SYSTEM_ERROR` 表示检测管道失败。返回的 `ALLOW` 决策不可信，不应使用。应用程序必须将此视为失败，不得将输入转发到 LLM。 ## 技术栈 | 组件 | 技术 | |---|---| | API | FastAPI, Python 3.10 | | 数据库 | PostgreSQL（SQLAlchemy async）| | 缓存 | Redis | | 控制面板 | Next.js 16, React 19 | | ML 模型 | TF-IDF + logistic regression, 基于 7 个威胁类别训练 | | 可观测性 | Prometheus, Grafana | ## 实体模型 ``` tenant └── departments ├── policy_override (independent thresholds per dept) └── applications ├── policy_override └── api_keys (sk_live_ | sk_trial_) ``` 策略解析：系统默认值 → 数据库设置 → 部门覆盖 → 应用程序覆盖。每一层深度合并——空字段从上一层继承。 ## API **仅扫描：** ``` POST /v1/ai/request ``` **代理（OpenAI 兼容）：** ``` POST /v1/chat/completions ``` 使用 `/v1/ai/request` 进行仅扫描集成。使用 `/v1/chat/completions` 进行完整代理模式——即插即用的 OpenAI 兼容替代方案。 身份验证：`x-api-key` 头用于 API 密钥，`Authorization: Bearer` 用于 JWT。如果两者都存在，API 密钥无条件优先。 完整 API 参考：`docs/api.md` ## Python SDK 和 CLI ``` pip install -e sdk/python/ wrapsec config set api_key sk_live_... wrapsec config set base_url http://your-wrapsec-host:8000 wrapsec scan "user input" wrapsec batch prompts.txt --summary wrapsec audit list --decision BLOCK ``` ``` import wrapsec client = wrapsec.Client( api_key = os.environ["WRAPSEC_API_KEY"], base_url = os.environ["WRAPSEC_BASE_URL"], ) result = client.scan("user input") if result.is_system_error: raise RuntimeError("Security check failed") if result.is_blocked: # Do not forward to LLM return input_to_forward = result.sanitized_input if result.is_sanitized else user_input ``` SDK 文档：`sdk/python/README.md` ## Node.js SDK ``` npm install wrapsec-node ``` ``` import WrapSec from 'wrapsec-node' const client = new WrapSec({ apiKey: process.env.WRAPSEC_API_KEY, baseUrl: process.env.WRAPSEC_BASE_URL, }) const result = await client.scan(userInput) if (result.isBlocked) { // Do not forward to LLM } ``` 包含 Express 和 Fastify 中间件。SDK 文档：`sdk/node/README.md` ## 代理模式 WrapSec 是代理模式的 OpenAI 兼容即插即用替代品： ``` from openai import OpenAI client = OpenAI( api_key = "sk_live_your_wrapsec_key", base_url = "http://your-wrapsec-host:8000/v1", ) response = client.chat.completions.create( model = "openai/gpt-4o", # format: provider/model messages = [{"role": "user", "content": user_prompt}], ) ``` 代理模式强制执行输入和输出安全，无需应用程序级集成。提供商 API 密钥以加密方式存储（AES-256-GCM），创建后永远不会完整返回。 ## 身份验证和访问控制 控制面板用户使用电子邮件和密码进行身份验证。JWT 访问令牌在 30 分钟后过期。刷新令牌以 SHA-256 哈希形式存储在数据库中——服务器端从不持久化原始令牌。 | 角色 | 范围 | 权限 | |---|---|---| | ADMIN | 租户范围 | 完整访问 - 用户、设置、密钥、所有部门 | | DEVELOPER | 部门范围 | 扫描、审计、API 密钥、读取设置 | | VIEWER | 部门范围 | 只读审计访问 | API 密钥严格用于运行时机器对机器访问。所有管理操作——用户管理、密钥创建、设置更改——都需要通过控制面板进行基于 JWT 的身份验证。 账户锁定：5 次失败的登录尝试会触发基于 Redis 的 15 分钟锁定。 ## 数据存储 三种模式，通过 `DATA_STORAGE_MODE` 环境变量设置： | 模式 | 行为 | |---|---| | `masked` | PII 在存储前被隐藏（默认）| | `full` | 文本原样存储 | | `none` | 文本永不持久化——仅存储安全元数据 | 这允许在存储原始用户输入受限的受监管环境中部署。审计日志根据配置的保留期保留（默认 30 天）。后台工作进程每天在 UTC 时间 02:00 运行。 ## 可观测性 Prometheus 抓取 `GET /metrics`。包含三个 Grafana 仪表板：安全概览、延迟和性能、威胁情报。 这些指标支持对威胁活动、延迟和系统健康状况的实时监控。关键指标：`wrapsec_requests_total`、`wrapsec_blocked_total`、`wrapsec_request_latency_ms`、`wrapsec_system_errors_total`、`wrapsec_proxy_latency_ms`。 ## 本地运行 此设置在本地运行完整的 WrapSec 栈，用于开发和测试。 ``` # 基础设施 docker compose -f infrastructure/docker/docker-compose.yml up -d postgres redis # API export PYTHONPATH=$(pwd) uvicorn api.main:app --reload --host 0.0.0.0 --port 8000 # Dashboard cd dashboard && npm run dev ``` 测试： ``` export TESTING=true export PYTHONPATH=$(pwd) pytest tests/unit tests/integration -v ``` ## 文档 | 文档 | 位置 | |---|---| | 核心概念和决策模型 | `docs/core_concepts.md` | | API 参考（47 个端点）| `docs/api.md` | | 架构和数据库模式 | `docs/architecture.md` | | 风险评分和置信度模型 | `docs/scoring_model.md` | | 开发者指南 | `docs/developer_guide.md` | | 用户指南（控制面板）| `docs/user_guide.md` | | CLI 参考 | `docs/cli_reference.md` | | Python SDK | `sdk/python/README.md` | | Node.js SDK | `sdk/node/README.md` | ## 生产环境注意事项 - 明确设置 `WRAPSEC_BASE_URL`。默认的 `http://localhost:8000` 不得用于生产环境。 - 在受监管环境中将 `DATA_STORAGE_MODE` 设置为 `masked` 或 `none`。 - 在首次部署前更改 `SECRET_KEY` 和 Grafana 默认密码。 - 设置 `TRUSTED_PROXY_IPS` 为您的反向代理 IP，以便 `X-Forwarded-For` 仅从已知来源受信任。 - 设置 `METRICS_TOKEN` 以要求在 `GET /metrics` 上进行 bearer 令牌身份验证——不要未经验证暴露指标。 - 将 Grafana 固定到 10.4.0 - Grafana 12 存在仪表板配置问题。 - Prometheus 目标在 Docker 部署中从 `host.docker.internal:8000` 变为 `api:8000`。 - JWT 部门不匹配警告（`auth_event=JWT_DEPT_MISMATCH`）必须路由到安全监控管道。 WrapSec 确保系统中的每个 AI 交互都经过检查、控制和可审计。 ## 许可证 MIT - 版权所有 © 2026 WrapSec

标签：AI安全, API安全, API密钥检测, Chat Copilot, JSON输出, PII脱敏, Prompt注入检测, TF-IDF, 云计算, 内容审核, 加密通信, 多层检测, 安全策略, 安全网关, 实时检测, 密钥泄露防护, 提示词设计, 搜索引擎查询, 数据泄露防护, 文本分类, 机器学习安全, 测试用例, 网络探测, 自定义请求头, 规则引擎, 越狱检测, 输入验证, 防护系统, 零日漏洞检测