@aliou/pi-guardrails 0.11.2 → 0.12.1

package/schema.json

@@ -0,0 +1,286 @@
+{
+  "$ref": "#/definitions/GuardrailsConfig",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "definitions": {
+    "DangerousPattern": {
+      "additionalProperties": false,
+      "description": "Permission gate pattern. When regex is false (default), the pattern is matched as substring against the raw command string. When regex is true, uses full regex against the raw string.",
+      "properties": {
+        "description": {
+          "description": "Optional description surfaced to the agent when the pattern triggers (e.g. auto-deny reason).",
+          "type": "string"
+        },
+        "pattern": {
+          "type": "string"
+        },
+        "regex": {
+          "type": "boolean"
+        }
+      },
+      "required": [
+        "description",
+        "pattern"
+      ],
+      "type": "object"
+    },
+    "GuardrailsConfig": {
+      "additionalProperties": false,
+      "properties": {
+        "$schema": {
+          "description": "JSON Schema URL for editor autocomplete and validation. Added automatically when Guardrails writes the file.",
+          "type": "string"
+        },
+        "applyBuiltinDefaults": {
+          "description": "When true, include Guardrails built-in policy rules before user rules are merged.",
+          "type": "boolean"
+        },
+        "enabled": {
+          "description": "Enable or disable all Guardrails checks.",
+          "type": "boolean"
+        },
+        "envFiles": {
+          "additionalProperties": false,
+          "properties": {
+            "allowedPatterns": {
+              "items": {
+                "$ref": "#/definitions/PatternConfig"
+              },
+              "type": "array"
+            },
+            "blockMessage": {
+              "type": "string"
+            },
+            "onlyBlockIfExists": {
+              "type": "boolean"
+            },
+            "protectedDirectories": {
+              "items": {
+                "$ref": "#/definitions/PatternConfig"
+              },
+              "type": "array"
+            },
+            "protectedPatterns": {
+              "items": {
+                "$ref": "#/definitions/PatternConfig"
+              },
+              "type": "array"
+            },
+            "protectedTools": {
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            }
+          },
+          "type": "object"
+        },
+        "features": {
+          "additionalProperties": false,
+          "description": "Enable or disable individual Guardrails feature extensions.",
+          "properties": {
+            "pathAccess": {
+              "type": "boolean"
+            },
+            "permissionGate": {
+              "type": "boolean"
+            },
+            "policies": {
+              "type": "boolean"
+            },
+            "protectEnvFiles": {
+              "type": "boolean"
+            }
+          },
+          "type": "object"
+        },
+        "onboarding": {
+          "additionalProperties": false,
+          "description": "Tracks whether the setup wizard has been completed. Usually managed by Guardrails.",
+          "properties": {
+            "completed": {
+              "description": "Whether onboarding is complete.",
+              "type": "boolean"
+            },
+            "completedAt": {
+              "description": "ISO timestamp for when onboarding completed.",
+              "type": "string"
+            },
+            "version": {
+              "description": "Guardrails config schema marker used when onboarding completed.",
+              "type": "string"
+            }
+          },
+          "type": "object"
+        },
+        "pathAccess": {
+          "$ref": "#/definitions/PathAccessConfig",
+          "description": "Outside-workspace path access settings."
+        },
+        "permissionGate": {
+          "additionalProperties": false,
+          "description": "Dangerous bash command detection and confirmation settings.",
+          "properties": {
+            "allowedPatterns": {
+              "description": "Command patterns that bypass dangerous command prompts.",
+              "items": {
+                "$ref": "#/definitions/PatternConfig"
+              },
+              "type": "array"
+            },
+            "autoDenyPatterns": {
+              "description": "Command patterns that are always blocked without prompting.",
+              "items": {
+                "$ref": "#/definitions/PatternConfig"
+              },
+              "type": "array"
+            },
+            "customPatterns": {
+              "description": "If set, replaces the default dangerous command patterns entirely.",
+              "items": {
+                "$ref": "#/definitions/DangerousPattern"
+              },
+              "type": "array"
+            },
+            "patterns": {
+              "description": "Additional dangerous command patterns.",
+              "items": {
+                "$ref": "#/definitions/DangerousPattern"
+              },
+              "type": "array"
+            },
+            "requireConfirmation": {
+              "description": "When true, prompt before running dangerous commands. When false, only warn.",
+              "type": "boolean"
+            }
+          },
+          "type": "object"
+        },
+        "policies": {
+          "additionalProperties": false,
+          "description": "File protection policies.",
+          "properties": {
+            "rules": {
+              "description": "Named policy rules. Rules with the same id override earlier rules across scopes.",
+              "items": {
+                "$ref": "#/definitions/PolicyRule"
+              },
+              "type": "array"
+            }
+          },
+          "type": "object"
+        },
+        "version": {
+          "description": "Internal config schema marker for migration/debugging. Not tied to the package version.",
+          "type": "string"
+        }
+      },
+      "type": "object"
+    },
+    "PathAccessConfig": {
+      "additionalProperties": false,
+      "properties": {
+        "allowedPaths": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "mode": {
+          "$ref": "#/definitions/PathAccessMode"
+        }
+      },
+      "type": "object"
+    },
+    "PathAccessMode": {
+      "enum": [
+        "allow",
+        "ask",
+        "block"
+      ],
+      "type": "string"
+    },
+    "PatternConfig": {
+      "additionalProperties": false,
+      "description": "A pattern with explicit matching mode. Default: glob for files, substring for commands. regex: true means full regex matching.",
+      "properties": {
+        "description": {
+          "description": "Optional description surfaced to the agent when the pattern triggers (e.g. auto-deny reason).",
+          "type": "string"
+        },
+        "pattern": {
+          "type": "string"
+        },
+        "regex": {
+          "type": "boolean"
+        }
+      },
+      "required": [
+        "pattern"
+      ],
+      "type": "object"
+    },
+    "PolicyRule": {
+      "additionalProperties": false,
+      "description": "A named policy rule. Matches files by patterns and enforces a protection level.",
+      "properties": {
+        "allowedPatterns": {
+          "description": "Optional exceptions.",
+          "items": {
+            "$ref": "#/definitions/PatternConfig"
+          },
+          "type": "array"
+        },
+        "blockMessage": {
+          "description": "Message shown when blocked; supports {file} placeholder.",
+          "type": "string"
+        },
+        "description": {
+          "description": "Human-readable description.",
+          "type": "string"
+        },
+        "enabled": {
+          "description": "Per-rule toggle. Default true.",
+          "type": "boolean"
+        },
+        "id": {
+          "description": "Stable identifier used for deduplication across scopes.",
+          "type": "string"
+        },
+        "name": {
+          "description": "Optional display name for settings/UI.",
+          "type": "string"
+        },
+        "onlyIfExists": {
+          "description": "Block only when file exists on disk. Default true.",
+          "type": "boolean"
+        },
+        "patterns": {
+          "description": "File patterns to protect.",
+          "items": {
+            "$ref": "#/definitions/PatternConfig"
+          },
+          "type": "array"
+        },
+        "protection": {
+          "$ref": "#/definitions/Protection",
+          "description": "Protection level."
+        }
+      },
+      "required": [
+        "id",
+        "patterns",
+        "protection"
+      ],
+      "type": "object"
+    },
+    "Protection": {
+      "description": "Protection level for a policy rule.",
+      "enum": [
+        "none",
+        "readOnly",
+        "noAccess"
+      ],
+      "type": "string"
+    }
+  }
+}

package/src/core/check.test.ts

@@ -0,0 +1,169 @@
+import { describe, expect, it, vi } from "vitest";
+import { checkAction, resolveDecision } from "./check";
+import type { Action, Rule, Safety } from "./types";
+
+const commandAction: Action = { kind: "command", command: "rm -rf /tmp/test" };
+
+type TestMeta = { pattern: string; source: "test" };
+
+const testMetadata: TestMeta = { pattern: "rm -rf", source: "test" };
+
+describe("checkAction", () => {
+  it("returns safe when no rules match", async () => {
+    const rules: Rule[] = [
+      {
+        key: "sudo",
+        check: () => ({ kind: "pass" }),
+      },
+    ];
+
+    await expect(checkAction(commandAction, rules)).resolves.toEqual({
+      kind: "safe",
+    });
+  });
+
+  it("returns dangerous for the first matching rule", async () => {
+    const secondCheck = vi.fn(() => ({
+      kind: "match" as const,
+      reason: "second match",
+      metadata: testMetadata,
+    }));
+    const rules: Rule<TestMeta>[] = [
+      {
+        key: "first",
+        check: () => ({
+          kind: "match",
+          reason: "first match",
+          metadata: testMetadata,
+        }),
+      },
+      {
+        key: "second",
+        check: secondCheck,
+      },
+    ];
+
+    await expect(checkAction(commandAction, rules)).resolves.toEqual({
+      kind: "dangerous",
+      action: commandAction,
+      key: "first",
+      reason: "first match",
+      metadata: testMetadata,
+    });
+    expect(secondCheck).not.toHaveBeenCalled();
+  });
+
+  it("supports async rules", async () => {
+    const rules: Rule[] = [
+      {
+        key: "async",
+        check: async (action) =>
+          action.kind === "command"
+            ? {
+                kind: "match",
+                reason: "async match",
+                metadata: null,
+              }
+            : { kind: "pass" },
+      },
+    ];
+
+    await expect(checkAction(commandAction, rules)).resolves.toMatchObject({
+      kind: "dangerous",
+      key: "async",
+      reason: "async match",
+      metadata: null,
+    });
+  });
+
+  it("propagates rule errors", async () => {
+    const error = new Error("rule failed");
+    const rules: Rule[] = [
+      {
+        key: "broken",
+        check: () => {
+          throw error;
+        },
+      },
+    ];
+
+    await expect(checkAction(commandAction, rules)).rejects.toThrow(error);
+  });
+
+  it("propagates async rule rejections", async () => {
+    const error = new Error("async rule failed");
+    const rules: Rule[] = [
+      {
+        key: "broken-async",
+        check: async () => {
+          throw error;
+        },
+      },
+    ];
+
+    await expect(checkAction(commandAction, rules)).rejects.toThrow(error);
+  });
+
+  it("preserves typed match metadata", async () => {
+    const rules: Rule<TestMeta>[] = [
+      {
+        key: "typed",
+        check: () => ({
+          kind: "match",
+          reason: "typed match",
+          metadata: testMetadata,
+        }),
+      },
+    ];
+
+    const safety = await checkAction(commandAction, rules);
+
+    if (safety.kind !== "dangerous") {
+      throw new Error("expected dangerous safety");
+    }
+
+    expect(safety.metadata.pattern).toBe("rm -rf");
+
+    const decision = resolveDecision(safety, "prompt");
+
+    if (decision.kind !== "prompt") {
+      throw new Error("expected prompt decision");
+    }
+
+    expect(decision.risk.metadata.pattern).toBe("rm -rf");
+  });
+});
+
+describe("resolveDecision", () => {
+  const dangerous: Safety = {
+    kind: "dangerous",
+    action: commandAction,
+    key: "rm-rf",
+    reason: "recursive force delete",
+    metadata: null,
+  };
+
+  it("allows safe actions", () => {
+    expect(resolveDecision({ kind: "safe" }, "denied")).toEqual({
+      kind: "allow",
+    });
+  });
+
+  it("allows dangerous actions when permission is granted", () => {
+    expect(resolveDecision(dangerous, "granted")).toEqual({ kind: "allow" });
+  });
+
+  it("denies dangerous actions when permission is denied", () => {
+    expect(resolveDecision(dangerous, "denied")).toEqual({
+      kind: "deny",
+      reason: "recursive force delete",
+    });
+  });
+
+  it("prompts for dangerous actions when permission is prompt", () => {
+    expect(resolveDecision(dangerous, "prompt")).toEqual({
+      kind: "prompt",
+      risk: dangerous,
+    });
+  });
+});

package/src/core/check.ts

@@ -0,0 +1,38 @@
+import type { Action, Decision, PermissionState, Rule, Safety } from "./types";
+
+export async function checkAction<TMeta = null>(
+  action: Action,
+  rules: readonly Rule<TMeta>[],
+): Promise<Safety<TMeta>> {
+  for (const rule of rules) {
+    const result = await rule.check(action);
+
+    if (result.kind === "match") {
+      return {
+        kind: "dangerous",
+        action,
+        key: rule.key,
+        reason: result.reason,
+        metadata: result.metadata,
+      };
+    }
+  }
+
+  return { kind: "safe" };
+}
+
+export function resolveDecision<TMeta = null>(
+  safety: Safety<TMeta>,
+  permissionState: PermissionState,
+): Decision<TMeta> {
+  if (safety.kind === "safe") return { kind: "allow" };
+
+  switch (permissionState) {
+    case "granted":
+      return { kind: "allow" };
+    case "denied":
+      return { kind: "deny", reason: safety.reason };
+    case "prompt":
+      return { kind: "prompt", risk: safety };
+  }
+}

package/src/{hooks/permission-gate/dangerous-commands.test.ts → core/commands/dangerous.test.ts}

@@ -1,5 +1,10 @@
 import { describe, expect, it } from "vitest";
-import { BUILTIN_MATCHERS, matchDangerousCommand } from "./dangerous-commands";
+import {
+  BUILTIN_MATCHERS,
+  checkDangerousCommand,
+  compileCommandPatterns,
+  matchDangerousCommand,
+} from "./dangerous";
 
 /**
  * Helper to run all matchers against a command string.
@@ -108,7 +113,7 @@ describe("dd matcher", () => {
     ).toBe("disk write operation");
   });
 
-  it("does not match dd with only if= (input only)", () => {
+  it("matches dd writing to /dev/null", () => {
     expect(findMatch(["dd", "if=/dev/sda", "of=/dev/null"])).toBe(
       "disk write operation",
     );
@@ -269,6 +274,18 @@ describe("container matcher (docker/podman)", () => {
       );
     });
 
+    it("matches docker run --uts=host", () => {
+      expect(findMatch(["docker", "run", "--uts=host", "alpine"])).toBe(
+        "container with host UTS namespace",
+      );
+    });
+
+    it("matches docker run --ipc=host", () => {
+      expect(findMatch(["docker", "run", "--ipc=host", "alpine"])).toBe(
+        "container with host IPC",
+      );
+    });
+
     it("matches docker run with root mount", () => {
       expect(findMatch(["docker", "run", "-v/:/host", "alpine"])).toBe(
         "container with root filesystem mount",
@@ -315,6 +332,121 @@ describe("container matcher (docker/podman)", () => {
   });
 });
 
+describe("checkDangerousCommand", () => {
+  it("matches built-in dangerous commands structurally", () => {
+    const result = checkDangerousCommand({
+      command: "rm -rf /tmp/example",
+      patterns: compileCommandPatterns([
+        { pattern: "rm -rf", description: "recursive force delete" },
+      ]),
+      useBuiltinMatchers: true,
+      fallbackPatterns: [
+        { pattern: "rm -rf", description: "recursive force delete" },
+      ],
+    });
+
+    expect(result).toEqual({
+      description: "recursive force delete",
+      pattern: "(structural)",
+    });
+  });
+
+  it("skips built-in substring matches after a successful parse", () => {
+    const result = checkDangerousCommand({
+      command: "echo 'rm -rf /tmp/example'",
+      patterns: compileCommandPatterns([
+        { pattern: "rm -rf", description: "recursive force delete" },
+      ]),
+      useBuiltinMatchers: true,
+      fallbackPatterns: [
+        { pattern: "rm -rf", description: "recursive force delete" },
+      ],
+    });
+
+    expect(result).toBeUndefined();
+  });
+
+  it("uses configured regex patterns", () => {
+    const result = checkDangerousCommand({
+      command: "terraform apply -auto-approve",
+      patterns: compileCommandPatterns([
+        {
+          pattern: "terraform\\s+apply",
+          description: "terraform apply",
+          regex: true,
+        },
+      ]),
+      useBuiltinMatchers: false,
+      fallbackPatterns: [],
+    });
+
+    expect(result).toEqual({
+      description: "terraform apply",
+      pattern: "terraform\\s+apply",
+    });
+  });
+
+  it("ignores invalid regex patterns", () => {
+    const result = checkDangerousCommand({
+      command: "anything",
+      patterns: compileCommandPatterns([
+        { pattern: "[", description: "invalid", regex: true },
+      ]),
+      useBuiltinMatchers: false,
+      fallbackPatterns: [],
+    });
+
+    expect(result).toBeUndefined();
+  });
+
+  it("uses configured patterns when built-in matchers are disabled", () => {
+    const result = checkDangerousCommand({
+      command: "deploy production",
+      patterns: compileCommandPatterns([
+        { pattern: "deploy production", description: "production deploy" },
+      ]),
+      useBuiltinMatchers: false,
+      fallbackPatterns: [],
+    });
+
+    expect(result).toEqual({
+      description: "production deploy",
+      pattern: "deploy production",
+    });
+  });
+
+  it("falls back to raw patterns when parsing fails", () => {
+    const result = checkDangerousCommand({
+      command: "if then rm -rf /tmp/example",
+      patterns: [],
+      useBuiltinMatchers: true,
+      fallbackPatterns: [
+        { pattern: "rm -rf", description: "recursive force delete" },
+      ],
+    });
+
+    expect(result).toEqual({
+      description: "recursive force delete",
+      pattern: "rm -rf",
+    });
+  });
+
+  it.each([
+    ["logical command", "echo ok && sudo true", "superuser command"],
+    ["pipeline", "echo ok | sudo tee /tmp/out", "superuser command"],
+    ["subshell", "(sudo true)", "superuser command"],
+  ])("matches dangerous commands nested in a %s", (_label, command, description) => {
+    const result = checkDangerousCommand({
+      command,
+      patterns: [],
+      useBuiltinMatchers: true,
+      fallbackPatterns: [],
+    });
+
+    expect(result).toEqual({ description, pattern: "(structural)" });
+  });
+});
+
 describe("matchDangerousCommand", () => {
   it("returns description and pattern for dangerous commands", () => {
     const result = matchDangerousCommand(["sudo", "apt", "update"]);