@aliou/pi-guardrails 0.9.5 → 0.11.0

package/src/hooks/permission-gate/dangerous-commands.test.ts

@@ -0,0 +1,336 @@
+import { describe, expect, it } from "vitest";
+import { BUILTIN_MATCHERS, matchDangerousCommand } from "./dangerous-commands";
+
+/**
+ * Helper to run all matchers against a command string.
+ * Returns the first match description, or undefined if none match.
+ */
+function findMatch(words: string[]): string | undefined {
+  for (const matcher of BUILTIN_MATCHERS) {
+    const result = matcher(words);
+    if (result) return result;
+  }
+  return undefined;
+}
+
+describe("rm matcher", () => {
+  it("matches rm -rf", () => {
+    expect(findMatch(["rm", "-rf", "/tmp/test"])).toBe(
+      "recursive force delete",
+    );
+  });
+
+  it("matches rm -fr (reversed flags)", () => {
+    expect(findMatch(["rm", "-fr", "/tmp/test"])).toBe(
+      "recursive force delete",
+    );
+  });
+
+  it("matches rm -r -f (separate flags)", () => {
+    expect(findMatch(["rm", "-r", "-f", "/tmp/test"])).toBe(
+      "recursive force delete",
+    );
+  });
+
+  it("matches rm --recursive --force (long options)", () => {
+    expect(findMatch(["rm", "--recursive", "--force", "/tmp/test"])).toBe(
+      "recursive force delete",
+    );
+  });
+
+  it("matches rm --force --recursive (reversed long options)", () => {
+    expect(findMatch(["rm", "--force", "--recursive", "/tmp/test"])).toBe(
+      "recursive force delete",
+    );
+  });
+
+  it("matches rm -Rfv (grouped with extra flags)", () => {
+    expect(findMatch(["rm", "-Rfv", "/tmp/test"])).toBe(
+      "recursive force delete",
+    );
+  });
+
+  it("does not match rm -r (no force)", () => {
+    expect(findMatch(["rm", "-r", "/tmp/test"])).toBeUndefined();
+  });
+
+  it("does not match rm -f (no recursive)", () => {
+    expect(findMatch(["rm", "-f", "/tmp/test"])).toBeUndefined();
+  });
+
+  it("does not match echo rm -rf", () => {
+    expect(findMatch(["echo", "rm", "-rf", "/"])).toBeUndefined();
+  });
+});
+
+describe("sudo matcher", () => {
+  it("matches sudo", () => {
+    expect(findMatch(["sudo", "apt", "update"])).toBe("superuser command");
+  });
+
+  it("matches sudo at start only", () => {
+    expect(findMatch(["echo", "sudo", "something"])).toBeUndefined();
+  });
+});
+
+describe("doas matcher", () => {
+  it("matches doas", () => {
+    expect(findMatch(["doas", "pkg_add", "vim"])).toBe(
+      "privileged command execution",
+    );
+  });
+});
+
+describe("pkexec matcher", () => {
+  it("matches pkexec", () => {
+    expect(findMatch(["pkexec", "apt", "install", "firefox"])).toBe(
+      "privileged command execution",
+    );
+  });
+});
+
+describe("dd matcher", () => {
+  it("matches dd with of= (output file)", () => {
+    expect(findMatch(["dd", "if=/dev/zero", "of=/dev/sda"])).toBe(
+      "disk write operation",
+    );
+  });
+
+  it("matches dd with of= in any order", () => {
+    expect(findMatch(["dd", "of=/dev/sda", "if=/dev/zero"])).toBe(
+      "disk write operation",
+    );
+  });
+
+  it("matches dd with progress and of=", () => {
+    expect(
+      findMatch(["dd", "status=progress", "of=/dev/sdb", "if=image.img"]),
+    ).toBe("disk write operation");
+  });
+
+  it("does not match dd with only if= (input only)", () => {
+    expect(findMatch(["dd", "if=/dev/sda", "of=/dev/null"])).toBe(
+      "disk write operation",
+    );
+  });
+
+  it("does not match dd with only if= (read-only)", () => {
+    expect(findMatch(["dd", "if=/dev/sda"])).toBeUndefined();
+  });
+});
+
+describe("mkfs matcher", () => {
+  it("matches mkfs.ext4", () => {
+    expect(findMatch(["mkfs.ext4", "/dev/sda1"])).toBe("filesystem format");
+  });
+
+  it("matches mkfs.xfs", () => {
+    expect(findMatch(["mkfs.xfs", "/dev/sdb1"])).toBe("filesystem format");
+  });
+
+  it("matches plain mkfs", () => {
+    expect(findMatch(["mkfs", "/dev/sda1"])).toBe("filesystem format");
+  });
+
+  it("matches mkfs.vfat", () => {
+    expect(findMatch(["mkfs.vfat", "/dev/sdc1"])).toBe("filesystem format");
+  });
+});
+
+describe("shred matcher", () => {
+  it("matches shred", () => {
+    expect(findMatch(["shred", "-u", "secret.txt"])).toBe(
+      "secure file overwrite",
+    );
+  });
+});
+
+describe("wipefs matcher", () => {
+  it("matches wipefs", () => {
+    expect(findMatch(["wipefs", "-a", "/dev/sda"])).toBe(
+      "filesystem signature wipe",
+    );
+  });
+});
+
+describe("blkdiscard matcher", () => {
+  it("matches blkdiscard", () => {
+    expect(findMatch(["blkdiscard", "/dev/nvme0n1"])).toBe(
+      "block device discard",
+    );
+  });
+});
+
+describe("fdisk matcher", () => {
+  it("matches fdisk", () => {
+    expect(findMatch(["fdisk", "/dev/sda"])).toBe("disk partitioning");
+  });
+
+  it("matches sfdisk", () => {
+    expect(findMatch(["sfdisk", "/dev/sda"])).toBe("disk partitioning");
+  });
+
+  it("matches cfdisk", () => {
+    expect(findMatch(["cfdisk", "/dev/sda"])).toBe("disk partitioning");
+  });
+});
+
+describe("parted matcher", () => {
+  it("matches parted", () => {
+    expect(findMatch(["parted", "/dev/sda"])).toBe("disk partitioning");
+  });
+
+  it("matches sgdisk", () => {
+    expect(findMatch(["sgdisk", "-l", "/dev/sda"])).toBe("disk partitioning");
+  });
+});
+
+describe("chmod matcher", () => {
+  it("matches chmod -R 777", () => {
+    expect(findMatch(["chmod", "-R", "777", "/tmp"])).toBe(
+      "insecure recursive permissions",
+    );
+  });
+
+  it("matches chmod --recursive 777", () => {
+    expect(findMatch(["chmod", "--recursive", "777", "/tmp"])).toBe(
+      "insecure recursive permissions",
+    );
+  });
+
+  it("matches chmod -R 0777", () => {
+    expect(findMatch(["chmod", "-R", "0777", "/tmp"])).toBe(
+      "insecure recursive permissions",
+    );
+  });
+
+  it("matches chmod -R a+rwx", () => {
+    expect(findMatch(["chmod", "-R", "a+rwx", "/tmp"])).toBe(
+      "insecure recursive permissions",
+    );
+  });
+
+  it("matches chmod -R ugo+rwx", () => {
+    expect(findMatch(["chmod", "-R", "ugo+rwx", "/tmp"])).toBe(
+      "insecure recursive permissions",
+    );
+  });
+
+  it("does not match chmod 755 (not world-writable)", () => {
+    expect(findMatch(["chmod", "755", "file"])).toBeUndefined();
+  });
+
+  it("does not match chmod -R 755 (not world-writable)", () => {
+    expect(findMatch(["chmod", "-R", "755", "/tmp"])).toBeUndefined();
+  });
+});
+
+describe("chown matcher", () => {
+  it("matches chown -R", () => {
+    expect(findMatch(["chown", "-R", "user:group", "/tmp"])).toBe(
+      "recursive ownership change",
+    );
+  });
+
+  it("matches chown --recursive", () => {
+    expect(findMatch(["chown", "--recursive", "user", "/tmp"])).toBe(
+      "recursive ownership change",
+    );
+  });
+
+  it("does not match chown without -R", () => {
+    expect(findMatch(["chown", "user:group", "/tmp/file"])).toBeUndefined();
+  });
+});
+
+describe("container matcher (docker/podman)", () => {
+  describe("docker", () => {
+    it("matches docker run --privileged", () => {
+      expect(findMatch(["docker", "run", "--privileged", "alpine"])).toBe(
+        "container with privileged mode",
+      );
+    });
+
+    it("matches docker run --pid=host", () => {
+      expect(findMatch(["docker", "run", "--pid=host", "alpine"])).toBe(
+        "container with host PID namespace",
+      );
+    });
+
+    it("matches docker run --network=host", () => {
+      expect(findMatch(["docker", "run", "--network=host", "alpine"])).toBe(
+        "container with host network",
+      );
+    });
+
+    it("matches docker run --userns=host", () => {
+      expect(findMatch(["docker", "run", "--userns=host", "alpine"])).toBe(
+        "container with host user namespace",
+      );
+    });
+
+    it("matches docker run with root mount", () => {
+      expect(findMatch(["docker", "run", "-v/:/host", "alpine"])).toBe(
+        "container with root filesystem mount",
+      );
+    });
+
+    it("matches docker run with docker socket", () => {
+      expect(
+        findMatch([
+          "docker",
+          "run",
+          "-v",
+          "/var/run/docker.sock:/var/run/docker.sock",
+          "alpine",
+        ]),
+      ).toBe("container with docker socket access");
+    });
+
+    it("does not match docker build", () => {
+      expect(
+        findMatch(["docker", "build", "-t", "myimage", "."]),
+      ).toBeUndefined();
+    });
+
+    it("does not match docker run without dangerous flags", () => {
+      expect(
+        findMatch(["docker", "run", "alpine", "echo", "hello"]),
+      ).toBeUndefined();
+    });
+  });
+
+  describe("podman", () => {
+    it("matches podman run --privileged", () => {
+      expect(findMatch(["podman", "run", "--privileged", "alpine"])).toBe(
+        "container with privileged mode",
+      );
+    });
+
+    it("matches podman create --privileged", () => {
+      expect(findMatch(["podman", "create", "--privileged", "alpine"])).toBe(
+        "container with privileged mode",
+      );
+    });
+  });
+});
+
+describe("matchDangerousCommand", () => {
+  it("returns description and pattern for dangerous commands", () => {
+    const result = matchDangerousCommand(["sudo", "apt", "update"]);
+    expect(result).toEqual({
+      description: "superuser command",
+      pattern: "sudo",
+    });
+  });
+
+  it("returns undefined for safe commands", () => {
+    expect(matchDangerousCommand(["echo", "hello"])).toBeUndefined();
+  });
+
+  it("returns first match when multiple could apply", () => {
+    // sudo comes before dd in the matcher list
+    const result = matchDangerousCommand(["sudo", "dd", "of=/dev/sda"]);
+    expect(result?.pattern).toBe("sudo");
+  });
+});

package/src/hooks/permission-gate/dangerous-commands.ts

@@ -0,0 +1,345 @@
+/**
+ * Dangerous command matchers for the permission gate.
+ *
+ * Built-in dangerous patterns are matched structurally via AST parsing.
+ * Each matcher receives the parsed command words and returns a description
+ * if the command is dangerous, or undefined if not matched.
+ */
+
+export type StructuralMatcher = (words: string[]) => string | undefined;
+
+/**
+ * Helper to check if any word starts with a given prefix.
+ */
+function hasArg(words: string[], prefix: string): boolean {
+  return words.some((w) => w.startsWith(prefix));
+}
+
+/**
+ * Helper to check if short options contain specific flags.
+ * Handles grouped short options like -rf, -fr, -Rfv, etc.
+ */
+function hasShortFlag(words: string[], flag: string): boolean {
+  return words.some(
+    (w) =>
+      w === `-${flag}` ||
+      (w.startsWith("-") && !w.startsWith("--") && w.includes(flag)),
+  );
+}
+
+/**
+ * Helper to check for long options.
+ */
+function hasLongOption(words: string[], option: string): boolean {
+  return words.some((w) => w === `--${option}`);
+}
+
+// =============================================================================
+// File/Directory Destruction
+// =============================================================================
+
+/**
+ * rm -rf, rm -r -f, rm --recursive --force, etc.
+ * Catches recursive force delete in any form.
+ */
+const rmMatcher: StructuralMatcher = (words) => {
+  if (words[0] !== "rm") return undefined;
+
+  const hasRecursive =
+    hasShortFlag(words, "r") ||
+    hasShortFlag(words, "R") ||
+    hasLongOption(words, "recursive") ||
+    hasLongOption(words, "dir");
+
+  const hasForce = hasShortFlag(words, "f") || hasLongOption(words, "force");
+
+  return hasRecursive && hasForce ? "recursive force delete" : undefined;
+};
+
+/**
+ * shred - secure file/device overwrite
+ */
+const shredMatcher: StructuralMatcher = (words) => {
+  if (words[0] === "shred") return "secure file overwrite";
+  return undefined;
+};
+
+// =============================================================================
+// Privilege Escalation
+// =============================================================================
+
+/**
+ * sudo - superuser command
+ */
+const sudoMatcher: StructuralMatcher = (words) => {
+  if (words[0] === "sudo") return "superuser command";
+  return undefined;
+};
+
+/**
+ * doas - privilege escalation (OpenBSD-style sudo alternative)
+ */
+const doasMatcher: StructuralMatcher = (words) => {
+  if (words[0] === "doas") return "privileged command execution";
+  return undefined;
+};
+
+/**
+ * pkexec - PolicyKit privilege escalation
+ */
+const pkexecMatcher: StructuralMatcher = (words) => {
+  if (words[0] === "pkexec") return "privileged command execution";
+  return undefined;
+};
+
+// =============================================================================
+// Disk/Filesystem Operations
+// =============================================================================
+
+/**
+ * dd of= - disk write operation
+ * Any dd command with an output file is potentially dangerous.
+ */
+const ddMatcher: StructuralMatcher = (words) => {
+  if (words[0] !== "dd") return undefined;
+  return hasArg(words, "of=") ? "disk write operation" : undefined;
+};
+
+/**
+ * mkfs, mkfs.* - filesystem format
+ */
+const mkfsMatcher: StructuralMatcher = (words) => {
+  const cmd = words[0];
+  if (cmd === "mkfs" || cmd?.startsWith("mkfs.")) return "filesystem format";
+  return undefined;
+};
+
+/**
+ * wipefs - filesystem signature wipe
+ */
+const wipefsMatcher: StructuralMatcher = (words) => {
+  if (words[0] === "wipefs") return "filesystem signature wipe";
+  return undefined;
+};
+
+/**
+ * blkdiscard - block device discard (destroys data)
+ */
+const blkdiscardMatcher: StructuralMatcher = (words) => {
+  if (words[0] === "blkdiscard") return "block device discard";
+  return undefined;
+};
+
+// =============================================================================
+// Disk Partitioning
+// =============================================================================
+
+/**
+ * fdisk, sfdisk, cfdisk - disk partitioning
+ */
+const fdiskMatcher: StructuralMatcher = (words) => {
+  const cmd = words[0];
+  if (cmd === "fdisk" || cmd === "sfdisk" || cmd === "cfdisk") {
+    return "disk partitioning";
+  }
+  return undefined;
+};
+
+/**
+ * parted, sgdisk - advanced disk partitioning
+ */
+const partedMatcher: StructuralMatcher = (words) => {
+  const cmd = words[0];
+  if (cmd === "parted" || cmd === "sgdisk") return "disk partitioning";
+  return undefined;
+};
+
+// =============================================================================
+// Permission Changes
+// =============================================================================
+
+/**
+ * chmod -R 777, chmod --recursive 777, chmod -R 0777, etc.
+ * Insecure recursive world-writable permissions.
+ */
+const chmodMatcher: StructuralMatcher = (words) => {
+  if (words[0] !== "chmod") return undefined;
+
+  const hasRecursive =
+    hasShortFlag(words, "R") || hasLongOption(words, "recursive");
+
+  const hasWorldWritable = words.some(
+    (w) =>
+      w === "777" ||
+      w === "0777" ||
+      w === "a+rwx" ||
+      w === "ugo+rwx" ||
+      w === "7777" || // setuid/setgid/sticky + world writable
+      w === "1777", // sticky + world writable
+  );
+
+  return hasRecursive && hasWorldWritable
+    ? "insecure recursive permissions"
+    : undefined;
+};
+
+/**
+ * chown -R, chown --recursive - recursive ownership change
+ */
+const chownMatcher: StructuralMatcher = (words) => {
+  if (words[0] !== "chown") return undefined;
+
+  const hasRecursive =
+    hasShortFlag(words, "R") || hasLongOption(words, "recursive");
+
+  return hasRecursive ? "recursive ownership change" : undefined;
+};
+
+// =============================================================================
+// Container Escape / Dangerous Container Operations
+// =============================================================================
+
+/**
+ * Docker/Podman dangerous run/create patterns.
+ * Flags: --privileged, --pid=host, --network=host, --userns=host,
+ *        --uts=host, --ipc=host, -v /:/host, docker socket mounts
+ */
+const containerMatcher: StructuralMatcher = (words) => {
+  const cmd = words[0];
+  if (!cmd) return undefined;
+
+  // Match docker or podman commands
+  const isDocker = cmd === "docker" || cmd === "podman";
+  if (!isDocker) return undefined;
+
+  // Only check run and create commands (not build, pull, etc.)
+  const subcommand = words[1];
+  if (subcommand !== "run" && subcommand !== "create") return undefined;
+
+  // Check for dangerous flags
+  const hasPrivileged = words.some(
+    (w) => w === "--privileged" || w.startsWith("--privileged="),
+  );
+
+  const hasHostPid = words.some(
+    (w) => w === "--pid=host" || w.startsWith("--pid=host"),
+  );
+
+  const hasHostNetwork = words.some(
+    (w) => w === "--network=host" || w.startsWith("--network=host"),
+  );
+
+  const hasHostUsers = words.some(
+    (w) => w === "--userns=host" || w.startsWith("--userns=host"),
+  );
+
+  const hasHostUts = words.some(
+    (w) => w === "--uts=host" || w.startsWith("--uts=host"),
+  );
+
+  const hasHostIpc = words.some(
+    (w) => w === "--ipc=host" || w.startsWith("--ipc=host"),
+  );
+
+  // Check for root filesystem bind mount
+  const hasRootMount = words.some(
+    (w) =>
+      w.startsWith("-v/:") ||
+      w.startsWith("-v/=>") ||
+      w.startsWith("--volume=/:") ||
+      w.startsWith("--mount=type=bind,source=/,"),
+  );
+
+  // Check for docker socket mount
+  const hasDockerSocket = words.some(
+    (w) =>
+      w.includes("/var/run/docker.sock") ||
+      w.includes("/run/docker.sock") ||
+      w.includes("/var/run/podman.sock") ||
+      w.includes("/run/podman.sock"),
+  );
+
+  if (hasPrivileged) return "container with privileged mode";
+  if (hasHostPid) return "container with host PID namespace";
+  if (hasHostNetwork) return "container with host network";
+  if (hasHostUsers) return "container with host user namespace";
+  if (hasHostUts) return "container with host UTS namespace";
+  if (hasHostIpc) return "container with host IPC";
+  if (hasRootMount) return "container with root filesystem mount";
+  if (hasDockerSocket) return "container with docker socket access";
+
+  return undefined;
+};
+
+// =============================================================================
+// Matcher Registry
+// =============================================================================
+
+/**
+ * All built-in dangerous command matchers.
+ * Order matters - earlier matchers take precedence if multiple match.
+ */
+export const BUILTIN_MATCHERS: StructuralMatcher[] = [
+  // Destruction (highest priority)
+  rmMatcher,
+  shredMatcher,
+
+  // Privilege escalation
+  sudoMatcher,
+  doasMatcher,
+  pkexecMatcher,
+
+  // Disk/filesystem operations
+  ddMatcher,
+  mkfsMatcher,
+  wipefsMatcher,
+  blkdiscardMatcher,
+  fdiskMatcher,
+  partedMatcher,
+
+  // Permission changes
+  chmodMatcher,
+  chownMatcher,
+
+  // Container escapes
+  containerMatcher,
+];
+
+/**
+ * Keywords for each built-in matcher, used for documentation/UI.
+ * These should match the patterns in DEFAULT_CONFIG in config.ts.
+ */
+export const BUILTIN_KEYWORD_PATTERNS = new Set([
+  "rm -rf",
+  "sudo",
+  "dd of=",
+  "mkfs.",
+  "chmod -R 777",
+  "chown -R",
+  "doas",
+  "pkexec",
+  "shred",
+  "wipefs",
+  "blkdiscard",
+  "fdisk",
+  "parted",
+  "docker run --privileged",
+]);
+
+/**
+ * Match a command against all built-in dangerous patterns.
+ * Returns the first match found, or undefined if no match.
+ */
+export function matchDangerousCommand(
+  words: string[],
+): { description: string; pattern: string } | undefined {
+  for (const matcher of BUILTIN_MATCHERS) {
+    const description = matcher(words);
+    if (description) {
+      // Use the command itself as the pattern identifier
+      const pattern = words[0] ?? "unknown";
+      return { description, pattern };
+    }
+  }
+  return undefined;
+}