@aria-cli/tools 1.0.18 → 1.0.31

package/dist/executors/shell-safety.js

@@ -0,0 +1,474 @@
+/**
+ * @aria/tools - Shell command risk classifier
+ *
+ * Statically classifies shell commands into risk tiers to gate execution:
+ * - "safe"     : read-only, execute immediately without approval
+ * - "moderate" : requires runtime policy handling (approval, allowlist, or autorun)
+ * - "blocked"  : catastrophic, hard-denied — never execute
+ */
+/** Read-only single-word commands that never modify state. */
+const SAFE_SINGLE = new Set([
+    "ls",
+    "cat",
+    "head",
+    "tail",
+    "wc",
+    "file",
+    "stat",
+    "grep",
+    "rg",
+    "find",
+    "which",
+    "whereis",
+    "echo",
+    "date",
+    "whoami",
+    "pwd",
+    "printenv",
+    "uname",
+    "hostname",
+]);
+/** Read-only multi-word command prefixes (order: longest match first). */
+const SAFE_MULTI = [
+    "git stash list",
+    "git status",
+    "git log",
+    "git diff",
+    "git show",
+    "git blame",
+    "git branch",
+    "git remote",
+    "git tag",
+    "node --version",
+    "npm --version",
+    "bun --version",
+    "python --version",
+    "bun pm ls",
+    "npm list",
+];
+/** Patterns that are unconditionally blocked — catastrophic risk. */
+export const BLOCKED_PATTERNS = [
+    /rm\s+(?:--?[A-Za-z0-9-]+\s+)*\/(?:\s|$)/, // rm targeting filesystem root (/)
+    /rm\s+(?:--?[A-Za-z0-9-]+\s+)*\/\*(?:\s|$)/, // rm targeting root wildcard (/*)
+    /rm\s+(?:--?[A-Za-z0-9-]+\s+)*\.(?:\s|$)/, // rm . (current dir wipe, not ./subdir)
+    /rm\s+(?:--?[A-Za-z0-9-]+\s+)*~(?:[a-zA-Z]\w*)?(?:\/\*)?(?:\s|$)/, // rm ~ (bare home), ~/* (home wildcard), ~user (other user home)
+    /rm\s+(?:--?[A-Za-z0-9-]+\s+)*\$HOME\b/, // rm with $HOME variable
+    /rm\s+(?:--?[A-Za-z0-9-]+\s+)*\*(?:\s|$)/, // rm with bare wildcard (rm -rf *)
+    />\s*\/dev\/(?:sd[a-z]|nvme\d+|vd[a-z])\b/, // write to block devices
+    /mkfs/, // format filesystems
+    /dd\s+.*(?:if=|of=)/, // raw disk reads/writes
+    /chmod\s+(?:-R\s+)?777\b/, // world-writable permissions
+    /curl[\s\S]*\|\s*(ba)?sh/, // pipe-to-shell (including newline-obfuscated variants)
+    /wget[\s\S]*\|\s*(ba)?sh/, // pipe-to-shell (including newline-obfuscated variants)
+    /(?:^|[;&|]\s*|\$\(|`|\()\s*(?:(?:env|command)\s+)*eval\b/, // shell eval injection
+    // Inline execution (sh -c, python -c, node -e, etc.) downgraded to moderate.
+    // These are legitimate developer operations — dangerous payloads are still
+    // caught by other blocked patterns (rm /, curl|sh, fork bombs, etc.).
+    /(?:^|[;&|]\s*|\$\(|`|\()\s*(?:(?:env|command)\s+)*shutdown\b/, // system shutdown
+    /(?:^|[;&|]\s*|\$\(|`|\()\s*(?:(?:env|command)\s+)*reboot\b/, // system reboot
+    /(?:^|[;&|]\s*|\$\(|`|\()\s*(?:(?:env|command)\s+)*halt\b/, // system halt
+    /(?:^|[;&|]\s*|\$\(|`|\()\s*(?:(?:env|command)\s+)*init\s+0\b/, // init runlevel poweroff
+    /(?:^|[;&|]\s*|\$\(|`|\()\s*(?:(?:env|command)\s+)*systemctl\s+(?:poweroff|halt|reboot)\b/, // systemctl power controls
+    // kill downgraded to moderate — legitimate process management (kill PID, kill -0)
+    // is a normal developer operation. Catastrophic kill (kill -9 1) is still caught
+    // by the PID-1 pattern below. See shell-safety.test.ts for coverage.
+    /(?:^|[;&|]\s*|\$\(|`|\()\s*(?:(?:env|command)\s+)*kill\s+(?:-\d+\s+|-[A-Z]+\s+)*\b1\b/, // kill PID 1 (init) — catastrophic
+    // ${...} parameter expansion downgraded to moderate — standard bash operations
+    // like ${VAR}, ${#VAR} (length), ${VAR:-default} are common developer patterns.
+    // Truly dangerous expansions (${VAR:=$(cmd)}) are caught by other patterns
+    // (eval, curl|sh, etc.) or by the subshell/backtick check in classifyCommand.
+    /:\(\)\{\s*:\|:&\s*\};:/, // fork bomb
+    /\bsudo\b/, // privilege escalation
+    /git\s+push\s+.*--force(?!-with-lease)\b/, // force push (allow --force-with-lease)
+    /git\s+push(?:\s+-[A-Za-z]*f[A-Za-z]*\b|\s+.*\s-[A-Za-z]*f[A-Za-z]*\b)/, // short force flags (-f, -uf, etc.)
+    /git\s+reset\s+--hard/, // hard reset
+];
+/**
+ * Returns true if the raw command text matches any blocked pattern.
+ */
+function isBlocked(raw) {
+    const withoutHeredocs = stripHeredocBodies(raw);
+    const withoutQuotedLiterals = stripSingleAndDoubleQuotedLiterals(withoutHeredocs);
+    return BLOCKED_PATTERNS.some((re) => re.test(withoutQuotedLiterals));
+}
+/**
+ * Strip heredoc bodies so that blocked-pattern checks don't fire on
+ * data content inside heredocs.  Supports both quoted and unquoted
+ * delimiters: `<< 'EOF'`, `<< "EOF"`, `<< EOF`, `<<-EOF`.
+ *
+ * Only the body between the delimiter lines is replaced with spaces;
+ * the shell command on the `<<` line and the closing delimiter are
+ * preserved so other pattern checks still apply to the command itself.
+ */
+function stripHeredocBodies(raw) {
+    // Match << (optional dash) then optional quotes around the delimiter word
+    const heredocRe = /<<-?\s*(?:'([^']+)'|"([^"]+)"|(\w+))/g;
+    let result = raw;
+    let match;
+    // Collect all heredoc markers first, then strip from the end backwards
+    // so index positions remain valid.
+    const markers = [];
+    while ((match = heredocRe.exec(raw)) !== null) {
+        const delimiter = match[1] ?? match[2] ?? match[3] ?? "";
+        if (!delimiter)
+            continue;
+        // Body starts after the next newline following the << marker
+        const afterMarker = raw.indexOf("\n", match.index);
+        if (afterMarker === -1)
+            continue;
+        const bodyStart = afterMarker + 1;
+        // Find the closing delimiter: must be on its own line (with optional
+        // leading whitespace for <<- heredocs).
+        const closingRe = new RegExp(`^\\s*${delimiter.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s*$`, "m");
+        const bodySlice = raw.slice(bodyStart);
+        const closingMatch = closingRe.exec(bodySlice);
+        if (!closingMatch)
+            continue;
+        const bodyEnd = bodyStart + closingMatch.index;
+        markers.push({ delimiter, bodyStart, bodyEnd });
+    }
+    // Strip bodies from last to first to preserve indices
+    for (let i = markers.length - 1; i >= 0; i--) {
+        const { bodyStart, bodyEnd } = markers[i];
+        const body = result.slice(bodyStart, bodyEnd);
+        result = result.slice(0, bodyStart) + body.replace(/[^\n]/g, " ") + result.slice(bodyEnd);
+    }
+    return result;
+}
+/**
+ * Remove single-quoted and double-quoted literal text from a command so
+ * blocked-pattern checks don't fire on plain quoted prose like:
+ *   echo "please do not run rm -rf /"
+ */
+function stripSingleAndDoubleQuotedLiterals(raw) {
+    let result = "";
+    let inSingle = false;
+    let inDouble = false;
+    let escaped = false;
+    for (let i = 0; i < raw.length; i++) {
+        const ch = raw[i];
+        if (inSingle) {
+            if (ch === "'") {
+                inSingle = false;
+                result += " ";
+            }
+            else {
+                result += " ";
+            }
+            continue;
+        }
+        if (inDouble) {
+            if (escaped) {
+                escaped = false;
+                result += " ";
+                continue;
+            }
+            if (ch === "\\") {
+                escaped = true;
+                result += " ";
+                continue;
+            }
+            if (ch === '"') {
+                inDouble = false;
+                result += " ";
+            }
+            else {
+                result += " ";
+            }
+            continue;
+        }
+        if (ch === "'") {
+            inSingle = true;
+            result += " ";
+            continue;
+        }
+        if (ch === '"') {
+            inDouble = true;
+            result += " ";
+            continue;
+        }
+        result += ch;
+    }
+    return result;
+}
+/**
+ * Strip an optional absolute-path prefix from a token
+ * so `/usr/bin/rm` is treated the same as `rm`.
+ */
+function stripPathPrefix(token) {
+    const i = token.lastIndexOf("/");
+    return i === -1 ? token : token.slice(i + 1);
+}
+function hasUnquotedSubshellOrBacktick(command) {
+    let inSingle = false;
+    let inDouble = false;
+    let escaped = false;
+    for (let i = 0; i < command.length; i++) {
+        const ch = command[i];
+        const next = command[i + 1];
+        if (inSingle) {
+            if (ch === "'")
+                inSingle = false;
+            continue;
+        }
+        if (inDouble) {
+            if (escaped) {
+                escaped = false;
+                continue;
+            }
+            if (ch === "\\") {
+                escaped = true;
+                continue;
+            }
+            if (ch === '"') {
+                inDouble = false;
+                continue;
+            }
+            if (ch === "`" || (ch === "$" && next === "(")) {
+                return true;
+            }
+            continue;
+        }
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+        if (ch === "\\") {
+            escaped = true;
+            continue;
+        }
+        if (ch === "'") {
+            inSingle = true;
+            continue;
+        }
+        if (ch === '"') {
+            inDouble = true;
+            continue;
+        }
+        if (ch === "`" || (ch === "$" && next === "(")) {
+            return true;
+        }
+    }
+    return false;
+}
+function splitTopLevelChain(command) {
+    const parts = [];
+    let current = "";
+    let inSingle = false;
+    let inDouble = false;
+    let escaped = false;
+    for (let i = 0; i < command.length; i++) {
+        const ch = command[i];
+        const next = command[i + 1];
+        if (inSingle) {
+            current += ch;
+            if (ch === "'")
+                inSingle = false;
+            continue;
+        }
+        if (inDouble) {
+            current += ch;
+            if (escaped) {
+                escaped = false;
+                continue;
+            }
+            if (ch === "\\") {
+                escaped = true;
+                continue;
+            }
+            if (ch === '"')
+                inDouble = false;
+            continue;
+        }
+        if (escaped) {
+            current += ch;
+            escaped = false;
+            continue;
+        }
+        if (ch === "\\") {
+            current += ch;
+            escaped = true;
+            continue;
+        }
+        if (ch === "'") {
+            current += ch;
+            inSingle = true;
+            continue;
+        }
+        if (ch === '"') {
+            current += ch;
+            inDouble = true;
+            continue;
+        }
+        const isSeparator = ch === ";" ||
+            ch === "\n" ||
+            ch === "\r" ||
+            (ch === "&" && next === "&") ||
+            (ch === "|" && next === "|");
+        if (isSeparator) {
+            parts.push(current.trim());
+            current = "";
+            if ((ch === "&" || ch === "|") && next === ch) {
+                i += 1;
+            }
+            continue;
+        }
+        current += ch;
+    }
+    parts.push(current.trim());
+    return parts;
+}
+function splitTopLevelPipes(command) {
+    const parts = [];
+    let current = "";
+    let inSingle = false;
+    let inDouble = false;
+    let escaped = false;
+    for (let i = 0; i < command.length; i++) {
+        const ch = command[i];
+        const next = command[i + 1];
+        const prev = i > 0 ? command[i - 1] : "";
+        if (inSingle) {
+            current += ch;
+            if (ch === "'")
+                inSingle = false;
+            continue;
+        }
+        if (inDouble) {
+            current += ch;
+            if (escaped) {
+                escaped = false;
+                continue;
+            }
+            if (ch === "\\") {
+                escaped = true;
+                continue;
+            }
+            if (ch === '"')
+                inDouble = false;
+            continue;
+        }
+        if (escaped) {
+            current += ch;
+            escaped = false;
+            continue;
+        }
+        if (ch === "\\") {
+            current += ch;
+            escaped = true;
+            continue;
+        }
+        if (ch === "'") {
+            current += ch;
+            inSingle = true;
+            continue;
+        }
+        if (ch === '"') {
+            current += ch;
+            inDouble = true;
+            continue;
+        }
+        if (ch === "|" && next !== "|" && prev !== "|") {
+            parts.push(current.trim());
+            current = "";
+            continue;
+        }
+        current += ch;
+    }
+    parts.push(current.trim());
+    return parts;
+}
+/**
+ * Matches shell output redirection operators that WRITE to the filesystem.
+ * Excludes 2>&1 (stderr-to-stdout merge) which is read-only.
+ *
+ * Matches: >, >>, 2> (not followed by &), &>
+ * Does NOT match: 2>&1, <, <<
+ */
+const REDIRECTION_RE = /(?:>>|(?:^|[^2])>(?!&)|2>(?!&)|&>)/;
+/**
+ * Determine whether a single simple command (no pipes/chains) is safe.
+ * Returns true only when the command prefix is in the safe lists
+ * AND the segment contains no output redirection.
+ */
+function isSegmentSafe(segment) {
+    const trimmed = segment.trim();
+    if (trimmed === "")
+        return false;
+    // Output redirection makes any command non-safe
+    if (REDIRECTION_RE.test(trimmed))
+        return false;
+    // Multi-word safe match first (e.g. "git status")
+    for (const prefix of SAFE_MULTI) {
+        if (trimmed === prefix || trimmed.startsWith(prefix + " "))
+            return true;
+    }
+    // Single-word: first token, path-stripped
+    const firstToken = trimmed.split(/\s+/)[0] ?? "";
+    return SAFE_SINGLE.has(stripPathPrefix(firstToken));
+}
+/**
+ * Classify a shell command's risk level.
+ *
+ * - "safe"     — skip approval, execute immediately
+ * - "moderate" — handle via runtime policy (approval, allowlist, or autorun)
+ * - "blocked"  — never execute, return error immediately
+ */
+export function classifyCommand(command) {
+    const trimmed = command.trim();
+    // Empty / whitespace-only — can't determine intent
+    if (trimmed === "")
+        return "moderate";
+    // 0. Strip heredoc bodies once, upfront, so every downstream check
+    //    (whole-command, per-segment, per-pipe) operates on the sanitised text.
+    //    This prevents heredoc *data* from triggering blocked patterns.
+    const stripped = stripHeredocBodies(trimmed);
+    // 1. Check blocked patterns on the entire raw command
+    if (isBlocked(stripped))
+        return "blocked";
+    // 2. Subshells / backticks — can't statically analyze safely.
+    // Check before splitting to avoid quote-unaware false positives.
+    if (hasUnquotedSubshellOrBacktick(stripped))
+        return "moderate";
+    // 3. Split on chain operators (&&, ||, ;, newline) outside quoted strings.
+    const chainSegments = splitTopLevelChain(stripped);
+    for (const seg of chainSegments) {
+        if (isBlocked(seg))
+            return "blocked";
+    }
+    // 4. Split each chain segment on top-level pipes and check.
+    const allSegments = [];
+    for (const seg of chainSegments) {
+        const piped = splitTopLevelPipes(seg);
+        for (const p of piped) {
+            if (isBlocked(p))
+                return "blocked";
+            allSegments.push(p);
+        }
+    }
+    // 5. Env-var assignment prefix (VAR=val command)
+    if (/^[A-Za-z_]\w*=/.test(trimmed))
+        return "moderate";
+    // 6. Check if ALL segments are safe (filter empty segments from chain splitting)
+    const nonEmpty = allSegments.filter((s) => s.trim() !== "");
+    if (nonEmpty.length > 0 && nonEmpty.every(isSegmentSafe))
+        return "safe";
+    // 7. Default — needs approval
+    return "moderate";
+}
+const EXPLICIT_SHELLS = new Set(["sh", "bash", "zsh", "ksh", "dash", "ash", "fish"]);
+/**
+ * Classify argv-based process execution (spawn/exec) with shell-aware behavior.
+ *
+ * When callers explicitly invoke a shell interpreter with `-c`, classify the
+ * payload command text itself. This preserves catastrophic-command blocking
+ * while avoiding false positives that would block every `bash -c ...` call.
+ */
+export function classifyExecInvocation(program, args = []) {
+    const shellName = stripPathPrefix(program).toLowerCase();
+    if (EXPLICIT_SHELLS.has(shellName) && args[0] === "-c" && typeof args[1] === "string") {
+        return classifyCommand(args[1]);
+    }
+    return classifyCommand([program, ...args].join(" "));
+}
+//# sourceMappingURL=shell-safety.js.map