@aria-cli/tools 1.0.0

package/src/executors/shell-safety.ts

@@ -0,0 +1,519 @@
+/**
+ * @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
+ */
+
+export type ShellRisk = "safe" | "moderate" | "blocked";
+
+/** 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: string[] = [
+  "git stash list",
+  "git status",
+  "git log",
+  "git diff",
+  "git show",
+  "git blame",
+  "git branch",
+  "git remote",
+  "git tag",
+  "node --version",
+  "npm --version",
+  "pnpm --version",
+  "python --version",
+  "pnpm list",
+  "npm list",
+];
+
+/** Patterns that are unconditionally blocked — catastrophic risk. */
+export const BLOCKED_PATTERNS: RegExp[] = [
+  /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: string): boolean {
+  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: string): string {
+  // Match << (optional dash) then optional quotes around the delimiter word
+  const heredocRe = /<<-?\s*(?:'([^']+)'|"([^"]+)"|(\w+))/g;
+  let result = raw;
+  let match: RegExpExecArray | null;
+
+  // Collect all heredoc markers first, then strip from the end backwards
+  // so index positions remain valid.
+  const markers: Array<{ delimiter: string; bodyStart: number; bodyEnd: number }> = [];
+
+  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: string): string {
+  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: string): string {
+  const i = token.lastIndexOf("/");
+  return i === -1 ? token : token.slice(i + 1);
+}
+
+function hasUnquotedSubshellOrBacktick(command: string): boolean {
+  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: string): string[] {
+  const parts: string[] = [];
+  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: string): string[] {
+  const parts: string[] = [];
+  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: string): boolean {
+  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: string): ShellRisk {
+  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: string[] = [];
+  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: string, args: string[] = []): ShellRisk {
+  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(" "));
+}