@sofagent/audit

命名说明：本目录是随安装分发的 engine 侧实现；维护者 SOP 脚本见同名 tools/audit；出口治理的裁决挂链在本模块 egress-audit。

v1.7.0 · 提交时审计 —— 扫描 git diff，检查 Agent 是否遵守工作纪律。

安装后运行：sofagent audit --init（一键初始化 config + hook + 冒烟测试）

最小运行时直接依赖（js-yaml + archiver，传递依赖随 @sofagent/core 引入）。TypeScript 实现。Node.js 18+。

快速开始

# 方式一：全局安装（伞包单入口——npm 通道唯一形态，含完整依赖树）
npm install -g sofagent

# 方式二：项目内安装
npm install --save-dev @sofagent/audit

# 方式三：一次性运行（不安装）
npx -y -p sofagent sofagent audit --diff HEAD~1..HEAD

安装后获得以下命令：

| 命令 | 来源 | 说明 | |---|---|---| | sofagent audit | @sofagent/audit | 审计 CLI 主入口 | | sofagent core | @sofagent/core | 核心运行时（含 verify / doctor 子命令） | | sofagent orchestrator | @sofagent/orchestrator | 编排模块 CLI（含 compose / compare 子命令） |

💡 其他常用命令：sofagent mcp（@sofagent/mcp，v1.2.0 起拆分为独立包）、sofagent daemon（@sofagent/daemon）、sofagent think（@sofagent/think）等均为各自独立 npm 包的 bin 命令。MCP 支持请安装 @sofagent/mcp 独立包。

CLI 用法

基本审计

# 审计最近一次提交
sofagent audit --diff HEAD~1..HEAD

# 带任务描述（用于 A3 越界检测）
sofagent audit --diff HEAD~1..HEAD --task "修复登录页 bug"

# 审计整个 PR
sofagent audit --diff origin/main..HEAD

# JSON 输出（适合 CI/CD）
sofagent audit --diff HEAD~1..HEAD --json

# CI 模式（= silent，紧凑输出。⚠️ 不隐含 --strict，如需严格模式请显式加 --strict）
sofagent audit --diff HEAD~1..HEAD --ci --json

全部参数

| 参数 | 说明 | 默认值 | |---|---|---| | --diff <range> | git diff 范围 | HEAD~1..HEAD | | --task <desc> | 任务描述（A3 越界检测） | — | | --strict | 严格模式：无日志时 A7 返回 FAIL 而非 WARN | off | | --silent | 沉默模式：跳过依赖 Agent 日志的规则（A3/A7/A8/A14 等），走 diff 启发式 | off | | --ci | CI 模式（= silent，紧凑输出） | off | | --json | JSON 输出：{ exitCode, rules } | off | | --webhook <platform> | 推送平台：dingtalk / feishu / wecom | — | | --webhook-url <url> | Webhook URL（或用 SOFAGENT_WEBHOOK_URL 环境变量） | — | | --root-cause | 分析审计历史，输出根因报告 | — | | --regression <dir> | 对指定目录跑回归验证 | — | | --install-hook | 安装 git commit-msg hook | — | | --mcp | 启动 MCP Server 模式 | — | | --revert <snapshot-sha> | 恢复到指定快照（回溯能力） | — | | --timeline [N] | 查看快照时间线（回溯能力，N 为显示条数） | 10 | | ontology view | 本体人类可读视图 | — | | --version | 版本号 | — | | --help | 帮助 | — |

退出码

| 码 | 含义 | |:---:|---| | 0 | 全部规则通过 | | 1 | 有警告（WARN） | | 2 | 有违规（FAIL）/ 非 git 仓库 |

装后验证

sofagent-verify 已迁至 @sofagent/core 包，请使用：

# 完整检查（文件/Hook/权限/daemon/脱敏/断路器/平台兼容性）
sofagent core verify

# 快速模式（4 项核心检查，5 秒出结果）
sofagent core verify --quick

# 只显示失败和警告项
sofagent core verify --quiet

# JSON 输出（CI/CD）
sofagent core verify --json

# 手动指定平台
sofagent core verify --platform workbuddy

# 运行 doctor 诊断
sofagent core doctor

| 参数 | 说明 | 默认值 | |---|---|---| | --quick | 仅 4 项核心检查 | — | | --quiet | 只显示失败和警告 | — | | --json | JSON 机器可读输出 | — | | --platform <name> | 手动指定平台 | 自动检测 |

审计报告（session-report）

每次审计后生成 data/audit/session-report.md（安装后位于 ~/.sofagent/data/audit/session-report.md），包含：

• 审计结果（通过/失败）与 exit code
• 检查数（通过/警告/违规/跳过）、引擎版本
• 变更文件列表与状态

可用 sofagent audit --timeline [N] 查看历史快照时间线（默认 10 条）。

Git Hook 集成

# 自动安装 commit-msg hook
sofagent audit --install-hook

# hook 会拦截违规提交（exit code 2 时阻止）

💡 注意：sofagent audit 进程自身 exit=2（FAIL 拦截），但经 git commit-msg hook 转发后，shell 看到的是 git 的 exit=1。测试拦截行为时以 sofagent audit 直接调用的 exit code 为准。

CI/CD 集成（GitHub Actions 示例）

# .github/workflows/audit.yml
name: sofagent-audit
on: [pull_request]
jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
        with:
          fetch-depth: 0  # 需要完整 git history
      - uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5
        with:
          node-version: '18'
      - run: npm install -g sofagent
      - run: sofagent audit --diff origin/main..HEAD --ci --json

Webhook 推送

# 环境变量方式（推荐）
export SOFAGENT_WEBHOOK_URL="https://oapi.dingtalk.com/robot/send?access_token=YOUR_TOKEN"
sofagent audit --diff HEAD~1..HEAD --webhook dingtalk

# 参数方式
sofagent audit --diff HEAD~1..HEAD --webhook feishu --webhook-url "https://open.feishu.cn/open-apis/bot/v2/hook/YOUR_ID"

有 WARN/FAIL 时自动推送（fire-and-forget，推送失败不影响审计结果）。

MCP Server

sofagent audit --mcp 启动内置 MCP Server（JSON-RPC 2.0 over stdio，协议版本 2024-11-05）：

• 工具：run_audit（返回 { exitCode, verdict, fileCount, triggeredRules[], allRules[] }，verdict ∈ PASS/WARN/FAIL）/ get_think / write_think
• 资源：think://latest / logs://today / audit://last-report
• 完整说明（工具全清单 · 客户端配置 · 角色收窄 SOFAGENT_MCP_ROLES，含 audit 专职面）：见 engine/mcp/README.md

审计规则

默认规则（A1-A11 + A18-A23，共 17 条）

| 规则 | 判定 | 严重度 | 分级 | |---|---|:---:|---| | A1 不碰敏感 | .env / *.pem / id_rsa / 密钥文件被修改 | FAIL | 业务底线 | | A2 不泄密钥 | 代码中出现 API Key（OpenAI / Anthropic / DeepSeek）/ Token / Password 模式 | FAIL | 业务底线 | | A3 不改越界 | 修改文件路径与任务描述不匹配 | WARN | 能力拐杖 | | A4 不删配置 | 配置文件被删除 | FAIL | 业务底线 | | A5 不瞒真相 | commit message 为空或纯占位符（fix/update/wip 等） | WARN | 业务底线 | | A6 不坏构建 | 构建配置文件异常改动 | WARN | 能力拐杖 | | A7 不存盲改 | 被修改文件无读取记录（依赖 .sofagent/task/logs/） | FAIL/WARN | 能力拐杖 | | A8 不逃验证 | 构建文件变更后无测试记录 | FAIL/WARN | 能力拐杖 | | A9 不纳注入 | 代码中存在命令注入风险模式 | FAIL | 业务底线 | | A10 不引毒源 | 依赖包黑名单检测 + typosquatting + postinstall 脚本注入 | WARN | 业务底线 | | A11 不滥资源 | 资源滥用检测（超大文件、大行数删除等，已合并原 E3） | WARN | 业务底线 | | A18 垃圾文件 | 临时文件名模式的垃圾文件（v1.1.5 起提升为默认规则，评估误报率 0/513） | WARN | 能力拐杖 | | A19 commit message 质量 | message 命中黑名单词或过短（防"add"/"test"/"fix" 等低质 message） | FAIL | 工程规范 | | A20 不泄外联 | 数据外传检测（curl/wget POST 外传、WebSocket 外联、DNS 隧道） | FAIL | 业务底线 | | A21 不植后门 | 持久化后门检测（LaunchAgent plist、systemd service、crontab、注册表自启） | FAIL | 业务底线 | | A22 不越权限 | 权限提升检测（全权限 chmod、sudoers 修改、setuid/setgid、owner 变更为特权用户） | FAIL | 业务底线 | | A23 不逃路径 | 路径穿越检测（三级以上目录穿越序列、symlink 逃逸） | FAIL | 业务底线 |

扩展规则（A14-A17 + A24 + E1/E2/E4/E5/E6/E7，共 11 条）

ℹ️ E1-E7 内部规则 ID 为 201-207，预留 101-199 区间给未来默认规则扩展。E3 已并入 A11（行数维度），编号跳号。E5 为 v1.5.7 章一新增（SMB 数据产物审计）；E6 为 v1.5.7 章三新增（OWASP ASI03 提示注入防护——prompt 载体文件的隐藏指令载荷/边界伪造/多轮持续操控，与 A9 单行注入评分判定面互补）；E7 为 v1.5.7 章八新增（决策质量信号——decision-log 输入源首条消费规则：FALLBACK_DEGRADE 高频 ⇒ WARN）。

A14-A17 + A24 + E1/E2/E4/E5/E6/E7 均需 extendedRules: true 启用（DEFAULT_CONFIG=false，opt-in）。仅当 config 解析失败走 safeDefaults 时 fail-closed 强制启用所有扩展规则——这是有意的保护性设计。

| 规则 | 判定 | 严重度 | 分级 | |---|---|:---:|---| | A14 知识库越权 | 访问超出工作流声明范围的知识库页面（事后审计，非运行时阻断） | WARN | 能力拐杖 | | A15 不盲动 | workflow.yml 节点未声明 actions 时 FAIL（防绕过，v1.1.3 起升级） | FAIL | 能力拐杖 | | A16 非授权文件变更 | 非工作流声明范围内的文件被修改（行为级检测，文件路径/扩展名） | FAIL | 工程规范 | | A17 异常批量变更 | 单次提交变更文件数超阈值（行为级检测，变更数量，evidenceMode=filesystem） | WARN | 工程规范 | | A24 交付物落点 | 新增交付物类文件落点须在声明目录白名单内（默认空=全不检，opt-in；越界 FAIL 附替代路径建议） | FAIL | 工程规范 | | E1 不含测试文件 | 测试文件被提交到生产目录 | WARN | 能力拐杖 | | E2 TODO 未声明 | 新增 TODO 未在任务中声明 | WARN | 能力拐杖 | | E4 低注释率 | 新增 >200 行且注释率 < 5% | WARN | 能力拐杖 | | E5 数据产物审计 | SMB 场景：数值勾稽（合计≠明细和 FAIL）+ 来源可溯（数值行缺 source 引用 WARN）+ 口径一致（同字段 unit 冲突 FAIL） | FAIL/WARN | 工程规范 | | E6 提示注入防护 | OWASP ASI03 对位：prompt 载体文件（SKILL/ FDE/ 目录 + SKILL.md/fde.md/role-*.md）新增行中的隐藏指令载荷（HTML 注释/零宽字符）、系统消息边界伪造（[SYSTEM] 伪造前缀）、多轮持续角色操控 | FAIL | 业务底线 | | E7 决策质量信号 | decision-log 输入源（第三通道）：FALLBACK_DEGRADE 高频（≥5）⇒ 主判定面不稳信号（降级是安全行为不判 FAIL，WARN 提示关注频率与根因） | WARN | 能力拐杖 |

⚠️ A15 说明：v1.1.3 起 A15 升级为 FAIL——workflow.yml 节点未声明 actions 时 FAIL（防 Agent 不声明 actions 绕过所有约束）。原 WARN 设计已废弃。

规则分级

每条规则标注 ruleClass：

• 业务底线：违反即破坏交付完整性（安全/边界/追溯）
• 能力拐杖：帮助 Agent 走完正确流程，违反不一定是事故
• 工程规范：代码工程质量的基线要求（文件变更规范、批量变更检测等），违反通常意味着流程失控而非恶意

⚠️ A7/A8 在 --strict / --ci 模式下为 FAIL，非严格模式下无日志时降级为 WARN。

配置

配置文件（可选）

在项目根目录创建 .sofagent/config.yml：

# 扩展规则开关
extendedRules: false

# 任务日志目录
taskLogsDir: .sofagent/task/logs

# 审计历史保留天数
historyRetentionDays: 90

不创建配置文件也能用——所有参数有默认值。

环境变量

| 变量 | 说明 | 默认值 | |---|---|---| | SOFAGENT_DATA | 数据目录（think.md / audit / task/logs） | .sofagent（cwd 下） | | SOFAGENT_WEBHOOK_URL | Webhook URL | — |

设计原则

• 最小运行时依赖：仅 js-yaml（YAML 配置解析），其余用 Node.js 内置模块（fs / child_process / readline / http）
• 焊死的门——审计规则独立只读，Agent 不可篡改审计逻辑
• 不依赖 Agent 运行时配合——看的是 git diff（已发生的历史记录）。A7/A8 日志检查依赖 Agent 写入的 .sofagent/task/logs/ 文件
• 安全第一——range 参数正则校验防注入，execFileSync 数组传参不 spawn shell

开发

⚠️ 单包测试前提：monorepo 未 build 时单包 npm test 可能因依赖 dist/ 而失败。先在根目录 npm run build --workspaces 或按 CONTRIBUTING 流程操作。

git clone https://github.com/KongFangXun/sofagent.git
cd engine/audit

npm ci           # 安装依赖
npm run build    # 编译 TypeScript
npm test         # 运行测试（测试数量以 tools/check/test-count.sh 实测为准）
npm run check    # 类型检查（tsc --noEmit）

⚠️ 构建链产物完整性：verify/ 与 hooks/ 由构建链生成并随 files 字段分发（package.json 的 files 含 hooks/、verify/）——绕过 npm run build 直接改 dist 或手工拷贝会产出残缺包（verify/hooks 缺位 → 安装侧完整性校验与 hook 安装失败）。发版与本地打包一律走标准构建链。

License

MIT