Caveman 安全与数据流全景：遥测策略、本地存储、Proxy 隔离与安装供应链

Caveman 是一个在 LLM 请求链路上做字节级压缩与可恢复缓存的本地工具集，其“安全”核心在于明确回答三个问题：哪些内容流向哪里、哪些东西只留在本地、哪些边界依赖文件系统而非加密。本文基于仓库的 SECURITY.md 展开，并逐条对照 packages/cli/src/index.ts、engine/ccr 与 proxy/internal 的源码实现，帮你建立一套可验证的 Caveman 数据安全模型：遥测如何默认开启又能彻底关闭、本地数据库为何必须按敏感文件对待、standalone Proxy 为何拒绝非回环监听地址。

支持版本与漏洞报告渠道

文档开篇先声明了两条适用前提：

• 该文档描述的是当前源码仓库的行为，已发布的 release 可能滞后于源码；当策略依赖精确版本时，应核对你所安装的 tag。
• 只有最新稳定版接收安全补丁，旧版本不在修复范围内。

漏洞报告方面，文档明确列出了“不得开公开 issue”的类别：疑似任意代码执行、路径逃逸、凭据泄露、proxy 隔离失效、恢复数据（recovery data）暴露等，必须走 GitHub 私有漏洞报告渠道提交。这与仓库整体的多进程架构相匹配——Caveman 同时存在 CLI 代理、CCR 恢复存储、MCP 服务和 hook 等多个信任边界，公开披露前修复（private reporting）是这类项目的标准做法。

数据流总览：六种表面，去向各不相同

理解 Caveman 数据安全的第一步，是分清它暴露的六种数据表面（surface）各自的去向。官方给出的数据流摘要如下：

表面	是否需要 Caveman 账户	内容去向
Caveman skill 与 classic 输出 hook	否	本地 agent 上下文与本地文件，这些组件不直接调用 Caveman 服务
Local Proxy + Engine	否	请求内容（可能经变换）与 provider 凭据发往 agent 所选的 provider；恢复原件留在本地 CCR 存储，除非 agent 稍后取回并发送
Agent SDK observe-only	否	直连所配置的 provider，不经过 Caveman gateway 的遥测
托管 Caveman gateway	是	请求与响应流经 Caveman Cloud 和所选 provider，不要将其视为仅本地
匿名 CLI 遥测	否	默认上报（可退出）的内容无关用量事件，含处理/节省的 token 数；首次交互运行时打印披露；caveman telemetry off 或 DO_NOT_TRACK=1 可永久关闭
已认证 dashboard 同步	是	存在凭据时，本地 span 元数据与聚合结果发往 Caveman Cloud，原始 prompt 与响应体被排除

文档同时划清了一条责任边界：你的模型 provider、MCP 服务器、浏览器目标、agent 插件以及 agent 运行的任何命令，都是独立的数据处理方。Caveman 无法使这些工具离线或私有化——这一点在评估整体隐私暴露面时容易被忽略，例如开启托管 gateway 后，即便 Caveman 侧不做内容遥测，请求内容本身也已经流经 Caveman Cloud。

匿名 CLI 遥测：默认开启、可退出、披露先行

默认行为与披露机制

遥测默认开启且为 opt-out，但默认从不静默：

caveman telemetry status
caveman telemetry on
caveman telemetry off

• 首次执行交互式命令时，CLI 会把决定持久化（附带一个稳定的匿名标识符），并打印一行披露，写明作用域与关闭开关；
• 披露运行之前什么都不会发送；CI/非交互运行从不发送，也从不持久化默认值；
• 登录不是前提条件，匿名事件发往 https://api.caveman.so/telemetry/cli。

控制优先级（从高到低）

1. 非空且非零的 DO_NOT_TRACK 强制关闭遥测；
2. CAVEMAN_TELEMETRY=1|true|on 启用，其余非空值禁用；
3. CI 与非交互运行永远关闭；
4. 否则应用 ~/.caveman-cloud/config.json 中持久化的选择——任何版本（包括旧 opt-in 提示中回答的 "no"）留下的持久化 opt-out 会被永远尊重；
5. 没有持久化选择时即为开启，并在首次交互式命令时打印披露后持久化。

另有 CAVEMAN_TELEMETRY_URL 可覆盖上报目的地（主要用于测试）。遥测请求 1.5 秒超时，且失败不会让 CLI 命令本身失败。

源码印证：优先级链与单一收口点

在 packages/cli/src/index.ts 中可以直接看到这套优先级链的实现，telemetryState() 按顺序判定：

// 非空且非零的 DO_NOT_TRACK 直接返回 off
if (dnt !== undefined && dnt !== "" && dnt !== "0") return { state: "off", source: "env", ... };
// CAVEMAN_TELEMETRY 仅在 1/true/on 时启用，其余非空值禁用
if (v === "1" || v === "true" || v === "on") return { state: "on", ... };
return { state: "off", source: "env", ... };
// CI 或非交互运行强制关闭
if (envTruthy(process.env.CI) || !interactive()) return { state: "off", source: "runtime", ... };

源码注释特别强调 telemetrySendable 是“每个发射器都必须通过的单一收口点（single choke point）”，且默认值只有在持久化成功之前不可发送——这保证了“披露先于发送”不只是文档承诺，而是由发送门控强制的。运行时行为由 packages/cli/tests/telemetry.runtime.mjs 等测试持续验证。

作用域版本：披露加宽时如何处理

当披露的作用域变宽时，持久化的决定会携带其制定时所处的措辞版本。更宽的作用域会在下一次交互式命令时重新打印一次披露并提升存储的版本号——它从不重新询问、从不翻转已有决定、从不触碰持久化的 opt-out。当前版本 4 新增了 token 总量字段。

事件字段白名单

匿名事件可以包含：

• 随机匿名 ID；CLI 版本；操作系统；架构；Node 主版本号；
• 白名单内的命令、子命令与已知 agent ID；时长；结果；宽泛的错误类别；
• 本地 Proxy 处理与节省的 token 数——上报为距上次事件的增量而非累计总量，且始终携带测量基准（inferred，即 tokenizer 估算，绝非账单计数，绝无美元数字）。应把它读作对本地存储的聚合；当没有存储或 Proxy 二进制时，字段直接省略而非报零。机器上的首次读取只记录基线、不上报任何内容，因此一份早于该披露就存有流量的数据库不会被追溯上报；
• 本地 Proxy 会话聚合：请求与 token 数、压缩次数、缓存读写次数、测量模式、headline 抑制状态；
• 首次运行聚合扫描计数：来自本地 Claude Code 或 Codex 历史，含会话数、轮次、token、估算削减量、扫描耗时、账户是否已连接；
• Caveman MCP 工具名、时长与结果。

增量语义在源码中对应 telemetryTokenDelta()：它读取磁盘上的水位线（watermark）、计算本次事件的 delta 并推进水位，注释明确说明“遥测从同意时刻起算，而不追溯”。

匿名遥测绝不含：prompt 或补全正文、原始 argv、文件路径、工具参数或结果、provider 凭据、本地数据库行/文件。文档把“源码级强制 + 运行时测试”的位置直接标出，即 packages/cli/src/index.ts 与 packages/cli/tests/telemetry.runtime.mjs。

已认证的 Caveman Cloud 流量

• 已连接命令需要存储的凭据或 CAVE_TOKEN；beta 期间新登录被阻止；
• 同步只发送用量元数据与聚合结果，从不发送 prompt、响应、凭据、工具证据或源码路径；
• 订阅流量不含美元数字，同步的本地数据保持 inferred 基准；
• 托管 gateway 模式会让请求与响应内容穿过 Caveman Cloud；本地模式只发给你的 provider；
• CAVEMAN_OFFLINE=1 禁用权益（entitlement）刷新与同步，但已开启的遥测还需 CAVEMAN_TELEMETRY=0 或 DO_NOT_TRACK=1 才会停发——两个开关互不替代。

本地存储：哪些文件必须按敏感数据对待

除非有文档记载的环境变量覆盖，运行时数据存于 ~/.caveman/，账户/配置状态存于 ~/.caveman-cloud/。关键文件：

• ~/.caveman/caveman.db：每请求元数据、用量、本地节省估算、变换后前缀替换及相关本地证据。常规请求行不存原始请求/响应体，但变换后的内容可能保留在此库中，应按敏感数据处理；
• ~/.caveman/ccr.db：可恢复变换的精确原件，可能包含 prompt、内嵌于内容的凭据和工具结果，必须按敏感数据处理；
• 显式 caveman trial 运行会把原始请求载荷存入本地 trial_payloads 表用于回放，报告中排除这些载荷；
• 本地 learn/首次运行扫描只读取受支持的 Claude Code 与 Codex 历史文件，聚合报告与状态写在本地；原始会话内容不进入匿名遥测或已认证的扫描同步；
• ~/.caveman-cloud/config.json：端点、项目/账户指针、遥测决定及其他 CLI 状态；
• 账户凭据：macOS 可用时存 Keychain，否则写 ~/.caveman/credentials 且文件权限 0600；CAVE_TOKEN 归父环境所有。

CLI 侧对这类文件普遍采用 0o600 写入——例如 packages/cli/src/index.ts 中 configPath() 的落盘与 atomicWriteFile 默认 mode 均为 0o600，与文档声明一致。

CCR 存储的权限与预算控制

CCR 的 SQLite 文件及 sidecar 创建或被收紧到 0600，并拒绝不安全的符号链接/非普通文件路径。需要强调：这是文件系统访问控制，不是数据库加密。默认保留的 CCR 载荷预算为 512 MiB，可用 CAVEMAN_CCR_MAX_BYTES 调整；已存在的恢复句柄永不被淘汰，预算耗尽时新的恢复写入失败，有损变换必须回退为直通（pass-through）。

源码层面，engine/ccr/store_sqlite.go 定义了 DefaultMaxStorageBytes = 512 << 20，并在 Open 时解析 CAVEMAN_CCR_MAX_BYTES（必须是正整数，否则报错）；configureStorageBudget 会把预算翻译成 SQLite 的 PRAGMA page_size 页数上限与 journal_size_limit。父目录安全检查在 engine/ccr/sqlite_parent_security_posix.go 中：

// 组/世界可写的父目录（无 sticky 位）会拒绝
if info.Mode().Perm()&0o022 != 0 && info.Mode()&os.ModeSticky == 0 {
    return fmt.Errorf("sqlite parent %q is group/world writable", path)
}

注释解释了原因：带 sticky 位的共享临时目录（/tmp、macOS /private/tmp）能阻止其他用户替换这个 0600 文件，而没有 sticky 位的组/世界可写父目录则不能。

最后，文档对卸载做了明确警示：卸载只移除已安装集成与 hook，不要假设它会抹除运行时数据库、报告、备份或凭据；如需删除数据，请单独检查 ~/.caveman/ 与 ~/.caveman-cloud/。

本地 Proxy 安全：回环是唯一信任边界

caveman start 默认监听 127.0.0.1:8787。standalone Proxy 的入站不鉴权——接受每一个入站请求，因为“回环 + 单操作员隔离”本身就是安全边界。因此启动时拒绝任何非回环的 --host 或 CAVEMAN_LISTEN 取值。

这一点在 proxy/internal/config/config.go 中是硬错误而非警告：

// 绑定空地址、通配符或非回环 host 都会暴露所有……
return fmt.Errorf("listen address %q must be loopback host:port", listen)
// ...
return fmt.Errorf("listen address %q is not loopback; standalone proxy has no inbound authentication", listen)

且 proxy/internal/config/config_test.go 有专门的测试断言：非回环监听地址必须被 Load 拒绝，回环地址必须被接受。文档还特别提醒：防火墙不会把 standalone 模式变成带鉴权的外部网关；需要远程访问时应使用托管鉴权 gateway。

上游方向，Proxy 的出站客户端应用 SSRF 控制。从 proxy/internal/standalone/standalone.go 的注释可以看到，默认的受保护客户端会阻断 loopback/私有/链路本地/元数据地址，且“除非显式加白名单，否则这类地址保持阻断”。压缩链路则是恢复优先（recovery-first）：解析失败、变换不安全、持久恢复不可用、存储失败，或结果不比原文小，都会原样返回原始字节而不是有损替换。这降低了内容损坏风险，但文档同时明确：它不会让模型输出或第三方工具变得可信。

安装与更新时的网络访问

网络安装器从 GitHub 拉取源码，可能调用 npm 或 agent 专属 registry；各 agent 的独立安装器可能接触 Anthropic/GitHub、Gemini extension、npm 或其他已配置 registry。完整性验证分两级：

• detached hook 安装：从不可变（immutable）release tag 下载文件，并校验 SHA-256 manifest 条目；
• 运行时 companion 设置：下载带签名的 checksum manifest，安装前逐个校验每个二进制的签名与 SHA-256。

文档给出了一条“先审查、后安装”的替代路径：clone 固定 tag 后运行本地安装器，而不是把远程脚本直接管道进 shell。并指出其局限：只有当所需依赖与运行时二进制在本地已可用时，源码 clone 才能避免安装器的下载行为。

扫描器误报速查

最后，文档预答了两类常见的安全软件告警，避免使用者误判为恶意软件：

• Windows Defender 或 SmartScreen 可能标记 install.ps1，因为它把下载的脚本管道进 PowerShell 并写入 agent 配置。若策略禁止 pipe-to-shell，应 clone 固定 tag 的源码先审查再安装；
• 通用扫描器可能标记 caveman-compress，因为它重写用户指定的文件并创建备份——这种文件变更是有意行为。启用前应先审查 skills/caveman-compress/ 目录（其中 skills/caveman-compress/SECURITY.md 专门说明了该 skill 的安全边界）。

小结：Caveman 的信任边界清单

把散落各节的结论收拢成一张操作清单：

1. 内容不外泄的默认配置：本地 Proxy + Engine 模式下，请求内容只到你的 provider；CCR 原件留在本地，但 ccr.db 与 caveman.db 都必须按敏感文件管理（权限、备份、销毁）；
2. 遥测三把锁：caveman telemetry off 持久化关闭，DO_NOT_TRACK=1 环境变量强制关闭，CAVEMAN_OFFLINE=1 只管云同步不管遥测；
3. 不要监听公网：standalone Proxy 无入站鉴权，任何远程需求走托管 gateway；
4. 供应链核验：安装前审查固定 tag 源码，或确认 hook 安装的 SHA-256 manifest 与运行时二进制的签名校验生效；
5. 卸载不等于销毁：清理 ~/.caveman/ 与 ~/.caveman-cloud/ 是独立步骤。