JohnXu22786/safety-net

English

Barricade（路障）

编码 agent 的破坏性命令拦截闸门：在 rm -rf、git reset --hard、git push --force 这类命令真正落地之前解析命令语义、判定风险，并要求人工确认。

Barricade 是一枚自包含的插件/CLI，零运行时依赖（纯 Node.js ESM），面向所有「把 shell 交给 agent 去跑」的 harness 设计。它不做沙箱、不限制能力，只做一件事：把不可逆的操作挡在确认关卡前——包括那些沙箱也拦不住的（git reset --hard 丢弃工作区、git push --force 覆盖远端历史、rm -rf 删掉工作区内未跟踪文件）。

能力一览

- 语义级命令解析：不是字符串匹配。自带 POSIX 词法分析器，识别引号、转义、heredoc、命令替换 $(...)、子 shell、管道链；bash -c "rm -rf /"、sudo rm -rf /、eval "rm -rf /"、echo $(rm -rf /) 都逃不过。
- 分命令判定器：git（reset/clean/push/checkout/branch/stash/restore 等 13 种危险形态，支持长旗标唯一前缀、短旗标解绑）、rm（按目标作用域分级：根目录/主目录/.git → 致命；工作区外/动态目标 → 高危；工作区内 → 中危）、dd/mkfs/shred/chmod/chown、find -delete、curl|sh、解释器单行、fork 炸弹、PowerShell 强删等 41 条内置规则。
- 三级策略：relaxed / balanced（默认）/ vigilant，严重度 → 动作（拒绝/确认/放行）逐级映射，vigilant 下无法解析的输入按需确认（fail-closed）。
- 交互式确认：TTY 下展示命令与命中规则，支持执行一次 / 拒绝 / 本会话放行 / 永久放行（写入策略）/ 查看详情；非 TTY 环境一律拒绝（失败安全）。
- 多 harness 可移植：判定核心与 harness 无关（输入 (命令, 工作目录, 策略)，输出结构化判定），三种接入形态任选：dsh 进程内插件、通用 stdin-hook JSON 契约、gate shell 包装。
- 审计：拦截与确认记录落盘 JSONL，密钥类内容自动脱敏。

工作原理

agent 准备执行命令
│
▼
┌─────────────────┐   ┌──────────────┐
│ 接入点(任一)      │──▶│ 命令分析引擎   │
│ dsh 插件事件      │   │ 分词 → 分段   │
│ stdin-hook       │   │ 拆包装 → 判定  │
│ gate 包装        │   └──────┬───────┘
└─────────────────┘          │
▼
┌─ 放行 ──▶ 命令执行
│
判定结果
│
└─ 需确认 ─▶ TTY 交互确认 ──▶ 执行/拒绝
非 TTY：拒绝（失败安全）

分析引擎的关键环节：

1. 分词：POSIX 风格词法分析（引号/转义/操作符/heredoc 正文/命令替换提取），输入超限或无法解析时回退到粗粒度模式扫描。
2. 分段：按 && || ; | & 与子 shell 切分命令段，cd 跟踪执行目录，逐段独立判定，任一危险段拦截整条命令。
3. 拆包装：递归剥离 sudo / env / command / timeout 等包装命令与 bash -c / sh -c / su -c 内嵌负载（深度上限 8，超限按需确认）。
4. 判定合并：致命优先、任一拒绝则拒绝、任一需确认则确认；策略 overrides 可调整高/中危动作，致命规则不可降级。

安装

要求 Node.js ≥ 18.13，无任何 npm 依赖。

直接运行（无需安装）
node bin/barricade.js --help

作为命令行工具使用（可选）
npm link          # 之后可直接使用 barricade 命令

接入 dsh（DeepSeek Harness）

本仓库即一个合法的 dsh bundle：package.json 声明了 dsh.bundle，cordis.patch.yml 是配置层补丁，plugin.js 是插件入口。

在 DSH 中安装

dsh plugin --profile demo add github:JohnXu22786/safety-net

加载方式

在目标 profile 中安装本 bundle（本地目录或已发布的 npm 包名）
dsh plugin --profile web add ../dsh-barricade      # 或 dsh plugin --profile web add dsh-barricade

启动
dsh --profile web

加载后 Cordis 会按 cordis.patch.yml 插入插件行：

- insert:
- id: barricade
name: dsh-barricade

插件接口

| 项 | 值 |
|---|---|
| 入口 | plugin.js（main 字段），导出 name / inject / apply(ctx, config) |
| 事件 | 监听工具执行管线事件 tools/pre-execute（waterfall），在工具真正执行前介入 |
| 拦截方式 | 判定为需拦截时抛出 BarricadeBlocked 错误，工具调用失败且原因对模型可见 |
| 配置 | cordis.patch.yml 中 config 字段，或 dsh --patch 覆盖层 |

可用配置项（均可省略）：

| 配置键 | 默认 | 说明 |
|---|---|---|
| mode | "deny" | deny：命中即拒绝；ask：经 ctx.approval 服务请求人工确认，确认被拒或服务不可用时按拒绝处理 |
| toolNames | 常见 shell 工具名列表 | 仅拦截这些工具；亦可用环境变量 BARRICADE_TOOLS 覆盖（逗号分隔） |
| commandPath | "args.command" | 工具调用中命令文本的取值路径（点路径），兼容 input.command / command 等形态 |
| level | 策略文件 | relaxed / balanced / vigilant |

示例（写入 profile 的 cordis.patch.yml 或 --patch 覆盖层）：

- insert:
- id: barricade
name: dsh-barricade
config:
mode: ask
toolNames: [bash, run_code, run_command]

说明：dsh 当前处于开发者预览期，接口可能演进。apply 对工具调用形态做了防御式识别（name/tool、args/input 等），并对 ctx.approval 的多种调用形态做探测；任何形态不可用时按拒绝处理，保证失败安全。若上游事件契约变化，只需调整 plugin.js 中的事件名与字段路径。

其他 harness 接入

判定核心不依赖任何 harness，以下三种形态任选：

① stdin-hook 契约（适用于支持「工具调用前运行钩子」的 harness，如 PreToolUse 类钩子）：

stdin  : {"command": "", "cwd": ""}    # 或纯命令文本
stdout : {"action": "allow|ask|deny", "severity": ..., "matches": [...], "warnings": [...]}
exit   : 0（正常输出判定）；加 --exit-on-block 时拦截退出 1

示例（将钩子命令指向 node /bin/barricade.js hook）：

echo '{"command":"git push --force origin main"}' | node bin/barricade.js hook
{"command":"git push --force origin main","action":"ask","severity":"high",
"reason":"强制推送覆盖远端提交历史，可能造成他人工作丢失","matches":[...],"warnings":[]}

② gate 包装（把 harness 的 shell 换成 barricade gate -- ）：终端交互确认后执行，非终端环境直接拦截。

③ 进程内复用：createInterceptor(config) 返回纯判定函数，任何 Node 进程内 harness 可直接调用（见 plugin.js 顶部注释）。

CLI 使用说明

barricade  [选项]

analyze [--json]               分析并输出判定（不执行；退出码恒 0）
check   [--json] [--quiet]     判定；放行退出 0，拦截退出 1
gate --                        分析 + 交互确认 + 执行
hook                                 见上文 stdin-hook 契约
policy --show [--json]               显示合并后的策略
policy --validate [--policy F]       校验策略文件
rules [--json]                       列出内置规则
audit [--tail N]                     查看审计记录

-c, --command     --stdin       命令输入方式
--level           --policy   临时等级 / 指定策略文件
--json                  --quiet       --exit-on-block
-h, --help              -v, --version --tail

示例：

barricade check -c "rm -rf /"                 # 退出 1，打印拦截原因
barricade analyze --json -c "git reset --hard"
barricade gate -- "npm run build"             # 终端下交互确认

策略配置

配置文件：用户级 ~/.barricade/barricade.json（BARRICADE_HOME 可改），项目级 .barricade.json（当前目录，优先于用户级）。均为 JSON，字段缺失/损坏时挽救式回退默认值并打印警告，绝不让策略文件把工作流打断。

{
"version": 1,
"level": "balanced",
"failClosed": false,
"allowlist": ["git status", "git log", "ls -la"],
"overrides": { "git/tag-delete": "allow" },
"rules": [
{
"id": "custom/dropdb-force",
"command": "dropdb",
"args": ["--force"],
"severity": "high",
"reason": "强制删除数据库不可恢复"
}
],
"confirmation": { "sessionMemory": true, "timeoutSeconds": 0 }
}

| 字段 | 说明 |
|---|---|
| level | relaxed（中危放行）/ balanced（中危确认）/ vigilant（+ 无法解析输入按需确认） |
| failClosed | 命令无法解析时也要求确认 |
| allowlist | 前缀放行清单（git status 放行 git status --porcelain） |
| overrides | 按规则 id 调整动作：allow / ask / deny / off；致命规则不可降级 |
| rules | 自定义规则：命令 + 子命令(可选) + 任一参数命中（支持短旗标解绑） |
| confirmation.timeoutSeconds | 交互确认超时（秒），超时按拒绝；0 为不超时 |

环境变量（只升不降）：

| 变量 | 说明 |
|---|---|
| BARRICADE_HOME | 数据目录（策略、审计日志），默认 ~/.barricade |
| BARRICADE_POLICY | 指定用户策略文件路径 |
| BARRICADE_LEVEL | 提升等级（仅当高于文件等级时生效） |
| BARRICADE_FAIL_CLOSED=1 | 开启 fail-closed |
| BARRICADE_CONFIRM_TIMEOUT | 确认超时秒数 |
| BARRICADE_TOOLS | dsh 插件拦截的工具名单（逗号分隔） |
| BARRICADE_NO_COLOR / NO_COLOR | 关闭彩色输出 |

交互确认

⚠️  Barricade 需要确认此命令 [高危]
命令: git push --force origin main
• git/push-force — 强制推送覆盖远端提交历史，可能造成他人工作丢失
[y] 执行一次  [n] 拒绝  [s] 本会话放行  [a] 永久放行  [d] 详情  [q] 退出

- a 会把规则写入用户策略文件（overrides）；致命规则不可永久放行。
- s 把规则记入本次调用的会话集合；gate 单次调用内只确认一次，s 与 y 等价；进程内复用同一 session 集合的场景下可跨调用生效。
- 命令展示前会转义控制字符并截断，防止终端注入（判定文本与审计日志同样处理）。

内置规则清单（节选）

| 规则 id | 严重度 | 说明 |
|---|---|---|
| fs/rm-root / fs/rm-home | 致命 | 删除根目录 / 主目录 |
| fs/rm-git | 致命 | 删除/写入/移动 .git 内部内容 |
| fs/mkfs-device / fs/dd-device | 致命/高危 | 格式化或写入块设备（/dev/null 等安全目标除外） |
| fs/rm-outside / fs/rm-dynamic / fs/rm-workspace | 高/高/中 | rm -rf 目标作用域分级 |
| fs/find-delete / fs/shred / fs/chmod-recursive / fs/chown-recursive | 高/高/中/中 | 批量或递归破坏性操作 |
| git/reset-hard / git/clean-force / git/push-force / git/push-delete | 高/高/高/中 | 覆盖历史、丢弃未提交修改、删远端分支 |
| git/checkout-force / git/checkout-discard / git/switch-force / git/restore-worktree | 高 | 丢弃工作区修改 |
| git/branch-delete-force / git/stash-drop / git/stash-clear / git/tag-delete | 高/高/高/中 | 不可恢复的引用/暂存操作 |
| git/fetch-force / git/ssh-env | 中/高 | 覆盖远端引用 / GIT_SSH* 与网络子命令组合 |
| shell/curl-pipe-sh / shell/fork-bomb / interp/embedded | 高 | 远程脚本管道、fork 炸弹、解释器内嵌删除代码 |
| sys/shutdown / sys/reboot / sys/powershell-remove / sys/cmd-del | 高/高/中/中 | 系统级操作 |

完整清单与动作映射见 barricade rules。

安全模型与已知边界

- 不是沙箱，不构成特权边界。它拦截的是「harness 通过受支持入口发起的命令」；绕过集成的方式（例如用编辑器工具直接写文件、在容器外手工执行）不在保护范围内。
- 静态分析的固有局限：bash 、eval "$X" 这类运行期才可知的内容无法审查——vigilant 等级下会要求确认，默认等级下直接放行（可配置 failClosed 或自定义规则收紧）。
- 分析按 POSIX 路径语义处理命令文本，与运行平台无关；Windows 下 gate 经 cmd /c 执行，命令本身仍按 POSIX 语法分析。
- 输入长度上限 128 KiB、嵌套深度上限 8 层，超限走粗粒度扫描或按需确认，防止构造畸形输入拖垮分析。

开发

node --test        # 或 npm test；测试用例见 test/ 目录

结构：

bin/barricade.js    CLI 入口
plugin.js           dsh（Cordis）插件入口
src/
tokenizer.js      词法分析（引号/heredoc/命令替换）
analyzer.js       命令段组织、包装拆解、分命令判定
rules.js          内置规则库与等级映射
verdict.js        判定合并模型
policy.js         策略加载与挽救式校验
prompt.js         交互确认
audit.js          审计日志（脱敏）
executor.js       gate 执行器
cordis.patch.yml    dsh 配置层补丁
examples/           示例配置与 hook 契约样例
test/               181 个测试用例

License

MIT