@theokit/sdk-tools 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.3.0
+
+### Minor Changes
+
+- 986f340: V3-1 — harden `catastrophicShellReason` to theocode's security-reviewed shell-guard. The `shell_exec` guardrail previously missed 18 of 42 catastrophic commands (empirical probe): `git reset --hard`, `git clean -fd`, secret-file exfiltration (`cat .env | curl`, `tar ~/.aws | nc`), command-substitution / eval RCE (`eval "$(curl)"`, `. <(curl)`, `bash -c "$(curl)"`), `find / -delete` / `-exec rm`, `truncate /dev/sda`, and a range of `rm -rf` targets (`~/sub`, `/usr/local`, `../..`, `$HOME/x`, flags after the operand, any absolute non-scratch path). The rules are ported from theocode's hardened guard (proven by a 42-blocked + 24-allowed corpus at 0 misses / 0 false-positives) as a SUPERSET — the SDK's extra screens (recursive `chmod`/`chown` on a root path, extra block-device families, `//` collapse) are kept, and the segment splitter now also covers `&` and newlines. Reason strings widened to describe each category; the public API (`catastrophicShellReason(cmd): string | null`, `CatastrophicCommandError`) is unchanged. No new dependency.
+
 ## 0.2.0
 
 ### Minor Changes

package/README.md

@@ -4,6 +4,8 @@ Built-in tools for `@theokit/sdk` agents. File system, git, subprocess, search-t
 
 Extracted from `@theokit/sdk@1.7.0` as part of the SDK 2.0 package split.
 
+See the [**Theo Harness Capability Map**](../../docs/harness-capability-map.md) for every tool + guard primitive (`buildRepoMap`, `isBlockedIp`, `screenedFetch`, `catastrophicShellReason`, ...) with import paths and examples.
+
 ## Install
 
 ```bash

package/dist/index.cjs

@@ -96,8 +96,8 @@ function isForbiddenPath(input) {
   if (first === ".git") return true;
   if (first === "node_modules") return true;
   if (first === ".theo") return true;
-  const basename2 = segments[segments.length - 1];
-  if (LOCK_FILES.has(basename2)) return true;
+  const basename = segments[segments.length - 1];
+  if (LOCK_FILES.has(basename)) return true;
   return false;
 }
 
@@ -601,128 +601,96 @@ var CatastrophicCommandError = class extends sdk.ConfigurationError {
     });
   }
 };
-var SHELL_NAMES = /* @__PURE__ */ new Set(["sh", "bash", "zsh", "dash", "ksh", "ash"]);
-var PREFIX_TOKENS = /* @__PURE__ */ new Set([
-  "sudo",
-  "doas",
-  "env",
-  "command",
-  "time",
-  "nice",
-  "nohup",
-  "exec",
-  "builtin"
-]);
-var FORK_BOMB = /:\s*\(\s*\)\s*\{[^}]*\|[^}]*&[^}]*\}/;
-var DEVICE_REDIRECT = /[>]\s*\/dev\/(?:sd|nvme|hd|vd|mmcblk|disk|loop|dm-)\w*/;
-var SYSTEM_DIR = /^\/(?:etc|usr|bin|sbin|lib|lib64|var|boot|home|root|opt|sys|proc|dev)(?:\/\*?)?$/;
-function basename(p) {
-  const i = p.lastIndexOf("/");
-  return i >= 0 ? p.slice(i + 1) : p;
-}
-function unquote(t) {
-  if (t.length >= 2) {
-    const a = t[0];
-    const b = t[t.length - 1];
-    if (a === '"' && b === '"' || a === "'" && b === "'") return t.slice(1, -1);
-  }
-  return t;
-}
-function tokenize(s) {
-  return s.trim().split(/\s+/).filter(Boolean);
-}
-function splitSegments(cmd) {
-  return cmd.split(/&&|\|\||;|\|/);
-}
-function stripPrefixTokens(tokens) {
-  let t = tokens;
-  let head = t[0];
-  while (head !== void 0 && PREFIX_TOKENS.has(basename(unquote(head)))) {
-    t = t.slice(1);
-    head = t[0];
-  }
-  return t;
-}
-function operandsOf(tokens) {
-  return tokens.slice(1).filter((t) => !t.startsWith("-")).map(unquote);
-}
-var HOME_VAR = /^\$\{?HOME\}?$/;
-function isRootishPath(op) {
-  if (op === "~" || op === "*" || op === "." || HOME_VAR.test(op)) return true;
-  let collapsed = op.replace(/\/+/g, "/");
-  if (collapsed.length > 1 && collapsed.endsWith("/")) collapsed = collapsed.slice(0, -1);
-  if (collapsed === "/" || collapsed === "/*" || collapsed === "/.") return true;
-  return SYSTEM_DIR.test(collapsed);
-}
-function hasRecursiveForce(tokens) {
-  const flags = tokens.slice(1).filter((t) => t.startsWith("-"));
-  const recursive = flags.some(
-    (f) => f === "--recursive" || !f.startsWith("--") && /[rR]/.test(f)
-  );
-  const force = flags.some((f) => f === "--force" || !f.startsWith("--") && f.includes("f"));
+function unquote(token) {
+  return token.replace(/^(['"])(.*)\1$/, "$2").replace(/^['"]|['"]$/g, "");
+}
+function commandSegments(command) {
+  return command.split(/&&|\|\||[;|&\n]/).map((s) => s.trim()).filter((s) => s.length > 0);
+}
+function commandArgs(segment, name) {
+  const tokens = segment.split(/\s+/);
+  let i = 0;
+  if (tokens[i] === "sudo") i += 1;
+  if (tokens[i] !== name) return null;
+  return tokens.slice(i + 1);
+}
+function commandSegmentsNamed(command, name) {
+  return commandSegments(command).map((s) => commandArgs(s, name)).filter((args) => args !== null);
+}
+function isRecursiveForce(args) {
+  const flags = args.filter((t) => t.startsWith("-")).join(" ");
+  if (flags.length === 0) return false;
+  const recursive = /-[a-z]*r/i.test(flags) || /--recursive/.test(flags);
+  const force = /-[a-z]*f/i.test(flags) || /--force/.test(flags);
   return recursive && force;
 }
-function hasRecursiveFlag(tokens) {
-  return tokens.slice(1).some(
-    (t) => t === "--recursive" || t.startsWith("-") && !t.startsWith("--") && /[rR]/.test(t)
-  );
+function isRecursive(args) {
+  const flags = args.filter((t) => t.startsWith("-")).join(" ");
+  return /-[a-z]*r/i.test(flags) || /--recursive/.test(flags);
+}
+var SAFE_ABSOLUTE_TARGET = /^\/(tmp|var\/tmp)(\/|$)/;
+function targetsDangerousPath(args) {
+  const targets = args.filter((token) => token.length > 0 && !token.startsWith("-")).map(unquote);
+  return targets.some((raw) => {
+    const t = raw.replace(/\/+/g, "/");
+    if (t === "/dev/null" || SAFE_ABSOLUTE_TARGET.test(t)) return false;
+    return /^\/($|\*)/.test(t) || // "/" or "/*"
+    /^\/[^/]/.test(t) || // an absolute path like /etc, /usr/local, /home/user/x
+    t === "~" || t.startsWith("~/") || /\$\{?HOME\b\}?/.test(t) || // $HOME or ${HOME}
+    t === ".." || t.startsWith("../") || t.includes("/..") || t === "*";
+  });
 }
-function isCurlPipedToShell(cmd) {
-  const segs = cmd.replace(/\|\|/g, ";").split(/[;|]/).map((s) => s.trim()).filter(Boolean);
-  let fetcher = false;
-  let shell = false;
-  for (const s of segs) {
-    const tk = stripPrefixTokens(tokenize(s));
-    const head = tk[0];
-    if (head === void 0) continue;
-    const c = basename(unquote(head));
-    if (c === "curl" || c === "wget") fetcher = true;
-    if (SHELL_NAMES.has(c)) shell = true;
-  }
-  return fetcher && shell;
-}
-var rmCheck = (cmd0, tokens) => {
-  if (cmd0 !== "rm" || !hasRecursiveForce(tokens)) return null;
-  const ops = operandsOf(tokens);
-  return ops.length === 0 || ops.some(isRootishPath) ? "rm -rf of a root/home/glob path" : null;
-};
-var mkfsCheck = (cmd0) => cmd0.startsWith("mkfs") ? "mkfs on a device" : null;
-var ddCheck = (cmd0, tokens) => {
-  if (cmd0 !== "dd") return null;
-  return tokens.some((t) => unquote(t).startsWith("of=/dev/")) ? "dd writing to a device" : null;
-};
-var gitForceCheck = (cmd0, tokens) => {
-  if (cmd0 !== "git" || !tokens.includes("push") || tokens.includes("--force-with-lease")) {
-    return null;
+var DEVICE_WIPE = [
+  /\bmkfs(\.\w+)?\b/,
+  /\bdd\b[^\n]*\bof=\/dev\//,
+  /\btruncate\b[^\n]*\s\/dev\//,
+  />\s*\/dev\/(sd|nvme|hd|vd|mmcblk|disk|loop|dm-)/
+];
+var checkRemoteExec = (cmd) => /\b(curl|wget|fetch)\b[^\n]*\|\s*(sudo\s+)?(sh|bash|zsh|dash|python[0-9.]*|node|ruby|perl)\b/i.test(
+  cmd
+) || /(\$\(|<\()\s*(sudo\s+)?(curl|wget|fetch)\b/i.test(cmd) || /\b(eval|source)\b[^\n]*\b(curl|wget|fetch)\b/i.test(cmd) ? "executes a remote download (pipe / command-substitution / eval) \u2014 remote code execution" : null;
+var checkDeviceWipe = (cmd) => DEVICE_WIPE.some((re) => re.test(cmd)) ? "writes to a raw block device / formats a disk" : null;
+var checkForkBomb = (cmd) => /:\(\)\s*\{\s*:\s*\|\s*:\s*&\s*\}\s*;\s*:/.test(cmd) ? "fork bomb" : null;
+var checkDestructiveGit = (cmd) => {
+  if (/\bgit\b[^\n]*\bpush\b[^\n]*(--force(?!-with-lease)\b|\s-f\b|\s\+\S)/.test(cmd)) {
+    return "git force-push (overwrites remote history)";
+  }
+  if (/\bgit\b[^\n]*\breset\b[^\n]*--hard\b/.test(cmd)) {
+    return "git reset --hard (discards committed and working changes)";
+  }
+  if (/\bgit\b[^\n]*\bclean\b[^\n]*(-[a-z]*f[a-z]*d|-[a-z]*d[a-z]*f)/.test(cmd)) {
+    return "git clean -fd (permanently deletes untracked files)";
   }
-  const force = tokens.includes("--force") || tokens.some((t) => /^-[a-z]*f[a-z]*$/.test(t)) || operandsOf(tokens).some((op) => /^\+[^+]/.test(op));
-  return force ? "git push --force" : null;
+  return null;
 };
-var permCheck = (cmd0, tokens) => {
-  if (cmd0 !== "chmod" && cmd0 !== "chown" || !hasRecursiveFlag(tokens)) return null;
-  return operandsOf(tokens).some(isRootishPath) ? `${cmd0} -R on a root path` : null;
+var checkRm = (cmd) => commandSegmentsNamed(cmd, "rm").some((a) => isRecursiveForce(a) && targetsDangerousPath(a)) ? "recursive force-delete of an absolute, home, or parent path" : null;
+var checkPerm = (cmd) => ["chmod", "chown"].some(
+  (name) => commandSegmentsNamed(cmd, name).some((a) => isRecursive(a) && targetsDangerousPath(a))
+) ? "recursive permission change on an absolute, home, or parent path" : null;
+var checkFind = (cmd) => /\bfind\s+(\/\S*|~\S*|\$\{?HOME\}?\S*)\s[^\n]*(-delete\b|-exec\s+rm\b)/.test(cmd) ? "find -delete / -exec rm on an absolute or home path" : null;
+var checkExfiltration = (cmd) => {
+  const touchesSecret = /(^|[\s/'"])(\.env(\.\w+)?|id_rsa|id_ed25519|\.ssh(\/|\b)|credentials|\.aws(\/|\b)|\.npmrc)\b/.test(
+    cmd
+  );
+  const sendsNetwork = /\b(curl|wget|nc|netcat|scp|ftp|telnet)\b/.test(cmd) || /\bpython[0-9.]*\s+-m\s+http/.test(cmd);
+  return touchesSecret && sendsNetwork ? "sends a secret/credential file over the network (exfiltration)" : null;
 };
-var redirectCheck = (_cmd0, _tokens, seg) => DEVICE_REDIRECT.test(seg) ? "redirect to a device" : null;
-var SEGMENT_CHECKS = [
-  rmCheck,
-  mkfsCheck,
-  ddCheck,
-  gitForceCheck,
-  permCheck,
-  redirectCheck
+var CATEGORY_CHECKS = [
+  checkRemoteExec,
+  checkDeviceWipe,
+  checkForkBomb,
+  checkDestructiveGit,
+  checkRm,
+  checkPerm,
+  checkFind,
+  checkExfiltration
 ];
-function catastrophicShellReason(cmd) {
-  if (FORK_BOMB.test(cmd)) return "fork bomb";
-  if (isCurlPipedToShell(cmd)) return "curl/wget piped into a shell";
-  for (const seg of splitSegments(cmd)) {
-    const tokens = stripPrefixTokens(tokenize(seg));
-    const head = tokens[0];
-    if (head === void 0) continue;
-    const cmd0 = basename(unquote(head));
-    for (const check of SEGMENT_CHECKS) {
-      const reason = check(cmd0, tokens, seg);
-      if (reason) return reason;
-    }
+function catastrophicShellReason(command) {
+  const cmd = command.trim();
+  if (cmd.length === 0) return null;
+  for (const check of CATEGORY_CHECKS) {
+    const reason = check(cmd);
+    if (reason) return reason;
   }
   return null;
 }