shield-harness 0.1.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/ocsf-mapper.js +279 -0
- package/.claude/hooks/lib/openshell-detect.js +235 -0
- package/.claude/hooks/lib/policy-compat.js +176 -0
- package/.claude/hooks/lib/session-modules/.gitkeep +0 -0
- package/.claude/hooks/lib/sh-utils.js +340 -0
- package/.claude/hooks/lint-on-save.js +240 -0
- package/.claude/hooks/sh-circuit-breaker.js +113 -0
- package/.claude/hooks/sh-config-guard.js +275 -0
- package/.claude/hooks/sh-data-boundary.js +390 -0
- package/.claude/hooks/sh-dep-audit.js +101 -0
- package/.claude/hooks/sh-elicitation.js +244 -0
- package/.claude/hooks/sh-evidence.js +193 -0
- package/.claude/hooks/sh-gate.js +365 -0
- package/.claude/hooks/sh-injection-guard.js +196 -0
- package/.claude/hooks/sh-instructions.js +212 -0
- package/.claude/hooks/sh-output-control.js +217 -0
- package/.claude/hooks/sh-permission-learn.js +227 -0
- package/.claude/hooks/sh-permission.js +157 -0
- package/.claude/hooks/sh-pipeline.js +623 -0
- package/.claude/hooks/sh-postcompact.js +173 -0
- package/.claude/hooks/sh-precompact.js +114 -0
- package/.claude/hooks/sh-quiet-inject.js +148 -0
- package/.claude/hooks/sh-session-end.js +143 -0
- package/.claude/hooks/sh-session-start.js +277 -0
- package/.claude/hooks/sh-subagent.js +86 -0
- package/.claude/hooks/sh-task-gate.js +141 -0
- package/.claude/hooks/sh-user-prompt.js +185 -0
- package/.claude/hooks/sh-worktree.js +230 -0
- package/.claude/patterns/injection-patterns.json +137 -0
- package/.claude/policies/openshell-default.yaml +65 -0
- package/.claude/rules/binding-governance.md +62 -0
- package/.claude/rules/channel-security.md +90 -0
- package/.claude/rules/coding-principles.md +79 -0
- package/.claude/rules/dev-environment.md +40 -0
- package/.claude/rules/implementation-context.md +132 -0
- package/.claude/rules/language.md +26 -0
- package/.claude/rules/security.md +109 -0
- package/.claude/rules/testing.md +43 -0
- package/LICENSE +21 -0
- package/README.ja.md +176 -0
- package/README.md +174 -0
- package/bin/shield-harness.js +241 -0
- package/package.json +42 -0
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
# Development Environment
|
|
2
|
+
|
|
3
|
+
## Script Execution
|
|
4
|
+
|
|
5
|
+
- **PowerShell 7** (`pwsh`) for all automation scripts
|
|
6
|
+
- Scripts are located in `scripts/` directory
|
|
7
|
+
|
|
8
|
+
## Pre-commit Security
|
|
9
|
+
|
|
10
|
+
- Git hooks in `.githooks/` (pre-commit)
|
|
11
|
+
- Pre-commit hook blocks internal files (tasks/, scripts/, HANDOFF, INSTRUCTIONS) from being committed
|
|
12
|
+
- Configured via `git config core.hooksPath .githooks`
|
|
13
|
+
|
|
14
|
+
## Linting (Future)
|
|
15
|
+
|
|
16
|
+
- PowerShell: PSScriptAnalyzer (`Invoke-ScriptAnalyzer`)
|
|
17
|
+
- Markdown: markdownlint (optional)
|
|
18
|
+
- Currently: manual review + git-guard-scan
|
|
19
|
+
|
|
20
|
+
## Testing (Future)
|
|
21
|
+
|
|
22
|
+
- PowerShell: Pester 5.0+ (`Invoke-Pester -Verbose`)
|
|
23
|
+
- Currently: manual verification + git-guard checks
|
|
24
|
+
|
|
25
|
+
## Task Management
|
|
26
|
+
|
|
27
|
+
- **SoT**: `tasks/backlog.yaml`
|
|
28
|
+
|
|
29
|
+
## Important Commands
|
|
30
|
+
|
|
31
|
+
```powershell
|
|
32
|
+
# Sync project views (backlog → docs/project/)
|
|
33
|
+
pwsh ./scripts/sync-project-views.ps1
|
|
34
|
+
|
|
35
|
+
# Sync bilingual README
|
|
36
|
+
pwsh ./scripts/sync-readme.ps1
|
|
37
|
+
|
|
38
|
+
# Pre-commit hook (manual run)
|
|
39
|
+
bash .githooks/pre-commit
|
|
40
|
+
```
|
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
# Shield Harness Implementation Context
|
|
2
|
+
|
|
3
|
+
> Shield Harness = Claude Code の `.claude/` ディレクトリ構造によるセキュリティハーネス(hooks + rules + skills + settings.json)
|
|
4
|
+
|
|
5
|
+
## Design Documents(実装時に必ず参照)
|
|
6
|
+
|
|
7
|
+
| # | ドキュメント | 層 | パス | 用途 |
|
|
8
|
+
| --- | ------------------ | --------- | -------------------------------------------------- | ---------------------------------------- |
|
|
9
|
+
| ① | REQUIREMENTS.md | Why | docs/REQUIREMENTS.md | 機能要件・受入基準 |
|
|
10
|
+
| ② | THREAT_MODEL.md | Why→What | docs/THREAT_MODEL.md | 脅威 ID・攻撃ベクトル |
|
|
11
|
+
| ③ | ARCHITECTURE.md | What | docs/ARCHITECTURE.md | 22 フック一覧・ディレクトリ構造 |
|
|
12
|
+
| ④ | CLAUDE_MD_SPEC.md | What | docs/CLAUDE_MD_SPEC.md | 28 ルール仕様・トレーサビリティ |
|
|
13
|
+
| ⑤ | DETAILED_DESIGN.md | How | docs/DETAILED_DESIGN.md | 各フックの入出力・正規表現・分岐ロジック |
|
|
14
|
+
| ADR | ADR 設計提案 | Reference | .reference/SHIELD_HARNESS_ADR_REDESIGN_PROPOSAL.md | 35 ADR の設計判断根拠 |
|
|
15
|
+
|
|
16
|
+
## Implementation Order(依存関係グラフに基づく)
|
|
17
|
+
|
|
18
|
+
```
|
|
19
|
+
Phase A(基盤 — 最初に実装):
|
|
20
|
+
ADR-033: backlog.yaml スキーマ + sync-project-views.ps1
|
|
21
|
+
↓ 他 ADR の前提
|
|
22
|
+
|
|
23
|
+
Phase B(パイプライン):
|
|
24
|
+
ADR-031: sh-pipeline.js(STG ゲート駆動)
|
|
25
|
+
ADR-032: 承認レスモード(approval_free) ← 並列可
|
|
26
|
+
ADR-035: バイリンガル README + sync-readme.ps1 ← 並列可
|
|
27
|
+
↓
|
|
28
|
+
|
|
29
|
+
Phase C(自律ループ):
|
|
30
|
+
ADR-034: auto-pickup + チャンネル連携 + ブロック通知
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
## Technical Constraints
|
|
34
|
+
|
|
35
|
+
- **Hook language**: Node.js CommonJS(ミリ秒応答必須)。共通ユーティリティは lib/sh-utils.js
|
|
36
|
+
- **Hook protocol**: exit 0 = allow, exit 2 = deny(stdout に JSON)。deny() は sh-utils.js 経由
|
|
37
|
+
- **Target**: 23 hook scripts (22 sh-\* + lint-on-save) + lib/sh-utils.js + injection-patterns.json
|
|
38
|
+
- **External deps**: node 18+ (CommonJS hooks), pwsh (sync scripts, bash fallback あり), gh (optional)
|
|
39
|
+
- **OS**: Windows ネイティブファースト(Git Bash 環境)。WSL2/Linux 互換
|
|
40
|
+
- **Trusted Operation**: pipeline の git 操作は bash 子プロセスとして直接実行(フックエンジン非経由)
|
|
41
|
+
- **fail-close**: 安全条件を確認できない場合は exit 2 で停止
|
|
42
|
+
|
|
43
|
+
## Directory Structure(生成対象の全量)
|
|
44
|
+
|
|
45
|
+
```
|
|
46
|
+
.claude/
|
|
47
|
+
├─ settings.json
|
|
48
|
+
├─ settings.local.json
|
|
49
|
+
├─ agents/
|
|
50
|
+
│ └─ general-purpose.md
|
|
51
|
+
├─ hooks/
|
|
52
|
+
│ ├─ sh-permission.js
|
|
53
|
+
│ ├─ sh-permission-learn.js
|
|
54
|
+
│ ├─ sh-gate.js
|
|
55
|
+
│ ├─ sh-injection-guard.js
|
|
56
|
+
│ ├─ sh-user-prompt.js
|
|
57
|
+
│ ├─ sh-evidence.js
|
|
58
|
+
│ ├─ sh-output-control.js
|
|
59
|
+
│ ├─ sh-quiet-inject.js
|
|
60
|
+
│ ├─ sh-circuit-breaker.js
|
|
61
|
+
│ ├─ sh-task-gate.js
|
|
62
|
+
│ ├─ sh-precompact.js
|
|
63
|
+
│ ├─ sh-postcompact.js
|
|
64
|
+
│ ├─ sh-instructions.js
|
|
65
|
+
│ ├─ sh-session-start.js
|
|
66
|
+
│ ├─ sh-session-end.js
|
|
67
|
+
│ ├─ sh-config-guard.js
|
|
68
|
+
│ ├─ sh-subagent.js
|
|
69
|
+
│ ├─ sh-dep-audit.js
|
|
70
|
+
│ ├─ sh-elicitation.js
|
|
71
|
+
│ ├─ sh-worktree.js
|
|
72
|
+
│ ├─ sh-data-boundary.js
|
|
73
|
+
│ ├─ sh-pipeline.js
|
|
74
|
+
│ ├─ lint-on-save.js
|
|
75
|
+
│ └─ lib/
|
|
76
|
+
│ └─ sh-utils.js
|
|
77
|
+
├─ patterns/
|
|
78
|
+
│ └─ injection-patterns.json
|
|
79
|
+
├─ rules/
|
|
80
|
+
│ ├─ binding-governance.md
|
|
81
|
+
│ ├─ channel-security.md
|
|
82
|
+
│ ├─ coding-principles.md
|
|
83
|
+
│ ├─ dev-environment.md
|
|
84
|
+
│ ├─ implementation-context.md
|
|
85
|
+
│ ├─ language.md
|
|
86
|
+
│ ├─ security.md
|
|
87
|
+
│ └─ testing.md
|
|
88
|
+
├─ skills/
|
|
89
|
+
│ ├─ checkpointing/
|
|
90
|
+
│ ├─ docs-sync/
|
|
91
|
+
│ ├─ handoff/
|
|
92
|
+
│ ├─ init/
|
|
93
|
+
│ ├─ plan/
|
|
94
|
+
│ ├─ simplify/
|
|
95
|
+
│ ├─ startproject/
|
|
96
|
+
│ ├─ tdd/
|
|
97
|
+
│ ├─ team-implement/
|
|
98
|
+
│ ├─ team-review/
|
|
99
|
+
│ └─ test-coverage-improver/
|
|
100
|
+
└─ logs/
|
|
101
|
+
├─ evidence-ledger.jsonl
|
|
102
|
+
└─ instructions-hashes.json
|
|
103
|
+
|
|
104
|
+
.shield-harness/
|
|
105
|
+
├─ session.json
|
|
106
|
+
├─ config/
|
|
107
|
+
│ └─ pipeline-config.json
|
|
108
|
+
└─ logs/
|
|
109
|
+
|
|
110
|
+
tasks/
|
|
111
|
+
└─ backlog.yaml
|
|
112
|
+
|
|
113
|
+
docs/project/
|
|
114
|
+
├─ ROADMAP.md
|
|
115
|
+
├─ WBS.md
|
|
116
|
+
├─ GANTT.md
|
|
117
|
+
└─ MILESTONES.md
|
|
118
|
+
|
|
119
|
+
scripts/
|
|
120
|
+
├─ sync-project-views.ps1
|
|
121
|
+
└─ sync-readme.ps1
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
## Coding Rules for Hook Scripts
|
|
125
|
+
|
|
126
|
+
- **DETAILED_DESIGN.md が唯一の実装仕様書** — 各フックの §番号を参照して実装すること
|
|
127
|
+
- deny() は stdout に JSON を出力 + exit 2(stderr ではない)
|
|
128
|
+
- NFKC 正規化: Node.js 不在時は fail-close(deny)
|
|
129
|
+
- Hash chain: flock ベースロック(Windows Git Bash では mkdir フォールバック)
|
|
130
|
+
- READONLY_PATTERNS から sed を除外(sed -i は書込操作)
|
|
131
|
+
- permissions.allow: standard プロファイルで 40 操作
|
|
132
|
+
- Circuit breaker: stop_hook_active フラグは allow 後にリセット
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
# Language Rules
|
|
2
|
+
|
|
3
|
+
## Thinking and Reasoning
|
|
4
|
+
|
|
5
|
+
- **Always think and reason in English**
|
|
6
|
+
- Internal analysis, planning, and problem-solving should be in English
|
|
7
|
+
- Code comments, variable names, function names, and docstrings should be in English
|
|
8
|
+
|
|
9
|
+
## User Communication
|
|
10
|
+
|
|
11
|
+
- **Always respond to users in Japanese**
|
|
12
|
+
- Explanations, questions, and status updates should be in Japanese
|
|
13
|
+
- Error messages shown to users should be in Japanese
|
|
14
|
+
|
|
15
|
+
## Code
|
|
16
|
+
|
|
17
|
+
- All code should be written in English:
|
|
18
|
+
- Variable names: `user_count`, not `ユーザー数`
|
|
19
|
+
- Function names: `calculate_total()`, not `合計計算()`
|
|
20
|
+
- Comments: `# Check if valid`, not `# 有効かチェック`
|
|
21
|
+
- Docstrings: English descriptions
|
|
22
|
+
|
|
23
|
+
## Documentation
|
|
24
|
+
|
|
25
|
+
- Technical documentation: English
|
|
26
|
+
- User-facing documentation (README, etc.): Japanese is acceptable
|
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
# Security Rules
|
|
2
|
+
|
|
3
|
+
Security checklist to always verify when writing code.
|
|
4
|
+
|
|
5
|
+
## Secrets Management
|
|
6
|
+
|
|
7
|
+
### Never Do
|
|
8
|
+
|
|
9
|
+
- Hardcode API keys or passwords
|
|
10
|
+
- Log sensitive information
|
|
11
|
+
- Commit `.env` files
|
|
12
|
+
|
|
13
|
+
### Required
|
|
14
|
+
|
|
15
|
+
```python
|
|
16
|
+
# Good: Get from environment variables
|
|
17
|
+
import os
|
|
18
|
+
API_KEY = os.environ["API_KEY"]
|
|
19
|
+
|
|
20
|
+
# Good: With existence check
|
|
21
|
+
API_KEY = os.environ.get("API_KEY")
|
|
22
|
+
if not API_KEY:
|
|
23
|
+
raise ValueError("API_KEY environment variable is required")
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
## Input Validation
|
|
27
|
+
|
|
28
|
+
Always validate external input:
|
|
29
|
+
|
|
30
|
+
```python
|
|
31
|
+
from pydantic import BaseModel, EmailStr, Field
|
|
32
|
+
|
|
33
|
+
class UserInput(BaseModel):
|
|
34
|
+
email: EmailStr
|
|
35
|
+
age: int = Field(ge=0, le=150)
|
|
36
|
+
name: str = Field(min_length=1, max_length=100)
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
## SQL Injection Prevention
|
|
40
|
+
|
|
41
|
+
```python
|
|
42
|
+
# Bad: String concatenation
|
|
43
|
+
cursor.execute(f"SELECT * FROM users WHERE id = {user_id}")
|
|
44
|
+
|
|
45
|
+
# Good: Parameterized query
|
|
46
|
+
cursor.execute("SELECT * FROM users WHERE id = ?", (user_id,))
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
## XSS Prevention
|
|
50
|
+
|
|
51
|
+
- Escape user input before embedding in HTML
|
|
52
|
+
- Enable template engine auto-escaping
|
|
53
|
+
|
|
54
|
+
## Error Messages
|
|
55
|
+
|
|
56
|
+
```python
|
|
57
|
+
# Bad: Too detailed (gives attackers information)
|
|
58
|
+
raise Exception(f"Database connection failed: {connection_string}")
|
|
59
|
+
|
|
60
|
+
# Good: Minimal information
|
|
61
|
+
raise Exception("Database connection failed")
|
|
62
|
+
# Details go to logs (logs are private)
|
|
63
|
+
logger.error(f"Database connection failed: {connection_string}")
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
## Dependencies
|
|
67
|
+
|
|
68
|
+
- Regular vulnerability checks: `pip-audit`, `safety`
|
|
69
|
+
- Remove unused dependencies
|
|
70
|
+
- Pin versions (`==` over `>=`)
|
|
71
|
+
|
|
72
|
+
## Code Review Checklist
|
|
73
|
+
|
|
74
|
+
- [ ] No hardcoded secrets
|
|
75
|
+
- [ ] External input is validated
|
|
76
|
+
- [ ] SQL queries are parameterized
|
|
77
|
+
- [ ] Error messages are not too detailed
|
|
78
|
+
- [ ] Logs don't contain sensitive information
|
|
79
|
+
|
|
80
|
+
## Git Operations Safety
|
|
81
|
+
|
|
82
|
+
git rm --cached is a prohibited operation.
|
|
83
|
+
Locally it appears to only remove files from the index,
|
|
84
|
+
but after committing, it propagates as physical deletion
|
|
85
|
+
when others pull/merge from the remote.
|
|
86
|
+
|
|
87
|
+
Prohibited commands:
|
|
88
|
+
|
|
89
|
+
- git rm --cached (single files or directories)
|
|
90
|
+
- git rm -r --cached (recursive untrack)
|
|
91
|
+
|
|
92
|
+
When managing files that should not be tracked via .gitignore,
|
|
93
|
+
the principle is to never commit them in the first place.
|
|
94
|
+
Simply adding an already-committed file to .gitignore does not
|
|
95
|
+
remove it from tracking, which tempts the use of git rm --cached,
|
|
96
|
+
but it is prohibited for the reasons stated above.
|
|
97
|
+
|
|
98
|
+
Alternative: When you need to remove already-committed files from tracking,
|
|
99
|
+
consult the human (project owner) and determine the approach
|
|
100
|
+
after confirming the impact scope.
|
|
101
|
+
|
|
102
|
+
## Line Ending Management
|
|
103
|
+
|
|
104
|
+
Line ending normalization is managed by `.gitattributes` only.
|
|
105
|
+
Do not set `core.autocrlf=true` in this repository.
|
|
106
|
+
|
|
107
|
+
When restoring files from old commits (`git checkout <commit> -- <path>`),
|
|
108
|
+
always run `git add --renormalize .` afterward to re-apply `.gitattributes` rules.
|
|
109
|
+
Otherwise, phantom diffs will appear in `git status` due to EOL mismatch.
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
# Testing Rules
|
|
2
|
+
|
|
3
|
+
## Principles (Language-Agnostic)
|
|
4
|
+
|
|
5
|
+
- **TDD when possible**: Write tests before implementation (Red-Green-Refactor)
|
|
6
|
+
- **AAA Pattern**: Arrange / Act / Assert
|
|
7
|
+
- **Naming**: `test_{subject}_{condition}_{expected_result}`
|
|
8
|
+
- **Coverage target**: 80%+ for source code
|
|
9
|
+
|
|
10
|
+
## Test Categories
|
|
11
|
+
|
|
12
|
+
1. **Happy path**: Normal input, expected output
|
|
13
|
+
2. **Boundary values**: Min, max, empty, zero
|
|
14
|
+
3. **Error cases**: Invalid input, error conditions
|
|
15
|
+
4. **Edge cases**: Null, empty string, special characters
|
|
16
|
+
|
|
17
|
+
## PowerShell Testing (Pester)
|
|
18
|
+
|
|
19
|
+
When Pester is available:
|
|
20
|
+
|
|
21
|
+
```powershell
|
|
22
|
+
# Run tests
|
|
23
|
+
Invoke-Pester -Verbose
|
|
24
|
+
|
|
25
|
+
# Run with coverage
|
|
26
|
+
Invoke-Pester -CodeCoverage ./scripts/*.ps1
|
|
27
|
+
|
|
28
|
+
# Test file naming: {Module}.Tests.ps1
|
|
29
|
+
# Test structure: Describe / Context / It
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
## Current Testing Approach
|
|
33
|
+
|
|
34
|
+
Until a formal test framework is adopted:
|
|
35
|
+
|
|
36
|
+
- **Git guard**: Pre-commit hooks catch secrets and sensitive data
|
|
37
|
+
- **Manual verification**: Review output before committing
|
|
38
|
+
|
|
39
|
+
## Mocking
|
|
40
|
+
|
|
41
|
+
- Isolate external dependencies (file I/O, network, CLI tools)
|
|
42
|
+
- Use `unittest.mock` (Python hooks) or Pester `Mock` (PowerShell)
|
|
43
|
+
- Test fixtures in dedicated `tests/` directory when available
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 sora
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.ja.md
ADDED
|
@@ -0,0 +1,176 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
3
|
+
# Shield Harness
|
|
4
|
+
|
|
5
|
+
**Claude Code の全操作を自動防御するセキュリティハーネス**
|
|
6
|
+
|
|
7
|
+
> 承認ダイアログなしで安全な自律開発を実現
|
|
8
|
+
|
|
9
|
+
> **Alpha (v0.1.0)**: セキュリティモデルは開発中です。パーミッションルールと設計ドキュメントの整合作業を進めています。本番利用は推奨しません。
|
|
10
|
+
|
|
11
|
+
[](README.md)
|
|
12
|
+
[](#)
|
|
13
|
+
|
|
14
|
+
</div>
|
|
15
|
+
|
|
16
|
+
## Shield Harness とは
|
|
17
|
+
|
|
18
|
+
Claude Code の全操作を自動防御するセキュリティハーネス。
|
|
19
|
+
承認ダイアログなしで安全な自律開発を実現します。`.claude/` ディレクトリに展開される hooks + rules + permissions による多層防御でエージェントを統制します。
|
|
20
|
+
|
|
21
|
+
## クイックスタート
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
npx shield-harness init [--profile minimal|standard|strict]
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
## なぜ Shield Harness なのか
|
|
28
|
+
|
|
29
|
+
- **フック駆動の防御**: 22 のセキュリティフックが Claude Code の全操作を監視
|
|
30
|
+
- **承認レスモード**: hooks に全セキュリティ判定を委譲し、人間の承認ダイアログを排除
|
|
31
|
+
- **fail-close 原則**: 安全条件を確認できない場合は自動的に停止
|
|
32
|
+
- **証跡記録**: SHA-256 ハッシュチェーンで全 allow/deny 決定を改ざん不能な形で記録
|
|
33
|
+
|
|
34
|
+
## アーキテクチャ概要
|
|
35
|
+
|
|
36
|
+
3 層防御モデル:
|
|
37
|
+
|
|
38
|
+
| 層 | 防御 | 実装 |
|
|
39
|
+
| -------- | ---------------------- | ------------------------------------------------------------- |
|
|
40
|
+
| Layer 1 | 権限制御 | `settings.json` の deny/allow ルール |
|
|
41
|
+
| Layer 2 | フック防御 | 22 の Node.js フックスクリプト |
|
|
42
|
+
| Layer 3 | サンドボックス | Claude Code ネイティブサンドボックス(bubblewrap / Seatbelt) |
|
|
43
|
+
| Layer 3b | コンテナサンドボックス | NVIDIA OpenShell(オプション、Docker 環境) |
|
|
44
|
+
|
|
45
|
+
## プロファイル
|
|
46
|
+
|
|
47
|
+
| プロファイル | 説明 | 承認レス | 用途 |
|
|
48
|
+
| ------------ | -------- | -------- | ---------------------------- |
|
|
49
|
+
| **minimal** | 最小構成 | 有効 | 低リスクタスク |
|
|
50
|
+
| **standard** | 推奨構成 | 有効 | 通常の開発 |
|
|
51
|
+
| **strict** | 厳格構成 | 無効 | セキュリティ監査が必要な場合 |
|
|
52
|
+
|
|
53
|
+
## フックカタログ
|
|
54
|
+
|
|
55
|
+
| # | フック | イベント | 責務 |
|
|
56
|
+
| --- | ---------------- | --------------------- | --------------------------------------------- |
|
|
57
|
+
| 1 | permission | PreToolUse | ツール使用の 4 カテゴリ分類 |
|
|
58
|
+
| 2 | gate | PreToolUse | Bash コマンドの 7 攻撃ベクトル検査 |
|
|
59
|
+
| 3 | injection-guard | PreToolUse | 9 カテゴリ 50+ パターンのインジェクション検出 |
|
|
60
|
+
| 4 | data-boundary | PreToolUse | 本番データ境界 + 管轄追跡 |
|
|
61
|
+
| 5 | quiet-inject | PreToolUse | quiet フラグ自動注入 |
|
|
62
|
+
| 6 | evidence | PostToolUse | SHA-256 ハッシュチェーン証跡 |
|
|
63
|
+
| 7 | output-control | PostToolUse | 出力トランケーション + トークン予算 |
|
|
64
|
+
| 8 | dep-audit | PostToolUse | パッケージインストール検出 |
|
|
65
|
+
| 9 | lint-on-save | PostToolUse | 自動 lint 実行 |
|
|
66
|
+
| 10 | session-start | SessionStart | セッション初期化 + 整合性ベースライン |
|
|
67
|
+
| 11 | session-end | SessionEnd | クリーンアップ + 統計 |
|
|
68
|
+
| 12 | circuit-breaker | Stop | リトライ上限 (3 回) |
|
|
69
|
+
| 13 | config-guard | ConfigChange | 設定変更の監視 |
|
|
70
|
+
| 14 | user-prompt | UserPromptSubmit | ユーザー入力のインジェクション検査 |
|
|
71
|
+
| 15 | permission-learn | PermissionRequest | 権限学習ガード |
|
|
72
|
+
| 16 | elicitation | Elicitation | フィッシング + スコープガード |
|
|
73
|
+
| 17 | subagent | SubagentStart | サブエージェント予算制約 (25%) |
|
|
74
|
+
| 18 | instructions | InstructionsLoaded | ルールファイル整合性監視 |
|
|
75
|
+
| 19 | precompact | PreCompact | コンパクション前バックアップ |
|
|
76
|
+
| 20 | postcompact | PostCompact | コンパクション後復元 + 検証 |
|
|
77
|
+
| 21 | worktree | WorktreeCreate/Remove | セキュリティ伝播 + 証跡マージ |
|
|
78
|
+
| 22 | task-gate | TaskCompleted | テストゲート |
|
|
79
|
+
|
|
80
|
+
## パイプライン
|
|
81
|
+
|
|
82
|
+
STG ゲート駆動の自動化パイプライン:
|
|
83
|
+
|
|
84
|
+
| STG0 | STG1 | STG2 | STG3 | STG4 | STG5 | STG6 |
|
|
85
|
+
| :--: | :--: | :--: | :--: | :--: | :------: | :-------: |
|
|
86
|
+
| 要件 | 設計 | 実装 | 検証 | CI | コミット | PR/マージ |
|
|
87
|
+
|
|
88
|
+
## Layer 3: サンドボックス(OS レベル隔離)
|
|
89
|
+
|
|
90
|
+
Layer 3 は Claude Code 組み込みのサンドボックスに依存します。Shield Harness は独自のサンドボックスを実装せず、サンドボックスが利用できない環境では Layer 1・2 で補填します。
|
|
91
|
+
|
|
92
|
+
### プラットフォーム対応状況
|
|
93
|
+
|
|
94
|
+
| OS | サンドボックス | 技術 | 状態 |
|
|
95
|
+
| ------------------ | -------------- | ------------------ | --------------------------------------- |
|
|
96
|
+
| macOS | 対応 | Seatbelt | 自動有効化 |
|
|
97
|
+
| Linux | 対応 | bubblewrap + socat | `sudo apt-get install bubblewrap socat` |
|
|
98
|
+
| WSL2 | 対応 | bubblewrap + socat | Linux と同一 |
|
|
99
|
+
| WSL1 | 非対応 | — | カーネル機能不足 |
|
|
100
|
+
| Windows ネイティブ | 非対応 | — | Anthropic 側で対応予定 |
|
|
101
|
+
|
|
102
|
+
### Windows ネイティブ: セキュリティギャップと補填策
|
|
103
|
+
|
|
104
|
+
Windows ネイティブでは Claude Code のサンドボックス機能(`sandbox.filesystem.*`、`sandbox.network.*`、`sandbox.autoAllow`)が動作しません。Shield Harness は以下で補填します:
|
|
105
|
+
|
|
106
|
+
- **Layer 1**: `permissions.deny` に Windows 固有コマンド(`type`、`del`、`format`、`Invoke-WebRequest`)を追加
|
|
107
|
+
- **Layer 2**: 22 フック全てが正常動作 — インジェクション検出、証跡記録、ゲートチェックは完全に機能
|
|
108
|
+
- **制約**: 子プロセスのファイルアクセスを OS レベルで制限できず、raw ソケット通信はコマンドパターンマッチをバイパス可能
|
|
109
|
+
|
|
110
|
+
エンタープライズ環境では Windows Firewall の送信規則によるプロセスレベルのネットワーク制御を推奨します。
|
|
111
|
+
|
|
112
|
+
### Layer 3b: NVIDIA OpenShell(オプション)
|
|
113
|
+
|
|
114
|
+
[NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell)(Apache 2.0)は Docker 上で AI エージェントに**カーネルレベルの隔離**を提供します:
|
|
115
|
+
|
|
116
|
+
| メカニズム | 対象 | 保護内容 |
|
|
117
|
+
| ------------ | ---------------- | ----------------------- |
|
|
118
|
+
| Landlock LSM | ファイルシステム | denyWrite / denyRead |
|
|
119
|
+
| Seccomp BPF | システムコール | ソケット / プロセス制限 |
|
|
120
|
+
| Network NS | ネットワーク | ドメインレベルの deny |
|
|
121
|
+
|
|
122
|
+
Windows ユーザーにとっての主なメリット:
|
|
123
|
+
|
|
124
|
+
- ポリシーがエージェントプロセスの**外部**に存在 — エージェント自身がガードレールを無効化できない
|
|
125
|
+
- Docker Desktop + WSL2 バックエンド(一般的な Windows 開発環境)で動作
|
|
126
|
+
- 残余リスクを 5% から 1% 未満に低減
|
|
127
|
+
- 自由に取り外し可能 — コンテナを停止すれば Shield Harness は Layer 1-2 にフォールバック
|
|
128
|
+
|
|
129
|
+
> **注意**: OpenShell は Alpha(v0.0.13)— API は将来変更の可能性があります。
|
|
130
|
+
|
|
131
|
+
## チャンネル連携
|
|
132
|
+
|
|
133
|
+
Claude Code Channels (Telegram/Discord) との連携をサポート。
|
|
134
|
+
チャンネル経由のメッセージには自動的に severity boost が適用されます。
|
|
135
|
+
|
|
136
|
+
## システム要件
|
|
137
|
+
|
|
138
|
+
| ツール | バージョン | 用途 | 必須/任意 |
|
|
139
|
+
| ------------ | ------------ | ------------------------ | -------------- |
|
|
140
|
+
| Git | 2.x | バージョン管理 | 必須 |
|
|
141
|
+
| Git Bash | (Git 同梱) | フックスクリプト実行環境 | 必須 (Windows) |
|
|
142
|
+
| Node.js | 18+ | フック実行 + NFKC 正規化 | 必須 |
|
|
143
|
+
| PowerShell 7 | 7.x (`pwsh`) | sync スクリプト | 推奨 |
|
|
144
|
+
| GitHub CLI | 2.x (`gh`) | PR 作成・マージ自動化 | 任意 |
|
|
145
|
+
|
|
146
|
+
OS: Windows ネイティブファースト(Git Bash 環境)、WSL2/Linux 互換。
|
|
147
|
+
|
|
148
|
+
## バージョニング
|
|
149
|
+
|
|
150
|
+
Shield Harness は [Semantic Versioning](https://semver.org/) に準拠します:
|
|
151
|
+
|
|
152
|
+
| バンプ | 条件 | 例 |
|
|
153
|
+
| ------- | ------------------------------------------------ | ------------------------------------------- |
|
|
154
|
+
| `patch` | バグ修正、パターン更新、ドキュメント修正 | injection-patterns.json 更新 |
|
|
155
|
+
| `minor` | 新機能(後方互換)、Phase 内 must タスク全完了時 | OCSF 対応、新フック追加、CLI オプション追加 |
|
|
156
|
+
| `major` | 破壊的変更 | スキーマ非互換変更、settings 構造変更 |
|
|
157
|
+
|
|
158
|
+
**リリーストリガー**: `git tag v1.x.x && git push origin v1.x.x` で `release.yml` が自動実行(npm publish + GitHub Release)。セキュリティ修正は即座に patch リリース。
|
|
159
|
+
|
|
160
|
+
## 参考プロジェクト
|
|
161
|
+
|
|
162
|
+
Shield Harness は 40 以上の Claude Code セキュリティプロジェクトを調査して設計されました。主な参考:
|
|
163
|
+
|
|
164
|
+
| プロジェクト | 影響を受けた点 |
|
|
165
|
+
| ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
|
|
166
|
+
| [claude-guardrails](https://github.com/dwarvesf/claude-guardrails) | npx install パターン、50+ インジェクションパターン、deny ルールカタログ |
|
|
167
|
+
| [claude-warden](https://github.com/johnzfitch/claude-warden) | 3 段階プロファイル、トークンガバナンス(quiet-inject、output-control)、ConfigChange 自己保護 |
|
|
168
|
+
| [claude-hooks](https://github.com/lasso-security/claude-hooks) | 5 カテゴリインジェクション検出、YAML パターン定義 |
|
|
169
|
+
| [tobari](https://github.com/Sora-bluesky/tobari) | 22 フックアーキテクチャ、SHA-256 ハッシュチェーン証跡、STG ゲートパイプライン、PermissionRequest 適応学習 |
|
|
170
|
+
| [OpenClaw](https://github.com/openclaw/openclaw) | 18 件の CVE/セキュリティ問題からの教訓(ゲートウェイ認証、認証情報管理、シムリンクトラバーサル)、チャンネル連携設計 |
|
|
171
|
+
| [everything-claude-code](https://github.com/affaan-m/everything-claude-code) | AgentShield セキュリティ統合(1,282 テスト、102 ルール)、包括的スキル/エージェントカタログ |
|
|
172
|
+
| [NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell) | Layer 3b カーネルレベルサンドボックス(Landlock、Seccomp BPF、Network NS)、宣言的 YAML ポリシー |
|
|
173
|
+
|
|
174
|
+
## ライセンス
|
|
175
|
+
|
|
176
|
+
MIT
|