shield-harness 0.3.0 → 0.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude/hooks/lib/automode-detect.js +184 -0
- package/.claude/hooks/lib/policy-drift.js +322 -0
- package/.claude/hooks/sh-config-guard.js +184 -2
- package/.claude/hooks/sh-session-start.js +83 -0
- package/.claude/permissions-spec.json +16 -1
- package/.claude/policies/openshell-generated.yaml +105 -0
- package/README.ja.md +98 -33
- package/README.md +97 -32
- package/package.json +5 -2
package/README.md
CHANGED
|
@@ -2,9 +2,9 @@
|
|
|
2
2
|
|
|
3
3
|
# Shield Harness
|
|
4
4
|
|
|
5
|
-
**
|
|
5
|
+
**Hook-driven auto-defense security harness for Claude Code**
|
|
6
6
|
|
|
7
|
-
> **
|
|
7
|
+
> **v0.5.0**: 22 hooks, 4-layer defense (L1 Permissions + L2 Hooks + L3 Sandbox + L3b OpenShell), 426 tests including 108 OWASP AITG attack simulations + 35 Auto Mode defense tests.
|
|
8
8
|
|
|
9
9
|
[](#)
|
|
10
10
|
[](README.ja.md)
|
|
@@ -25,13 +25,13 @@ npx shield-harness init [--profile minimal|standard|strict]
|
|
|
25
25
|
## Why Shield Harness
|
|
26
26
|
|
|
27
27
|
- **Hooks-driven defense**: 22 security hooks monitor every Claude Code operation
|
|
28
|
-
- **
|
|
28
|
+
- **Automated security decisions**: Hooks handle all security judgments in real time — no manual approval bottleneck
|
|
29
29
|
- **fail-close principle**: Automatically stops when safety conditions cannot be verified
|
|
30
30
|
- **Evidence recording**: Tamper-proof SHA-256 hash chain records all allow/deny decisions
|
|
31
31
|
|
|
32
32
|
## Architecture Overview
|
|
33
33
|
|
|
34
|
-
|
|
34
|
+
4-layer defense model:
|
|
35
35
|
|
|
36
36
|
| Layer | Defense | Implementation |
|
|
37
37
|
| -------- | ------------------ | -------------------------------------------------- |
|
|
@@ -50,30 +50,30 @@ npx shield-harness init [--profile minimal|standard|strict]
|
|
|
50
50
|
|
|
51
51
|
## Hook Catalog
|
|
52
52
|
|
|
53
|
-
| # | Hook | Event | Responsibility
|
|
54
|
-
| --- | ---------------- | --------------------- |
|
|
55
|
-
| 1 | permission | PreToolUse | 4-category tool usage classification
|
|
56
|
-
| 2 | gate | PreToolUse | 7 attack vector inspection for Bash commands
|
|
57
|
-
| 3 | injection-guard | PreToolUse | 9-category 50+ pattern injection detection
|
|
58
|
-
| 4 | data-boundary | PreToolUse | Production data boundary + jurisdiction tracking
|
|
59
|
-
| 5 | quiet-inject | PreToolUse | Auto-inject quiet flags
|
|
60
|
-
| 6 | evidence | PostToolUse | SHA-256 hash chain evidence
|
|
61
|
-
| 7 | output-control | PostToolUse | Output truncation + token budget
|
|
62
|
-
| 8 | dep-audit | PostToolUse | Package install detection
|
|
63
|
-
| 9 | lint-on-save | PostToolUse | Auto lint execution
|
|
64
|
-
| 10 | session-start | SessionStart | Session init + integrity baseline
|
|
65
|
-
| 11 | session-end | SessionEnd | Cleanup + statistics
|
|
66
|
-
| 12 | circuit-breaker | Stop | Retry limit (3 attempts)
|
|
67
|
-
| 13 | config-guard | ConfigChange | Settings change monitoring
|
|
68
|
-
| 14 | user-prompt | UserPromptSubmit | User input injection scanning
|
|
69
|
-
| 15 | permission-learn | PermissionRequest | Permission learning guard
|
|
70
|
-
| 16 | elicitation | Elicitation | Phishing + scope guard
|
|
71
|
-
| 17 | subagent | SubagentStart | Subagent budget constraint (25%)
|
|
72
|
-
| 18 | instructions | InstructionsLoaded | Rule file integrity monitoring
|
|
73
|
-
| 19 | precompact | PreCompact | Pre-compaction backup
|
|
74
|
-
| 20 | postcompact | PostCompact | Post-compaction restore + verify
|
|
75
|
-
| 21 | worktree | WorktreeCreate/Remove | Security propagation + evidence merge
|
|
76
|
-
| 22 | task-gate | TaskCompleted | Test gate
|
|
53
|
+
| # | Hook | Event | Responsibility |
|
|
54
|
+
| --- | ---------------- | --------------------- | ------------------------------------------------------------------------------------ |
|
|
55
|
+
| 1 | permission | PreToolUse | 4-category tool usage classification |
|
|
56
|
+
| 2 | gate | PreToolUse | 7 attack vector inspection for Bash commands |
|
|
57
|
+
| 3 | injection-guard | PreToolUse | 9-category 50+ pattern injection detection |
|
|
58
|
+
| 4 | data-boundary | PreToolUse | Production data boundary + jurisdiction tracking |
|
|
59
|
+
| 5 | quiet-inject | PreToolUse | Auto-inject quiet flags |
|
|
60
|
+
| 6 | evidence | PostToolUse | SHA-256 hash chain evidence |
|
|
61
|
+
| 7 | output-control | PostToolUse | Output truncation + token budget |
|
|
62
|
+
| 8 | dep-audit | PostToolUse | Package install detection |
|
|
63
|
+
| 9 | lint-on-save | PostToolUse | Auto lint execution |
|
|
64
|
+
| 10 | session-start | SessionStart | Session init + integrity baseline |
|
|
65
|
+
| 11 | session-end | SessionEnd | Cleanup + statistics |
|
|
66
|
+
| 12 | circuit-breaker | Stop | Retry limit (3 attempts) |
|
|
67
|
+
| 13 | config-guard | ConfigChange | Settings change monitoring + OpenShell policy file protection + Auto Mode protection |
|
|
68
|
+
| 14 | user-prompt | UserPromptSubmit | User input injection scanning |
|
|
69
|
+
| 15 | permission-learn | PermissionRequest | Permission learning guard |
|
|
70
|
+
| 16 | elicitation | Elicitation | Phishing + scope guard |
|
|
71
|
+
| 17 | subagent | SubagentStart | Subagent budget constraint (25%) |
|
|
72
|
+
| 18 | instructions | InstructionsLoaded | Rule file integrity monitoring |
|
|
73
|
+
| 19 | precompact | PreCompact | Pre-compaction backup |
|
|
74
|
+
| 20 | postcompact | PostCompact | Post-compaction restore + verify |
|
|
75
|
+
| 21 | worktree | WorktreeCreate/Remove | Security propagation + evidence merge |
|
|
76
|
+
| 22 | task-gate | TaskCompleted | Test gate |
|
|
77
77
|
|
|
78
78
|
## Pipeline
|
|
79
79
|
|
|
@@ -146,10 +146,75 @@ Key benefits for Windows users:
|
|
|
146
146
|
|
|
147
147
|
- Policies exist **outside** the agent process — the agent cannot disable its own guardrails
|
|
148
148
|
- Runs on Docker Desktop + WSL2 backend (typical Windows dev setup)
|
|
149
|
-
-
|
|
149
|
+
- Significantly reduces residual risk from Layer 1-2 pattern matching limitations
|
|
150
150
|
- Freely removable — stop the container and Shield Harness falls back to Layer 1-2
|
|
151
151
|
|
|
152
|
-
> **Note**: OpenShell is Alpha (v0.0.13) — APIs may change with future releases.
|
|
152
|
+
> **Note**: OpenShell is Alpha (v0.0.13) — APIs may change with future releases. Shield Harness GA Phase integration is complete (ADR-037): config guard policy file protection, policy drift check, and full documentation are ready.
|
|
153
|
+
|
|
154
|
+
#### Setup
|
|
155
|
+
|
|
156
|
+
**Prerequisites**: [Docker Desktop](https://www.docker.com/products/docker-desktop/) (WSL2 backend on Windows)
|
|
157
|
+
|
|
158
|
+
```bash
|
|
159
|
+
# 1. Install Docker Desktop and verify it is running
|
|
160
|
+
# https://www.docker.com/products/docker-desktop/
|
|
161
|
+
docker --version
|
|
162
|
+
|
|
163
|
+
# 2. Install OpenShell CLI
|
|
164
|
+
pip install openshell
|
|
165
|
+
|
|
166
|
+
# 3. Generate policy from permissions-spec.json
|
|
167
|
+
# Creates .claude/policies/openshell-generated.yaml
|
|
168
|
+
npx shield-harness policy generate
|
|
169
|
+
|
|
170
|
+
# 4. Start OpenShell container and run Claude Code inside it
|
|
171
|
+
# Docker pulls the sandbox image automatically on first run
|
|
172
|
+
# Kernel-level enforcement (Landlock/Seccomp/Network NS) is active inside the container
|
|
173
|
+
openshell run --policy .claude/policies/openshell-generated.yaml
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
Claude Code running inside the OpenShell container automatically receives Layer 3b kernel enforcement. Shield Harness detects this at session start (`sh-session-start.js`) — no additional configuration required.
|
|
177
|
+
|
|
178
|
+
Without OpenShell, Shield Harness falls back to Layer 1-2 defense (no degradation in hook protection).
|
|
179
|
+
|
|
180
|
+
Policy files are protected by:
|
|
181
|
+
|
|
182
|
+
- `permissions.deny`: `Edit/Write(.claude/policies/**)` blocks agent modification
|
|
183
|
+
- `sandbox.denyWrite`: `.claude/policies` in filesystem deny list
|
|
184
|
+
- `sh-config-guard.js`: Hash tracking detects policy file tampering or weakening
|
|
185
|
+
- `sh-session-start.js`: Drift check at session start verifies spec-policy alignment
|
|
186
|
+
|
|
187
|
+
## Testing
|
|
188
|
+
|
|
189
|
+
```bash
|
|
190
|
+
# Run all tests (426 tests including attack simulations)
|
|
191
|
+
npm test
|
|
192
|
+
|
|
193
|
+
# Run attack simulation tests only
|
|
194
|
+
node --test tests/attack-sim-*.test.js
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
| Test Suite | Category | Tests |
|
|
198
|
+
| ----------------------------- | -------------------------------------- | ----- |
|
|
199
|
+
| attack-sim-prompt-injection | AITG-APP-01: Direct Prompt Injection | 25 |
|
|
200
|
+
| attack-sim-indirect-injection | AITG-APP-02: Indirect Prompt Injection | 18 |
|
|
201
|
+
| attack-sim-data-leak | AITG-APP-03: Sensitive Data Leak | 20 |
|
|
202
|
+
| attack-sim-agentic-limits | AITG-APP-06: Agentic Behavior Limits | 18 |
|
|
203
|
+
| attack-sim-sandbox-escape | NVIDIA 3-axis: Sandbox Escape | 15 |
|
|
204
|
+
| attack-sim-defense-chain | SAIF: Defense-in-depth Chain | 12 |
|
|
205
|
+
| attack-sim-automode-bypass | Auto Mode: soft_deny/soft_allow bypass | 15 |
|
|
206
|
+
|
|
207
|
+
## Auto Mode Awareness (v0.5.0)
|
|
208
|
+
|
|
209
|
+
Shield Harness detects Claude Code's Auto Mode (Research Preview) configuration at session start and protects against dangerous settings:
|
|
210
|
+
|
|
211
|
+
| Setting | Risk | Shield Harness Response |
|
|
212
|
+
| ---------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------- |
|
|
213
|
+
| `autoMode.soft_deny` | **CRITICAL** — disables all classifier default protections | Config-guard blocks addition; session-start outputs CRITICAL warning |
|
|
214
|
+
| `autoMode.soft_allow` | WARN — auto-approves specific tools | Config-guard blocks expansion; session-start outputs WARNING |
|
|
215
|
+
| `autoMode.environment` | Safe — informational only | Detected and recorded in session |
|
|
216
|
+
|
|
217
|
+
All existing hooks (PreToolUse, PostToolUse) fire normally under Auto Mode — `permissions.deny` rules remain absolute. Auto Mode's classifier cannot override hook denials.
|
|
153
218
|
|
|
154
219
|
## Channel Integration
|
|
155
220
|
|
|
@@ -178,11 +243,11 @@ Shield Harness follows [Semantic Versioning](https://semver.org/):
|
|
|
178
243
|
| `minor` | New features (backward compatible), Phase must-tasks completed | OCSF support, new hook, CLI option |
|
|
179
244
|
| `major` | Breaking changes | Schema incompatible, settings change |
|
|
180
245
|
|
|
181
|
-
**Release trigger**: `git tag
|
|
246
|
+
**Release trigger**: `git tag vX.Y.Z && git push origin vX.Y.Z` triggers `release.yml` (automated npm publish + GitHub Release). Security fixes trigger an immediate patch release.
|
|
182
247
|
|
|
183
248
|
## References
|
|
184
249
|
|
|
185
|
-
|
|
250
|
+
Key references:
|
|
186
251
|
|
|
187
252
|
| Project | Influence |
|
|
188
253
|
| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "shield-harness",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.5.0",
|
|
4
4
|
"description": "Security harness for Claude Code — hooks-driven, zero-hassle defense",
|
|
5
5
|
"bin": {
|
|
6
6
|
"shield-harness": "./bin/shield-harness.js"
|
|
@@ -27,7 +27,10 @@
|
|
|
27
27
|
"test:openshell-detect": "node --test tests/openshell-detect.test.js",
|
|
28
28
|
"test:openshell-evidence": "node --test tests/openshell-evidence.test.js",
|
|
29
29
|
"test:tier-policy": "node --test tests/tier-policy-gen.test.js",
|
|
30
|
-
"test:policy-effectiveness": "node --test tests/policy-effectiveness.test.js"
|
|
30
|
+
"test:policy-effectiveness": "node --test tests/policy-effectiveness.test.js",
|
|
31
|
+
"test:automode": "node --test tests/automode-detect.test.js",
|
|
32
|
+
"test:automode-guard": "node --test tests/config-guard-automode.test.js",
|
|
33
|
+
"test:attack-automode": "node --test tests/attack-sim-automode-bypass.test.js"
|
|
31
34
|
},
|
|
32
35
|
"keywords": [
|
|
33
36
|
"claude-code",
|