简体中文 # Barricade > A destructive-command interception gate for coding agents: it parses command semantics and judges risk before rm -rf, git reset --hard, git push --force and similar commands actually land, then requires human confirmation. Barricade is a self-contained plugin/CLI with zero runtime dependencies (pure Node.js ESM), designed for any harness that "hands the shell over to an agent". It does not sandbox and does not limit capabilities; it does only one thing: hold irreversible operations at a confirmation gate — including those even a sandbox can't stop (git reset --hard discards the working tree, git push --force overwrites remote history, rm -rf deletes untracked files in the workspace). ## Capabilities at a Glance - Semantic-level command parsing: not string matching. Ships its own POSIX lexer that recognizes quotes, escapes, heredocs, command substitution $(...), sub-shells and pipeline chains; bash -c "rm -rf /", sudo rm -rf /, eval "rm -rf /", echo $(rm -rf /) cannot slip through. - Per-command verifiers: git (reset/clean/push/checkout/branch/stash/restore — 13 dangerous forms, supporting long-flag unique prefixes and short-flag unbinding), rm (tiered by target scope: root/home/.git → fatal; outside workspace / dynamic targets → high; inside workspace → medium), dd/mkfs/shred/chmod/chown, find -delete, curl|sh, interpreter one-liners, fork bombs, PowerShell forced deletion — 41 built-in rules. - Three levels: relaxed / balanced (default) / vigilant, mapping severity → action (deny/ask/allow) tier by tier; under vigilant, unparseable inputs ask as needed (fail-closed). - Interactive confirmation: on a TTY it shows the command and matched rules, supporting run once / deny / allow for this session / allow permanently (written to policy) / show details; non-TTY environments always deny (fail-safe). - Portable across harnesses: the verdict core is harness-agnostic (input (command, cwd, level), output structured verdict); three integration forms to choose from: a dsh in-process plugin, a generic stdin-hook JSON contract, and a gate shell wrapper. - Audit: interception and confirmation records are persisted as JSONL; secret-like content is automatically redacted. ## How It Works agent 准备执行命令 │ ▼ ┌─────────────────┐ ┌──────────────┐ │ 接入点(任一) │──▶│ 命令分析引擎 │ │ dsh 插件事件 │ │ 分词 → 分段 │ │ stdin-hook │ │ 拆包装 → 判定 │ │ gate 包装 │ └──────┬───────┘ └─────────────────┘ │ ▼ ┌─ 放行 ──▶ 命令执行 │ 判定结果 │ └─ 需确认 ─▶ TTY 交互确认 ──▶ 执行/拒绝 非 TTY：拒绝（失败安全） Key steps of the analysis engine: 1. Tokenize: POSIX-style lexing (quotes/escapes/operators/heredoc bodies/command-substitution extraction); falls back to a coarse-grained pattern scan when input is over the limit or unparseable. 2. Segment: splits command segments by && || ; | & and sub-shells; tracks cd execution directories; each segment is judged independently, and any dangerous segment blocks the whole command. 3. Unwrap: recursively strips wrapper commands like sudo / env / command / timeout and embedded loads in bash -c / sh -c / su -c (depth limit 8; beyond the limit, ask as needed). 4. Verdict merge: fatal first; any deny → deny; any ask → ask; policy overrides can adjust high/medium actions, but fatal rules cannot be downgraded. ## Installation Requires Node.js ≥ 18.13, no npm dependencies. bash # 直接运行（无需安装） node bin/barricade.js --help # 作为命令行工具使用（可选） npm link # 之后可直接使用 barricade 命令 ## Integrating with dsh (DeepSeek Harness) This repository is a valid dsh bundle: package.json declares dsh.bundle, cordis.patch.yml is the config-layer patch, and plugin.js is the plugin entry point. ### Installing in DSH bash dsh plugin --profile demo add github:JohnXu22786/safety-net ### Loading bash # 在目标 profile 中安装本 bundle（本地目录或已发布的 npm 包名） dsh plugin --profile web add ../dsh-barricade # 或 dsh plugin --profile web add dsh-barricade # 启动 dsh --profile web After loading, Cordis inserts the plugin line per cordis.patch.yml: yaml - insert: - id: barricade name: dsh-barricade ### Plugin Interface | Item | Value | |---|---| | Entry | plugin.js (main field), exports name / inject / apply(ctx, config) | | Events | listens to the tool execution pipeline event tools/pre-execute (waterfall), intervening before the tool actually runs | | Interception | throws BarricadeBlocked when a block verdict is produced; the tool call fails and the reason is visible to the model | | Config | the config field in cordis.patch.yml, or a dsh --patch overlay | Available config keys (all optional): | Key | Default | Description | |---|---|---| | mode | "deny" | deny: deny on match; ask: request human confirmation through the ctx.approval service; if confirmation is refused or the service is unavailable, treat as deny | | toolNames | common shell tool name list | only intercept these tools; can also be overridden via the BARRICADE_TOOLS env var (comma-separated) | | commandPath | "args.command" | dot-path to the command text in the tool call; compatible with input.command / command and other shapes | | level | policy file | relaxed / balanced / vigilant | Example (written into the profile's cordis.patch.yml or a --patch overlay): yaml - insert: - id: barricade name: dsh-barricade config: mode: ask toolNames: [bash, run_code, run_command] > Note: dsh is currently in developer preview and its interfaces may evolve. apply defensively recognizes tool-call shapes (name/tool, args/input, etc.) and probes the various calling forms of ctx.approval; if any form is unavailable it falls back to deny, keeping fail-safe. If the upstream event contract changes, just adjust the event name and field paths in plugin.js. ### Other Harness Integration The verdict core depends on no harness; pick any of the three forms: ① stdin-hook contract (for harnesses that support "run a hook before tool invocation", such as PreToolUse-style hooks): stdin : {"command": "<待执行命令>", "cwd": "<可选>"} # 或纯命令文本 stdout : {"action": "allow|ask|deny", "severity": ..., "matches": [...], "warnings": [...]} exit : 0（正常输出判定）；加 --exit-on-block 时拦截退出 1 Example (point the hook command at node <本目录>/bin/barricade.js hook): bash 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 wrapper (swap the harness's shell for barricade gate -- <command>): executes after terminal confirmation; non-terminal environments are blocked outright. ③ in-process reuse: createInterceptor(config) returns a pure verdict function callable from any Node in-process harness (see the comments at the top of plugin.js). ## CLI Usage 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 <F> 临时等级 / 指定策略文件 --json --quiet --exit-on-block -h, --help -v, --version --tail <N> Examples: bash barricade check -c "rm -rf /" # 退出 1，打印拦截原因 barricade analyze --json -c "git reset --hard" barricade gate -- "npm run build" # 终端下交互确认 ## Policy Configuration Config files: user-level ~/.barricade/barricade.json (BARRICADE_HOME to change), project-level .barricade.json (current directory, takes precedence over user-level). Both are JSON; missing/corrupt fields rescue-fall back to defaults with a warning — a policy file can never interrupt your workflow. 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 } } | Field | Description | |---|---| | level | relaxed (medium allowed) / balanced (medium asks) / vigilant (+ unparseable input asks as needed) | | failClosed | require confirmation even when a command cannot be parsed | | allowlist | prefix allowlist (git status allows git status --porcelain) | | overrides | adjust per-rule-id actions: allow / ask / deny / off; fatal rules cannot be downgraded | | rules | custom rules: command + optional subcommand + any arg match (short-flag unbinding supported) | | confirmation.timeoutSeconds | interactive confirmation timeout (seconds); timeout counts as deny; 0 means no timeout | Environment variables (raise-only, never lower): | Variable | Description | |---|---| | BARRICADE_HOME | data directory (policy, audit logs), default ~/.barricade | | BARRICADE_POLICY | specify a user policy file path | | BARRICADE_LEVEL | raise the level (only takes effect when higher than the file level) | | BARRICADE_FAIL_CLOSED=1 | enable fail-closed | | BARRICADE_CONFIRM_TIMEOUT | confirmation timeout seconds | | BARRICADE_TOOLS | comma-separated list of tools the dsh plugin intercepts | | BARRICADE_NO_COLOR / NO_COLOR | disable colored output | ## Interactive Confirmation ⚠️ Barricade 需要确认此命令 [高危] 命令: git push --force origin main • git/push-force — 强制推送覆盖远端提交历史，可能造成他人工作丢失 [y] 执行一次 [n] 拒绝 [s] 本会话放行 [a] 永久放行 [d] 详情 [q] 退出 > - a writes the rule into the user policy file (overrides); fatal rules cannot be allowed permanently. - s records the rule into this invocation's session set; within a single gate call it confirms only once, so s is equivalent to y; it can take effect across calls when the same session set is reused in-process. - Control characters are escaped and the command truncated before display, preventing terminal injection (the verdict text and audit logs are handled the same way). ## Built-in Rules (excerpt) | Rule id | Severity | Description | |---|---|---| | fs/rm-root / fs/rm-home | fatal | delete root / home directory | | fs/rm-git | fatal | delete/write/move .git internals | | fs/mkfs-device / fs/dd-device | fatal/high | format or write block devices (safe targets such as /dev/null excluded) | | fs/rm-outside / fs/rm-dynamic / fs/rm-workspace | high/high/medium | rm -rf target scope tiers | | fs/find-delete / fs/shred / fs/chmod-recursive / fs/chown-recursive | high/high/medium/medium | bulk or recursive destructive operations | | git/reset-hard / git/clean-force / git/push-force / git/push-delete | high/high/high/medium | overwrite history, discard uncommitted changes, delete remote branches | | git/checkout-force / git/checkout-discard / git/switch-force / git/restore-worktree | high | discard working-tree changes | | git/branch-delete-force / git/stash-drop / git/stash-clear / git/tag-delete | high/high/high/medium | unrecoverable ref/stash operations | | git/fetch-force / git/ssh-env | medium/high | overwrite remote refs / GIT_SSH* combined with network subcommands | | shell/curl-pipe-sh / shell/fork-bomb / interp/embedded | high | remote-script piping, fork bombs, interpreter-embedded deletion code | | sys/shutdown / sys/reboot / sys/powershell-remove / sys/cmd-del | high/high/medium/medium | system-level operations | The full list and action mapping: barricade rules. ## Security Model and Known Boundaries - Not a sandbox, and not a privilege boundary. It intercepts "commands the harness issues through supported entry points"; bypassing the integration (e.g. writing files directly with an editor tool, executing manually outside a container) is out of protection scope. - Inherent limits of static analysis: runtime-only content such as bash <unknown script> and eval "$X" cannot be inspected — under vigilant they require confirmation; under the default level they pass (tightenable with failClosed or custom rules). - Analysis handles command text with POSIX path semantics, independent of the running platform; on Windows, gate runs via cmd /c, while the command itself is still parsed with POSIX syntax. - Input size limit 128 KiB and nesting depth limit 8; beyond the limits it falls back to coarse-grained scanning or asks as needed, preventing malformed input from stalling analysis. ## Development bash node --test # 或 npm test；测试用例见 test/ 目录 Structure: 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