v1.2.3 · 2026-07-30（UTC）· 孔放勋

按安全主题组织，版本号作为括号注释。企业 IT 可按主题快速定位。

• 已知风险（明文存储）
• 一、传输安全
• 二、知识安全
• 三、编排安全
• 四、审计与存储安全
• 五、工程安全
• 六、LLM API Key 透明度
• 报告漏洞

sofagent 是一个 FDE Agent——底层引擎是纯本地 Harness 中间件（约束中间层），数据不出本机——但以下数据以明文 Markdown 存储，请评估风险：

安装后数据目录结构（~/.sofagent/）：

~/.sofagent/
├── data/          ← 用户可见运行时数据（审计/知识库/反思/任务日志）
├── internal/      ← 引擎内部状态（checkpoint / .git-shadow / watch.yml）
├── bin/           ← CLI 入口
└── skill/         ← Skill 文件

当前状态（v1.2.3）：

• ✅ 脱敏：sanitize() 管道扫描 API Key / 密码 / 手机号，写入前自动打码
• ✅ 数据保留：cleanup.sh 支持 --purge --before 定时清理 + tar.gz 归档
• ✅ 审计日志：task-record.sh 独立审计日志 + task/logs 追溯双通道
• ⚠️ 明文存储：data/ 下文件仍为 Markdown 明文，未做加密
• ⚠️ 当前限制：数据明文存储 + LLM 自评无外部基准。GDPR / 等保 / SOC2 场景需额外加密措施。age 加密预计 v1.3.0（目标 2026 年 Q3）落地。合规审查员请注意：v1.2.x 版本不适合直接用于强合规场景，需配合外部加密卷（gpg / disk encryption）。

在 age 加密（目标 v1.3.0）交付之前，建议：

1. 设置 ~/.sofagent/data/ 目录权限为 700：chmod 700 ~/.sofagent/data/
2. 将 ~/.sofagent/ 父目录放在加密文件系统上（如 macOS APFS 加密卷）
3. 定期轮换 ~/.sofagent/data/ 中的历史审计数据

• data/ 目录权限建议 700（用户可见运行时数据）；~/.sofagent/internal/ 目录权限 700（引擎内部状态）。同一服务器其他用户若有 root 权限可读

企业环境建议：

• 对 data/ 目录做 gpg 加密或放在加密卷上
• 脱敏/保留/审计能力已在 v0.71 落地，详见 企业部署指南

🔴 OpenClaw channel 审计结论（v1.1.8 开发前置核实）：OpenClaw 本地回环 ws:// 明文传输、无 TLS——第 3 层 sofagent 应用加密是唯一保密防线。因此 federation channel 只搬运密文帧（iv‖tag‖ciphertext），绝不触碰明文 payload；即使 channel 被中间人劫持，内容仍不可读（纵深防御原则，不依赖 channel 自身安全性）。

风险（已修复）：联邦配对使用的 SOFAGENT_FEDERATION_TOKEN 曾通过环境变量传递， 在进程列表（ps e、/proc/*/environ）中明文可见。

修复：v1.2.3 已将 token 从环境变量迁移至 ~/.sofagent/federation.token 文件读取（权限 600）， 不再在进程列表中暴露。详见 engine/core/src/crypto/pairing.ts 的 readTokenFromFile()。

影响范围：v1.1.0 - v1.2.2（已修复于 v1.2.3）

⚠️ HMAC key 分发安全（v1.1.8）：路径 C 的 HMAC 签名密钥如与 federation.json 同放在 USB 等可移动介质上，攻击者获取介质即可伪造 .sig 文件。建议 HMAC key 通过独立渠道（如密码管理器 / 加密邮件）分发，不与 federation.json 同介质存储。

⚠️ 企业环境警告：v1.1.4 的 USB federation 曾是基础检测模式、无签名校验；自 v1.1.5 起已加入 HMAC 签名校验。

企业部署建议（v1.1.6）：

• 不要在共享/公共设备上启用 USB federation 自动检测
• 如需使用，插入 U 盘前先在隔离设备上检查 federation.json 内容
• 生产环境等 v1.1.5 的签名校验上线后再启用

detectSofagentUsb() 源码见 engine/daemon/src/usb-detect.ts，错误处理完善（设备不存在/文件不存在/JSON 解析失败都 try-catch 返回明确错误）。内容安全校验自 v1.1.5 起由 HMAC 签名校验覆盖（.sig sidecar + timingSafeEqual），v1.1.9 升级为全量签名（usb-signature.ts：HMAC-SHA256 路径 POSIX 归一化 + 字典序 + SHA-256 内容哈希串联，详见上方「USB 完整运行时攻防表」）。

通过 openclaw:im 推送的知识摘要不含 restricted 内容（sensitivity 双重过滤），但 internal 内容可能含项目内部信息。openclaw:im 通道的安全性由 OpenClaw 保证（本地回环 ws://，摘要内容不含结构化密钥格式，redactForPrompt 管道同样适用于通知内容）。

「Node 便携版 + 启动脚本」方案——IT 用 sofagent-daemon create-usb-key 写入 U 盘（Node 便携版 + sofagent dist + 三平台启动脚本 + federation.json + 空 knowledge/），员工双击 start 3 秒联邦在线，拔盘零残留。两道防线：HMAC-SHA256 全量签名防篡改（daemon/src/usb-signature.ts，路径 POSIX 归一化 + 字典序 + 内容哈希串联，不含 mtime，确定性可复算）+ knowledge/ AES-256-GCM 磁盘加密防失窃（复用 v1.1.8 core/crypto/aes-gcm.ts，密钥 32 字节存 U 盘 federation.json 的 key 字段——U 盘本身即信任根，防的是「丢盘后 knowledge/ 被读」）。

⚠️ 密钥模型边界（U2 决策）：AES key 明文存 U 盘 federation.json——拿到 U 盘的人可读出 key 再解密 knowledge/。「拿到盘也解不开」需 PBKDF2/Argon2 密码派生（启动时输入密码），与「双击 start 3 秒联邦在线」体验冲突，v1.1.9 保持简单模型，v1.2.x 再评估密码保护。

⚠️ 签名排除项：runtime/（Node 便携版二进制，各平台不同）不纳入 HMAC 签名——被替换的 runtime 二进制在签名保护之外，企业 IT 应通过官方渠道制作 U 盘并核对 Node 版本。.sofagent-signature 自身亦排除。

⚠️ HMAC 密钥双轨制（U3 决策）：本机场景复用 ~/.sofagent/usb-secret.key；U 盘运行时从 U 盘 federation.json 的 hmacKey 字段读取（便携化要求）。两个密钥源按 startUsbRuntime vs 本机 daemon 场景切换，v1.2.x 再评估统一。

core/memory-contract.ts 定义 Sensitivity（public/internal/restricted），DEFAULT_SENSITIVITY='internal' 为 safe-by-default，restricted 绝不默认。语义是可见性分级而非加密——restricted 内容在 knowledge status 聚合时只计数不返回内容，但明文存储不变。

core/src/security/trust-grading.ts 的 resolveTrust 缺省 internal；TRUST_ORDER official>internal>user>web；web+restricted 组合直接丢弃；RAG 召回 sortByTrust。

6 阶段流水线经 LLMProvider 接口抽象；v1.1.7 默认使用 MockLLM（确定性、无外部调用），RealLLM 在 v1.1.8 才接入。LLM 仅读取 think.md/知识库内容并产出结构化事实/概念，不回写代码、不执行命令、不访问网络。注入隔离见 daemon/src/dream-cycle/ 的 system-role 声明与返回 schema 校验（P2-5）。

素材仅 log.md + health-report.md（restricted 在生产侧已被 sensitivity 过滤，不进通知）；通道复用 push-target（daemon:notice + openclaw:im outbox），仅本机/联邦内通知，非 v1.2.1 规划的对外 Webhook/飞书推送；失败静默不阻塞 dream-cycle / health 主流程。

2026-07 行业研报对「知识库作为 Agent 可信调用载体」提出的 4 道关卡，与 sofagent 安全模型同构：

• 权限实时回连核验：研报强调数据入口权限必须实时回连核验、不静态拷贝。对应 sofagent 审计 A14（知识库越权：事后审计而非运行时阻断，见 LIMITATIONS §五）——当前为事后发现，运行时阻断是 v2.x 方向（计划中，参见 ROADMAP.md）。
• 受控 Action + 全链路审计：研报的 Action（前置·权限·幂等·副作用·审计）与 sofagent「模型提建议、审计引擎控执行」同一原则（见 DEVELOPMENT §八 财务报销沙盒）。
• 权限隔离（Entity Resolution）：多源知识需先解析实体归属再授权，避免越权拼接——对应 knowledge/ 的实体归属与 A15 约束验证。

📖 来源：温故知新 2026-07-21（行业研报《企业知识库进阶》《Ontology Runtime 企业级架构落地》）

⚠️ A9 注入检测局限——编码绕过：A9 正则检测覆盖常见中文"忽略类"指令、英文"ignore 类"指令，以及 leet speak 变体（1gn0r3 → ignore，通过 normalizeLine() 反转 + ×0.8 降权匹配）。但不覆盖：① Unicode 同形字替换（西里尔字母 а 替换拉丁 a）；② Base64/hex 编码后的注入 payload。这些绕过手法依赖语义分析（非纯正则可覆盖），规划在 v1.3.x 评估 LLM 辅助检测。

每个 Sub Agent 的工具集按职责域划分，无重叠。详见各 Sub Agent 配置。

每个 Sub Agent 的 systemPrompt 前置四层约束加载链（SKILL.md 宪法层不可被 workflow YAML 覆盖）；同文件冲突检测 WARN（filesValue 文件级 LWW 合并的提醒，不阻塞）；SubAgent 继承 LangGraph createReactAgent 默认工具集（read_file/write_file/edit_file/glob/grep/execute），主 Agent 仅保留 task 委派工具（tools: []）。

单 peer 5s 超时按离线跳过不阻塞；全部 peer 离线 / federation 整块失败 → 退化纯本地查，不影响 MCP server 运行（best-effort）。

⚠️ 审计日志全局共享：当前版本审计日志写入全局 ~/.sofagent/data/audit/history.jsonl，不做项目级隔离。多项目场景下审计记录会混合存储。按 git 仓库隔离计划在 v1.3.x 落地。

~/.sofagent/
├── data/          ← 用户可见运行时数据（审计/知识库/反思/任务日志）
├── internal/      ← 引擎内部状态（checkpoint / .git-shadow / watch.yml）
├── bin/           ← CLI 入口
└── skill/         ← Skill 文件

审计记录升级为可问责的动作凭证：ActionGovernance（actor/timestamp/targetEntity/context）+ DecisionProvenance 决策溯源组，写入 history.jsonl。提供事后可追溯性，但不在运行时阻断——Agent 仍可伪造 actor 字段（信任模型同 §审计工具信任模型）。防篡改 HMAC 签名详见下方「HMAC 签名（v1.1.8+ 已落地）」。

history.jsonl 自 v1.1.8 起支持 HMAC-SHA256 签名（密钥来自 ~/.sofagent-key）。有密钥时每条记录签名，Agent 无法在无密钥情况下伪造签名；无密钥时降级为 SHA-256 hash chain（Agent 可重算整链，仅事后可追溯非强防篡改）。--doctor（v1.2.0 起）会实际调用 checkHistoryChainIntegrity() 校验链完整性。建议高安全场景配置 ~/.sofagent-key 启用强校验。

sofagent-audit（v0.92+）是 TypeScript CLI，执行 execFileSync('git', ...) 读取 git diff 和文件系统。不使用 eval、不 spawn shell、不执行外部脚本。命令参数使用数组传入（['diff', '--unified=3', range]），range 参数经过正则校验 [a-zA-Z0-9~^.\-]，无命令注入风险。

数据访问：审计工具只读取 git diff 输出和 data/task/logs/ 目录下的 Markdown 文件，不发起网络请求，不写入任何文件。

信任边界：审计工具本身是确定性的——给定相同的 git diff 和日志，输出相同。但审计 A7/A8 的结果依赖 Agent 日志的真实性（Agent 可以伪造日志）。这不是审计工具的安全漏洞，是架构级别的信任模型选择。详见 LIMITATIONS.md（「审计工具信任模型：Agent 自我报告」节）。

⚠️ A14/A15 是 commit 时审计，不是运行时阻断。 Agent 在 commit 前仍可能访问受限数据——审计只能事后发现。这不是运行时沙箱。

history.jsonl 存储审计拦截记录（含被拦截的 diff 摘要）。以下为当前访问模型：

缓解：sanitize() 管道在写入前对密钥/密码/手机号打码。但这不是加密——Agent 可以从原始 git diff 中直接读到敏感内容。根治方案（age 加密 + 独立审计存储）推到 v2.x（计划中，参见 ROADMAP.md）。

sanitize() 管道在写入 history.jsonl、think.md、task/logs 等文件前自动执行：

• 密钥打码：匹配 sk-/Bearer/api_key/password= 等模式 → 替换为 ***REDACTED***
• 手机号打码：匹配 11 位手机号格式 → 138****1234
• 密码字段打码：匹配 password[:=]\s*\S+ → password=***

以上为掩码（masking）非加密——原始数据仍在 git diff 中可读。sanitize() 只保护写入 data/ 的副本，不保护源头。

文件权限：data/ 目录权限建议 700（用户可见运行时数据）；~/.sofagent/internal/ 目录权限 700（引擎内部状态）。install.sh 和 --init 自动设置。同一服务器其他非 root 用户无法读取。root 用户可读——如需防 root，建议将 data/ 放在加密卷上。

审计拦截记录以 JSONL 明文存储在 data/audit/history.jsonl，目录权限 0o700、文件权限 0o600（v1.1.3 起收紧）。仅追加写入（appendFileSync），不覆盖、不删除。历史记录供编排引擎和进化引擎本地读取。

⚠️ 以上绕过路径均依赖 Agent 的"自觉"——这是 sofagent 架构级别的信任模型选择：审计工具是协助人类监督，不是替代人类监督。已知绕过路径详见 LIMITATIONS 已有信任模型描述。

⚠️ 企业高安全场景：config.yml 篡改可绕过审计规则（如关闭规则、放宽阈值）。建议：① CI 侧独立校验 config 完整性（sofagent-audit --diff 兜底，hook 可绕 CI 不可绕）；② 文件权限锁（chmod 600 .sofagent/config.yml，仅受信用户可写）。与已有 --no-verify CI 兜底建议呼应。

1. CI 侧兜底（推荐）：在 CI/CD pipeline 中独立运行 sofagent-audit --all， 使用 CI 环境内受保护的 config.yml 副本，不依赖开发机上的配置文件。
2. 文件权限加固：chmod 444 .sofagent/config.yml 将配置设为只读。 注意：此方法不能防止 Agent 以 root/同用户身份强制写入， 但能防止意外修改。
3. 完整性校验：使用 tools/sign-config.mjs 对 config.yml 签名， 定期运行 sofagent-audit --doctor 检查配置完整性。

💡 更多本地开发缓解措施详见 LIMITATIONS.md → 本地开发紧急缓解措施（chmod 400、git hooksPath、定期 doctor）。

受影响场景：

• 不上 CI 的小团队或个人项目（风险最高）
• Agent 具有文件系统写入权限的任何场景
• sofagent-audit --init 后未额外加固配置权限的场景

sofagent daemon 是本地文件系统监控守护进程，其行为边界如下：

💡 企业集中收集（v1.2.1）：v1.2.1 已支持 Webhook 推送（飞书/钉钉/企微），企业 IT 可配置 webhook 字段实现实时告警推送。如仍需集中收集审计日志（如用 Filebeat / Logstash / Fluentd 采集），可定时轮询 data/audit/history.jsonl（append-only、JSONL 明文），转发至 SIEM / 企业日志平台。注意 history.jsonl 为明文存储，转发前建议配合外部加密卷或 age 加密，避免敏感 diff 摘要外泄。

daemon 源码见 engine/daemon/src/：fs-watch.ts（文件监听）、cron.ts（定时巡检）、snapshot.ts（快照）、usb-detect.ts（USB federation 检测，v1.1.4+）、dream-cycle/（Dream Cycle 6 阶段管道，v1.1.7+）、inspectors/knowledge-health.ts（知识健康巡检，v1.1.7+）、commands/knowledge-status.ts（知识状态聚合命令，v1.1.7+）、federation/（联邦查询，v1.1.8+）、usb-signature.ts（USB HMAC 签名，v1.1.9+）、usb-key.ts（USB key 创建，v1.1.9+）、usb-runtime.ts（USB 运行时启动，v1.1.9+）、notify.ts（统一通知接口，v1.1.3+）。

install.sh 是 sofagent 的一键安装脚本。以下是其完整行为清单，供安全审查：

• ❌ 不会 sudo——所有操作在用户权限范围内
• ❌ 不会改系统文件——不碰 /etc、/usr、/System
• ❌ 不会联网下载额外内容
• ❌ 不会执行远程脚本（--remote 模式只做 git clone 官方仓库）
• ❌ 不会收集或上传任何用户数据

install.sh 拆分为以下模块，便于逐模块审查：

@langchain/langgraph 是 sofagent 编排引擎的正式依赖（提供 createReactAgent）。v1.2.0 起从 DeepAgents 迁移为正式依赖。

🔴 Breaking Change（v1.0.7）：ao（agency-orchestrator）已完全退役。v1.0.6 用户升级到 v1.0.7 后需手动卸载：npm uninstall -g agency-orchestrator。编排引擎已全面迁移到 LangGraph createReactAgent，ao 代码路径全部移除。

供应链安全建议：

• 每次 npm install 后运行 npm audit
• 内网环境建议预装 @langchain/langgraph 并验证安装通过后再部署

automerge@1.0.1-preview.7 风险声明（v1.1.9 F-04）：

automerge@1.0.1-preview.7 为 preview 版（非稳定版），API 可能在后续版本变更。截至 v1.1.9 发布时，npm 上尚无 ≥1.0.0 的 automerge 稳定版（仅 preview 和 2.0.0-alpha）。daemon 精确锁定版本号（"automerge": "1.0.1-preview.7"，非 ^ 前缀）避免意外升级。如 automerge 发布 stable 版本或 breaking change，daemon/src/merge.ts 的 Automerge.change/clone/merge 调用需重新验证。

FORGE fresh-eyes-loop 的 A/B sub-agent 需要 LLM API key。 本节说明 key 的存储、使用、边界。

仅本地环境变量（用户自行配置）：

代码库中零硬编码 key——.env 文件被 .gitignore 排除。

SOFAGENT_LLM_{ROLE}_API_KEY  >  SOFAGENT_LLM_API_KEY  >  OPENAI_API_KEY
   角色专用 key（A/B 分账）     通用 key（共用一把）     OpenAI 兼容默认

• SOFAGENT_LLM_A_API_KEY：A 角色（审查模型，用户自行配置）专用 key
• SOFAGENT_LLM_B_API_KEY：B 角色（工程模型，用户自行配置）专用 key
• SOFAGENT_LLM_API_KEY：A/B 共用一把 key（两个 provider 都是 OpenAI 兼容格式时可用）
• OPENAI_API_KEY：兜底默认（OpenAI SDK 标准环境变量）

key 仅用于：

• ❌ 不上传到任何第三方服务（sofagent 无后端服务器，key 不离开本机）
• ❌ 不写入任何日志文件（usage.jsonl 只记 token 数，不记 key）
• ❌ 不写入 git 历史（.gitignore 排除 .env）
• ❌ 不转发给除目标 LLM 厂商以外的任何端点

用户可自行扫描代码确认无硬编码 key：

# 扫描代码中的 key 硬编码（不应有结果）
grep -rnE "sk-[a-zA-Z0-9]{20,}" FORGE/src/ engine/

# 确认 .env 在 .gitignore 中
grep -n "\.env" .gitignore

# 确认 usage.jsonl 不含 key（只有 token 计数）
grep -i "api_key\|apikey\|sk-" runs/*/usage.jsonl   # 应无结果

如发现安全漏洞，请通过以下方式私下报告（不要在公开 Issue 中披露）：

1. 邮箱：kong.yao@evfrey.com
2. GitHub Security Advisory：提交私有报告
3. 响应时间：我们承诺在 72 小时内确认收到报告，7 天内提供初步评估。

-----BEGIN PGP PUBLIC KEY BLOCK-----
（待安全团队补充实际公钥）
-----END PGP PUBLIC KEY BLOCK-----

• 确认：7 天内确认收到报告
• 初步评估：30 天内给出初步评估和影响范围
• 修复：根据严重程度排期——高危（数据泄露/权限提升）优先修复并发布补丁版本

本安全策略适用于 sofagent 项目仓库内的所有文件。第三方依赖（如 @langchain/langgraph、OpenClaw）的安全问题请向对应项目报告。

sofagent 基于 MIT 许可证发布，按「现状」（AS IS）提供，不附带任何明示或暗示的担保。作者不对因使用本软件而产生的任何直接、间接、附带或后果性损害承担责任。sofagent 是审计工具而非安全防线——它能检测常见的 Agent 违规模式，但不能保证拦截所有攻击向量。