|
| 1 | +/** |
| 2 | + * Pre-execution critic gate. |
| 3 | + * |
| 4 | + * Before a SIDE-EFFECTING tool runs (bash, write, edit, sql_execute, dbt_*), a |
| 5 | + * verifier checks the proposed args; on hard failure the call is denied and the |
| 6 | + * reason is fed back so the model can retry — instead of executing a bad action. |
| 7 | + * |
| 8 | + * The judgment plugs in via the `Verifier` interface. Two impls ship here: |
| 9 | + * - `ALLOW_ALL` — ungated (open); for tests / opt-out. |
| 10 | + * - `basicSafetyVerifier` — the wired default: a conservative, dependency-free |
| 11 | + * heuristic that blocks catastrophic, unambiguous |
| 12 | + * host-destructive bash (e.g. `rm -rf /`, fork bombs, |
| 13 | + * `mkfs`/`dd` on a raw device). |
| 14 | + * |
| 15 | + * This is a best-effort safety NET, NOT a security boundary or sandbox: a |
| 16 | + * determined caller can obfuscate around literal patterns (command substitution, |
| 17 | + * base64-decode-pipe-sh, etc.). Defense in depth lives elsewhere (OS sandbox, the |
| 18 | + * permission system, and a richer pluggable verifier the caller may inject). |
| 19 | + * |
| 20 | + * Pure + testable. Wired into session/prompt.ts, just before `item.execute(args, ctx)`. |
| 21 | + */ |
| 22 | + |
| 23 | +export namespace Critic { |
| 24 | + /** |
| 25 | + * Side-effecting tools worth gating. Reads (glob/grep/read) are never gated. |
| 26 | + * NOTE: the gate is wired into the native ToolRegistry execute wrapper only; |
| 27 | + * MCP-provided tools run through a separate wrapper and are NOT gated. The |
| 28 | + * shipped `basicSafetyVerifier` is bash-only (a native tool), so this is a |
| 29 | + * no-op gap today — but a product injecting a verifier for `sql_execute`/ |
| 30 | + * `dbt_run` must confirm those are native, not MCP, tools. |
| 31 | + */ |
| 32 | + export const DEFAULT_GATED = ["bash", "write", "edit", "sql_execute", "dbt_run", "patch"] |
| 33 | + |
| 34 | + export interface Verdict { |
| 35 | + ok: boolean |
| 36 | + reason?: string |
| 37 | + } |
| 38 | + |
| 39 | + /** The judgment interface. Default impl allows all (open). Product plugs a richer verifier. */ |
| 40 | + export interface Verifier { |
| 41 | + verify(toolName: string, args: Record<string, any>): Verdict | Promise<Verdict> |
| 42 | + } |
| 43 | + |
| 44 | + export const ALLOW_ALL: Verifier = { verify: () => ({ ok: true }) } |
| 45 | + |
| 46 | + export function enabled(): boolean { |
| 47 | + return process.env["ALTIMATE_CRITIC_GATE"] === "1" |
| 48 | + } |
| 49 | + |
| 50 | + export function isGated(toolName: string, gated: string[] = DEFAULT_GATED): boolean { |
| 51 | + return gated.includes(toolName) |
| 52 | + } |
| 53 | + |
| 54 | + // ── Heuristic bash safety ────────────────────────────────────────────────── |
| 55 | + // |
| 56 | + // Targets that, combined with a recursive+force `rm`, mean catastrophic loss. |
| 57 | + // Deliberately ABSOLUTE only — `.`, `./` and bare `*` are NOT here: clearing |
| 58 | + // the working/build directory (`rm -rf *`, `rm -rf .`) is routine and safe in a |
| 59 | + // sandboxed workspace, and we have no `workdir` context to judge them. |
| 60 | + const RM_FATAL_TARGETS = new Set(["/", "/*", "/.", "/..", "~", "~/", "~/*", "$home", "$home/", "$home/*"]) |
| 61 | + // Top-level system paths whose recursive deletion bricks the machine. |
| 62 | + const RM_FATAL_TOPLEVEL = [ |
| 63 | + "/etc", |
| 64 | + "/usr", |
| 65 | + "/var", |
| 66 | + "/bin", |
| 67 | + "/sbin", |
| 68 | + "/boot", |
| 69 | + "/lib", |
| 70 | + "/lib64", |
| 71 | + "/sys", |
| 72 | + "/dev", |
| 73 | + "/proc", |
| 74 | + "/root", |
| 75 | + "/home", |
| 76 | + "/opt", |
| 77 | + ] |
| 78 | + |
| 79 | + // Transparent command prefixes: words that may precede the real command without |
| 80 | + // changing which command runs. Lets `sudo rm -rf /` and `bash -c "rm -rf /"` |
| 81 | + // still be seen as an `rm` in command position, while `git commit -m "rm -rf /"` |
| 82 | + // (rm buried in an argument) is not. |
| 83 | + const TRANSPARENT_PREFIX = new Set([ |
| 84 | + "sudo", |
| 85 | + "doas", |
| 86 | + "nohup", |
| 87 | + "time", |
| 88 | + "env", |
| 89 | + "exec", |
| 90 | + "command", |
| 91 | + "builtin", |
| 92 | + "ionice", |
| 93 | + "nice", |
| 94 | + "setsid", |
| 95 | + "stdbuf", |
| 96 | + "then", |
| 97 | + "do", |
| 98 | + "else", |
| 99 | + "bash", |
| 100 | + "sh", |
| 101 | + "zsh", |
| 102 | + "dash", |
| 103 | + "ksh", |
| 104 | + ]) |
| 105 | + |
| 106 | + function isFatalRmTarget(tok: string): boolean { |
| 107 | + // Normalize bash brace expansion: ${home} -> $home, ${home}/ -> $home/ |
| 108 | + const norm = tok.replace(/^\$\{([a-z_]+)\}(\/.*)?$/, (_m, v, rest) => "$" + v + (rest ?? "")) |
| 109 | + if (RM_FATAL_TARGETS.has(tok) || RM_FATAL_TARGETS.has(norm)) return true |
| 110 | + // Catch a system path itself, its trailing-slash form, OR a glob wipe of its |
| 111 | + // contents (`/var/*`) — but NOT a scoped subpath like `/home/user/project`. |
| 112 | + return RM_FATAL_TOPLEVEL.some((p) => tok === p || tok === p + "/" || tok === p + "/*") |
| 113 | + } |
| 114 | + |
| 115 | + /** |
| 116 | + * Is the token at index `i` in COMMAND position (the start of a pipeline |
| 117 | + * segment), versus an argument to some other command? Walks left skipping |
| 118 | + * flags and transparent prefixes; a separator or the start means command |
| 119 | + * position, any other bareword means it's an argument. |
| 120 | + */ |
| 121 | + function isCommandPosition(tokens: string[], i: number, sep: Set<string>): boolean { |
| 122 | + for (let j = i - 1; j >= 0; j--) { |
| 123 | + const t = tokens[j] |
| 124 | + if (sep.has(t)) return true |
| 125 | + if (t.startsWith("-")) continue // a flag (e.g. `sudo -E`, `bash -c`) |
| 126 | + if (TRANSPARENT_PREFIX.has(t)) continue |
| 127 | + return false // a real preceding word -> rm is an argument, not the command |
| 128 | + } |
| 129 | + return true // reached the start through only flags/prefixes |
| 130 | + } |
| 131 | + |
| 132 | + /** |
| 133 | + * Detect a catastrophic, unambiguous host-destructive bash command. Returns a |
| 134 | + * human reason when dangerous, else null. Conservative on purpose — it only |
| 135 | + * fires on the few patterns that are almost never legitimate. Quotes are |
| 136 | + * stripped so `bash -c "rm -rf /"` is still seen; this can over-match a command |
| 137 | + * that merely mentions such a string (acceptable: the gate is opt-in/off by default). |
| 138 | + */ |
| 139 | + export function detectDangerousBash(raw: string): string | null { |
| 140 | + if (!raw || typeof raw !== "string") return null |
| 141 | + if (raw.length > 1_000_000) return null // cap — don't scan pathologically huge input |
| 142 | + // Normalize: drop quotes, collapse whitespace, lowercase for keyword/path matching. |
| 143 | + const norm = raw.replace(/['"`]/g, "").replace(/\s+/g, " ").trim().toLowerCase() |
| 144 | + if (!norm) return null |
| 145 | + |
| 146 | + // Fork bomb: :(){ :|:& };: |
| 147 | + if (norm.replace(/\s+/g, "").includes(":|:&") || /:\s*\(\s*\)\s*\{/.test(norm)) { |
| 148 | + return "fork bomb" |
| 149 | + } |
| 150 | + // Explicit intent to remove the root filesystem. |
| 151 | + if (norm.includes("--no-preserve-root")) { |
| 152 | + return "rm with --no-preserve-root targets the root filesystem" |
| 153 | + } |
| 154 | + // mkfs on a block device. |
| 155 | + if (/\bmkfs(\.\w+)?\b/.test(norm) && /\/dev\//.test(norm)) { |
| 156 | + return "mkfs on a block device" |
| 157 | + } |
| 158 | + // dd writing to a raw disk. |
| 159 | + if (/\bdd\b/.test(norm) && /\bof=\/dev\/(sd|nvme|disk|hd|vd|mmcblk)/.test(norm)) { |
| 160 | + return "dd writing to a raw block device" |
| 161 | + } |
| 162 | + // Redirect over a raw disk. |
| 163 | + if (/>\s*\/dev\/(sd|nvme|disk|hd|vd|mmcblk)/.test(norm)) { |
| 164 | + return "redirect over a raw block device" |
| 165 | + } |
| 166 | + // Recursive chmod/chown of the root filesystem (short `-R`/`-rf` or long |
| 167 | + // `--recursive`, against bare `/` or a `/*` glob wipe). |
| 168 | + if (/\bch(mod|own)\b/.test(norm) && /(^|\s)(-[a-z]*r|--recursive)\b/.test(norm) && /\s\/\*?(\s|$)/.test(norm)) { |
| 169 | + return "recursive permission/ownership change on /" |
| 170 | + } |
| 171 | + // Recursive + force rm of a fatal target. Split shell separators into their |
| 172 | + // own tokens so they don't glue to a target (`/;`) and so EVERY `rm` in a |
| 173 | + // compound command is inspected — not just the last one. |
| 174 | + const SEP = new Set([";", "|", "&", ">", "<"]) |
| 175 | + const tokens = norm |
| 176 | + .replace(/([;|&><])/g, " $1 ") |
| 177 | + .replace(/\s+/g, " ") |
| 178 | + .trim() |
| 179 | + .split(" ") |
| 180 | + for (let i = 0; i < tokens.length; i++) { |
| 181 | + // Match `rm` or a fully-qualified `/bin/rm`, but only in command position |
| 182 | + // (not when `rm -rf /` merely appears inside another command's argument). |
| 183 | + if (tokens[i] !== "rm" && !tokens[i].endsWith("/rm")) continue |
| 184 | + if (!isCommandPosition(tokens, i, SEP)) continue |
| 185 | + let recursive = false |
| 186 | + let force = false |
| 187 | + const targets: string[] = [] |
| 188 | + for (let j = i + 1; j < tokens.length; j++) { |
| 189 | + const t = tokens[j] |
| 190 | + if (SEP.has(t)) break // end of this rm invocation |
| 191 | + if (t.startsWith("-")) { |
| 192 | + if (t === "--recursive" || (/^-[a-z]+$/.test(t) && t.includes("r"))) recursive = true |
| 193 | + if (t === "--force" || (/^-[a-z]+$/.test(t) && t.includes("f"))) force = true |
| 194 | + } else { |
| 195 | + targets.push(t) |
| 196 | + } |
| 197 | + } |
| 198 | + if (recursive && force) { |
| 199 | + for (const t of targets) { |
| 200 | + if (isFatalRmTarget(t)) return `recursive force-delete of "${t}"` |
| 201 | + } |
| 202 | + } |
| 203 | + } |
| 204 | + return null |
| 205 | + } |
| 206 | + |
| 207 | + /** |
| 208 | + * The wired default verifier. Blocks only catastrophic bash; everything else |
| 209 | + * (other gated tools, non-bash) is allowed. A product may inject a richer one. |
| 210 | + */ |
| 211 | + export const basicSafetyVerifier: Verifier = { |
| 212 | + verify(toolName, args) { |
| 213 | + if (toolName !== "bash") return { ok: true } |
| 214 | + const reason = detectDangerousBash(String(args?.["command"] ?? "")) |
| 215 | + return reason ? { ok: false, reason } : { ok: true } |
| 216 | + }, |
| 217 | + } |
| 218 | + |
| 219 | + export interface GateResult { |
| 220 | + allow: boolean |
| 221 | + /** when blocked, the message to feed back to the model in place of execution. */ |
| 222 | + feedback?: string |
| 223 | + } |
| 224 | + |
| 225 | + /** |
| 226 | + * Decide whether a proposed tool call may execute. Non-gated tools always pass. |
| 227 | + * Gated tools are checked by the verifier; a not-ok verdict blocks with feedback. |
| 228 | + * NEVER throws — a critic failure must not break the agent (fail-open on error). |
| 229 | + */ |
| 230 | + /** Max time to wait on a verifier before failing open. A hung verifier must |
| 231 | + * never hang the agent. */ |
| 232 | + export const VERIFIER_TIMEOUT_MS = 5000 |
| 233 | + |
| 234 | + export async function gate( |
| 235 | + toolName: string, |
| 236 | + args: Record<string, any>, |
| 237 | + verifier: Verifier = ALLOW_ALL, |
| 238 | + gated: string[] = DEFAULT_GATED, |
| 239 | + timeoutMs: number = VERIFIER_TIMEOUT_MS, |
| 240 | + ): Promise<GateResult> { |
| 241 | + if (!enabled() || !isGated(toolName, gated)) return { allow: true } |
| 242 | + try { |
| 243 | + // async IIFE so a synchronous throw in verify() rejects the promise (and is |
| 244 | + // caught below) rather than escaping the Promise.race. |
| 245 | + const verifyPromise = (async () => verifier.verify(toolName, args))() |
| 246 | + const timeout = new Promise<Verdict>((resolve) => { |
| 247 | + const t = setTimeout(() => resolve({ ok: true, reason: "__timeout__" }), timeoutMs) |
| 248 | + // don't keep the event loop alive for this guard timer |
| 249 | + ;(t as any)?.unref?.() |
| 250 | + }) |
| 251 | + const v = await Promise.race([verifyPromise, timeout]) |
| 252 | + if (v.ok) return { allow: true } |
| 253 | + return { |
| 254 | + allow: false, |
| 255 | + feedback: `Blocked by altimate verifier before execution: ${v.reason ?? "failed validation"}. Fix and retry.`, |
| 256 | + } |
| 257 | + } catch { |
| 258 | + // Fail-open: observability/governance must never break core functionality. |
| 259 | + return { allow: true } |
| 260 | + } |
| 261 | + } |
| 262 | +} |
0 commit comments