shield-harness 0.1.0

package/README.md

@@ -0,0 +1,174 @@
+<div align="center">
+
+# Shield Harness
+
+**Auto-defense security harness for Claude Code — approval-free, safe autonomous development**
+
+> **Alpha (v0.1.0)**: Security model is under active development. Permission rules and design documents are being aligned. Not recommended for production use yet.
+
+[![English](https://img.shields.io/badge/lang-English-blue?style=flat-square)](#)
+[![日本語](https://img.shields.io/badge/lang-日本語-red?style=flat-square)](README.ja.md)
+
+</div>
+
+## What is Shield Harness
+
+A security harness that governs Claude Code through multi-layered defense:
+hooks + rules + permissions + settings deployed in the `.claude/` directory.
+
+## Quick Start
+
+```bash
+npx shield-harness init [--profile minimal|standard|strict]
+```
+
+## Why Shield Harness
+
+- **Hooks-driven defense**: 22 security hooks monitor every Claude Code operation
+- **Approval-free mode**: Delegate all security decisions to hooks, eliminating human approval dialogs
+- **fail-close principle**: Automatically stops when safety conditions cannot be verified
+- **Evidence recording**: Tamper-proof SHA-256 hash chain records all allow/deny decisions
+
+## Architecture Overview
+
+3-layer defense model:
+
+| Layer    | Defense            | Implementation                                     |
+| -------- | ------------------ | -------------------------------------------------- |
+| Layer 1  | Permission control | `settings.json` deny/allow rules                   |
+| Layer 2  | Hook defense       | 22 Node.js hook scripts                            |
+| Layer 3  | Sandbox            | Claude Code native sandbox (bubblewrap / Seatbelt) |
+| Layer 3b | Container sandbox  | NVIDIA OpenShell (optional, Docker environments)   |
+
+## Profiles
+
+| Profile      | Description    | Approval-free | Use case                                    |
+| ------------ | -------------- | ------------- | ------------------------------------------- |
+| **minimal**  | Minimal config | Enabled       | Low-risk tasks                              |
+| **standard** | Recommended    | Enabled       | Normal development                          |
+| **strict**   | Strict config  | Disabled      | When security audit requires human approval |
+
+## Hook Catalog
+
+| #   | Hook             | Event                 | Responsibility                                   |
+| --- | ---------------- | --------------------- | ------------------------------------------------ |
+| 1   | permission       | PreToolUse            | 4-category tool usage classification             |
+| 2   | gate             | PreToolUse            | 7 attack vector inspection for Bash commands     |
+| 3   | injection-guard  | PreToolUse            | 9-category 50+ pattern injection detection       |
+| 4   | data-boundary    | PreToolUse            | Production data boundary + jurisdiction tracking |
+| 5   | quiet-inject     | PreToolUse            | Auto-inject quiet flags                          |
+| 6   | evidence         | PostToolUse           | SHA-256 hash chain evidence                      |
+| 7   | output-control   | PostToolUse           | Output truncation + token budget                 |
+| 8   | dep-audit        | PostToolUse           | Package install detection                        |
+| 9   | lint-on-save     | PostToolUse           | Auto lint execution                              |
+| 10  | session-start    | SessionStart          | Session init + integrity baseline                |
+| 11  | session-end      | SessionEnd            | Cleanup + statistics                             |
+| 12  | circuit-breaker  | Stop                  | Retry limit (3 attempts)                         |
+| 13  | config-guard     | ConfigChange          | Settings change monitoring                       |
+| 14  | user-prompt      | UserPromptSubmit      | User input injection scanning                    |
+| 15  | permission-learn | PermissionRequest     | Permission learning guard                        |
+| 16  | elicitation      | Elicitation           | Phishing + scope guard                           |
+| 17  | subagent         | SubagentStart         | Subagent budget constraint (25%)                 |
+| 18  | instructions     | InstructionsLoaded    | Rule file integrity monitoring                   |
+| 19  | precompact       | PreCompact            | Pre-compaction backup                            |
+| 20  | postcompact      | PostCompact           | Post-compaction restore + verify                 |
+| 21  | worktree         | WorktreeCreate/Remove | Security propagation + evidence merge            |
+| 22  | task-gate        | TaskCompleted         | Test gate                                        |
+
+## Pipeline
+
+STG gate-driven automation pipeline:
+
+| STG0 |  STG1  | STG2 |  STG3  | STG4 |  STG5  |   STG6   |
+| :--: | :----: | :--: | :----: | :--: | :----: | :------: |
+| Reqs | Design | Impl | Verify |  CI  | Commit | PR/Merge |
+
+## Layer 3: Sandbox (OS-Level Isolation)
+
+Layer 3 relies on Claude Code's built-in sandbox. Shield Harness does not implement its own sandbox — it leverages Layers 1 & 2 to compensate when sandboxing is unavailable.
+
+### Platform Support
+
+| OS             | Sandbox       | Technology         | Status                                  |
+| -------------- | ------------- | ------------------ | --------------------------------------- |
+| macOS          | Supported     | Seatbelt           | Auto-enabled                            |
+| Linux          | Supported     | bubblewrap + socat | `sudo apt-get install bubblewrap socat` |
+| WSL2           | Supported     | bubblewrap + socat | Same as Linux                           |
+| WSL1           | Not supported | —                  | Kernel features missing                 |
+| Windows native | Not supported | —                  | Planned by Anthropic                    |
+
+### Windows Native: Security Gap & Mitigation
+
+On Windows native, Claude Code's sandbox features (`sandbox.filesystem.*`, `sandbox.network.*`, `sandbox.autoAllow`) do not function. Shield Harness compensates through:
+
+- **Layer 1**: `permissions.deny` includes Windows-specific commands (`type`, `del`, `format`, `Invoke-WebRequest`)
+- **Layer 2**: All 22 hooks operate normally — injection detection, evidence recording, and gate checks are fully functional
+- **Limitation**: Child process file access cannot be restricted at the OS level; raw socket communication bypasses command pattern matching
+
+For enterprise environments, supplementing with Windows Firewall outbound rules for process-level network control is recommended.
+
+### Layer 3b: NVIDIA OpenShell (Optional)
+
+[NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell) (Apache 2.0) provides **kernel-level isolation** for AI agents via Docker:
+
+| Mechanism    | Target     | Protection                |
+| ------------ | ---------- | ------------------------- |
+| Landlock LSM | Filesystem | denyWrite / denyRead      |
+| Seccomp BPF  | Syscalls   | Socket / process restrict |
+| Network NS   | Network    | Domain-level deny         |
+
+Key benefits for Windows users:
+
+- Policies exist **outside** the agent process — the agent cannot disable its own guardrails
+- Runs on Docker Desktop + WSL2 backend (typical Windows dev setup)
+- Reduces residual risk from 5% to <1%
+- Freely removable — stop the container and Shield Harness falls back to Layer 1-2
+
+> **Note**: OpenShell is Alpha (v0.0.13) — APIs may change with future releases.
+
+## Channel Integration
+
+Supports Claude Code Channels (Telegram/Discord).
+Channel-sourced messages automatically receive severity boost for enhanced security.
+
+## System Requirements
+
+| Tool         | Version            | Purpose                             | Required           |
+| ------------ | ------------------ | ----------------------------------- | ------------------ |
+| Git          | 2.x                | Version control                     | Required           |
+| Git Bash     | (bundled with Git) | Hook script runtime                 | Required (Windows) |
+| Node.js      | 18+                | Hook execution + NFKC normalization | Required           |
+| PowerShell 7 | 7.x (`pwsh`)       | Sync scripts                        | Recommended        |
+| GitHub CLI   | 2.x (`gh`)         | PR creation/merge automation        | Optional           |
+
+OS: Windows-native first (Git Bash), WSL2/Linux compatible.
+
+## Versioning
+
+Shield Harness follows [Semantic Versioning](https://semver.org/):
+
+| Bump    | Condition                                                      | Example                              |
+| ------- | -------------------------------------------------------------- | ------------------------------------ |
+| `patch` | Bug fixes, pattern updates, documentation fixes                | injection-patterns.json update       |
+| `minor` | New features (backward compatible), Phase must-tasks completed | OCSF support, new hook, CLI option   |
+| `major` | Breaking changes                                               | Schema incompatible, settings change |
+
+**Release trigger**: `git tag v1.x.x && git push origin v1.x.x` triggers `release.yml` (automated npm publish + GitHub Release). Security fixes trigger an immediate patch release.
+
+## References
+
+Shield Harness was designed by surveying 40+ Claude Code security projects. Key references:
+
+| Project                                                                      | Influence                                                                                                          |
+| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| [claude-guardrails](https://github.com/dwarvesf/claude-guardrails)           | npx install pattern, 50+ injection patterns, deny rule catalog                                                     |
+| [claude-warden](https://github.com/johnzfitch/claude-warden)                 | 3-tier profiles, token governance (quiet-inject, output-control), ConfigChange self-protection                     |
+| [claude-hooks](https://github.com/lasso-security/claude-hooks)               | 5-category injection detection, YAML pattern definitions                                                           |
+| [tobari](https://github.com/Sora-bluesky/tobari)                             | 22-hook architecture, SHA-256 hash chain evidence, STG gate pipeline, PermissionRequest adaptive learning          |
+| [OpenClaw](https://github.com/openclaw/openclaw)                             | 18 CVE/security issue lessons (gateway auth, credential management, symlink traversal), channel integration design |
+| [everything-claude-code](https://github.com/affaan-m/everything-claude-code) | AgentShield security integration (1,282 tests, 102 rules), comprehensive skill/agent catalog                       |
+| [NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell)                      | Layer 3b kernel-level sandbox (Landlock, Seccomp BPF, Network NS), declarative YAML policies                       |
+
+## License
+
+MIT

package/bin/shield-harness.js

@@ -0,0 +1,241 @@
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+const PROFILES = ["minimal", "standard", "strict"];
+const DEFAULT_PROFILE = "standard";
+
+// Source directories within the npm package
+const PKG_ROOT = path.resolve(__dirname, "..");
+const HOOK_SRC = path.join(PKG_ROOT, ".claude", "hooks");
+const PATTERN_SRC = path.join(PKG_ROOT, ".claude", "patterns");
+const RULES_SRC = path.join(PKG_ROOT, ".claude", "rules");
+
+/**
+ * Recursively copy a directory.
+ * @param {string} src
+ * @param {string} dest
+ */
+function copyDir(src, dest) {
+  if (!fs.existsSync(src)) return;
+  fs.mkdirSync(dest, { recursive: true });
+
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+/**
+ * Main init command.
+ * @param {string} profile
+ */
+function init(profile) {
+  const targetDir = process.cwd();
+  const claudeDir = path.join(targetDir, ".claude");
+  const shieldHarnessDir = path.join(targetDir, ".shield-harness");
+
+  // Check if already initialized
+  if (fs.existsSync(path.join(claudeDir, "hooks", "sh-gate.js"))) {
+    console.error("Shield Harness is already initialized in this directory.");
+    console.error("To re-initialize, remove .claude/hooks/sh-*.js first.");
+    process.exit(1);
+  }
+
+  console.log(`Initializing Shield Harness (profile: ${profile})...`);
+
+  // Copy hooks
+  copyDir(HOOK_SRC, path.join(claudeDir, "hooks"));
+  console.log("  [OK] hooks/");
+
+  // Copy patterns
+  copyDir(PATTERN_SRC, path.join(claudeDir, "patterns"));
+  console.log("  [OK] patterns/");
+
+  // Copy rules
+  copyDir(RULES_SRC, path.join(claudeDir, "rules"));
+  console.log("  [OK] rules/");
+
+  // Create .shield-harness runtime directories
+  fs.mkdirSync(path.join(shieldHarnessDir, "config"), { recursive: true });
+  fs.mkdirSync(path.join(shieldHarnessDir, "logs"), { recursive: true });
+  fs.mkdirSync(path.join(shieldHarnessDir, "state"), { recursive: true });
+  console.log("  [OK] .shield-harness/");
+
+  // Create default pipeline config
+  const pipelineConfig = {
+    auto_commit: false,
+    auto_push: false,
+    auto_pr: false,
+    auto_merge: false,
+    auto_branch_cleanup: false,
+    commit_message_format: "[{task_id}] STG{gate}: {intent}",
+    pr_template: ".github/pull_request_template.md",
+    protected_branches: ["main", "master"],
+    approval_free: profile !== "strict",
+    sync_views_on_commit: true,
+    sync_views_on_session_start: true,
+    auto_tag: false,
+    version_bump: "patch",
+    auto_pickup_next_task: false,
+    auto_skip_blocked: false,
+    blocked_notification_channel: null,
+  };
+
+  const configPath = path.join(
+    shieldHarnessDir,
+    "config",
+    "pipeline-config.json",
+  );
+  if (!fs.existsSync(configPath)) {
+    fs.writeFileSync(
+      configPath,
+      JSON.stringify(pipelineConfig, null, 2) + "\n",
+    );
+    console.log("  [OK] pipeline-config.json");
+  }
+
+  console.log("");
+  console.log(`Shield Harness initialized successfully (profile: ${profile}).`);
+  console.log("Run 'claude' to start a secured session.");
+
+  // OpenShell setup guide (Layer 3b)
+  printOpenShellGuide();
+}
+
+/**
+ * Detect OpenShell status and print a setup guide.
+ * fail-safe: never throws, prints basic guide on any error.
+ */
+function printOpenShellGuide() {
+  console.log("");
+  console.log("─── OpenShell Setup (Layer 3b: Sandbox Isolation) ───");
+  console.log("");
+
+  let status;
+  try {
+    const {
+      detectOpenShell,
+    } = require("../.claude/hooks/lib/openshell-detect");
+    status = detectOpenShell();
+  } catch {
+    // Detection library not available — show basic guide
+    printBasicGuide();
+    return;
+  }
+
+  if (status.available) {
+    // OpenShell is running
+    console.log("  [OK] OpenShell detected and running");
+    console.log(`       Version: ${status.version || "unknown"}`);
+    if (status.update_available && status.latest_version) {
+      console.log(
+        `       Update available: ${status.version} -> ${status.latest_version}`,
+      );
+      console.log("       Run: openshell update");
+    }
+    console.log("");
+    console.log("  Layer 3b sandbox isolation is active.");
+    return;
+  }
+
+  // Not fully available — guide based on what's missing
+  switch (status.reason) {
+    case "docker_not_found":
+      console.log("  [1/3] Install Docker Desktop:");
+      console.log("        https://www.docker.com/products/docker-desktop/");
+      console.log("");
+      console.log("  [2/3] Install NVIDIA OpenShell:");
+      console.log("        https://github.com/NVIDIA/OpenShell");
+      console.log("        pip install openshell");
+      console.log("");
+      console.log("  [3/3] Start a sandbox:");
+      console.log("        openshell sandbox start");
+      break;
+
+    case "openshell_not_installed":
+      console.log("  [OK] Docker detected");
+      console.log("");
+      console.log("  [1/2] Install NVIDIA OpenShell:");
+      console.log("        https://github.com/NVIDIA/OpenShell");
+      console.log("        pip install openshell");
+      console.log("");
+      console.log("  [2/2] Start a sandbox:");
+      console.log("        openshell sandbox start");
+      break;
+
+    case "container_not_running":
+      console.log("  [OK] Docker detected");
+      console.log(`  [OK] OpenShell installed (v${status.version || "?"})`);
+      if (status.update_available && status.latest_version) {
+        console.log(
+          `       Update available: ${status.version} -> ${status.latest_version}`,
+        );
+      }
+      console.log("");
+      console.log("  [1/1] Start the sandbox:");
+      console.log("        openshell sandbox start");
+      break;
+
+    default:
+      printBasicGuide();
+      return;
+  }
+
+  console.log("");
+  console.log("  OpenShell adds container-level isolation to Shield Harness,");
+  console.log("  limiting blast radius even if a hook bypass is found.");
+}
+
+/**
+ * Fallback: print basic setup guide without detection.
+ */
+function printBasicGuide() {
+  console.log("  For enhanced security, set up NVIDIA OpenShell:");
+  console.log("  https://github.com/NVIDIA/OpenShell");
+  console.log("");
+  console.log("  Setup steps:");
+  console.log("    1. Install Docker Desktop");
+  console.log("    2. pip install openshell");
+  console.log("    3. openshell sandbox start");
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+if (command === "init") {
+  let profile = DEFAULT_PROFILE;
+  const profileIdx = args.indexOf("--profile");
+  if (profileIdx !== -1 && args[profileIdx + 1]) {
+    profile = args[profileIdx + 1];
+    if (!PROFILES.includes(profile)) {
+      console.error(`Unknown profile: ${profile}`);
+      console.error(`Available profiles: ${PROFILES.join(", ")}`);
+      process.exit(1);
+    }
+  }
+  init(profile);
+} 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("");
+  console.log("Profiles:");
+  console.log("  minimal   — Minimal config, approval-free");
+  console.log("  standard  — Recommended (default), approval-free");
+  console.log("  strict    — Strict config, requires human approval");
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "shield-harness",
+  "version": "0.1.0",
+  "description": "Security harness for Claude Code — hooks-driven, zero-hassle defense",
+  "bin": {
+    "shield-harness": "./bin/shield-harness.js"
+  },
+  "files": [
+    ".claude/hooks/",
+    ".claude/patterns/",
+    ".claude/policies/",
+    ".claude/rules/",
+    "bin/"
+  ],
+  "scripts": {
+    "test": "node --test tests/*.test.js",
+    "test:evidence": "node --test tests/evidence-integrity.test.js",
+    "test:gate": "node --test tests/gate-evasion.test.js",
+    "test:injection": "node --test tests/injection-evasion.test.js",
+    "test:config": "node --test tests/config-guard-evasion.test.js",
+    "test:boundary": "node --test tests/data-boundary-evasion.test.js",
+    "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"
+  },
+  "keywords": [
+    "claude-code",
+    "security",
+    "hooks",
+    "harness",
+    "ai-safety"
+  ],
+  "author": "Sora",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Sora-bluesky/shield-harness.git"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}