New:Introducing Socket Scanning for VS Code Marketplace Extensions.Learn more →
Get Started

@sofagent/audit

Package Overview
Dependencies
Maintainers
1
Versions
67
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@sofagent/audit

sofagent 提交时审计——扫描 git diff，检查 Agent 是否遵守工作纪律

Source
npmnpm
Version
1.5.4
Version published
Maintainers
1
Created
Source

@sofagent/audit

命名说明：本目录是随安装分发的 engine 侧实现；维护者 SOP 脚本见同名 tools/audit

v1.5.3：规则引擎统一与自测——tool-level 与 git-diff 两套规则定义收敛为单一引擎（一套定义、两种触发时机）· 每条规则强制携带 match/notMatch 正负样例，加载时断言 fail-closed（规则写错当场拒载）· A24 交付物落点规则（出生即带正负样例，24→25）· doctor --refresh 修复闭环（备份 + 一键重置到默认 + 前后 diff）。

v1.5.2：审计对外面——audit_query 只读查询 / ruleset_export 导出与 verify-chain 独立验签 / 结论失效语义（invalidation 三钩子）；出口治理的裁决挂链在本模块 egress-audit。——职责边界见 tools/README.md。

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

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

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

快速开始

# 方式一：全局安装
npm install -g @sofagent/audit

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

# 方式三：一次性运行（不安装）
npx -y -p @sofagent/audit 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 而非 WARNoff
--silent沉默模式：跳过依赖 Agent 日志的规则（A3/A7/A8/A14 等），走 diff 启发式off
--ciCI 模式（= silent，紧凑输出）off
--jsonJSON 输出：{ 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只显示失败和警告—
--jsonJSON 机器可读输出—
--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/audit
      - 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 Server（Model Context Protocol），可被 Claude Desktop / Cursor / Continue / 任何 MCP Client 调用。

启动 MCP Server

# 方式一：通过 CLI 参数
sofagent-audit --mcp

# 方式二：直接调用独立入口
sofagent-mcp

MCP Server 通过 stdio 通信（JSON-RPC 2.0），最小运行时依赖。

MCP Client 配置

通用模板（command: sofagent-audit, args: [--mcp]），各客户端配置文件路径：

客户端配置文件字段
Claude Desktopclaude_desktop_config.jsonmcpServers.sofagent
Cursor设置 > MCPmcpServers.sofagent
Continue~/.continue/config.jsonexperimental.modelContextProtocolServers[]

不装 npm 包直接用 npx：

{
  "mcpServers": {
    "sofagent": {
      "command": "npx",
      "args": ["-y", "@sofagent/audit", "--mcp"]
    }
  }
}

暴露的 Tools（3 个）

Tool说明参数
run_audit对 git diff 跑全量审计规则（A1-A11、A14-A24 + E1-E2/E4，共 25 条），返回结构化报告diff（git range）、task（任务描述）、strict（布尔）、silent（布尔）
get_think读取 think.md 最近 N 条反思条目count（默认 1）
write_think向 think.md 追加一条反思记录lesson（必填）、task（可选）

注：A12/A13 已合并入 A11（不滥资源），编号不再使用。

run_audit 返回示例：

{
  "exitCode": 1,
  "verdict": "WARN",
  "fileCount": 3,
  "triggeredRules": [
    { "name": "A3 不改越界", "status": "WARN", "ruleClass": "能力拐杖" }
  ],
  "allRules": [
    { "name": "A1 不碰敏感", "status": "PASS" },
    { "name": "A2 不泄密钥", "status": "PASS" }
  ]
}

暴露的 Resources（3 个）

URI说明类型
think://latestthink.md 最后一条反思条目text/markdown
logs://today今日任务日志text/plain
audit://last-report最近一次审计历史记录application/json

协议细节

  • 协议版本：2024-11-05
  • 传输层：stdio（stdin 读 JSON-RPC，stdout 写 JSON-RPC，stderr 写日志）
  • 必须先 initialize 才能调用 tools/resources
  • 最小运行时依赖：仅 js-yaml（YAML 配置解析），其余用 Node.js 内置模块

审计规则

默认规则（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，共 8 条）

ℹ️ E1-E4 内部规则 ID 为 201-204，预留 101-199 区间给未来默认规则扩展。E3 已并入 A11（行数维度），编号跳号。

A14-A17 + A24 + E1/E2/E4 均需 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能力拐杖

⚠️ 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_URLWebhook 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）

License

MIT

Keywords

sofagent
audit
git
agent
discipline
mcp

FAQs

Package last updated on 30 Sep 2026

Related posts

Deno Goes the Way of the Dinosaur

Security News

Deno Goes the Way of the Dinosaur

Cloudflare is acquiring Deno’s team, which will provide another year of bug fixes and security updates before ending support for the runtime.

By Sarah Gooding  -  Oct 16, 2026