shield-harness 0.1.0

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

@@ -0,0 +1,279 @@
+// ocsf-mapper.js — OCSF Detection Finding (class_uid: 2004) transformer
+// Maps Shield Harness hook evidence entries to OCSF Detection Finding format.
+// Spec: https://schema.ocsf.io/ (v1.3.0)
+"use strict";
+
+const crypto = require("crypto");
+const path = require("path");
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const OCSF_VERSION = "1.3.0";
+const CLASS_UID = 2004;
+const CATEGORY_UID = 2;
+const TYPE_UID = 200401; // Detection Finding: Create
+
+// Product version from package.json (cached at module load)
+let productVersion = "1.0.0";
+try {
+  productVersion = require(path.resolve("package.json")).version;
+} catch {
+  // Fallback — running outside project root
+}
+
+// Fields that map to OCSF common fields (not placed in unmapped)
+const OCSF_COMMON_FIELDS = new Set([
+  "hook",
+  "event",
+  "decision",
+  "session_id",
+  "tool",
+  "seq",
+  "severity",
+]);
+
+// ---------------------------------------------------------------------------
+// Severity mapping
+// ---------------------------------------------------------------------------
+
+const SEVERITY_NAMES = {
+  1: "Informational",
+  2: "Low",
+  3: "Medium",
+  4: "High",
+  5: "Critical",
+};
+
+/**
+ * Resolve OCSF severity_id from hook context.
+ * @param {string} hook
+ * @param {string} decision
+ * @param {string} [severity] - Hook-provided severity string
+ * @returns {number} 1-5
+ */
+function resolveSeverityId(hook, decision, severity) {
+  if (decision !== "deny" && !severity) return 1; // Informational for allow
+
+  // If hook provides explicit severity, map it
+  if (severity) {
+    const map = { critical: 5, high: 4, medium: 3, low: 2 };
+    return map[severity.toLowerCase()] || 3;
+  }
+
+  // Hook-specific deny severity
+  const hookSeverity = {
+    "sh-injection-guard": 4,
+    "sh-config-guard": 4,
+    "sh-data-boundary": 4,
+    "sh-gate": 3,
+    "sh-user-prompt": 3,
+    "sh-circuit-breaker": 3,
+    "sh-elicitation": 3,
+    "sh-permission": 3,
+  };
+  return hookSeverity[hook] || 3;
+}
+
+// ---------------------------------------------------------------------------
+// Disposition mapping
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve OCSF disposition_id.
+ * @param {string} decision
+ * @param {string|null} category
+ * @returns {number}
+ */
+function resolveDispositionId(decision, category) {
+  if (decision === "deny") return 2; // Blocked
+  if (category === "pii_detected" || category === "leakage_detected") {
+    return 15; // Detected
+  }
+  return 1; // Allowed
+}
+
+// ---------------------------------------------------------------------------
+// Title generation
+// ---------------------------------------------------------------------------
+
+const TITLE_TEMPLATES = {
+  "sh-evidence": (e) => `Tool execution recorded: ${e.tool || "unknown"}`,
+  "sh-config-guard": (e) =>
+    `Configuration change ${e.action || "check"}: ${e.decision}`,
+  "sh-injection-guard": (e) =>
+    `Injection pattern detected: ${e.category || "unknown"}`,
+  "sh-circuit-breaker": (e) => `Circuit breaker: ${e.reason || e.decision}`,
+  "sh-gate": (e) => `Bash command gate: ${e.decision}`,
+  "sh-data-boundary": (e) =>
+    `Data boundary violation: ${e.host || "unknown host"}`,
+  "sh-instructions": (e) => `Instructions integrity: ${e.action || "check"}`,
+  "sh-elicitation": (e) => `Elicitation check: ${e.reason || e.decision}`,
+  "sh-dep-audit": (e) => `Dependency audit: ${e.reason || "recorded"}`,
+  "sh-precompact": () => "Pre-compaction backup",
+  "sh-postcompact": () => "Post-compaction integrity check",
+  "sh-session-end": () => "Session closed",
+  "sh-session-start": () => "Session initialized",
+  "sh-subagent": () => "Subagent budget allocated",
+  "sh-worktree": (e) => `Worktree operation: ${e.event || "unknown"}`,
+  "sh-permission-learn": (e) =>
+    `Permission learning: ${e.reason || "recorded"}`,
+  "sh-permission": (e) => `Permission check: ${e.decision}`,
+  "sh-pipeline": (e) => `Pipeline stage: ${e.stage || "unknown"}`,
+  "sh-task-gate": (e) => `Task gate: ${e.reason || "check"}`,
+  "sh-user-prompt": (e) =>
+    `User prompt scan: ${e.category || "clean"} (${e.severity || "info"})`,
+  "sh-output-control": (e) => `Output control: ${e.decision || "allow"}`,
+};
+
+/**
+ * Generate finding_info.title from hook and entry.
+ * @param {string} hook
+ * @param {Object} entry
+ * @returns {string}
+ */
+function generateTitle(hook, entry) {
+  const template = TITLE_TEMPLATES[hook];
+  if (template) return template(entry);
+  return `${hook}: ${entry.decision || entry.event || "recorded"}`;
+}
+
+// ---------------------------------------------------------------------------
+// UUID generation (Node.js 18 compatible)
+// ---------------------------------------------------------------------------
+
+function generateUUID() {
+  if (typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+  // Fallback for Node.js < 19
+  const bytes = crypto.randomBytes(16);
+  bytes[6] = (bytes[6] & 0x0f) | 0x40; // version 4
+  bytes[8] = (bytes[8] & 0x3f) | 0x80; // variant 1
+  const hex = bytes.toString("hex");
+  return [
+    hex.slice(0, 8),
+    hex.slice(8, 12),
+    hex.slice(12, 16),
+    hex.slice(16, 20),
+    hex.slice(20, 32),
+  ].join("-");
+}
+
+// ---------------------------------------------------------------------------
+// Unmapped field extraction
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract hook-specific fields that have no OCSF mapping.
+ * @param {Object} entry
+ * @returns {Object}
+ */
+function extractUnmapped(entry) {
+  const unmapped = {};
+  for (const [key, value] of Object.entries(entry)) {
+    if (!OCSF_COMMON_FIELDS.has(key) && value !== undefined) {
+      unmapped[key] = value;
+    }
+  }
+  return Object.keys(unmapped).length > 0 ? unmapped : undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Main transformer
+// ---------------------------------------------------------------------------
+
+/**
+ * Transform a hook evidence entry to OCSF Detection Finding (class_uid: 2004).
+ * @param {Object} entry - Raw hook evidence entry
+ * @returns {Object} OCSF-compliant Detection Finding
+ */
+function toDetectionFinding(entry) {
+  const hook = entry.hook || "unknown";
+  const decision = entry.decision || "allow";
+  const severityId = resolveSeverityId(hook, decision, entry.severity);
+  const dispositionId = resolveDispositionId(decision, entry.category);
+  const isAllow = decision === "allow";
+
+  const finding = {
+    // OCSF required
+    class_uid: CLASS_UID,
+    class_name: "Detection Finding",
+    category_uid: CATEGORY_UID,
+    category_name: "Findings",
+    type_uid: TYPE_UID,
+    activity_id: 1,
+    time: Date.now(),
+    severity_id: severityId,
+    severity: SEVERITY_NAMES[severityId] || "Unknown",
+    status_id: 1,
+    status: "New",
+
+    // OCSF recommended
+    action_id: isAllow ? 1 : 2,
+    action: isAllow ? "Allowed" : "Denied",
+    disposition_id: dispositionId,
+
+    // Metadata
+    metadata: {
+      version: OCSF_VERSION,
+      product: {
+        name: "Shield Harness",
+        vendor_name: "Shield Harness",
+        version: productVersion,
+      },
+      log_name: "evidence-ledger",
+    },
+
+    // Finding info
+    finding_info: {
+      uid: generateUUID(),
+      title: generateTitle(hook, entry),
+      analytic: {
+        type_id: 1,
+        type: "Rule",
+        name: hook,
+        uid: hook,
+      },
+    },
+  };
+
+  // Correlation (session_id → metadata.correlation_uid)
+  if (entry.session_id) {
+    finding.metadata.correlation_uid = entry.session_id;
+  }
+
+  // Sequence (seq → metadata.sequence)
+  if (typeof entry.seq === "number") {
+    finding.metadata.sequence = entry.seq;
+  }
+
+  // Resources (tool name)
+  if (entry.tool) {
+    finding.resources = [{ type: "tool", name: entry.tool }];
+  }
+
+  // Unmapped (hook-specific fields)
+  const unmapped = extractUnmapped(entry);
+  if (unmapped) {
+    finding.unmapped = unmapped;
+  }
+
+  return finding;
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  toDetectionFinding,
+  // Exported for testing
+  resolveSeverityId,
+  resolveDispositionId,
+  generateTitle,
+  extractUnmapped,
+  generateUUID,
+  OCSF_VERSION,
+};

package/.claude/hooks/lib/openshell-detect.js

@@ -0,0 +1,235 @@
+#!/usr/bin/env node
+// openshell-detect.js — NVIDIA OpenShell detection & version tracking
+// Spec: DETAILED_DESIGN.md §5.1.2, ADR-037
+// Purpose: Detect OpenShell availability at SessionStart, track version updates
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { execSync } = require("child_process");
+const { commandExists, SH_DIR } = require("./sh-utils");
+
+const CACHE_DIR = path.join(SH_DIR, "state");
+const CACHE_FILE = path.join(CACHE_DIR, "openshell-version-cache.json");
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+const CMD_TIMEOUT = 3000; // 3 seconds
+const FETCH_TIMEOUT = 5000; // 5 seconds
+const RELEASES_URL =
+  "https://api.github.com/repos/NVIDIA/OpenShell/releases/latest";
+
+/**
+ * Run a command synchronously with timeout. Returns stdout or null on failure.
+ * @param {string} cmd
+ * @param {number} [timeout]
+ * @returns {string|null}
+ */
+function runCmd(cmd, timeout = CMD_TIMEOUT) {
+  try {
+    return execSync(cmd, {
+      encoding: "utf8",
+      timeout,
+      stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Parse version string from openshell --version output.
+ * Expected format: "openshell X.Y.Z" or just "X.Y.Z"
+ * @param {string} output
+ * @returns {string|null}
+ */
+function parseVersion(output) {
+  if (!output) return null;
+  const match = output.match(/(\d+\.\d+\.\d+)/);
+  return match ? match[1] : null;
+}
+
+/**
+ * Read version cache file.
+ * @returns {{ latest_version: string, checked_at: string, current_version: string }|null}
+ */
+function readCache() {
+  try {
+    return JSON.parse(fs.readFileSync(CACHE_FILE, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write version cache file atomically.
+ * @param {Object} data
+ */
+function writeCache(data) {
+  if (!fs.existsSync(CACHE_DIR)) fs.mkdirSync(CACHE_DIR, { recursive: true });
+  const tmp = `${CACHE_FILE}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(data, null, 2));
+  fs.renameSync(tmp, CACHE_FILE);
+}
+
+/**
+ * Fetch latest OpenShell version from GitHub Releases API.
+ * Uses curl if available, otherwise Node.js https as fallback.
+ * Returns null on any failure (fail-safe).
+ * @returns {string|null} version string (e.g., "0.0.14") or null
+ */
+function fetchLatestVersion() {
+  // Try curl first (simpler, faster)
+  if (commandExists("curl")) {
+    const raw = runCmd(
+      `curl -s -H "Accept: application/vnd.github.v3+json" -H "User-Agent: shield-harness" "${RELEASES_URL}"`,
+      FETCH_TIMEOUT,
+    );
+    if (raw) {
+      try {
+        const data = JSON.parse(raw);
+        return (data.tag_name || "").replace(/^v/, "") || null;
+      } catch {
+        // Parse error — fall through
+      }
+    }
+  }
+
+  // Fallback: Node.js https (via temp script to avoid shell quoting issues)
+  const tmpScript = path.join(CACHE_DIR, "fetch-version.js");
+  try {
+    if (!fs.existsSync(CACHE_DIR)) fs.mkdirSync(CACHE_DIR, { recursive: true });
+    fs.writeFileSync(
+      tmpScript,
+      'const https=require("https");' +
+        'const o={hostname:"api.github.com",path:"/repos/NVIDIA/OpenShell/releases/latest",' +
+        'headers:{"User-Agent":"shield-harness","Accept":"application/vnd.github.v3+json"}};' +
+        'https.get(o,(r)=>{let d="";r.on("data",(c)=>d+=c);' +
+        'r.on("end",()=>{try{process.stdout.write(JSON.parse(d).tag_name||"")}catch{}});})' +
+        '.on("error",()=>{});',
+    );
+    const tag = runCmd(`node "${tmpScript}"`, FETCH_TIMEOUT);
+    try {
+      fs.unlinkSync(tmpScript);
+    } catch {
+      // cleanup failure is non-critical
+    }
+    return tag ? tag.replace(/^v/, "") || null : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check latest version with 24-hour cache.
+ * @param {string} currentVersion
+ * @returns {{ latest_version: string|null, update_available: boolean }}
+ */
+function checkLatestVersion(currentVersion) {
+  const cache = readCache();
+  const now = Date.now();
+
+  // Use cache if within TTL
+  if (cache && cache.checked_at) {
+    const elapsed = now - new Date(cache.checked_at).getTime();
+    if (elapsed < CACHE_TTL_MS && cache.latest_version) {
+      return {
+        latest_version: cache.latest_version,
+        update_available: cache.latest_version !== currentVersion,
+      };
+    }
+  }
+
+  // Fetch from GitHub
+  const latest = fetchLatestVersion();
+  if (latest) {
+    writeCache({
+      latest_version: latest,
+      checked_at: new Date(now).toISOString(),
+      current_version: currentVersion,
+    });
+    return {
+      latest_version: latest,
+      update_available: latest !== currentVersion,
+    };
+  }
+
+  // Network failure — use stale cache if available
+  if (cache && cache.latest_version) {
+    return {
+      latest_version: cache.latest_version,
+      update_available: cache.latest_version !== currentVersion,
+    };
+  }
+
+  return { latest_version: null, update_available: false };
+}
+
+/**
+ * Detect OpenShell availability, version, container status, and update info.
+ * fail-safe: never throws, returns { available: false } on any error.
+ * @returns {{
+ *   available: boolean,
+ *   version: string|null,
+ *   docker_available: boolean,
+ *   container_running: boolean,
+ *   reason: string|null,
+ *   latest_version: string|null,
+ *   update_available: boolean,
+ *   detected_at: string
+ * }}
+ */
+function detectOpenShell() {
+  const detected_at = new Date().toISOString();
+  const base = {
+    available: false,
+    version: null,
+    docker_available: false,
+    container_running: false,
+    reason: null,
+    latest_version: null,
+    update_available: false,
+    detected_at,
+  };
+
+  try {
+    // Step 1: Docker CLI
+    if (!commandExists("docker")) {
+      return { ...base, reason: "docker_not_found" };
+    }
+    base.docker_available = true;
+
+    // Step 2: OpenShell CLI
+    if (!commandExists("openshell")) {
+      return { ...base, reason: "openshell_not_installed" };
+    }
+
+    // Step 3: Version
+    const versionOutput = runCmd("openshell --version");
+    const version = parseVersion(versionOutput);
+    base.version = version;
+
+    // Step 4: Container status (strict match to avoid "inactive"/"No active" false positives)
+    const listOutput = runCmd("openshell sandbox list");
+    const running =
+      listOutput !== null &&
+      /\brunning\b/i.test(listOutput) &&
+      !/\b(not|no|in)active\b/i.test(listOutput);
+    base.container_running = running;
+
+    if (!running) {
+      return { ...base, reason: "container_not_running" };
+    }
+
+    // Step 5: Version tracking (24h cache)
+    const versionInfo = checkLatestVersion(version || "0.0.0");
+    base.latest_version = versionInfo.latest_version;
+    base.update_available = versionInfo.update_available;
+
+    base.available = true;
+    return base;
+  } catch {
+    // Catch-all: detection failure is not a security issue
+    return { ...base, reason: "detection_error" };
+  }
+}
+
+module.exports = { detectOpenShell, fetchLatestVersion, parseVersion };

package/.claude/hooks/lib/policy-compat.js

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+// policy-compat.js — Policy version compatibility check
+// Spec: TASK-021, ADR-037 Phase Beta
+// Purpose: Verify OpenShell policy schema version compatibility at SessionStart
+"use strict";
+
+const fs = require("fs");
+
+/**
+ * Compatibility matrix: OpenShell CLI version range → supported policy schema versions.
+ * Each entry defines which policy schema versions are supported by a given
+ * OpenShell CLI version range (min inclusive, max exclusive).
+ *
+ * Update this matrix when OpenShell releases breaking policy schema changes.
+ * @type {Array<{openshell_min: string, openshell_max: string, supported_policy_versions: number[], latest_policy_version: number}>}
+ */
+const COMPAT_MATRIX = [
+  {
+    // OpenShell Alpha (0.0.x): policy schema v1 only
+    openshell_min: "0.0.0",
+    openshell_max: "1.0.0",
+    supported_policy_versions: [1],
+    latest_policy_version: 1,
+  },
+  // Future entries (example):
+  // {
+  //   openshell_min: "1.0.0",
+  //   openshell_max: "2.0.0",
+  //   supported_policy_versions: [1, 2],
+  //   latest_policy_version: 2,
+  // },
+];
+
+/**
+ * Extract policy schema version from YAML content string.
+ * Uses regex to avoid js-yaml dependency (zero external deps).
+ * Only matches top-level (non-indented, non-commented) version: field.
+ * @param {string} content - Raw YAML file content
+ * @returns {number|null} - Extracted version number, or null if not found/invalid
+ */
+function extractPolicyVersion(content) {
+  if (!content) return null;
+  // Match top-level version field: no leading whitespace, not in a comment
+  // Supports: version: 1, version: "1", version: '1'
+  const match = content.match(/^version:\s*["']?(\d+)["']?/m);
+  if (!match) return null;
+  // Verify the matched line is not indented (top-level only)
+  const lineStart = content.lastIndexOf("\n", match.index) + 1;
+  if (match.index > lineStart) return null; // indented
+  // Verify line is not a comment
+  const linePrefix = content.slice(lineStart, match.index);
+  if (linePrefix.includes("#")) return null;
+  return parseInt(match[1], 10);
+}
+
+/**
+ * Compare two semver strings (X.Y.Z format).
+ * @param {string} a - First version string
+ * @param {string} b - Second version string
+ * @returns {-1|0|1} - -1 if a < b, 0 if equal, 1 if a > b
+ */
+function compareSemver(a, b) {
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  for (let i = 0; i < 3; i++) {
+    const va = pa[i] || 0;
+    const vb = pb[i] || 0;
+    if (va < vb) return -1;
+    if (va > vb) return 1;
+  }
+  return 0;
+}
+
+/**
+ * Check if a semver version falls within a range [min, max).
+ * @param {string} version - Version to check
+ * @param {string} min - Minimum version (inclusive)
+ * @param {string} maxExclusive - Maximum version (exclusive)
+ * @returns {boolean}
+ */
+function semverInRange(version, min, maxExclusive) {
+  return (
+    compareSemver(version, min) >= 0 && compareSemver(version, maxExclusive) < 0
+  );
+}
+
+/**
+ * Check policy file schema version compatibility with installed OpenShell version.
+ * fail-safe: never throws, returns { compatible: null } on any error.
+ * @param {{ openshellVersion: string|null, policyFilePath: string }} params
+ * @returns {{
+ *   compatible: boolean|null,
+ *   policy_version: number|null,
+ *   openshell_version: string|null,
+ *   reason: string|null,
+ *   recommended_policy_version: number|null,
+ *   migration_hint: string|null,
+ *   checked_at: string
+ * }}
+ */
+function checkPolicyCompatibility({ openshellVersion, policyFilePath }) {
+  const checked_at = new Date().toISOString();
+  const base = {
+    compatible: null,
+    policy_version: null,
+    openshell_version: openshellVersion || null,
+    reason: null,
+    recommended_policy_version: null,
+    migration_hint: null,
+    checked_at,
+  };
+
+  try {
+    // Step 1: Read policy file
+    if (!fs.existsSync(policyFilePath)) {
+      return { ...base, reason: "policy_not_found" };
+    }
+
+    const content = fs.readFileSync(policyFilePath, "utf8");
+
+    // Step 2: Extract schema version
+    const policyVersion = extractPolicyVersion(content);
+    base.policy_version = policyVersion;
+
+    if (policyVersion == null) {
+      return { ...base, reason: "version_not_readable" };
+    }
+
+    // Step 3: Check OpenShell version availability
+    if (!openshellVersion) {
+      return { ...base, reason: "openshell_version_unknown" };
+    }
+
+    // Step 4: Find matching matrix entry
+    const entry = COMPAT_MATRIX.find((e) =>
+      semverInRange(openshellVersion, e.openshell_min, e.openshell_max),
+    );
+
+    if (!entry) {
+      return { ...base, reason: "unknown_combination" };
+    }
+
+    // Step 5: Check compatibility
+    if (entry.supported_policy_versions.includes(policyVersion)) {
+      return { ...base, compatible: true };
+    }
+
+    // Incompatible: policy version not supported by this OpenShell range
+    return {
+      ...base,
+      compatible: false,
+      recommended_policy_version: entry.latest_policy_version,
+      migration_hint:
+        "Policy schema v" +
+        policyVersion +
+        " is not supported by OpenShell v" +
+        openshellVersion +
+        ". " +
+        "Supported versions: " +
+        entry.supported_policy_versions.join(", ") +
+        ". " +
+        "Regenerate policy with: npx shield-harness init --policy",
+    };
+  } catch {
+    // fail-safe: any unexpected error returns unknown
+    return { ...base, reason: "check_error" };
+  }
+}
+
+module.exports = {
+  extractPolicyVersion,
+  compareSemver,
+  semverInRange,
+  checkPolicyCompatibility,
+  COMPAT_MATRIX,
+};