shield-harness 0.2.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/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-session-start.js

@@ -269,6 +269,10 @@ try {
           }
         : { available: false, reason: openshellResult.reason },
       session_id: input.sessionId,
+      sandbox_state: openshellResult.available ? "active" : "inactive",
+      sandbox_version: openshellResult.version || null,
+      sandbox_policy_enforced:
+        openshellResult.available && openshellResult.container_running,
       policy_compat: policyCompat
         ? {
             compatible: policyCompat.compatible,

package/README.ja.md

@@ -111,6 +111,31 @@ Windows ネイティブでは Claude Code のサンドボックス機能（`sand
 
 ### Layer 3b: NVIDIA OpenShell（オプション）
 
+#### なぜ Layer 3b が必要か？
+
+Layer 1（permissions）と Layer 2（hooks）はツール呼び出しの入力テキスト（実行前のコマンド文字列）を検査します。しかし検査を通過したコマンドが実行されると、**OS 上の子プロセスは自由に動作します**。
+
+```
+Layer 1-2（プロセス内）:
+  Claude Code → [Hook が入力を検査] → コマンド実行 → [子プロセスは自由]
+                 ↑ ここしか制御できない
+
+Layer 3b（プロセス外 = カーネルレベル）:
+  Claude Code → コマンド実行 → [Landlock: ファイルアクセス制御]
+                                [Seccomp: syscall 制御]
+                                [Network NS: ネットワーク隔離]
+                ↑ 子プロセスも含めて全てカーネルが制御
+```
+
+| 攻撃ベクトル                         | Layer 1-2 の対処             | すり抜ける理由                        | Layer 3b の防御                       |
+| ------------------------------------ | ---------------------------- | ------------------------------------- | ------------------------------------- |
+| パイプチェーンによるファイル読み取り | パターンマッチング           | `awk`、`python -c` による間接アクセス | Landlock LSM がカーネルレベルで拒否   |
+| Raw ソケット通信                     | `curl`/`wget` の deny ルール | `python`/`node` でソケットを直接操作  | Seccomp BPF がソケット syscall を拒否 |
+| DNS トンネリング                     | sandbox.network（WSL2 のみ） | DNS クエリにデータを埋め込み          | Network Namespace が全 DNS を隔離     |
+| PowerShell ソケット                  | パターンマッチング           | エンコード・難読化                    | Seccomp BPF + Network NS の二重防御   |
+
+**構造的保証**: エージェント自身がガードレールを無効化することは**不可能** — ポリシーはコンテナ外に存在し、サンドボックス作成時にロックされます。
+
 [NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell)（Apache 2.0）は Docker 上で AI エージェントに**カーネルレベルの隔離**を提供します:
 
 | メカニズム   | 対象             | 保護内容                |

package/README.md

@@ -109,6 +109,31 @@ For enterprise environments, supplementing with Windows Firewall outbound rules
 
 ### Layer 3b: NVIDIA OpenShell (Optional)
 
+#### Why Layer 3b?
+
+Layer 1 (permissions) and Layer 2 (hooks) inspect tool call inputs — the command text before execution. Once a command passes these checks, the **spawned child process runs freely at the OS level**.
+
+```
+Layer 1-2 (in-process):
+  Claude Code → [Hook inspects input] → Command execution → [Child process is free]
+                 ↑ Only controls this point
+
+Layer 3b (out-of-process = kernel-level):
+  Claude Code → Command execution → [Landlock: Filesystem access control]
+                                     [Seccomp: Syscall control]
+                                     [Network NS: Network isolation]
+                ↑ Kernel controls ALL processes including children
+```
+
+| Attack Vector            | Layer 1-2 Defense           | Why It Bypasses                        | Layer 3b Defense                      |
+| ------------------------ | --------------------------- | -------------------------------------- | ------------------------------------- |
+| Pipe chain file access   | Pattern matching            | Indirect access via `awk`, `python -c` | Landlock LSM denies at kernel level   |
+| Raw socket communication | `curl`/`wget` deny rules    | Direct socket via `python`/`node`      | Seccomp BPF blocks socket syscalls    |
+| DNS tunneling            | sandbox.network (WSL2 only) | Data embedded in DNS queries           | Network Namespace isolates all DNS    |
+| PowerShell sockets       | Pattern matching            | Encoding/obfuscation                   | Seccomp BPF + Network NS dual defense |
+
+**Structural guarantee**: The agent **cannot** disable its own guardrails — policies exist outside the container and are locked at sandbox creation.
+
 [NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell) (Apache 2.0) provides **kernel-level isolation** for AI agents via Docker:
 
 | Mechanism    | Target     | Protection                |

package/bin/shield-harness.js

@@ -208,6 +208,84 @@ function printBasicGuide() {
   console.log("    3. openshell sandbox start");
 }
 
+// ---------------------------------------------------------------------------
+// generate-policy command
+// ---------------------------------------------------------------------------
+
+const POLICY_PROFILES = ["standard", "strict"];
+const DEFAULT_POLICY_OUTPUT = path.join(
+  ".claude",
+  "policies",
+  "openshell-generated.yaml",
+);
+
+/**
+ * Generate OpenShell policy YAML from permissions-spec.json.
+ * @param {string[]} args - CLI arguments (after "generate-policy")
+ */
+function generatePolicy(args) {
+  // Parse --output
+  let output = DEFAULT_POLICY_OUTPUT;
+  const outputIdx = args.indexOf("--output");
+  if (outputIdx !== -1 && args[outputIdx + 1]) {
+    output = args[outputIdx + 1];
+  }
+
+  // Parse --profile
+  let profile = "standard";
+  const profileIdx = args.indexOf("--profile");
+  if (profileIdx !== -1 && args[profileIdx + 1]) {
+    profile = args[profileIdx + 1];
+    if (!POLICY_PROFILES.includes(profile)) {
+      console.error(`Unknown profile: ${profile}`);
+      console.error(`Available profiles: ${POLICY_PROFILES.join(", ")}`);
+      process.exit(1);
+    }
+  }
+
+  // Read permissions-spec.json
+  const specPath = path.join(process.cwd(), ".claude", "permissions-spec.json");
+  if (!fs.existsSync(specPath)) {
+    console.error("permissions-spec.json not found at: " + specPath);
+    console.error("Run 'npx shield-harness init' first.");
+    process.exit(1);
+  }
+
+  let spec;
+  try {
+    spec = JSON.parse(fs.readFileSync(specPath, "utf8"));
+  } catch (err) {
+    console.error("Failed to parse permissions-spec.json: " + err.message);
+    process.exit(1);
+  }
+
+  // Generate YAML
+  let yaml;
+  try {
+    const {
+      generatePolicyYaml,
+    } = require("../.claude/hooks/lib/tier-policy-gen");
+    yaml = generatePolicyYaml(spec, { profile });
+  } catch (err) {
+    console.error("Failed to generate policy: " + err.message);
+    process.exit(1);
+  }
+
+  // Write output
+  const outputPath = path.resolve(process.cwd(), output);
+  const outputDir = path.dirname(outputPath);
+  if (!fs.existsSync(outputDir)) {
+    fs.mkdirSync(outputDir, { recursive: true });
+  }
+  fs.writeFileSync(outputPath, yaml);
+
+  console.log(`Policy generated successfully (profile: ${profile}).`);
+  console.log(`  Output: ${output}`);
+  console.log("");
+  console.log("Usage:");
+  console.log(`  openshell sandbox create --policy ${output} -- claude`);
+}
+
 // ---------------------------------------------------------------------------
 // CLI
 // ---------------------------------------------------------------------------
@@ -227,12 +305,17 @@ if (command === "init") {
     }
   }
   init(profile);
+} else if (command === "generate-policy") {
+  generatePolicy(args);
 } else {
   const pkg = require("../package.json");
   console.log(`Shield Harness v${pkg.version}`);
   console.log("");
   console.log("Usage:");
   console.log("  npx shield-harness init [--profile minimal|standard|strict]");
+  console.log(
+    "  npx shield-harness generate-policy [--output <path>] [--profile standard|strict]",
+  );
   console.log("");
   console.log("Profiles:");
   console.log("  minimal   — Minimal config, approval-free");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shield-harness",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Security harness for Claude Code — hooks-driven, zero-hassle defense",
   "bin": {
     "shield-harness": "./bin/shield-harness.js"
@@ -23,7 +23,11 @@
     "test:output": "node --test tests/output-security.test.js",
     "test:ocsf": "node --test tests/ocsf-mapper.test.js",
     "test:policy-compat": "node --test tests/policy-compat.test.js",
-    "test:permissions": "node --test tests/permissions-alignment.test.js"
+    "test:permissions": "node --test tests/permissions-alignment.test.js",
+    "test:openshell-detect": "node --test tests/openshell-detect.test.js",
+    "test:openshell-evidence": "node --test tests/openshell-evidence.test.js",
+    "test:tier-policy": "node --test tests/tier-policy-gen.test.js",
+    "test:policy-effectiveness": "node --test tests/policy-effectiveness.test.js"
   },
   "keywords": [
     "claude-code",