shield-harness 0.1.0 → 0.3.0

package/.claude/hooks/lib/ocsf-mapper.js

@@ -32,6 +32,9 @@ const OCSF_COMMON_FIELDS = new Set([
   "tool",
   "seq",
   "severity",
+  "sandbox_state",
+  "sandbox_version",
+  "sandbox_policy_enforced",
 ]);
 
 // ---------------------------------------------------------------------------
@@ -254,6 +257,20 @@ function toDetectionFinding(entry) {
     finding.resources = [{ type: "tool", name: entry.tool }];
   }
 
+  // OpenShell sandbox metadata (Beta Phase)
+  if (entry.sandbox_state === "active") {
+    finding.resources = finding.resources || [];
+    finding.resources.push({
+      type: "container",
+      name: "openshell-sandbox",
+      labels: [
+        "state:" + entry.sandbox_state,
+        entry.sandbox_version ? "version:" + entry.sandbox_version : null,
+        entry.sandbox_policy_enforced ? "policy_enforced:true" : null,
+      ].filter(Boolean),
+    });
+  }
+
   // Unmapped (hook-specific fields)
   const unmapped = extractUnmapped(entry);
   if (unmapped) {

package/.claude/hooks/lib/permissions-validator.js

@@ -0,0 +1,211 @@
+#!/usr/bin/env node
+// permissions-validator.js — Validates alignment between permissions-spec.json and settings.json
+// Part of the permanent countermeasure system for design-implementation divergence prevention
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+/**
+ * Load and validate permissions-spec.json.
+ * @param {string} specPath - Path to permissions-spec.json
+ * @returns {{ deny: string[], ask: string[], allow: string[], expected_counts: object }}
+ * @throws {Error} If file is missing, invalid JSON, or malformed
+ */
+function loadPermissionsSpec(specPath) {
+  if (!fs.existsSync(specPath)) {
+    throw new Error(`Permissions spec not found: ${specPath}`);
+  }
+
+  const raw = fs.readFileSync(specPath, "utf8");
+  let spec;
+  try {
+    spec = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`Permissions spec is not valid JSON: ${err.message}`);
+  }
+
+  if (!spec.permissions) {
+    throw new Error("Permissions spec missing 'permissions' field");
+  }
+
+  const perms = spec.permissions;
+  const deny = (perms.deny || []).map((entry) =>
+    typeof entry === "string" ? entry : entry.rule,
+  );
+  const ask = (perms.ask || []).map((entry) =>
+    typeof entry === "string" ? entry : entry.rule,
+  );
+  const allow = (perms.allow || []).map((entry) =>
+    typeof entry === "string" ? entry : entry.rule,
+  );
+
+  return {
+    deny,
+    ask,
+    allow,
+    expected_counts: spec.expected_counts || null,
+  };
+}
+
+/**
+ * Load permissions from settings.json.
+ * @param {string} settingsPath - Path to settings.json
+ * @returns {{ deny: string[], ask: string[], allow: string[] }}
+ * @throws {Error} If file is missing, invalid JSON, or missing permissions
+ */
+function loadSettingsPermissions(settingsPath) {
+  if (!fs.existsSync(settingsPath)) {
+    throw new Error(`Settings file not found: ${settingsPath}`);
+  }
+
+  const raw = fs.readFileSync(settingsPath, "utf8");
+  let settings;
+  try {
+    settings = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`Settings file is not valid JSON: ${err.message}`);
+  }
+
+  const perms = settings.permissions || {};
+  return {
+    deny: perms.deny || [],
+    ask: perms.ask || [],
+    allow: perms.allow || [],
+  };
+}
+
+/**
+ * Compute the set difference: items in setA but not in setB.
+ * @param {string[]} setA
+ * @param {string[]} setB
+ * @returns {string[]}
+ */
+function setDiff(setA, setB) {
+  const bSet = new Set(setB);
+  return setA.filter((item) => !bSet.has(item));
+}
+
+/**
+ * Diff permissions spec against settings.json.
+ * @param {{ deny: string[], ask: string[], allow: string[] }} spec
+ * @param {{ deny: string[], ask: string[], allow: string[] }} settings
+ * @returns {object} Diff result with missing/extra rules per category
+ */
+function diffPermissions(spec, settings) {
+  const result = {
+    missingDeny: setDiff(spec.deny, settings.deny),
+    extraDeny: setDiff(settings.deny, spec.deny),
+    missingAsk: setDiff(spec.ask, settings.ask),
+    extraAsk: setDiff(settings.ask, spec.ask),
+    missingAllow: setDiff(spec.allow, settings.allow),
+    extraAllow: setDiff(settings.allow, spec.allow),
+  };
+
+  result.totalMissing =
+    result.missingDeny.length +
+    result.missingAsk.length +
+    result.missingAllow.length;
+  result.totalExtra =
+    result.extraDeny.length + result.extraAsk.length + result.extraAllow.length;
+  result.aligned = result.totalMissing === 0 && result.totalExtra === 0;
+
+  return result;
+}
+
+/**
+ * Validate alignment between permissions-spec.json and settings.json.
+ * @param {string} specPath
+ * @param {string} settingsPath
+ * @returns {{ aligned: boolean, diff: object, summary: string, counts: string }}
+ */
+function validateAlignment(specPath, settingsPath) {
+  const spec = loadPermissionsSpec(specPath);
+  const settings = loadSettingsPermissions(settingsPath);
+  const diff = diffPermissions(spec, settings);
+
+  const counts = `${spec.deny.length} deny, ${spec.ask.length} ask, ${spec.allow.length} allow`;
+
+  if (diff.aligned) {
+    return { aligned: true, diff, summary: "All rules aligned", counts };
+  }
+
+  const parts = [];
+  if (diff.missingDeny.length > 0) {
+    parts.push(`${diff.missingDeny.length} deny rules missing from settings`);
+  }
+  if (diff.extraDeny.length > 0) {
+    parts.push(`${diff.extraDeny.length} extra deny rules in settings`);
+  }
+  if (diff.missingAsk.length > 0) {
+    parts.push(`${diff.missingAsk.length} ask rules missing from settings`);
+  }
+  if (diff.extraAsk.length > 0) {
+    parts.push(`${diff.extraAsk.length} extra ask rules in settings`);
+  }
+  if (diff.missingAllow.length > 0) {
+    parts.push(`${diff.missingAllow.length} allow rules missing from settings`);
+  }
+  if (diff.extraAllow.length > 0) {
+    parts.push(`${diff.extraAllow.length} extra allow rules in settings`);
+  }
+
+  const summary = parts.join("; ");
+  return { aligned: false, diff, summary, counts };
+}
+
+/**
+ * Format a human-readable report of the alignment diff.
+ * @param {{ aligned: boolean, diff: object, summary: string }} result
+ * @returns {string}
+ */
+function formatReport(result) {
+  if (result.aligned) {
+    return "Permissions alignment: OK";
+  }
+
+  const lines = ["Permissions alignment: DIVERGENCE DETECTED", ""];
+  const { diff } = result;
+
+  if (diff.missingDeny.length > 0) {
+    lines.push("Missing deny rules (in spec but not in settings.json):");
+    diff.missingDeny.forEach((r) => lines.push(`  - ${r}`));
+    lines.push("");
+  }
+  if (diff.extraDeny.length > 0) {
+    lines.push("Extra deny rules (in settings.json but not in spec):");
+    diff.extraDeny.forEach((r) => lines.push(`  - ${r}`));
+    lines.push("");
+  }
+  if (diff.missingAsk.length > 0) {
+    lines.push("Missing ask rules (in spec but not in settings.json):");
+    diff.missingAsk.forEach((r) => lines.push(`  - ${r}`));
+    lines.push("");
+  }
+  if (diff.extraAsk.length > 0) {
+    lines.push("Extra ask rules (in settings.json but not in spec):");
+    diff.extraAsk.forEach((r) => lines.push(`  - ${r}`));
+    lines.push("");
+  }
+  if (diff.missingAllow.length > 0) {
+    lines.push("Missing allow rules (in spec but not in settings.json):");
+    diff.missingAllow.forEach((r) => lines.push(`  - ${r}`));
+    lines.push("");
+  }
+  if (diff.extraAllow.length > 0) {
+    lines.push("Extra allow rules (in settings.json but not in spec):");
+    diff.extraAllow.forEach((r) => lines.push(`  - ${r}`));
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+module.exports = {
+  loadPermissionsSpec,
+  loadSettingsPermissions,
+  setDiff,
+  diffPermissions,
+  validateAlignment,
+  formatReport,
+};

package/.claude/hooks/lib/sh-utils.js

@@ -306,6 +306,25 @@ function loadPatterns() {
   }
 }
 
+// --- Repeat Deny Tracking (§4.5 FR-04-07) ---
+
+const REPEAT_DENY_THRESHOLD = 3;
+
+/**
+ * Track deny occurrences per pattern key in session.
+ * Increments deny_tracker[patternKey] in session.json.
+ * @param {string} patternKey - Identifier for the denied pattern
+ * @returns {{ exceeded: boolean, count: number }}
+ */
+function trackDeny(patternKey) {
+  const session = readSession();
+  if (!session.deny_tracker) session.deny_tracker = {};
+  const count = (session.deny_tracker[patternKey] || 0) + 1;
+  session.deny_tracker[patternKey] = count;
+  writeSession(session);
+  return { exceeded: count >= REPEAT_DENY_THRESHOLD, count };
+}
+
 module.exports = {
   // Constants
   SH_DIR,
@@ -337,4 +356,7 @@ module.exports = {
   loadPatterns,
   // Hash Chain
   verifyHashChain,
+  // Deny Tracking
+  trackDeny,
+  REPEAT_DENY_THRESHOLD,
 };

package/.claude/hooks/lib/tier-policy-gen.js

@@ -0,0 +1,348 @@
+#!/usr/bin/env node
+// tier-policy-gen.js — Generate OpenShell Policy Schema v1 YAML from permissions-spec.json
+// Spec: ADR-037 Phase Beta, Stream C
+// Purpose: Convert Shield Harness permission rules into OpenShell sandbox policy files
+"use strict";
+
+// --- Rule Parsing ---
+
+/**
+ * Parse a permission rule string into structured components.
+ * Supports formats:
+ *   "Read(~/.ssh/**)"          -> { action: "Read", target: "~/.ssh/**" }
+ *   "Bash(curl *)"             -> { action: "Bash", command: "curl", pattern: "*" }
+ *   "Edit(.claude/hooks/**)"   -> { action: "Edit", target: ".claude/hooks/**" }
+ *   "Glob(*)"                  -> { action: "Glob", target: "*" }
+ * @param {string} rule - Raw permission rule string
+ * @returns {{ action: string, target?: string, command?: string, pattern?: string }|null}
+ */
+function parsePermissionRule(rule) {
+  if (!rule || typeof rule !== "string") return null;
+
+  const match = rule.match(/^(\w+)\((.+)\)$/);
+  if (!match) return null;
+
+  const action = match[1];
+  const inner = match[2];
+
+  if (action === "Bash") {
+    // Split into command and pattern: "curl *" -> { command: "curl", pattern: "*" }
+    const spaceIdx = inner.indexOf(" ");
+    if (spaceIdx === -1) {
+      return { action, command: inner, pattern: "" };
+    }
+    return {
+      action,
+      command: inner.slice(0, spaceIdx),
+      pattern: inner.slice(spaceIdx + 1),
+    };
+  }
+
+  return { action, target: inner };
+}
+
+// --- Domain Classification ---
+
+/**
+ * Network-related commands (Bash rules classified as network domain).
+ * @type {Set<string>}
+ */
+const NETWORK_COMMANDS = new Set([
+  "curl",
+  "wget",
+  "nc",
+  "ncat",
+  "nmap",
+  "Invoke-WebRequest",
+]);
+
+/**
+ * Destructive commands (classified as process domain).
+ * @type {Set<string>}
+ */
+const DESTRUCTIVE_COMMANDS = new Set(["rm", "del", "format"]);
+
+/**
+ * Remove trailing glob wildcards from a path for policy use.
+ * Example: "~/.ssh/[star][star]" becomes "~/.ssh"
+ * Leading globs are preserved (e.g., "[star][star]/.env" stays as-is).
+ * @param {string} p - Glob path
+ * @returns {string}
+ */
+function cleanGlobPath(p) {
+  return p.replace(/\/\*\*$/, "").replace(/\/\*$/, "");
+}
+
+/**
+ * Classify an array of deny rules by security domain.
+ * @param {Array<{rule: string, rationale?: string, threat_id?: string}>} rules
+ * @returns {{
+ *   denyRead: string[],
+ *   denyWrite: string[],
+ *   network: string[],
+ *   process: string[],
+ *   unclassified: string[]
+ * }}
+ */
+function classifyRulesByDomain(rules) {
+  const result = {
+    denyRead: [],
+    denyWrite: [],
+    network: [],
+    process: [],
+    unclassified: [],
+  };
+
+  const readPaths = new Set();
+  const writePaths = new Set();
+
+  for (const entry of rules) {
+    const ruleStr = typeof entry === "string" ? entry : entry.rule;
+    const parsed = parsePermissionRule(ruleStr);
+
+    if (!parsed) {
+      result.unclassified.push(ruleStr);
+      continue;
+    }
+
+    switch (parsed.action) {
+      case "Read": {
+        const cleaned = cleanGlobPath(parsed.target);
+        if (!readPaths.has(cleaned)) {
+          readPaths.add(cleaned);
+          result.denyRead.push(cleaned);
+        }
+        break;
+      }
+
+      case "Edit":
+      case "Write": {
+        const cleaned = cleanGlobPath(parsed.target);
+        if (!writePaths.has(cleaned)) {
+          writePaths.add(cleaned);
+          result.denyWrite.push(cleaned);
+        }
+        break;
+      }
+
+      case "Bash": {
+        const cmd = parsed.command;
+        const fullRule =
+          parsed.command + (parsed.pattern ? " " + parsed.pattern : "");
+
+        if (NETWORK_COMMANDS.has(cmd)) {
+          result.network.push(fullRule);
+        } else if (DESTRUCTIVE_COMMANDS.has(cmd)) {
+          result.process.push(fullRule);
+        } else if (cmd === "git" && /push\s+--force/.test(parsed.pattern)) {
+          result.network.push(fullRule);
+        } else if (cmd === "npm" && /publish/.test(parsed.pattern)) {
+          result.network.push(fullRule);
+        } else {
+          // Other bash commands (e.g., cat */.ssh/*) — classify by intent
+          result.process.push(fullRule);
+        }
+        break;
+      }
+
+      default:
+        result.unclassified.push(ruleStr);
+        break;
+    }
+  }
+
+  return result;
+}
+
+// --- YAML Generation ---
+
+/**
+ * Merge two classification results (for strict mode: deny + ask).
+ * Deduplicates paths/commands.
+ * @param {ReturnType<typeof classifyRulesByDomain>} base
+ * @param {ReturnType<typeof classifyRulesByDomain>} extra
+ * @returns {ReturnType<typeof classifyRulesByDomain>}
+ */
+function mergeClassified(base, extra) {
+  const readSet = new Set(base.denyRead);
+  const writeSet = new Set(base.denyWrite);
+  const networkSet = new Set(base.network);
+  const processSet = new Set(base.process);
+
+  for (const p of extra.denyRead) {
+    if (!readSet.has(p)) {
+      readSet.add(p);
+      base.denyRead.push(p);
+    }
+  }
+  for (const p of extra.denyWrite) {
+    if (!writeSet.has(p)) {
+      writeSet.add(p);
+      base.denyWrite.push(p);
+    }
+  }
+  for (const p of extra.network) {
+    if (!networkSet.has(p)) {
+      networkSet.add(p);
+      base.network.push(p);
+    }
+  }
+  for (const p of extra.process) {
+    if (!processSet.has(p)) {
+      processSet.add(p);
+      base.process.push(p);
+    }
+  }
+
+  return base;
+}
+
+/**
+ * Generate OpenShell Policy Schema v1 YAML from permissions-spec.json.
+ * Uses template literals — no js-yaml dependency.
+ * @param {Object} spec - Full permissions-spec.json object
+ * @param {{ profile?: string }} [options]
+ * @returns {string} YAML policy file content
+ */
+function generatePolicyYaml(spec, options = {}) {
+  const profile = options.profile || "standard";
+
+  if (!spec || !spec.permissions) {
+    throw new Error("Invalid spec: missing permissions field");
+  }
+
+  const classified = classifyRulesByDomain(spec.permissions.deny || []);
+
+  // In strict mode, also treat ask rules as deny
+  if (profile === "strict" && spec.permissions.ask) {
+    const askClassified = classifyRulesByDomain(spec.permissions.ask);
+    mergeClassified(classified, askClassified);
+  }
+
+  const lines = [];
+  lines.push("# Auto-generated by Shield Harness tier-policy-gen");
+  lines.push("# Source: permissions-spec.json v" + (spec.version || "1.0.0"));
+  lines.push("# Profile: " + profile);
+  lines.push("# Generated: " + new Date().toISOString());
+  lines.push("#");
+  lines.push("# Usage:");
+  lines.push("#   openshell sandbox create --policy <this-file> -- claude");
+  lines.push("#");
+  lines.push("# Static policies require sandbox recreation to change.");
+  lines.push(
+    "# Network policies can be hot-reloaded: openshell policy set <name> --policy <file> --wait",
+  );
+  lines.push("");
+  lines.push("version: 1");
+
+  // --- Filesystem policy (static) ---
+  lines.push("");
+  lines.push("# --- Static (locked at sandbox creation) ---");
+  lines.push("");
+  lines.push("filesystem_policy:");
+  lines.push("  include_workdir: true");
+
+  if (classified.denyRead.length > 0) {
+    lines.push("  deny_read:");
+    for (const p of classified.denyRead) {
+      lines.push("    - " + p);
+    }
+  }
+
+  if (classified.denyWrite.length > 0) {
+    lines.push("  deny_write:");
+    for (const p of classified.denyWrite) {
+      lines.push("    - " + p);
+    }
+  }
+
+  lines.push("  read_only:");
+  lines.push("    - /usr");
+  lines.push("    - /lib");
+  lines.push("    - /etc");
+  lines.push("  read_write:");
+  lines.push("    - /sandbox");
+  lines.push("    - /tmp");
+
+  // --- Landlock ---
+  lines.push("");
+  lines.push("landlock:");
+  lines.push("  compatibility: best_effort");
+
+  // --- Process ---
+  lines.push("");
+  lines.push("process:");
+  lines.push("  run_as_user: sandbox");
+  lines.push("  run_as_group: sandbox");
+
+  // --- Network policies (dynamic / hot-reloadable) ---
+  lines.push("");
+  lines.push("# --- Dynamic (hot-reloadable) ---");
+  lines.push("");
+  lines.push("network_policies:");
+
+  // Default allowlist (matching openshell-default.yaml)
+  lines.push("  anthropic_api:");
+  lines.push("    name: anthropic-api");
+  lines.push("    endpoints:");
+  lines.push("      - host: api.anthropic.com");
+  lines.push("        port: 443");
+  lines.push("        access: full");
+  lines.push("    binaries:");
+  lines.push("      - path: /usr/local/bin/claude");
+  lines.push("");
+  lines.push("  github:");
+  lines.push("    name: github");
+  lines.push("    endpoints:");
+  lines.push("      - host: github.com");
+  lines.push("        port: 443");
+  lines.push("        access: read-only");
+  lines.push('      - host: "*.githubusercontent.com"');
+  lines.push("        port: 443");
+  lines.push("        access: read-only");
+  lines.push("    binaries:");
+  lines.push("      - path: /usr/bin/git");
+  lines.push("");
+  lines.push("  npm_registry:");
+  lines.push("    name: npm-registry");
+  lines.push("    endpoints:");
+  lines.push("      - host: registry.npmjs.org");
+  lines.push("        port: 443");
+  lines.push("        access: read-only");
+  lines.push("    binaries:");
+  lines.push("      - path: /usr/bin/npm");
+  lines.push("      - path: /usr/bin/node");
+
+  // Append blocked network commands as comments for visibility
+  if (classified.network.length > 0) {
+    lines.push("");
+    lines.push(
+      "# Blocked network operations (from permissions-spec.json deny rules):",
+    );
+    for (const cmd of classified.network) {
+      lines.push("#   - " + cmd);
+    }
+  }
+
+  // Append blocked destructive commands as comments
+  if (classified.process.length > 0) {
+    lines.push("");
+    lines.push(
+      "# Blocked process operations (from permissions-spec.json deny rules):",
+    );
+    for (const cmd of classified.process) {
+      lines.push("#   - " + cmd);
+    }
+  }
+
+  return lines.join("\n") + "\n";
+}
+
+module.exports = {
+  parsePermissionRule,
+  classifyRulesByDomain,
+  generatePolicyYaml,
+  // Internal helpers exported for testing
+  cleanGlobPath,
+  mergeClassified,
+};

package/.claude/hooks/sh-evidence.js

@@ -111,8 +111,9 @@ try {
 
   // Check channel source for evidence metadata (§8.6.3)
   let isChannel = false;
+  let session = {};
   try {
-    const session = readSession();
+    session = readSession();
     isChannel = session.source === "channel";
   } catch {
     // Session read failure is non-blocking for evidence
@@ -135,6 +136,18 @@ try {
     category: null,
     is_channel: isChannel,
     session_id: sessionId,
+    // OpenShell metadata (Beta Phase)
+    sandbox_state:
+      session.sandbox_openshell && session.sandbox_openshell.available
+        ? "active"
+        : "inactive",
+    sandbox_version:
+      (session.sandbox_openshell && session.sandbox_openshell.version) || null,
+    sandbox_policy_enforced: !!(
+      session.sandbox_openshell &&
+      session.sandbox_openshell.available &&
+      session.sandbox_openshell.container_running
+    ),
   };
 
   // Collect context messages

package/.claude/hooks/sh-gate.js

@@ -12,6 +12,7 @@ const {
   nfkcNormalize,
   normalizePath,
   appendEvidence,
+  trackDeny,
 } = require("./lib/sh-utils");
 
 // ---------------------------------------------------------------------------
@@ -324,7 +325,14 @@ if (require.main === module) {
         normalizedCommand,
         input.sessionId,
       );
-      deny(`[sh-gate] Blocked: ${match.label}`);
+      const tracker = trackDeny(`gate:${match.label}`);
+      if (tracker.exceeded) {
+        deny(
+          `[sh-gate] PROBING DETECTED: "${match.label}" denied ${tracker.count} times. User confirmation required.`,
+        );
+      } else {
+        deny(`[sh-gate] Blocked: ${match.label}`);
+      }
       return;
     }