@theowlops/boombot 0.0.0-stage → 1.1.1

package/dist/node_modules/@boombot/sandbox/sandbox.js

@@ -0,0 +1,229 @@
+/**
+ * @boombot/sandbox — injectable subprocess sandbox.
+ *
+ * Honest framing (root SECURITY.md §3): the `subprocess` backend is
+ * OS-process isolation, NOT a container/VM. It contains: timeout kill of
+ * the whole process group on POSIX (grandchildren die with the child),
+ * cwd confinement, env allowlist-only, output limits, shell-metacharacter
+ * rejection. It does NOT contain: a grandchild that calls setsid() to leave
+ * the process group, subprocesses started outside the sandbox by
+ * plugins/MCP, or a hostile binary exploiting a kernel bug. On Windows
+ * Node cannot signal a process group, so the kill stays single-process and
+ * grandchildren may survive there. For strong isolation, add a Docker/
+ * cloud backend behind the same `SandboxProvider` interface.
+ */
+import { spawn } from 'node:child_process';
+import { dirname, resolve, sep } from 'node:path';
+/**
+ * Reject shell metacharacters in the *executable* (cmd[0]). Arguments are
+ * passed to the executable literally with `shell: false`, so characters
+ * like `;` or `$` inside an argument are inert — e.g. `node -e 'a;b'`
+ * receives the script verbatim. The executable path is where a smuggled
+ * `sh -c` chain or command substitution would do damage, so it gets the
+ * strict check.
+ */
+const SHELL_METACHARACTERS = /[|&;`$<>()"'\n\r]/;
+export function assertNoShellMetacharacters(cmd) {
+    const executable = cmd[0];
+    if (executable !== undefined && SHELL_METACHARACTERS.test(executable)) {
+        throw new Error(`SubprocessSandbox: refusing executable containing shell metacharacters: ${JSON.stringify(executable.slice(0, 80))}`);
+    }
+}
+/** Resolve `cwd` and prove it stays inside `root`. Throws on escape. */
+export function confineCwd(root, cwd) {
+    const resolvedRoot = resolve(root);
+    const resolvedCwd = resolve(resolvedRoot, cwd);
+    if (resolvedCwd !== resolvedRoot && !resolvedCwd.startsWith(resolvedRoot + sep)) {
+        throw new Error(`SubprocessSandbox: cwd escapes workspaceRoot (root=${resolvedRoot}, cwd=${resolvedCwd})`);
+    }
+    return resolvedCwd;
+}
+export function buildSandboxEnv(allowlist, minPath) {
+    const env = { PATH: minPath };
+    // Windows crypto/process initialization needs the OS directory even when
+    // the caller asks for an otherwise empty environment. It is not a secret.
+    if (process.platform === 'win32') {
+        env['SystemRoot'] = process.env['SystemRoot'] ?? 'C:\\Windows';
+        env['WINDIR'] = process.env['WINDIR'] ?? env['SystemRoot'];
+        // Prevent cp1252 UnicodeEncodeError for Vietnamese and UTF-8 output on Windows
+        env['PYTHONUTF8'] = '1';
+        env['PYTHONIOENCODING'] = 'utf-8';
+    }
+    for (const name of allowlist) {
+        const value = process.env[name];
+        if (value !== undefined)
+            env[name] = value;
+    }
+    return env;
+}
+/**
+ * Platform-aware default for `minPath`. The POSIX value cannot work on
+ * Windows: `spawn` resolves bare executables via PATH, and without
+ * System32 even `where`/built-ins fail. The running Node's own directory
+ * is appended so `node` itself is spawnable by name (the gateway's own
+ * runtime — scripts the agent runs usually want it).
+ */
+export function defaultMinPath() {
+    if (process.platform === 'win32') {
+        return ['C:\\Windows\\System32', 'C:\\Windows', dirname(process.execPath)].join(';');
+    }
+    return '/usr/bin:/bin';
+}
+/**
+ * Subprocess sandbox: `spawn` WITHOUT a shell, timeout kill
+ * (SIGTERM → SIGKILL after grace, delivered to the whole process group on
+ * POSIX), cwd confinement, env allowlist-only, and per-stream output caps.
+ *
+ * Known limitations: on POSIX the child is spawned detached as a process
+ * group leader, so the timeout kill reaches grandchildren — unless a
+ * grandchild calls setsid() to escape into its own group. On Windows Node
+ * cannot signal a process group, so the kill stays single-process and
+ * grandchildren may survive. Neither is a container/VM boundary: use a
+ * container backend when that matters.
+ *
+ * Windows behavior: Node maps both SIGTERM and SIGKILL to TerminateProcess,
+ * so the two-phase kill has no graceful phase on win32 — the process dies on
+ * the first kill and the grace timer is cleared by `close`. `kill()` on an
+ * already-exited process is a safe no-op (returns false, never throws), and
+ * a group kill whose members are all gone throws ESRCH which is swallowed,
+ * so a grace timer racing the process's natural exit cannot throw or hang
+ * the promise: `finish()` is idempotent and `close` always clears the timer.
+ */
+export class SubprocessSandbox {
+    name = 'subprocess';
+    workspaceRoot;
+    defaultTimeoutMs;
+    maxOutputBytes;
+    killGraceMs;
+    minPath;
+    constructor(options) {
+        if (typeof options.workspaceRoot !== 'string' || options.workspaceRoot.length === 0) {
+            throw new Error('SubprocessSandbox: workspaceRoot is required');
+        }
+        this.workspaceRoot = resolve(options.workspaceRoot);
+        this.defaultTimeoutMs = options.defaultTimeoutMs ?? 30_000;
+        this.maxOutputBytes = options.maxOutputBytes ?? 1_048_576;
+        this.killGraceMs = options.killGraceMs ?? 2000;
+        this.minPath = options.minPath ?? defaultMinPath();
+    }
+    async run(cmd, opts) {
+        if (cmd.length === 0)
+            throw new Error('SubprocessSandbox: cmd must not be empty');
+        const executable = cmd[0];
+        if (executable === undefined || executable.length === 0) {
+            throw new Error('SubprocessSandbox: cmd[0] must not be empty');
+        }
+        assertNoShellMetacharacters(cmd);
+        const cwd = confineCwd(this.workspaceRoot, opts.cwd);
+        const timeoutMs = opts.timeoutMs > 0 ? opts.timeoutMs : this.defaultTimeoutMs;
+        const env = buildSandboxEnv(opts.envAllowlist ?? [], this.minPath);
+        const maxBytes = this.maxOutputBytes;
+        return new Promise((promiseResolve) => {
+            let settled = false;
+            let graceTimer;
+            const finish = (result) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timeoutTimer);
+                // NOTE: the grace timer is deliberately NOT cleared here. It only
+                // exists after the timeout fired, and the direct child's `close`
+                // does not mean the group is empty — a SIGTERM-ignoring grandchild
+                // may still run. The timer stays armed so its SIGKILL reaps group
+                // stragglers; `killTree` swallows ESRCH when the group is already
+                // fully dead. (The timer is unref'd, so it never holds the loop.)
+                promiseResolve(result);
+            };
+            // POSIX: spawn detached so the child becomes a process-group leader.
+            // The timeout kill below signals the whole group (negative pid), so
+            // double-forked grandchildren die with the child instead of escaping
+            // as orphans. Windows has no process-group signaling through Node, so
+            // `detached` stays off there and the kill is single-process.
+            const child = spawn(executable, cmd.slice(1), {
+                cwd,
+                env,
+                shell: false,
+                detached: process.platform !== 'win32',
+                stdio: ['ignore', 'pipe', 'pipe'],
+            });
+            /**
+             * Kill the child — and on POSIX the entire process group it leads.
+             * A group whose members have all exited no longer exists: the ESRCH
+             * from `process.kill` is swallowed because "nothing left to kill" is
+             * exactly the outcome wanted.
+             */
+            const killTree = (signal) => {
+                try {
+                    if (process.platform === 'win32' || child.pid === undefined) {
+                        child.kill(signal);
+                    }
+                    else {
+                        process.kill(-child.pid, signal);
+                    }
+                }
+                catch {
+                    // ESRCH: the process/group is already gone.
+                }
+            };
+            const stdoutChunks = [];
+            const stderrChunks = [];
+            let truncated = false;
+            let timedOut = false;
+            const stdoutState = { chunks: stdoutChunks, bytes: 0 };
+            const stderrState = { chunks: stderrChunks, bytes: 0 };
+            const collect = (state, data) => {
+                if (state.bytes >= maxBytes) {
+                    truncated = true;
+                    return;
+                }
+                const remaining = maxBytes - state.bytes;
+                if (data.length > remaining) {
+                    state.chunks.push(data.subarray(0, remaining));
+                    state.bytes = maxBytes;
+                    truncated = true;
+                }
+                else {
+                    state.chunks.push(data);
+                    state.bytes += data.length;
+                }
+            };
+            child.stdout?.on('data', (data) => collect(stdoutState, data));
+            child.stderr?.on('data', (data) => collect(stderrState, data));
+            const timeoutTimer = setTimeout(() => {
+                timedOut = true;
+                killTree('SIGTERM');
+                graceTimer = setTimeout(() => {
+                    killTree('SIGKILL');
+                }, this.killGraceMs);
+                if (graceTimer.unref !== undefined)
+                    graceTimer.unref();
+            }, timeoutMs);
+            if (timeoutTimer.unref !== undefined)
+                timeoutTimer.unref();
+            child.on('error', (err) => {
+                finish({
+                    stdout: Buffer.concat(stdoutChunks).toString('utf8'),
+                    stderr: `sandbox spawn error: ${err.message}`,
+                    exitCode: null,
+                    timedOut: false,
+                    truncated,
+                });
+            });
+            child.on('close', (code, signal) => {
+                // When the timeout did NOT fire, no grace timer can exist (it is
+                // only armed by the timeout) — clear defensively. When it DID fire,
+                // the timer stays armed: the direct child being gone does not mean
+                // the group is empty (see `finish`).
+                if (!timedOut && graceTimer !== undefined)
+                    clearTimeout(graceTimer);
+                finish({
+                    stdout: Buffer.concat(stdoutChunks).toString('utf8'),
+                    stderr: Buffer.concat(stderrChunks).toString('utf8'),
+                    exitCode: signal === null ? code : null,
+                    timedOut,
+                    truncated,
+                });
+            });
+        });
+    }
+}

package/dist/node_modules/@boombot/security/harness-guard/boundary.d.ts

@@ -0,0 +1,22 @@
+import type { GuardPolicyConfig, GuardVerdict, TaggedContent } from './types.js';
+export declare function wrapUntrusted(source: string, content: string): TaggedContent;
+export declare function wrapTrusted(source: string, content: string): TaggedContent;
+export interface BoundaryMatch {
+    readonly patternId: string;
+    /** Up to 120 characters of content surrounding the match. */
+    readonly excerpt: string;
+}
+/**
+ * Rule-based scan of a content string for instruction-like payloads.
+ * Returns one match per distinct pattern (first occurrence), in pattern order.
+ */
+export declare function detectInstructions(content: string): BoundaryMatch[];
+/**
+ * Boundary layer verdict for tagged content:
+ * - `trusted` content is never inspected (provenance is the trust root).
+ * - `untrusted` content with no matches is allowed.
+ * - Prompt-leak matches, or two or more distinct patterns, are `high` severity.
+ * - A single ordinary pattern is `medium` severity.
+ * The severity is then resolved through {@link decide} against the policy.
+ */
+export declare function scanTagged(tagged: TaggedContent, policy: GuardPolicyConfig): GuardVerdict;

package/dist/node_modules/@boombot/security/harness-guard/boundary.js

@@ -0,0 +1,105 @@
+import { decide } from './policy.js';
+export function wrapUntrusted(source, content) {
+    return { trust: 'untrusted', source, content };
+}
+export function wrapTrusted(source, content) {
+    return { trust: 'trusted', source, content };
+}
+/**
+ * Instruction-like patterns typical of prompt-injection payloads.
+ * All regexes are case-insensitive and deliberately anchored on the
+ * instruction verb + target so ordinary uses of words like "ignore"
+ * (e.g. "ignore the previous email") do not match.
+ */
+const PATTERNS = [
+    {
+        id: 'ignore-previous-instructions',
+        re: /\bignore\s+(all\s+)?(your\s+|the\s+)?(previous|prior|earlier|above)\s+instructions?\b/i,
+    },
+    {
+        id: 'disregard-previous-instructions',
+        re: /\bdisregard\s+(all\s+)?(your\s+|the\s+)?(previous|prior|above)\s+instructions?\b/i,
+    },
+    {
+        id: 'you-are-now',
+        re: /\byou\s+are\s+now\b/i,
+    },
+    {
+        id: 'forget-everything',
+        re: /\bforget\s+(everything|all)\b/i,
+    },
+    {
+        id: 'conceal-from-user',
+        re: /\bdo\s+not\s+(tell|reveal|mention|disclose|share)\b[^.!?]{0,60}\b(the\s+)?(user|human)\b/i,
+    },
+    {
+        id: 'reveal-system-prompt',
+        re: /\b(reveal|disclose|expose|show|print)\b[^.!?]{0,40}\byour\s+system\s+prompt\b/i,
+    },
+    {
+        id: 'new-instructions',
+        re: /\bnew\s+instructions?\s*:/i,
+    },
+    {
+        id: 'override-your',
+        re: /\boverride\s+(your|the)\b/i,
+    },
+];
+const EXCERPT_BEFORE = 40;
+const EXCERPT_MAX = 120;
+function excerptAround(content, index) {
+    const start = Math.max(0, index - EXCERPT_BEFORE);
+    const end = Math.min(content.length, start + EXCERPT_MAX);
+    return content.slice(start, end);
+}
+/**
+ * Rule-based scan of a content string for instruction-like payloads.
+ * Returns one match per distinct pattern (first occurrence), in pattern order.
+ */
+export function detectInstructions(content) {
+    const matches = [];
+    for (const pattern of PATTERNS) {
+        // Fresh lastIndex each call: patterns are module-level regexes without /g,
+        // so exec is stateless, but re-running exec keeps this robust anyway.
+        const found = pattern.re.exec(content);
+        if (found !== null) {
+            matches.push({
+                patternId: pattern.id,
+                excerpt: excerptAround(content, found.index),
+            });
+        }
+    }
+    return matches;
+}
+const PROMPT_LEAK_ID = 'reveal-system-prompt';
+/**
+ * Boundary layer verdict for tagged content:
+ * - `trusted` content is never inspected (provenance is the trust root).
+ * - `untrusted` content with no matches is allowed.
+ * - Prompt-leak matches, or two or more distinct patterns, are `high` severity.
+ * - A single ordinary pattern is `medium` severity.
+ * The severity is then resolved through {@link decide} against the policy.
+ */
+export function scanTagged(tagged, policy) {
+    if (tagged.trust === 'trusted') {
+        return {
+            decision: 'allow',
+            reason: `trusted content from ${tagged.source}: not inspected`,
+            layer: 'boundary',
+        };
+    }
+    const matches = detectInstructions(tagged.content);
+    if (matches.length === 0) {
+        return {
+            decision: 'allow',
+            reason: `untrusted content from ${tagged.source}: no injection patterns`,
+            layer: 'boundary',
+        };
+    }
+    const ids = matches.map((m) => m.patternId);
+    const isPromptLeak = ids.includes(PROMPT_LEAK_ID);
+    const severity = isPromptLeak || ids.length >= 2 ? 'high' : 'medium';
+    const reason = `untrusted content from ${tagged.source} matched ${ids.length} ` +
+        `injection pattern(s): ${ids.join(', ')}`;
+    return decide(policy, 'boundary', severity, reason);
+}

package/dist/node_modules/@boombot/security/harness-guard/gates.d.ts

@@ -0,0 +1,90 @@
+/**
+ * `@boombot/security` — deterministic tool gates (layer: `'gates'`).
+ *
+ * Fail-closed static checks that run *before* a tool executes:
+ *
+ * - `tokenizeBash` / `analyzeBash` — a hand-written bash tokenizer (quotes,
+ *   escapes, comments, operators, `$(...)`, backticks, `${...}`) plus a
+ *   rule-based risk classifier. Deterministic: the same command always yields
+ *   the same risk. When in doubt it escalates (fail-closed).
+ * - `checkHttpUrl` — outbound URL gate: protocol check, userinfo (credential
+ *   in URL) check, and hostname allowlist with `*.example.com` wildcards.
+ * - `evaluateToolCall` — the entry point the verifier imports. Routes a tool
+ *   call through deny-list / approval-list / bash-like / http-like gates.
+ *
+ * Zero dependencies. Findings are mapped to a severity and passed to `decide()`
+ * from `./policy.js` so `GuardMode` semantics stay in one place; clean checks
+ * (no finding at all) allow directly, so strict mode never denies a command
+ * or URL that nothing flagged. Every finding's reason names the exact
+ * construct that was caught.
+ */
+import type { GuardPolicyConfig, GuardToolCall, GuardVerdict } from './types.js';
+/**
+ * Tokenize a bash command line.
+ *
+ * Handles single/double quotes (quote-aware, quotes stripped from the token
+ * value), backslash escapes, `#` comments (only at the start of a word,
+ * outside quotes), and emits operators as standalone tokens: `|`, `||`,
+ * `&&`, `;`, `;;`, `&`, `>`, `>>`, `<`, `<<`, `(`, `)`, `{`, `}`, `` ` ``,
+ * `$(`, `${`.
+ *
+ * This is a real tokenizer, not a naive whitespace split: `echo "a b" | cat`
+ * yields `['echo', 'a b', '|', 'cat']`, and `#` inside quotes never starts a
+ * comment.
+ */
+export declare function tokenizeBash(command: string): string[];
+export interface BashAnalysis {
+    readonly risk: 'low' | 'medium' | 'high' | 'critical';
+    readonly reasons: string[];
+}
+/**
+ * Analyze a bash command and classify its risk.
+ *
+ * - `critical`: `rm -rf /` (and `/*`, `~`, `$HOME` variants, `--recursive`
+ *   `--force` spellings), `mkfs`, `dd … of=/dev/…`, fork bombs
+ *   (`:(){ :|:& };:` and whitespace/named variants), `> /dev/sdX`.
+ * - `high`: piping a download into a shell (`curl … | sh`, `… | sudo sh`),
+ *   `$(curl …)` / backtick command substitution fetching remote content,
+ *   env exfiltration (`env | curl …`), writes to system paths (`/etc/`,
+ *   `/usr/bin`, …), `chmod -R 777 /`.
+ * - `medium`: any `sudo`, `nc -l` listeners, `chmod +x` on a downloaded
+ *   file, `find / … -delete`.
+ * - `low`: everything else.
+ *
+ * Every finding appends a reason quoting the exact construct caught; the
+ * overall risk is the maximum over all findings (fail-closed).
+ */
+export declare function analyzeBash(command: string): BashAnalysis;
+/**
+ * Gate an outbound URL (layer: `'gates'`).
+ *
+ * - Unparseable URL → deny, severity `critical`.
+ * - Non-http(s) protocol → deny, severity `high`.
+ * - Userinfo (`user:pass@host`) → deny, severity `high` ("credential in URL").
+ * - `httpMode: 'off'` → allow. `'warn'` → off-list hosts still allow, but the
+ *   reason flags them (severity `low`). `'allowlist'` → off-list hosts deny
+ *   with severity `high`.
+ *
+ * Host matching is case-insensitive, ignores ports, and supports exact and
+ * `*.example.com` wildcard entries.
+ */
+export declare function checkHttpUrl(rawUrl: string, policy: GuardPolicyConfig): GuardVerdict;
+/**
+ * Evaluate one tool call against the gates layer.
+ *
+ * Order (first match wins):
+ * 1. guard `off` → allow unconditionally;
+ * 2. name exactly in `denyTools` → deny (`critical`);
+ * 3. name exactly in `approvalTools` → require-approval;
+ * 4. write-zone gate — `file.write`/`file.edit` (by `path`) and `shell.exec`
+ *    (by explicit `cwd`) outside every configured `writeZones` →
+ *    require-approval (fail-closed); in-zone keeps the previous behavior;
+ * 5. bash-like — name matches the bash regex **or** a string arg named
+ *    `command`/`script`/`cmd` → `analyzeBash`; risk `medium`/`high`/`critical`
+ *    goes through `decide()`, risk `low` (no findings) allows directly;
+ * 6. http-like — name in the known research/fetch set, name matches
+ *    `/fetch|https?|request/i`, **or** a string arg named `url`/`href`/`link`
+ *    → `checkHttpUrl` on that URL argument;
+ * 7. anything else → allow.
+ */
+export declare function evaluateToolCall(call: GuardToolCall, policy: GuardPolicyConfig): GuardVerdict;