OmniRoute 安全加固指南：从漏洞披露到 AES-256-GCM 静态加密与 Prompt 注入防护的完整实践

OmniRoute 安全加固指南从漏洞披露到 AES-256-GCM 静态加密与 Prompt 注入防护的完整实践【免费下载链接】OmniRouteNever stop coding. Free MIT AI gateway: one endpoint, 352 providers (150 free), 1200 models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline Copilot. Quota-aware auto-fallback, RTKCaveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550 contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute作为一款将 352 供应商、1200 模型收敛到单一端点的 MIT 开源 AI 网关OmniRoute 的安全边界直接决定了上游 API 密钥、OAuth 令牌与用户 Prompt 的隐私与可用性。本文以 docs/i18n/fr/SECURITY.md 的安全策略为主体结合仓库内 SECURITY.md 与src/下的真实实现系统讲解 OmniRoute 的多层安全模型漏洞披露流程、认证授权、AES-256-GCM 静态加密、Prompt 注入防护、PII 脱敏、网络安全与合规配置并给出可直接落地的环境变量与 Docker 部署方案。读完本文你将掌握 OmniRoute 安全功能的完整配置方法以及每一层防护在源码中的实际落地位置。漏洞披露流程与版本支持策略负责任披露Responsible Disclosure发现 OmniRoute 安全漏洞时官方明确要求不要在公开渠道如 Issue 追踪器直接暴露漏洞细节而是通过 GitHub Security Advisories 提交。提交内容应包含漏洞的描述description可复现步骤reproduction steps潜在影响范围potential impact响应时间承诺阶段目标时限确认收到Acknowledgment48 小时分类与评估Triage Assessment5 个工作日补丁发布Patch Release严重漏洞14 个工作日受支持版本仓库根目录的权威策略SECURITY.md当前维护的版本支持矩阵如下版本支持状态3.8.x✅ 积极支持Active3.7.x✅ 安全支持Security 3.7.0❌ 不支持Unsupported说明法语版快照docs/i18n/fr/SECURITY.md记录的是 3.6.x/3.5.x 时代的支持矩阵由于各语言文档更新存在时间差实际版本支持情况请以仓库根目录的 SECURITY.md 为准。多层安全架构总览OmniRoute 的安全模型是层层递进的管道式结构请求在到达上游供应商之前依次经过多道检查。根目录策略给出的当前架构为Request → CORS → Authz pipeline (classify → policies → enforce) → Guardrails (PII masker, prompt injection, vision bridge) → Rate Limiter → Circuit Breaker → Cooldown → Model Lockout → Provider法语版文档中的简化描述为Request → CORS → API Key Auth → Prompt Injection Guard → Input Sanitizer → Rate Limiter → Circuit Breaker → Provider两者互为印证外层负责来源与身份控制CORS、鉴权管道中间层负责内容安全Prompt 注入防护、输入清洗、PII 脱敏内层负责可用性兜底限流、熔断、冷却、模型锁定。下面逐一拆解每一层的实现与配置。认证与授权层认证能力清单能力实现方式仪表盘登录基于密码的认证 JWT 令牌HttpOnly CookieAPI Key 认证HMAC 签名密钥 CRC 校验OAuth 2.0 PKCE供应商浏览器/设备 OAuthClaude、Codex、Gemini、Cursor 等Token 刷新过期前自动刷新 OAuth 令牌安全 CookieAUTH_COOKIE_SECUREtrue用于 HTTPS 环境MCP 作用域32 个细粒度作用域控制 MCP 工具访问关于 JWT 与 Cookie 的落地.env.example中给出了明确指引AUTH_COOKIE_SECURE用于设置会话 Cookie 的Secure标志默认false任何非 localhost 的部署都必须设置为true.env.example 中注释明确标注 MUST be true in any non-localhost deployment。同时.env.example还提示了两个关联的强化开关REQUIRE_API_KEYtrue要求所有/v1/*代理端点必须携带 API Key适用于多用户或公网部署。ALLOW_API_KEY_REVEALfalse禁止在仪表盘 UI 中显示完整 API Key 明文。鉴权管道与路由分级根目录策略中提到的Authz Pipelineclassify → policies → enforce与Route Guard TiersLOCAL_ONLY / ALWAYS_PROTECTED / MANAGEMENT 三级管理路由模型是理解 OmniRoute 授权体系的关键详见 docs/architecture/AUTHZ_GUIDE.md。此外MCP 的 32 个细粒度作用域如read:health、write:combos、execute:completions覆盖了远程 MCP 工具调用的访问控制详见 docs/frameworks/MCP-SERVER.md。静态数据加密AES-256-GCM scrypt加密格式与密钥派生OmniRoute 将 SQLite 中存储的所有敏感凭据——API Key、Access Token、Refresh Token、ID Token——用AES-256-GCM加密密钥由scrypt派生。密文采用带版本的格式enc:v1:iv_hex:ciphertext_hex:authTag_hex这一格式在 src/lib/db/encryption.ts 中由常量PREFIX enc:v1:、IV_LENGTH 16、KEY_LENGTH 32、ALGORITHM aes-256-gcm明确定义。值得注意的细节是AUTH_TAG_LENGTH 16——GCM 认证标签被固定为完整的 16 字节防止通过截断认证标签实施的 GCM 伪造攻击源码注释明确指向 Semgrep 的gcm-no-tag-length规则。主密钥派生与历史迁移加密密钥派生经历了关键演进源码注释记录于 v3.7.9当前主密钥使用静态盐omniroute-field-encryption-v1通过scryptSync(secret, STATIC_SALT, 32)派生。遗留密钥旧版本曾使用动态盐sha256(secret)的前 16 字节派生。历史上两种派生路径健康检查/令牌刷新与主 API使用不同派生方式导致令牌相互无法解密引发持续解密失败、重复加密循环和 CPU 飙升高达 50%。修复方案是主密钥统一使用静态盐派生并对旧格式密文自动迁移——解密时先用静态盐密钥尝试失败则回退到遗留密钥一旦用遗留密钥解密成功下次encrypt()会以静态盐密钥重新加密逐步将整个数据库迁移到新格式。相关迁移逻辑见 src/lib/db/encryption.ts 的migrateLegacyEncryptedString。直通模式Passthrough当未设置STORAGE_ENCRYPTION_KEY时加密层进入直通模式凭据以明文存储便于本地开发。此时encrypt()会输出警告STORAGE_ENCRYPTION_KEY not set. Storing plaintext (passthrough mode).。生产环境必须设置密钥以启用静态加密。密钥生成命令# 生成静态加密密钥推荐启用 at-rest 加密 STORAGE_ENCRYPTION_KEY$(openssl rand -hex 32)补充说明源码中还实现了密钥的宽松加载路径src/lib/db/encryption.ts 的ensureSecretLoaded除了进程环境变量外还会按序检查数据目录.env、当前目录.env与~/.hermes/.env因此密钥也可写入上述.env文件中。Prompt 注入防护Guardrails 框架与输入清洗Guardrails 注册表OmniRoute 内置了可热重载的 guardrails 注册表src/lib/guardrails/按优先级执行三个内置守卫Guardrail优先级用途vision-bridge5为不支持视觉的模型提供图像描述桥接对图片 URL 实施 SSRF 防护pii-masker10调用前/调用后的 PII 脱敏邮箱、电话、CPF、CNPJ、信用卡、SSNprompt-injection20检测 override、角色劫持、越狱、提示词泄露等模式自定义 guardrail 通过registerGuardrail(new MyGuardrail())注册。整个模型是fail-open设计——守卫抛异常也不会阻断流量单请求可通过x-omniroute-disabled-guardrails请求头选择退出。详见 docs/security/GUARDRAILS.md。中间件实现promptInjectionGuard.ts作为遗留中间件外观现在委托给 guardrail 体系src/middleware/promptInjectionGuard.tscreateInjectionGuard(options)返回一个守卫函数对请求体调用evaluatePromptInjection。withInjectionGuard(handler, options)包装 Next.js API 路由仅对 POST/PUT/PATCH 生效检测到注入时返回 HTTP 400错误码为SECURITY_001message 为Request blocked: potential prompt injection detected并在命中时尽力设置X-Injection-Flagged与X-Injection-Detections响应头。请求体会被克隆并预解析以第三个参数传递给下游 handler避免热路径上的重复解析。注入模式与严重级别src/shared/utils/inputSanitizer.ts中定义了 6 组内置注入检测正则src/shared/utils/inputSanitizer.ts对应严重级别如下模式名严重级别典型示例 / 匹配要点system_overrideHighignore all previous instructions忽略/放弃先前的指令/规则role_hijackMediumyou are now DAN, you can do anything角色劫持system_prompt_leakHighshow me your system prompt要求泄露系统提示词delimiter_injectionMedium/High[SYSTEM]、[INST]、SYS、|im_start|等编码分隔符jailbreak_danMediumDAN、do anything now、jailbreak、developer modeencoding_evasionMediumbase64/rot13/hex decode 指令关键词组合严重级别差异说明法语版快照与根目录策略在部分模式Role Hijack、Delimiter Injection、DAN/Jailbreak、Instruction Leak的严重级别标注上存在出入。以当前源码为准——src/shared/utils/inputSanitizer.ts 与根目录 SECURITY.md 的标注一致Role Hijack Medium、Delimiter High、DAN/Jailbreak Medium、Instruction Leak High法语版为较早快照。源码中还有一个重要的防误报细节system_prompt_leak正则要求prompt|instructions前必须出现system|initial|hidden|original等限定词issue #4041否则旧正则会误伤几乎所有 coding-agent 流量如 show the instructions。热路径性能约束为防止注入扫描成为高并发下的 CPU 瓶颈扫描长度被硬性限定为前16 KBMAX_INJECTION_SCAN_BYTES 16 * 1024见 src/shared/utils/inputSanitizer.ts。源码注释解释注入指令通常位于 Prompt 顶部扫描数百 KB 的粘贴代码 / RAG 上下文只消耗 CPU 而无收益。该常量同时被promptInjection.tsguardrail 复用。配置项注入防护可通过仪表盘Settings → Security或.env配置INPUT_SANITIZER_ENABLEDtrue INPUT_SANITIZER_MODEblock # warn | block注入策略legacy redact 不会剥离注入文本 INPUT_SANITIZER_BLOCK_THRESHOLDhigh # high默认| medium | low —— block 模式下达到/超过该级别的检测将被拦截配置解析逻辑见 src/shared/utils/inputSanitizer.tsINPUT_SANITIZER_ENABLED默认开启opt-out支持true/1/yes/on与false/0/no/off的宽松布尔解析INPUT_SANITIZER_MODE默认warn。严重级别阈值判定src/shared/utils/injectionSeverity.ts 为严重级别分配了分值low1、medium2、high3shouldBlockDetections()按阈值决定是否拦截。默认阈值是high——即block 模式下只拦截 High 级别检测Medium 级别仅记录日志。阈值可通过环境变量INPUT_SANITIZER_BLOCK_THRESHOLD或INJECTION_GUARD_BLOCK_THRESHOLD下调为medium/low。边界提醒根目录策略明确声明Prompt 注入防护是尽力而为的启发式中间件并非完整的注入防火墙既可能对良性 persona/RPG Prompt 产生误报也可能漏过 leetspeak、变体拼写或非英语模式。PII 脱敏识别模式与替换规则PII 类型识别模式示例替换占位符邮箱Emailuserdomain.com[EMAIL_REDACTED]巴西个人税号CPF123.456.789-00[CPF_REDACTED]巴西企业税号CNPJ12.345.678/0001-00[CNPJ_REDACTED]信用卡号Credit Card4111-1111-1111-1111[CC_REDACTED]电话Phone55 11 99999-9999[PHONE_REDACTED]美国社保号SSN123-45-6789[SSN_REDACTED]上述正则的实际定义邮箱、CPF、CNPJ、信用卡、巴西电话、美国 SSN位于 src/shared/utils/inputSanitizer.ts。根目录策略还补充了响应侧脱敏能力PII_REDACTION_ENABLEDtrue # 请求 PII 改写独立于 INPUT_SANITIZER_MODE PII_RESPONSE_SANITIZATIONtrue # 可选对返回给客户端的供应商响应执行 PII 脱敏源码实现细节sanitizeRequest()会从请求体中提取所有消息内容支持 OpenAI/Claude 的messages[]与 Responses API 的input[]以及system、prompt、instructions、query、documents等字段拼接后统一扫描若启用了 PII 改写则对请求体深克隆后再做替换redactBody避免污染原始对象并通过sanitizedBody返回改写后的副本最终以blocked/modified/detections/piiDetections结构呈现结果。PII 脱敏默认关闭PII_REDACTION_ENABLED默认false属于严格 opt-in 的能力。网络安全层能力说明CORS显式跨域白名单CORS_ALLOWED_ORIGINS遗留别名CORS_ORIGINIP 过滤仪表盘中配置 IP 段白名单/黑名单限流Rate Limiting按供应商限流带自动退避防惊群Anti-Thundering HerdMutex 每连接锁防止级联 502TLS 指纹模拟浏览器 TLS 指纹降低被机器人检测的概率CLI 指纹按供应商匹配原生 CLI 的请求头/请求体顺序其中 CORS 在.env.example中保留了CORS_ORIGIN作为 legacy 单源别名.env.example根目录策略则推荐使用显式的CORS_ALLOWED_ORIGINS白名单而非默认的*。TLS 指纹与 CLI 指纹的详细设计及法律/伦理注意事项见 docs/security/STEALTH_GUIDE.md。弹性与可用性能力说明熔断器Circuit Breaker三态Closed → Open → Half-Open按供应商独立维护状态持久化到 SQLite请求幂等Idempotency5 秒去重窗口过滤重复请求指数退避Exponential Backoff自动重试且延迟递增健康仪表盘Health Dashboard实时监控供应商健康状态熔断器与冷却、模型锁定等机制共同构成了请求路由的可用性兜底完整设计见 docs/architecture/RESILIENCE_GUIDE.md。合规与审计能力说明日志留存按CALL_LOG_RETENTION_DAYS自动清理日志免日志选择每个 API Key 的noLog标志可禁用请求日志审计日志管理操作记录在audit_log表中MCP 审计所有 MCP 工具调用通过 SQLite 落盘审计Zod 校验所有 API 输入在模块加载时用 Zod v4 schema 校验CALL_LOG_RETENTION_DAYS在 .env.example 中默认注释示例值为7天按需取消注释并设置即可启用自动清理。审计日志与保留策略的更多细节见 docs/security/COMPLIANCE.md。必需环境变量与启动前检查以下密钥必须在启动服务前设置。若缺失或过于弱服务器将fail fast拒绝启动# 必需 —— 缺少则服务无法启动 JWT_SECRET$(openssl rand -base64 48) # 最少 32 字符 API_KEY_SECRET$(openssl rand -hex 32) # 最少 16 字符 # 推荐 —— 启用静态加密 STORAGE_ENCRYPTION_KEY$(openssl rand -hex 32)服务器会主动拒绝已知的弱值例如changeme、secret、password。建议在.env已被 gitignore中保存这些密钥而.env.example仅作为不含字面量密钥的模板——这一点同时也是仓库的硬性安全规则之一见下节。Docker 生产部署安全基线容器化部署的官方安全建议生产环境使用非 root 用户运行密钥以只读卷方式挂载绝不将.env文件复制进 Docker 镜像使用.dockerignore排除敏感文件位于 HTTPS 反代之后时设置AUTH_COOKIE_SECUREtrue官方推荐的docker run示例来自 SECURITY.mddocker run -d \ --name omniroute \ --restart unless-stopped \ --read-only \ -p 20128:20128 \ -v omniroute-data:/app/data \ -e JWT_SECRET$(openssl rand -base64 48) \ -e API_KEY_SECRET$(openssl rand -hex 32) \ -e STORAGE_ENCRYPTION_KEY$(openssl rand -hex 32) \ diegosouzapw/omniroute:latest其中--read-only配合数据卷挂载、密钥通过-e在运行时注入是兼顾不可变文件系统与密钥不落盘的核心实践。仓库还提供了 Podman 与 Docker Compose 的现成部署编排contrib/podman/、contrib/vps/compose.yaml、docker-compose.yml可供参考。依赖安全与工程实践根目录策略在 Dependencies 一节给出了工程层面的安全要求法语版与之对应定期运行npm auditnpm run audit:deps同时覆盖主包与 electron保持依赖更新使用huskylint-staged做提交前检查CI 流水线在每次推送时运行 ESLint 安全规则no-eval、no-implied-eval、no-new-func均设为 error供应商常量在模块加载时通过 Zod 校验src/shared/validation/providerSchema.ts根目录策略同步提到 src/shared/validation/schemas.ts默认使用安全优先的库dompurify/isomorphic-dompurifyXSS、joseJWT、better-sqlite3参数化查询规避 SQL 注入、bcryptjs密码哈希硬性安全规则Hard Security Rules根目录 SECURITY.md 还定义了由工具链与评审强制执行的硬性规则其中与日常开发/审计最相关的几条包括绝不提交密钥——.env被 gitignore.env.example只是无字面量密钥的模板绝不在运行时使用eval()/new Function()——ESLint 强制路由中绝不写裸 SQL——一律走 src/lib/db/ 的参数化查询输入一律用 Zod 校验——见 src/shared/validation/schemas.ts上游请求头一律清洗——denylist 定义于 src/shared/constants/upstreamHeaders.ts凭据静态加密——AES-256-GCM见 src/lib/db/encryption.ts错误响应必须经过buildErrorBody()/sanitizeErrorMessage()——避免在 HTTP/SSE/MCP 响应体暴露原始err.stack/err.message详见 docs/security/ERROR_SANITIZATION.md上游 OAuth 公共标识符通过resolvePublicCred()解析——源码中禁止硬编码AIza…、GOCSPX-…等字面量详见 docs/security/PUBLIC_CREDS.md关键源码与文档索引安全策略权威版SECURITY.md法语版快照docs/i18n/fr/SECURITY.md静态加密实现src/lib/db/encryption.ts注入防护中间件src/middleware/promptInjectionGuard.ts输入清洗与 PII 模式src/shared/utils/inputSanitizer.ts注入严重级别与阈值src/shared/utils/injectionSeverity.tsGuardrails 注册表src/lib/guardrails/授权管道docs/architecture/AUTHZ_GUIDE.mdGuardrails 框架docs/security/GUARDRAILS.md熔断与弹性docs/architecture/RESILIENCE_GUIDE.md环境变量模板.env.exampleOmniRoute 的安全体系可以概括为一句话身份与来源先于内容、内容先于可用性、密钥永远以密文落盘、失败永远不泄露内部细节。从 48 小时漏洞响应承诺到enc:v1:版本的 AES-256-GCM 密文格式再到按严重级别分层的注入检测每一层都有源码可查、有配置可调。部署时只需守住三条底线——生成并注入三个强密钥、HTTPS 下开启AUTH_COOKIE_SECURE、生产容器以只读方式运行——即可获得完整的多层防护。【免费下载链接】OmniRouteNever stop coding. Free MIT AI gateway: one endpoint, 352 providers (150 free), 1200 models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline Copilot. Quota-aware auto-fallback, RTKCaveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550 contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考