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，发布前人工复核并记录处置结论。
• gitleaks 规则集：.gitleaks.toml 以 [extend] useDefault = true 加载 gitleaks 默认检测规则——不写这一行则规则集为空、扫描静默空转（[[allowlist.rules]] 单数写法在 8.19 后已废弃，现行为 [[allowlists]] + regexes + condition）。
• gitleaks 豁免范围：占位 JWT 形态的豁免按路径收窄到 docs/ / tests/ / examples/ / src/security/，src/ 内的真实签名令牌不再被全局豁免吞掉；test_ 前缀的测试值豁免保持全局（取值自述即测试值）。
• gitleaks 历史基线：.gitleaks-baseline.json 记录 1 条已定位的历史测试凭证（src/module_registry/tests.rs，该文件已从仓库删除，仅存于历史提交），使每周全量扫描不被它阻断；新增泄漏仍会失败。
• 新增依赖须经审批：优先活跃维护、特性门控按需启用（Cargo.toml 中各依赖均 default-features = false 并显式列出 feature）。

请勿通过公开 issue 报告安全漏洞。

首选渠道：通过 GitHub Security Advisories 私密披露通道提交报告（仓库页 Security → Report a vulnerability）。

备选渠道：仅当首选通道不可用时，发送邮件至 kirky-x@outlook.com（受理人：Kirky.X），标题注明 [security]。Kirky.X 收到报告后会尽快回复。

请尽量包含：

• 受影响版本（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/v1/model/* 与 /embed/file 要求 admin 角色。
• 登录收敛：仅 default_admin_username（默认 admin）可登录；启用认证时必须配置 VECBOOST_ADMIN_PASSWORD（≥12 位，缺失拒绝启动）。
• Token 生命周期：token_expiration_hours 缺省 24 小时；支持 TOTP（secure-totp）、账号锁定（account-lockout）、凭证清零（account-credential-zeroize）、异常检测（anomalous-detector-dual）与安全告警。
• 会话存储：[auth] session_backend 可选 memory（默认，进程内存 oxcache，仅限单副本）或 database（部署库 garrison_kv 表，garrison DbnexusKvDao，auth 开启时可多副本共享）；database 需以 --features "db,sqlite" 或 "db,postgres" 构建并配置 [database]，未编译 db 或 auth 关闭时启动期显性拒绝。
• 多副本语义边界：会话外置后认证可水平扩展；限流、精确向量缓存、语义缓存模糊层与封禁清单均可经 distributed-redis 外置 Redis 跨副本共享（缺省 memory 仍进程内）。语义缓存模糊层采用与单机一致的 trigram Jaccard 语义，索引存 Redis Hash + LRU ZSET（不依赖 RediSearch）；封禁清单经 limiteron ban-sync + CacheBanStorage 共享；账号锁定计数经 AtomicKvDao 单语句原子自增（INSERT ... ON CONFLICT ... RETURNING，SQLite/PostgreSQL，SQLite 并发写走有界 busy 重试 + WAL），跨副本无丢失；set_if_absent 在旧键已过期的清理路径为 DELETE→set 两步非原子，"恰一赢家"语义在该窗口不保证。
• database 后端运行前提与会话数据卫生：TTL 以各副本 UTC 墙钟为基准，多副本部署需 NTP 对时（时钟偏移会等量伸缩会话与锁定期限）；会话令牌以明文键值落库，部署库备份等同会话凭据库，需同等级加密保管；过期会话行仅在同键再次访问时惰性删除，需运维侧定时清理 garrison_kv 过期行（如 DELETE FROM garrison_kv WHERE expire_at IS NOT NULL AND expire_at <= <unix 秒>）。

• 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（默认 24 小时）；纯 Bearer API 可显式关闭 CSRF。
• CORS 勿用通配符 "*"（等同公开接口）；显式列出可信来源。
• 水平扩展：auth 开启时默认单副本（会话在进程内存）；多副本需设置 session_backend = "database" 并以 db,sqlite|postgres 构建（会话共享于部署库，备份等同会话凭据库、需同等级加密保管）；限流、语义缓存与封禁清单在启用 distributed-redis 后经 Redis 跨副本共享，缺省 memory 仍按副本独立。
• 容器等受信网络如需非回环绑定，显式设置 VECBOOST_ALLOW_INSECURE=1 并理解 ERROR 告警含义。

密钥与配置

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