LiteLLM 数据隐私与安全体系全解：从漏洞披露流程到自托管与云版纵深防御

LiteLLM 在仓库根目录维护了一份面向安全研究者和运维人员的《Data Privacy and Security》指南（security.md），它界定了漏洞如何上报、按什么标准分级与奖励，以及三类部署形态（GitHub 开源仓库、自托管实例、LiteLLM Cloud 托管版）各自的安全边界与数据隐私承诺。本文以该文档为骨架，逐条展开其中的流程、等级与措施，并结合当前仓库中的 CI/CD 安全工作流、示例配置与源码实现，帮助读者理解“LiteLLM 靠什么保护用户数据、漏洞按什么规则被受理、自托管与云版的安全责任分别在哪里”。

一、LiteLLM 安全模型：三条并行的信任边界

security.md 把安全问题划分为三个互相关联但责任主体不同的层面，这也是理解全文的关键框架：

1. LiteLLM GitHub（开源仓库侧）：保障代码与发布物（PyPI 包、Docker 镜像）的供应链可信，属于防御“投毒/篡改”类攻击的主阵地；
2. Self-hosted Instances（自托管实例侧）：用户在自己基础设施上部署的 Proxy，核心承诺是“不采集遥测、不向 LiteLLM 服务器回传业务数据”，安全责任主要由使用方通过正确的配置（如 master_key）承担；
3. LiteLLM Cloud（托管版侧）：官方托管的云服务，负责加密、访问控制（SSO、IP 白名单）、审计与区域隔离等平台级安全能力。

其中 1 对应下面要讲的 P0 供应链攻击，2 与 3 则对应 P1/P2 应用层攻击——后文的分级体系正是建立在“哪些东西受我们保护、哪些依赖你正确配置”这一边界之上。

二、安全漏洞披露与赏金机制

security.md 明确定义了官方受理漏洞的完整流程，任何想向 LiteLLM 提交漏洞的研究者都应先对齐这一套规则。

2.1 上报渠道与标准流程

上报漏洞的统一入口是仓库的私密漏洞报告功能：在仓库页面的 Security → Security Advisories → “Report a vulnerability” 中创建报告，内容须包含：

• 可复现问题的步骤（steps to reproduce）；
• 一段完整演示 exploit 的录屏：要求针对正在运行的 Live LiteLLM 实例，从初始访问一直演示到最终影响；纯 CLI 类漏洞允许使用终端录屏（如 asciinema）；
• 其他有助于研判的补充信息。

[!WARNING] security.md 特别强调：不含演示视频的报告会被直接关闭且不进入评审。原因是 AI 工具目前已经能轻松生成“听上去很合理、实际无法复现”的报告，人工研判这些噪音会挤占处理真实问题的时间。如果之后补上视频，官方会重新打开并开始 triage。

2.2 漏洞分级：P0 / P1 / P2

官方把漏洞划分为三个严重级别，分别对应攻击面从供应链到应用权限的纵深：

级别	名称	定义	对应攻击面
P0	Supply Chain Attacks（供应链攻击）	攻击者攻破 LiteLLM 的 CI/CD 流水线，将 PyPI 包或 Docker 镜像（GHCR / Docker Hub）指向被植入或篡改的产物	发布物完整性
P1	Unauthenticated Proxy Access（未认证代理访问）	未认证用户即可获取本应受保护的 Proxy 实例数据（例如 API Key）的应用层攻击	鉴权边界
P2	Authenticated Malicious Actions（已认证恶意操作）	已认证用户执行超出自身权限的操作，如权限提升、越权访问数据	授权模型

从分级可以读出 LiteLLM 的威胁建模思路：供应链（P0）优先级最高，因为它影响所有下游用户；其次是“匿名即可窃取凭据”（P1）；最后才是“登录后的越权”（P2）。

2.3 Bug Bounty 赏金计划

security.md 声明对负责任披露的漏洞按严重程度提供赏金，当前只有 P0/P1 报告有资格获得赏金，但 P2 的提交仍被鼓励：

严重度	赏金区间	示例
Critical（严重）	$1,500 – $3,000	P0 供应链攻破
High（高危）	$500 – $1,500	P1 未认证的代理访问
Medium（中危）	不适用（N/A）	P2 认证后的权限提升
Low（低危）	不适用（N/A）	轻微信息泄露、低影响错误配置

获得赏金的合格条件：报告须包含清晰复现步骤、上文要求的复现视频，且不得涉及你不拥有的系统或账户。官方承诺及时评审，并在 5 个工作日内跟进。

2.4 已知非问题（明确不在范围内）

这一点对研究者尤其重要——依赖部署方配置失误才能成立的攻击被明确排除在外，例如：

• Proxy 配置中没有设置 master_key 就对外暴露实例（相当于匿名开放网关），此类场景不被视为漏洞。

这再次印证了 2.1 中“边界划分”的思路：master_key 是自托管 Proxy 的第一道鉴权闸门，属于使用方的安全责任，官方不把它计入自身漏洞范围（详见第四节）。

三、仓库侧安全：LiteLLM GitHub 的供应链防护工程

security.md 宣称“所有提交都会经过 GitHub 的 CodeQL 检查”，而仓库里实际沉淀的是一整套远超单点扫描的供应链安全工作流。下面按证据文件逐一展开。

3.1 CodeQL 静态分析：语言矩阵 + 安全质量规则集

核心工作流定义在 .github/workflows/codeql.yml：

• 触发条件：push 到 main、针对 main 的 pull request，外加每天 04:00 UTC 的定时任务；
• 分析语言矩阵：python、javascript-typescript、actions 三种，均使用 build-mode: none（无需编译，直接语义分析）；
• 规则集：通过 .github/codeql/codeql-config.yml 引入 security-and-quality 查询套件，并排除两个已知会在大型 Python 代码库上内存爆炸（OOM）的查询——py/clear-text-logging-sensitive-data（CWE-312，明文日志泄漏敏感数据）和 py/polynomial-redos（CWE-730，多项式级正则回溯），同时将 tests、docs 与所有 *.md 排除在分析路径之外；
• 一个值得借鉴的细节：工作流中对 CodeQL 告警做了 SARIF 后置过滤，仅豁免 litellm/llms/oci/common_utils.py 中的 py/weak-sensitive-data-hashing 单条规则——因为该处 sha256 是 OCI HTTP 签名规范要求的“内容完整性哈希”而非口令哈希，代码里已通过 usedforsecurity=False 声明非安全用途，但 CodeQL 污点流仍会误报，因此用 filter-sarif 把豁免范围精确钉在“文件+规则”这一对组合上，仓库其他位置的同类检查不受影响。

这说明 security.md 中“All commits run through GitHub's CodeQL checking”在工程上是有语言矩阵、规则裁剪与告警豁免治理支撑的，而非一句空泛声明。

3.2 依赖漏洞扫描：osv-scanner 对锁定文件做全量比对

在 CI 中随 pull request 与每日定时任务运行（.github/workflows/osv-scan.yml）：

• 使用 osv-scanner v2.3.8（下载时校验 sha256 固定版本，防供应链投毒）；
• 按根目录 osv-scanner.toml 的配置扫描两份关键锁定文件：Python 侧 uv.lock 与前端侧 ui/litellm-dashboard/package-lock.json。

也就是说，Python SDK/Proxy 与 Dashboard 前端的第三方依赖都纳入了 OSV 漏洞库比对。仓库还配套部署了 dependabot.yaml、scorecard.yml、针对 CI 配置注入的 zizmor.yml、正则/规则扫描的 test-semgrep.yml，以及对构建产物做镜像扫描的 image-scan.yml；仓库根目录同时维护着 cosign.pub（镜像签名公钥）和面向加固部署的 docker-compose.hardened.yml。这些工程细节共同支撑着 security.md 对 P0“供应链攻击”的最高优先级定位。

四、自托管实例（Self-hosted）安全措施与责任边界

4.1 核心承诺：不自上而下的遥测与数据回传

security.md 对自托管给出两条明确承诺：

• 你在自托管 LiteLLM 时，没有数据或遥测被存储在 LiteLLM 的服务器上；
• 遥测（Telemetry）：自托管 LiteLLM 时不运行任何遥测。

仓库的官方参考配置对此做了印证：proxy_server_config.yaml 的 litellm_settings 段落中默认写着 telemetry: False。也就是说，如果你把请求发往自建的 LiteLLM Proxy（而不是 LiteLLM Cloud），流量只在你与各家模型供应商之间流动，LiteLLM 侧不采集使用行为数据。

4.2 master_key：自托管实例的第一道（也是必须的）鉴权闸门

self-hosted 部署的安装与配置可参考 docker/README.md、根目录 docker-compose.yml 与示例配置 proxy_server_config.yaml 中的 general_settings 段。其中最关键的鉴权项是：

general_settings:
  master_key: sk-1234 # [OPTIONAL] Use to enforce auth on proxy

security.md 在“已知非问题”中已声明：不设置 master_key 属于配置失误，相关攻击不计入漏洞范围。源码侧也印证了该键的枢纽地位：

• 在认证工具 litellm/proxy/auth/auth_utils.py 的调用约定中，master_key（示例 sk-1234）被作为管理员主密钥使用；
• 在 litellm/proxy/auth/login_utils.py 中，登录 Admin UI 时若 master_key 为 None，会直接抛出 ProxyException，提示需通过 LITELLM_MASTER_KEY 环境变量或配置 general_settings: master_key 设置——只有设置后 UI 才能取得管理员登录凭据。

因此对自托管用户而言，永远不要留空 master_key，并应通过环境变量（如 LITELLM_MASTER_KEY）或 secrets 管理注入，避免明文写死在镜像或仓库里。

五、LiteLLM Cloud 托管版：平台侧安全能力

如果选择官方托管服务，security.md 列出的平台侧措施包括：

• 静态加密：所有存储数据使用你的 LITELLM_MASTER_KEY 加密；传输加密：使用 TLS；
• 基础设施：数据库与应用运行在 GCP、AWS 基础设施之上，其中数据库部分由 NeonDB 参与托管；
• 身份与访问：所有用户可用 SSO（单点登录），基于 OAuth 2.0 对接 Google、Okta、Microsoft、KeyCloak；
• 审计：提供带保留策略的 Audit Logs（审计日志）；
• 网络控制：可控制允许访问 Cloud 实例的 IP 地址（Allowed IPs）。

仓库里可以找到这些能力的实现痕迹：

• 审计日志管理端点位于 enterprise/litellm_enterprise/proxy/audit_logging_endpoints.py，提供 get_audit_logs（按条件分页查询，返回 audit_logs 列表与 total_count）与 get_audit_log_by_id（按 ID 取单条），底层使用 Prisma 模型 LiteLLM_AuditLog 进行读写——注意该模块在 enterprise/ 目录下，说明审计属于企业级/付费能力；
• SSO/OAuth 路由在 litellm/proxy/management_endpoints/ui_sso.py 以及企业自定义 SSO 处理器 enterprise/litellm_enterprise/proxy/auth/custom_sso_handler.py 中有对应实现。

5.1 LiteLLM Cloud 支持的数据区域

官方支持的托管数据区域及其完全隔离特性如下：

区域	位置	云厂商节点
US（美国）	加州北部（Northern California）	AWS/GCP us-west-1；另提及弗吉尼亚（Virginia）AWS us-east-1
EU（欧洲）	德国法兰克福（Frankfurt）	AWS/GCP eu-central-1

security.md 特别强调：两个区域之间的所有数据、用户账户与基础设施完全相互隔离。这意味着选择 EU 区域的客户，其数据不会与 US 区域共享任何存储或账户体系。

六、源码纵深：从“允许 IP”到反代可信边界的工程细节

security.md 提到 Cloud 支持控制可访问的 IP 地址。自托管场景中做同类网络级访问控制时，一个常见的坑是“信任了不该信任的 X-Forwarded-For 头”，从而被攻击者伪造来源 IP 绕过白名单。仓库中 litellm/proxy/auth/ip_address_utils.py 展示了值得推广的 fail-closed 设计：

• 默认内部网络仅含 RFC1918 私网段与回环地址（10.0.0.0/8、172.16.0.0/12、192.168.0.0/16、127.0.0.0/8、::1/128、fc00::/7）；
• 只有当配置开启 use_x_forwarded_for 且 请求直连来源 IP 落在 mcp_trusted_proxy_ranges（可信反代 CIDR）内时，才信任 X-Forwarded-For 头；否则告警并 fail-closed（视作外部访问者）；
• 若启用 mcp_xff_num_trusted_hops，则按“从右向左数 N 跳”的方式取真实客户端 IP，因为 XFF 链的右端由可信基础设施写入、左端是攻击者可控的，从而防御“客户端前置伪造 IP”的追加式欺骗；配置值非法（非正整数）时同样 fail-closed，而不是静默退回旧路径。

这段实现说明，IP 级访问控制只有在“正确识别真实来源 IP”的前提下才有意义——这也是运维自托管网关、把 Proxy 放到反代之后时必须同步配置可信代理网段的原因。

七、面向使用者的安全行动清单

综合 security.md 的分级与仓库证据，不同角色的可落地动作如下：

1. 漏洞研究者：准备好完整复现步骤与“从初始访问到最终影响”的演示录屏（CLI 场景可用 asciinema 终端录屏），经由 Security → Report a vulnerability 私密上报；聚焦 P0/P1 可获得赏金，P2 建议一并提交；不要提交依赖配置失误（如未设 master_key）的攻击。
2. 自托管运维者：务必在 general_settings 设置高强度 master_key（或注入 LITELLM_MASTER_KEY 环境变量）；保持 telemetry: False；开启或接入等效于 CodeQL、OSV 的静态与依赖扫描；校验镜像签名（仓库根目录的 cosign.pub）；部署在反代之后时按 ip_address_utils.py 的模型配置可信代理 CIDR，避免 XFF 伪造绕过网络控制。
3. 托管版用户：依托平台侧的静态加密（LITELLM_MASTER_KEY）、TLS、SSO/OAuth 2.0（Google、Okta、Microsoft、KeyCloak）、带保留策略的审计日志与 Allowed IP 白名单，并结合数据区域隔离要求选择 US（us-west-1/us-east-1）或 EU（eu-central-1）区域；涉及隐私合规诉求时应优先选择符合当地要求的区域。

结语

security.md 表面看是一份安全政策声明，实则完整勾勒了 LiteLLM 的三层信任模型：仓库侧用 CodeQL 语言矩阵、OSV 锁定文件扫描与镜像签名等 CI 工程守住 P0 供应链防线；自托管侧以“零遥测、不存数据”换取用户对数据流的完全掌控，同时用 master_key 明确划分使用方责任；托管版则以主密钥静态加密、OAuth 2.0 SSO、审计日志、IP 白名单与区域硬隔离承载平台级承诺。对研究者而言，它是一份附有“复现视频硬门槛”与 P0/P1/P2 赏金规则的操作手册；对部署者而言，它又是一份可直接对照源码与配置落实的安全基线。