VecBoost 将安全性作为核心设计目标。本文档介绍 VecBoost 的安全策略、漏洞报告流程、内置安全机制与安全最佳实践。

VecBoost 要求 Rust 1.91+（edition 2024，以 Cargo.toml 的 rust-version 字段为权威值）。请使用 rustup update stable 保持工具链更新以获得安全补丁。

# 运行安全审计（CI Security Audit job 同款命令）
cargo install cargo-audit --locked
cargo audit

# 依赖供应链门禁（advisories/licenses/bans）
cargo deny check

• cargo audit：RustSec 安全公告扫描，豁免配置在 .cargo/audit.toml（须附理由，与 deny.toml 处置策略一致）。
• cargo deny check：漏洞必须修复；unmaintained/yanked/unsound 为信息性警告，不阻断 CI，发布前人工复核并记录处置结论。
• 新增依赖须经审批：优先活跃维护、特性门控按需启用（Cargo.toml 中各依赖均 default-features = false 并显式列出 feature）。

请勿通过公开 issue 报告安全漏洞。 请发送邮件联系 maintainer：kirky-x@outlook.com，并在标题注明 [security]。确认时限与披露时间线：待补充（维护者收到报告后会尽快回复）。

请尽量包含：

• 受影响版本（vecboost --version 或 git commit）
• 漏洞类型与影响面（认证绕过 / 路径遍历 / 注入 / DoS / 信息泄露等）
• 复现步骤或 PoC（配置片段、请求样例）
• 缓解建议（如有）

• 漏洞（vulnerability）必须修复；不可达路径（transitive/未启用 feature）的 advisory 可记录豁免并附理由。
• 修复随语义化版本发布，并在 CHANGELOG 的 ### 安全 段记录（先例：RUSTSEC-2026-0258 h2 DoS、vuln-0009 HF Hub repo_id 校验）。

• 出厂 host = "127.0.0.1" 仅回环绑定；auth.enabled=false 时绑定非回环地址拒绝启动，逃生阀 VECBOOST_ALLOW_INSECURE=1 会打 ERROR 告警（仅供受信网络容器）。
• 出厂 use_gpu = false；请求 GPU 但 feature 缺失时 WARN + CPU 回退，不静默。
• --config 显式路径不存在时 fail-fast 报错退出（码 2），不静默回退默认配置。
• CLI 未知子命令报错退出（码 2），不静默启动服务。

• JWT 认证（protocol-jwt）+ CSRF 保护（跟随 auth.enabled）+ Web CORS/防火墙系列（bruteforce / ratelimit / ddos / anomalous）。
• RBAC：/api/1/model/* 与 /embed/file 要求 admin 角色。
• 登录收敛：仅 default_admin_username（默认 admin）可登录；启用认证时必须配置 VECBOOST_ADMIN_PASSWORD（≥12 位，缺失拒绝启动）。
• Token 生命周期：token_expiration_hours 缺省 1 小时；支持 TOTP（secure-totp）、账号锁定（account-lockout）、凭证清零（account-credential-zeroize）、异常检测（anomalous-detector-dual）与安全告警。
• 会话存储：进程内存（oxcache DAO），auth 开启时仅限单副本；外置会话需 garrison db 后端（规划中）。

• XFF 信任反转：trusted_proxies 为空时忽略 X-Forwarded-For，使用直连地址（防头伪造限流绕过）。
• 速率限制：limiteron 令牌桶，全局 / 每 IP / 每用户 / 每 API 密钥多维独立计数，支持封禁管理（ban-manager）与 GCRA。
• 输入限制：单文本最大字节长度（max_text_length，防资源耗尽）、批量大小校验（validate_batch_size）。

• /embed/file 必须显式配置 [server] grpc_allowed_roots 允许根（不再回退 cwd）；单文件上限 10 MiB；text_preview 仅 admin。
• PathValidator 默认拒绝 /、/etc 等敏感目录。
• HF Hub repo_id 格式校验（src/utils/hf_hub.rs 的 is_valid_hf_repo_id + build_hf_repo）统一覆盖所有远程下载入口，防恶意配置注入与路径遍历（vuln-0009）。

• AES-256-GCM 配置加密（src/config/encryption.rs），VECBOOST_ENCRYPTION_KEY / VECBOOST_REQUIRE_ENCRYPTION / VECBOOST_KEY_STORAGE_TYPE / VECBOOST_KEY_FILE_PATH 控制密钥存储。
• SecretKey 零化（zeroize）；环境变量 keystore 只读。
• 所有密钥脱敏与文本预览函数使用 UTF-8 字符边界安全切片（防多字节切片 panic）。

• 审计日志（audit 段 + inklog）：用户、操作、资源、IP、时间戳。
• 错误响应脱敏：sanitize_error_message 统一清理；错误码经 i18n 双语翻译，不泄露内部细节。

生产部署

• 始终通过 HTTPS 暴露服务；反代部署显式配置 trusted_proxies。
• 启用 auth.enabled = true，VECBOOST_JWT_SECRET / VECBOOST_ADMIN_PASSWORD 经环境变量或密钥管理注入，不入库不入镜像。
• 按需评估 token_expiration_hours（默认 1 小时）；纯 Bearer API 可显式关闭 CSRF。
• CORS 勿用通配符 "*"（等同公开接口）；显式列出可信来源。
• auth 开启时为单副本部署（会话在进程内存）；水平扩展需先外置会话（待 garrison db 后端）。
• 容器等受信网络如需非回环绑定，显式设置 VECBOOST_ALLOW_INSECURE=1 并理解 ERROR 告警含义。

密钥与配置

• 定期轮换 JWT 密钥；/embed/file 允许根配置最小化（仅业务目录）。
• 使用 cargo audit / cargo deny check 保持依赖更新；新增豁免必须附理由。
• 客户端不要依赖 /embed/file 的 text_preview（已收敛为 admin-only）。