shield-harness 0.2.0 → 0.4.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/policy-drift.js

@@ -0,0 +1,322 @@
+#!/usr/bin/env node
+// policy-drift.js — Detect drift between permissions-spec.json deny rules and OpenShell policy YAML
+// Part of Shield Harness: ensures policy files stay in sync with the canonical deny rules
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+// --- Dependencies (local modules) ---
+
+const { loadPermissionsSpec } = require("./permissions-validator");
+const { classifyRulesByDomain } = require("./tier-policy-gen");
+
+// --- YAML Parsing (regex-based, no js-yaml dependency) ---
+
+/**
+ * Extract a YAML list section by name.
+ * Expects predictable structure generated by tier-policy-gen.js:
+ *   section_name:
+ *     - item1
+ *     - item2
+ *
+ * @param {string} content - Full YAML file content
+ * @param {string} sectionName - Name of the section (e.g., "deny_read")
+ * @returns {string[]} List of items found under the section
+ */
+function extractYamlList(content, sectionName) {
+  // Match section header followed by indented list items
+  var pattern = new RegExp(
+    sectionName + ":\\n((?:[ \\t]+-[ \\t]+.+\\n)*)",
+    "m",
+  );
+  var match = content.match(pattern);
+  if (!match) return [];
+  return match[1]
+    .split("\n")
+    .filter(function (l) {
+      return l.trim().startsWith("- ");
+    })
+    .map(function (l) {
+      return l.trim().replace(/^-\s+/, "");
+    });
+}
+
+/**
+ * Extract blocked network operations from YAML comment block.
+ * Expects format generated by tier-policy-gen.js:
+ *   # Blocked network operations (from permissions-spec.json deny rules):
+ *   #   - curl *
+ *   #   - wget *
+ *
+ * @param {string} content - Full YAML file content
+ * @returns {string[]} List of blocked network commands
+ */
+function extractBlockedNetworkComments(content) {
+  var pattern =
+    /# Blocked network operations[^\n]*:\n((?:#[ \t]+-[ \t]+.+\n)*)/m;
+  var match = content.match(pattern);
+  if (!match) return [];
+  return match[1]
+    .split("\n")
+    .filter(function (l) {
+      return l.trim().startsWith("#");
+    })
+    .map(function (l) {
+      return l.trim().replace(/^#\s+-\s+/, "");
+    });
+}
+
+/**
+ * Parse all relevant sections from a policy YAML file.
+ * Returns structured data without requiring js-yaml.
+ *
+ * @param {string} content - Full YAML file content
+ * @returns {{
+ *   denyRead: string[],
+ *   denyWrite: string[],
+ *   readWrite: string[],
+ *   blockedNetwork: string[]
+ * }}
+ */
+function parsePolicyYaml(content) {
+  return {
+    denyRead: extractYamlList(content, "deny_read"),
+    denyWrite: extractYamlList(content, "deny_write"),
+    readWrite: extractYamlList(content, "read_write"),
+    blockedNetwork: extractBlockedNetworkComments(content),
+  };
+}
+
+// --- Drift Detection ---
+
+/**
+ * Check drift between permissions-spec deny rules and OpenShell policy YAML.
+ *
+ * Compares the classified deny rules from permissions-spec.json against
+ * the content of policy YAML files in the specified directory.
+ *
+ * Drift rules:
+ *   1. Missing filesystem deny (read): spec denyRead paths not in policy deny_read
+ *   2. Missing filesystem deny (write): spec denyWrite paths not in policy deny_write
+ *   3. Policy allows denied: paths in denyRead/denyWrite that also appear in read_write
+ *   4. Missing network deny: network commands not in blocked network comments
+ *   5. No policy files: skip (no drift reported)
+ *   6. No spec file: skip (no drift reported)
+ *   7. Parse errors: fail-safe (no drift, warning logged)
+ *
+ * @param {{ specPath: string, policyDir: string }} params
+ * @returns {{
+ *   has_drift: boolean,
+ *   warnings: string[],
+ *   details: {
+ *     missing_filesystem_deny: string[],
+ *     missing_network_deny: string[],
+ *     policy_allows_denied: string[]
+ *   },
+ *   checked_at: string
+ * }}
+ */
+function checkPolicyDrift({ specPath, policyDir }) {
+  var emptyResult = {
+    has_drift: false,
+    warnings: [],
+    details: {
+      missing_filesystem_deny: [],
+      missing_network_deny: [],
+      policy_allows_denied: [],
+    },
+    checked_at: new Date().toISOString(),
+  };
+
+  // Rule 6: No spec file — skip silently
+  if (!specPath || !fs.existsSync(specPath)) {
+    return emptyResult;
+  }
+
+  // Rule 5: No policy directory or no .yaml files — skip silently
+  if (!policyDir || !fs.existsSync(policyDir)) {
+    return emptyResult;
+  }
+
+  var policyFiles;
+  try {
+    policyFiles = fs.readdirSync(policyDir).filter(function (f) {
+      return f.endsWith(".yaml") || f.endsWith(".yml");
+    });
+  } catch (e) {
+    return emptyResult;
+  }
+
+  if (policyFiles.length === 0) {
+    return emptyResult;
+  }
+
+  // Load and classify spec deny rules
+  var spec;
+  try {
+    spec = loadPermissionsSpec(specPath);
+  } catch (err) {
+    return {
+      has_drift: false,
+      warnings: ["parse_error: spec load failed \u2014 " + err.message],
+      details: {
+        missing_filesystem_deny: [],
+        missing_network_deny: [],
+        policy_allows_denied: [],
+      },
+      checked_at: new Date().toISOString(),
+    };
+  }
+
+  var classified;
+  try {
+    classified = classifyRulesByDomain(spec.deny);
+  } catch (err) {
+    return {
+      has_drift: false,
+      warnings: [
+        "parse_error: rule classification failed \u2014 " + err.message,
+      ],
+      details: {
+        missing_filesystem_deny: [],
+        missing_network_deny: [],
+        policy_allows_denied: [],
+      },
+      checked_at: new Date().toISOString(),
+    };
+  }
+
+  // Aggregate policy content from all YAML files
+  var aggregated = {
+    denyRead: new Set(),
+    denyWrite: new Set(),
+    readWrite: new Set(),
+    blockedNetwork: new Set(),
+  };
+
+  for (var i = 0; i < policyFiles.length; i++) {
+    var filePath = path.join(policyDir, policyFiles[i]);
+    var content;
+    try {
+      content = fs.readFileSync(filePath, "utf8");
+    } catch (err) {
+      // Rule 7: Parse error — fail-safe
+      return {
+        has_drift: false,
+        warnings: [
+          "parse_error: cannot read " + filePath + " \u2014 " + err.message,
+        ],
+        details: {
+          missing_filesystem_deny: [],
+          missing_network_deny: [],
+          policy_allows_denied: [],
+        },
+        checked_at: new Date().toISOString(),
+      };
+    }
+
+    var parsed;
+    try {
+      parsed = parsePolicyYaml(content);
+    } catch (err) {
+      return {
+        has_drift: false,
+        warnings: [
+          "parse_error: cannot parse " + filePath + " \u2014 " + err.message,
+        ],
+        details: {
+          missing_filesystem_deny: [],
+          missing_network_deny: [],
+          policy_allows_denied: [],
+        },
+        checked_at: new Date().toISOString(),
+      };
+    }
+
+    parsed.denyRead.forEach(function (p) {
+      aggregated.denyRead.add(p);
+    });
+    parsed.denyWrite.forEach(function (p) {
+      aggregated.denyWrite.add(p);
+    });
+    parsed.readWrite.forEach(function (p) {
+      aggregated.readWrite.add(p);
+    });
+    parsed.blockedNetwork.forEach(function (cmd) {
+      aggregated.blockedNetwork.add(cmd);
+    });
+  }
+
+  // --- Compare classified rules against aggregated policy ---
+
+  var warnings = [];
+  var missingFilesystemDeny = [];
+  var missingNetworkDeny = [];
+  var policyAllowsDenied = [];
+
+  // Rule 1: Missing filesystem deny (read)
+  for (var ri = 0; ri < classified.denyRead.length; ri++) {
+    var readPath = classified.denyRead[ri];
+    if (!aggregated.denyRead.has(readPath)) {
+      warnings.push("deny_read missing in policy: " + readPath);
+      missingFilesystemDeny.push(readPath);
+    }
+  }
+
+  // Rule 2: Missing filesystem deny (write)
+  for (var wi = 0; wi < classified.denyWrite.length; wi++) {
+    var writePath = classified.denyWrite[wi];
+    if (!aggregated.denyWrite.has(writePath)) {
+      warnings.push("deny_write missing in policy: " + writePath);
+      missingFilesystemDeny.push(writePath);
+    }
+  }
+
+  // Rule 3: Policy allows denied — conflict detection
+  var allDeniedPaths = new Set(
+    classified.denyRead.concat(classified.denyWrite),
+  );
+  aggregated.readWrite.forEach(function (rwPath) {
+    if (allDeniedPaths.has(rwPath)) {
+      warnings.push("conflict: read_write allows denied path: " + rwPath);
+      policyAllowsDenied.push(rwPath);
+    }
+  });
+
+  // Rule 4: Missing network deny
+  for (var ni = 0; ni < classified.network.length; ni++) {
+    var netCmd = classified.network[ni];
+    if (!aggregated.blockedNetwork.has(netCmd)) {
+      warnings.push(
+        "blocked network command missing in policy comments: " + netCmd,
+      );
+      missingNetworkDeny.push(netCmd);
+    }
+  }
+
+  var hasDrift =
+    missingFilesystemDeny.length > 0 ||
+    missingNetworkDeny.length > 0 ||
+    policyAllowsDenied.length > 0;
+
+  return {
+    has_drift: hasDrift,
+    warnings: warnings,
+    details: {
+      missing_filesystem_deny: missingFilesystemDeny,
+      missing_network_deny: missingNetworkDeny,
+      policy_allows_denied: policyAllowsDenied,
+    },
+    checked_at: new Date().toISOString(),
+  };
+}
+
+module.exports = {
+  // Main entry point
+  checkPolicyDrift: checkPolicyDrift,
+  // Parsing helpers (exported for unit testing)
+  extractYamlList: extractYamlList,
+  extractBlockedNetworkComments: extractBlockedNetworkComments,
+  parsePolicyYaml: parsePolicyYaml,
+};

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,
+};