shield-harness 1.0.0

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

@@ -0,0 +1,330 @@
+#!/usr/bin/env node
+// sh-gate.js — Destructive command blocker + hook evasion defense
+// Spec: DETAILED_DESIGN.md §3.2
+// Event: PreToolUse (Bash)
+// Target response time: < 50ms
+"use strict";
+
+const {
+  readHookInput,
+  allow,
+  deny,
+  nfkcNormalize,
+  normalizePath,
+  appendEvidence,
+} = require("./lib/sh-utils");
+
+// ---------------------------------------------------------------------------
+// Pattern Arrays (§3.2 — all 7 attack vectors + destructive commands)
+// ---------------------------------------------------------------------------
+
+// Destructive commands — catastrophic file system / device operations
+const DESTRUCTIVE_PATTERNS = [
+  [/^rm\s+-rf\s+\//, "rm -rf / (root filesystem destruction)"],
+  [/^rm\s+-rf\s+~/, "rm -rf ~ (home directory destruction)"],
+  [/^del\s+\/s\s+\/q\s+[A-Z]:\\/, "del /s /q (Windows recursive delete)"],
+  [/^format\s+[A-Z]:/, "format drive (disk format)"],
+  [/^mkfs\./, "mkfs (filesystem creation on device)"],
+  [/^dd\s+if=.*\s+of=\/dev\//, "dd to device (raw disk write)"],
+];
+
+// E-1: Tool switching — bypass Edit/Write tool via Bash scripting languages
+const TOOL_SWITCHING_PATTERNS = [
+  [/sed\s+-i/, "sed -i (in-place edit bypasses Edit tool)"],
+  [
+    /sed\s.*['"][^'"]*[/][^'"]*[ew]\s*['"]/,
+    "sed e/w modifier (execute/write via sed)",
+  ],
+  [/sed\s.*-e\s/, "sed -e (expression, potential execute)"],
+  [/python3?\s+-c\s+['"].*open\(/, "python -c open() (file write via python)"],
+  [/node\s+-e\s+['"].*fs\./, "node -e fs.* (file write via node)"],
+  [/ruby\s+-e\s+['"].*File\./, "ruby -e File.* (file write via ruby)"],
+  [/perl\s+-[pei]/, "perl -p/-e/-i (in-place or eval mode)"],
+  [
+    /powershell.*-Command.*Set-Content/i,
+    "PowerShell Set-Content (file write via powershell)",
+  ],
+  [/echo\s+.*>\s/, "echo redirect (file write via echo)"],
+  [/printf\s+.*>\s/, "printf redirect (file write via printf)"],
+  [/\|\s*tee\s/, "pipe to tee (file write via tee)"],
+];
+
+// E-3: Dynamic linker — execute arbitrary code via loader injection
+const DYNAMIC_LINKER_PATTERNS = [
+  [/LD_PRELOAD=/, "LD_PRELOAD (shared library injection)"],
+  [/LD_LIBRARY_PATH=/, "LD_LIBRARY_PATH (library path hijack)"],
+  [/DYLD_INSERT_LIBRARIES=/, "DYLD_INSERT_LIBRARIES (macOS library injection)"],
+  [/ld-linux/, "ld-linux (direct dynamic linker invocation)"],
+  [/\/lib.*\/ld-/, "/lib*/ld- (dynamic linker path)"],
+  [/\/usr\/lib.*\/ld-/, "/usr/lib*/ld- (dynamic linker path)"],
+  [/rundll32/i, "rundll32 (Windows DLL execution)"],
+];
+
+// E-4: sed dangerous modifiers (subset of tool switching, explicit check)
+const SED_DANGER_PATTERNS = [
+  [
+    /sed\s.*['"][^'"]*[/][^'"]*[ew]\s*['"]/,
+    "sed e/w modifier (arbitrary command execution)",
+  ],
+];
+
+// E-5: Self-config modification — agent modifying its own governance files
+const CONFIG_MODIFY_PATTERNS = [
+  [/>\s*\.claude\//, "redirect to .claude/ (config overwrite)"],
+  [/>>\s*\.claude\//, "append redirect to .claude/ (config modification)"],
+  [/tee\s+.*\.claude\//, "tee to .claude/ (config write)"],
+  [/cp\s+.*\.claude\//, "cp to .claude/ (config copy)"],
+  [/mv\s+.*\.claude\//, "mv to .claude/ (config move)"],
+];
+
+// FR-02-06: PATH hijack — override command resolution
+const PATH_HIJACK_PATTERNS = [
+  [/^PATH=/, "PATH= (command search path override)"],
+  [/export\s+PATH=/, "export PATH= (persistent path override)"],
+  [/\$SHELL/, "$SHELL (shell variable reference)"],
+  [/\$PATH/, "$PATH (path variable reference)"],
+  [/env\s+-[SiuC]/, "env -S/-i/-u/-C (environment manipulation)"],
+  [/env\s+--split-string/, "env --split-string (argument injection)"],
+];
+
+// FR-02-09, FR-02-10: Windows-specific attack vectors
+const WINDOWS_PATTERNS = [
+  [/\.lnk\b/, ".lnk (Windows shortcut — potential code execution)"],
+  [/\.scf\b/, ".scf (Shell Command File — potential code execution)"],
+  [/\.url\b/, ".url (Internet shortcut — potential redirect)"],
+  [/\.cmd\b/, ".cmd (Windows batch — uncontrolled execution)"],
+  [/\.bat\b/, ".bat (Windows batch — uncontrolled execution)"],
+  [/\bpowershell\b.*-enc/i, "powershell -enc (encoded command — obfuscation)"],
+  [/::\$DATA/, "NTFS ADS (Alternate Data Stream)"],
+  [/\\\\\?\\UNC\\/, "UNC extended path (network path injection)"],
+];
+
+// E-8: Pipeline environment variable spoofing (§8.1)
+const PIPELINE_SPOOFING_PATTERNS = [
+  [/export\s+SH_PIPELINE/, "export SH_PIPELINE (pipeline env spoofing)"],
+  [/SH_PIPELINE=1/, "SH_PIPELINE=1 (pipeline env spoofing)"],
+  [/env\s+SH_PIPELINE/, "env SH_PIPELINE (pipeline env spoofing)"],
+  [/set\s+SH_PIPELINE/, "set SH_PIPELINE (pipeline env spoofing)"],
+];
+
+// E-2: Path obfuscation (checked after normalization)
+const PATH_OBFUSCATION_PATTERNS = [
+  [/\/proc\/self\/root/, "/proc/self/root (filesystem escape)"],
+  [/\/proc\/[0-9]+\/root/, "/proc/PID/root (filesystem escape)"],
+  [/PROGRA~[0-9]/, "8.3 short name (path obfuscation)"],
+  [/::\$DATA/, "NTFS ADS :$DATA (hidden data stream)"],
+  [/::\$INDEX_ALLOCATION/, "NTFS ADS :$INDEX_ALLOCATION"],
+];
+
+// ---------------------------------------------------------------------------
+// Pattern matching engine
+// ---------------------------------------------------------------------------
+
+/**
+ * Test a command against an array of [RegExp, label] patterns.
+ * @param {string} command - Normalized command string
+ * @param {Array<[RegExp, string]>} patterns - Pattern array
+ * @returns {{ pattern: RegExp, label: string } | null}
+ */
+function matchPatterns(command, patterns) {
+  for (const [pattern, label] of patterns) {
+    if (pattern.test(command)) {
+      return { pattern, label };
+    }
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Evidence recording helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Record a deny decision to the evidence ledger.
+ * @param {string} hookName
+ * @param {string} decision - "deny"
+ * @param {string} reason
+ * @param {string} command - Truncated command for audit
+ * @param {string} sessionId
+ */
+function recordEvidence(hookName, decision, reason, command, sessionId) {
+  try {
+    appendEvidence({
+      hook: hookName,
+      event: "PreToolUse",
+      tool: "Bash",
+      decision,
+      reason,
+      command: command.length > 120 ? command.slice(0, 120) + "..." : command,
+      session_id: sessionId,
+    });
+  } catch (_) {
+    // Evidence recording failure must not block the deny response
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Main: 10-step judgment flow (§3.2)
+// ---------------------------------------------------------------------------
+
+try {
+  const input = readHookInput();
+  const command = (input.toolInput && input.toolInput.command) || "";
+
+  // Empty command = not a Bash tool call or no-op — allow
+  if (!command) {
+    allow();
+  }
+
+  // Step 1: Path normalization (E-2 defense)
+  // normalizePath resolves symlinks, Windows backslashes, 8.3 short names
+  // We apply it to the command string to detect obfuscated paths
+  let normalizedCommand = command;
+  // Note: normalizePath works on file paths; for commands we rely on
+  // NFKC normalization + pattern matching. Path-specific normalization
+  // is applied within PATH_OBFUSCATION_PATTERNS check.
+
+  // Step 2: NFKC normalization (E-7 defense)
+  // Normalizes zero-width characters, homoglyphs, fullwidth chars
+  normalizedCommand = nfkcNormalize(normalizedCommand);
+
+  // Step 3: Destructive command detection
+  let match = matchPatterns(normalizedCommand, DESTRUCTIVE_PATTERNS);
+  if (match) {
+    recordEvidence(
+      "sh-gate",
+      "deny",
+      match.label,
+      normalizedCommand,
+      input.sessionId,
+    );
+    deny(`[sh-gate] Blocked: ${match.label}`);
+  }
+
+  // Step 4: Tool switching detection (E-1 defense)
+  match = matchPatterns(normalizedCommand, TOOL_SWITCHING_PATTERNS);
+  if (match) {
+    recordEvidence(
+      "sh-gate",
+      "deny",
+      match.label,
+      normalizedCommand,
+      input.sessionId,
+    );
+    deny(`[sh-gate] Blocked: ${match.label}. Use the Edit tool instead.`);
+  }
+
+  // Step 5: sed dangerous modifier detection (E-4 defense)
+  match = matchPatterns(normalizedCommand, SED_DANGER_PATTERNS);
+  if (match) {
+    recordEvidence(
+      "sh-gate",
+      "deny",
+      match.label,
+      normalizedCommand,
+      input.sessionId,
+    );
+    deny(
+      `[sh-gate] Blocked: ${match.label}. sed e/w modifiers are prohibited.`,
+    );
+  }
+
+  // Step 6: Dynamic linker detection (E-3 defense)
+  match = matchPatterns(normalizedCommand, DYNAMIC_LINKER_PATTERNS);
+  if (match) {
+    recordEvidence(
+      "sh-gate",
+      "deny",
+      match.label,
+      normalizedCommand,
+      input.sessionId,
+    );
+    deny(
+      `[sh-gate] Blocked: ${match.label}. Dynamic linker manipulation is prohibited.`,
+    );
+  }
+
+  // Step 7: Self-config modification detection (E-5 defense)
+  match = matchPatterns(normalizedCommand, CONFIG_MODIFY_PATTERNS);
+  if (match) {
+    recordEvidence(
+      "sh-gate",
+      "deny",
+      match.label,
+      normalizedCommand,
+      input.sessionId,
+    );
+    deny(
+      `[sh-gate] Blocked: ${match.label}. Modifying .claude/ config is prohibited.`,
+    );
+  }
+
+  // Step 8: Absolute path enforcement / PATH hijack (FR-02-06)
+  match = matchPatterns(normalizedCommand, PATH_HIJACK_PATTERNS);
+  if (match) {
+    recordEvidence(
+      "sh-gate",
+      "deny",
+      match.label,
+      normalizedCommand,
+      input.sessionId,
+    );
+    deny(
+      `[sh-gate] Blocked: ${match.label}. PATH/environment manipulation is prohibited.`,
+    );
+  }
+
+  // Step 9: Windows-specific detection (FR-02-09, FR-02-10)
+  match = matchPatterns(normalizedCommand, WINDOWS_PATTERNS);
+  if (match) {
+    recordEvidence(
+      "sh-gate",
+      "deny",
+      match.label,
+      normalizedCommand,
+      input.sessionId,
+    );
+    deny(
+      `[sh-gate] Blocked: ${match.label}. Windows shell attack vector detected.`,
+    );
+  }
+
+  // Additional: Pipeline spoofing detection (E-8, §8.1)
+  match = matchPatterns(normalizedCommand, PIPELINE_SPOOFING_PATTERNS);
+  if (match) {
+    recordEvidence(
+      "sh-gate",
+      "deny",
+      match.label,
+      normalizedCommand,
+      input.sessionId,
+    );
+    deny(
+      `[sh-gate] Blocked: ${match.label}. Pipeline environment spoofing detected.`,
+    );
+  }
+
+  // Additional: Path obfuscation detection (E-2 post-normalization)
+  match = matchPatterns(normalizedCommand, PATH_OBFUSCATION_PATTERNS);
+  if (match) {
+    recordEvidence(
+      "sh-gate",
+      "deny",
+      match.label,
+      normalizedCommand,
+      input.sessionId,
+    );
+    deny(`[sh-gate] Blocked: ${match.label}. Path obfuscation detected.`);
+  }
+
+  // Step 10: All checks passed — allow
+  allow();
+} catch (err) {
+  // fail-close: any uncaught error = deny (§2.3b)
+  process.stdout.write(
+    JSON.stringify({
+      reason: `Hook error (sh-gate): ${err.message}`,
+    }),
+  );
+  process.exit(2);
+}

package/.claude/hooks/sh-injection-guard.js

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+// sh-injection-guard.js — 9-category 50+ pattern injection detection (Injection Stage 2)
+// Spec: DETAILED_DESIGN.md §3.3
+// Hook event: PreToolUse
+// Matcher: Bash|Edit|Write|Read|WebFetch
+// Target response time: < 50ms
+"use strict";
+
+const {
+  readHookInput,
+  allow,
+  deny,
+  nfkcNormalize,
+  loadPatterns,
+  appendEvidence,
+} = require("./lib/sh-utils");
+
+// Zero-width character regex (checked BEFORE pattern matching to prevent bypass)
+// U+200B-200F: zero-width space, non-joiner, joiner, LTR mark, RTL mark
+// U+2028-2029: line separator, paragraph separator
+// U+2060-2064: word joiner, invisible operators
+// U+FEFF: byte order mark
+// U+00AD: soft hyphen
+// U+034F: combining grapheme joiner
+const ZERO_WIDTH_RE =
+  /[\u200b-\u200f\u2028\u2029\u2060-\u2064\ufeff\u00ad\u034f]/;
+
+/**
+ * Extract the text to scan from tool_input based on tool_name.
+ * @param {string} toolName
+ * @param {Object} toolInput
+ * @returns {string} text to scan (empty string if nothing to scan)
+ */
+function extractText(toolName, toolInput) {
+  switch (toolName) {
+    case "Bash":
+      return toolInput.command || "";
+    case "Edit":
+      return toolInput.new_string || "";
+    case "Write":
+      return toolInput.content || "";
+    case "Read":
+      return toolInput.file_path || "";
+    case "WebFetch":
+      return toolInput.url || "";
+    default:
+      return "";
+  }
+}
+
+try {
+  const input = readHookInput();
+  const { toolName, toolInput, sessionId } = input;
+
+  // Step 0: Extract text to scan
+  const rawText = extractText(toolName, toolInput);
+
+  // If no text to scan, allow (nothing to check)
+  if (!rawText) {
+    allow();
+  }
+
+  // Step 1: NFKC normalization
+  const text = nfkcNormalize(rawText);
+
+  // Step 2: Zero-width character detection (BEFORE pattern load — prevents bypass)
+  if (ZERO_WIDTH_RE.test(rawText)) {
+    // Test against raw text (pre-NFKC) since NFKC may normalize some away
+    appendEvidence({
+      hook: "sh-injection-guard",
+      event: "deny",
+      tool: toolName,
+      category: "zero_width",
+      severity: "high",
+      detail: "Zero-width character detected in raw input",
+      session_id: sessionId,
+    });
+    deny(
+      "[sh-injection-guard] Zero-width character detected. " +
+        "Invisible characters can be used to bypass security patterns. " +
+        "Category: zero_width (severity: high)",
+    );
+  }
+
+  // Step 3: Load injection patterns (fail-close on missing/corrupted file)
+  const patterns = loadPatterns();
+
+  if (!patterns || !patterns.categories) {
+    deny("[sh-injection-guard] injection-patterns.json has invalid structure.");
+  }
+
+  // Step 4: Match each category's patterns in severity order
+  // Collect medium-severity warnings (not blocking)
+  const warnings = [];
+  const categories = patterns.categories;
+
+  for (const [categoryName, category] of Object.entries(categories)) {
+    const severity = category.severity || "medium";
+    const categoryPatterns = category.patterns || [];
+
+    for (const patternStr of categoryPatterns) {
+      let re;
+      try {
+        re = new RegExp(patternStr, "i");
+      } catch {
+        // Invalid regex in patterns file — skip (don't crash the hook)
+        continue;
+      }
+
+      if (re.test(text)) {
+        if (severity === "critical" || severity === "high") {
+          // Deny immediately with evidence
+          appendEvidence({
+            hook: "sh-injection-guard",
+            event: "deny",
+            tool: toolName,
+            category: categoryName,
+            severity,
+            pattern: patternStr,
+            session_id: sessionId,
+          });
+          deny(
+            `[sh-injection-guard] Injection pattern detected. ` +
+              `Category: ${categoryName} (severity: ${severity}). ` +
+              `Description: ${category.description || "N/A"}`,
+          );
+        }
+
+        if (severity === "medium") {
+          // Collect warning — do not deny
+          warnings.push({
+            category: categoryName,
+            severity,
+            pattern: patternStr,
+            description: category.description || "",
+          });
+          // Only record the first match per category for warnings
+          break;
+        }
+      }
+    }
+  }
+
+  // Step 5: If only medium warnings, allow with additionalContext
+  if (warnings.length > 0) {
+    const warningMessages = warnings.map(
+      (w) => `[${w.category}] ${w.description}`,
+    );
+    allow(
+      `[sh-injection-guard] Warning: potential security concern detected.\n` +
+        warningMessages.join("\n"),
+    );
+  }
+
+  // All patterns passed — allow
+  allow();
+} catch (err) {
+  // fail-close: any uncaught error = deny
+  process.stdout.write(
+    JSON.stringify({
+      reason: `Hook error (sh-injection-guard): ${err.message}`,
+    }),
+  );
+  process.exit(2);
+}

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

@@ -0,0 +1,210 @@
+#!/usr/bin/env node
+// sh-instructions.js — Rule file integrity monitoring
+// Spec: DETAILED_DESIGN.md §5.8
+// Event: InstructionsLoaded
+// Target response time: < 200ms
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const {
+  readHookInput,
+  allow,
+  sha256,
+  appendEvidence,
+} = require("./lib/sh-utils");
+
+const HOOK_NAME = "sh-instructions";
+const CLAUDE_MD = "CLAUDE.md";
+const RULES_DIR = path.join(".claude", "rules");
+const HASHES_FILE = path.join(".claude", "logs", "instructions-hashes.json");
+
+// ---------------------------------------------------------------------------
+// Hash Collection
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute SHA-256 hash for a file.
+ * @param {string} filePath
+ * @returns {string|null}
+ */
+function hashFile(filePath) {
+  try {
+    return sha256(fs.readFileSync(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Collect current hashes for CLAUDE.md and all rule files.
+ * @returns {Object} { filePath: hash }
+ */
+function collectCurrentHashes() {
+  const hashes = {};
+
+  // CLAUDE.md
+  if (fs.existsSync(CLAUDE_MD)) {
+    hashes[CLAUDE_MD] = hashFile(CLAUDE_MD);
+  }
+
+  // .claude/rules/*.md
+  if (fs.existsSync(RULES_DIR)) {
+    try {
+      const files = fs.readdirSync(RULES_DIR).filter((f) => f.endsWith(".md"));
+      for (const f of files) {
+        const fp = path.join(RULES_DIR, f);
+        hashes[fp] = hashFile(fp);
+      }
+    } catch {
+      // Directory read failure — non-critical
+    }
+  }
+
+  return hashes;
+}
+
+/**
+ * Load stored hashes from disk.
+ * @returns {Object|null} null if no baseline exists
+ */
+function loadStoredHashes() {
+  try {
+    if (!fs.existsSync(HASHES_FILE)) return null;
+    return JSON.parse(fs.readFileSync(HASHES_FILE, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Save hashes to disk.
+ * @param {Object} hashes
+ */
+function saveHashes(hashes) {
+  const dir = path.dirname(HASHES_FILE);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(HASHES_FILE, JSON.stringify(hashes, null, 2));
+}
+
+/**
+ * Detect changes between stored and current hashes.
+ * @param {Object} stored
+ * @param {Object} current
+ * @returns {{ added: string[], modified: string[], removed: string[] }}
+ */
+function detectChanges(stored, current) {
+  const added = [];
+  const modified = [];
+  const removed = [];
+
+  // Check current against stored
+  for (const [file, hash] of Object.entries(current)) {
+    if (!(file in stored)) {
+      added.push(file);
+    } else if (stored[file] !== hash) {
+      modified.push(file);
+    }
+  }
+
+  // Check for removed files
+  for (const file of Object.keys(stored)) {
+    if (!(file in current)) {
+      removed.push(file);
+    }
+  }
+
+  return { added, modified, removed };
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+try {
+  const input = readHookInput();
+  const currentHashes = collectCurrentHashes();
+  const storedHashes = loadStoredHashes();
+
+  // First run: save baseline, no warning
+  if (!storedHashes) {
+    saveHashes(currentHashes);
+
+    try {
+      appendEvidence({
+        hook: HOOK_NAME,
+        event: "InstructionsLoaded",
+        decision: "allow",
+        action: "baseline_recorded",
+        file_count: Object.keys(currentHashes).length,
+        session_id: input.sessionId,
+      });
+    } catch {
+      // Non-blocking
+    }
+
+    allow(
+      `[${HOOK_NAME}] Baseline recorded: ${Object.keys(currentHashes).length} files`,
+    );
+  }
+
+  // Detect changes
+  const changes = detectChanges(storedHashes, currentHashes);
+  const hasChanges =
+    changes.added.length > 0 ||
+    changes.modified.length > 0 ||
+    changes.removed.length > 0;
+
+  // Update stored hashes
+  saveHashes(currentHashes);
+
+  if (hasChanges) {
+    // Build warning message
+    const warnings = ["[RULE FILE CHANGE DETECTED]"];
+
+    if (changes.added.length > 0) {
+      warnings.push(`  Added: ${changes.added.join(", ")}`);
+    }
+    if (changes.modified.length > 0) {
+      warnings.push(`  Modified: ${changes.modified.join(", ")}`);
+    }
+    if (changes.removed.length > 0) {
+      warnings.push(`  Removed: ${changes.removed.join(", ")}`);
+    }
+
+    warnings.push("Re-read these files to ensure instructions are current.");
+
+    try {
+      appendEvidence({
+        hook: HOOK_NAME,
+        event: "InstructionsLoaded",
+        decision: "allow",
+        action: "changes_detected",
+        changes,
+        session_id: input.sessionId,
+      });
+    } catch {
+      // Non-blocking
+    }
+
+    allow(warnings.join("\n"));
+  }
+
+  // No changes
+  allow();
+} catch (_err) {
+  // Operational hook — fail-open
+  allow();
+}
+
+// ---------------------------------------------------------------------------
+// Exports (for testing)
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  hashFile,
+  collectCurrentHashes,
+  loadStoredHashes,
+  saveHashes,
+  detectChanges,
+};