Skip to content

Feat/vscode session allowlist #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Goki602 merged 6 commits into from
Mar 25, 2026
Merged

Feat/vscode session allowlist #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
306b643
feat(adapter-claude): session allowlist for VSCode confirm-to-deny fa…
Goki602 Mar 4, 2026
b9f62ee
feat: reposition as convenience tool + explicit allow to suppress Cla…
Goki602 Mar 10, 2026
9fcc7a0
feat: unify confirm handling as deny+retry, harden server security, a…
Goki602 Mar 10, 2026
29c0ed1
chore: fix lint/format, add Phase 1 security rules, improve historica…
Goki602 Mar 10, 2026
ea9f29f
chore: remove pricing/license references, add LLM discoverability (co…
Goki602 Mar 25, 2026
2561313
feat: respect reputation.opt_in config for telemetry upload
Goki602 Mar 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
201 changes: 121 additions & 80 deletions README.ja.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,20 +1,20 @@
# ClawGuard

> AIエージェント・セキュリティ・コンパニオン — 防御・監査・更新
> AIエージェントの記憶 — 確認を減らして、判断を賢く

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Tests](https://img.shields.io/badge/tests-375%20passing-brightgreen)]()
[![Tests](https://img.shields.io/badge/tests-380%20passing-brightgreen)]()
[![Node](https://img.shields.io/badge/node-%3E%3D20-green)]()

[English version](README.md)

## ClawGuardとは？

ClawGuardは、AIコーディングエージェントのためのリアルタイム・セキュリティレイヤーです。シェルコマンド・ファイル書き込み・ネットワークアクセスなどのツール呼び出しを実行前にインターセプトし、ポリシールールでリスクを評価して、100ms以内にallow（許可）/ confirm（確認）/ deny（拒否）の判定を返します。
AIエージェント、確認が多すぎませんか？ `npm install`のたびに確認、`git push`のたびに確認。5分前に「いいよ」って言ったのに、また同じことを聞いてくる。

Claude Code、Codex、MCPなど、フックベースのインターセプションに対応するあらゆるAIエージェントプラットフォームで動作します。判断データはローカルに保存され、署名付き脅威フィードを通じてコミュニティの評判データで強化できます。
ClawGuardが覚えておきます。一度OKした操作は記録して、次からは自動で通す。セッションをまたいでも、別のエージェントでも、別のツールでも。Claude Codeをはじめ、フック対応のエージェントならどれでも使えます。

ClawGuardは「完全な防御」を約束しません。被害の確率を下げ、影響範囲を小さくし、すべてのAIエージェントセッションを監査・再現可能にします。
危ない操作（`rm -rf`、`git push --force`、`curl|bash`）はもちろん止めます。でもインストールする本当の理由は、エージェントが静かに・速くなるから。

## クイックスタート

Expand All @@ -32,85 +32,52 @@ claw-guard test
## しくみ

```
AIエージェントのツール呼び出し
│
▼
┌─────────────┐
│ ClawGuard │
│ フック層 │
└──────┬──────┘
│
▼
┌─────────────┐ ┌──────────┐
│ ポリシー │────▶│ ルール │ 12コア + コミュニティ
│ エンジン │ └──────────┘
└──────┬──────┘
│
┌───┼───┐
▼ ▼ ▼
許可 確認 拒否
│
▼
ExplainRisk
（データに裏付けられた理由説明）
```

## アーキテクチャ

### 2層設計
初回: Agent → npm install foo → ClawGuard が確認 → 許可 → 記憶 ✓

**層1 — ランタイム防御**（フックベース、Docker不要）
- Adapter → Policy Engine → allow/confirm/deny
- confirm（確認）ダイアログに評判データ（ローカル＋フィード）を表示
- クロスエージェント判断記憶（SQLite）
- セキュリティパスポート（継続監視証明）
2回目: Agent → npm install foo → 自動許可（中断なし） ✓

**層2 — インフラ隔離**（Docker、Pro/Max向け）
- 3コンテナ構成: gateway / fetcher / agent
- ネットワーク分離（agentは外部に直接通信不可）
危険な操作: Agent → rm -rf / → 検知して理由を説明＋あなたの確認が必要 ✗
```

## CLIコマンド
## 静かさレベルを選ぶ

| コマンド | 説明 |
|---|---|
| `claw-guard init` | AIエージェント環境のセットアップ |
| `claw-guard evaluate --json` | ツールリクエストの評価（フックエントリポイント） |
| `claw-guard test` | ルール・エンジン・設定の検証 |
| `claw-guard serve` | HTTPフックサーバー（レイテンシ1-3ms） |
| `claw-guard log` | 監査ログの閲覧 |
| `claw-guard dashboard` | Webダッシュボードを起動 |
| `claw-guard feed` | 脅威フィードの管理（`--update`, `--status`） |
| `claw-guard marketplace` | ルールパックの管理（`installed`, `install`, `remove`） |
| `claw-guard upgrade` | ライセンス管理（`--key`, `--remove`） |
| `claw-guard passport` | セキュリティパスポート＆GitHubバッジ |
| `claw-guard replay` | インシデントリプレイ＆因果分析 |
| `claw-guard report` | 週次安全レポート |
| `claw-guard monitor` | 誤検知モニタリング |
| `claw-guard docker` | Dockerデプロイ（`init`, `up`, `down`） |
| `claw-guard skills` | Skills AVスキャン |
どれくらい静かにするかは自分で決められます。全部見せるモードから、ほぼ無音まで:

## 設定
| プリセット | スタイル | 低リスク | 中リスク | 高リスク |
|---|---|---|---|---|
| `observer` | 見るだけ | log | log | log |
| `guardian` | よく確認 | allow | confirm | deny |
| `balanced` | **おすすめ** | allow | confirm | confirm |
| `expert` | ほぼ無音 | allow | allow | confirm |

最小構成 — `clawguard.yaml` に1行書くだけ:

```yaml
profile: balanced
```

### プリセット

| プリセット | 低リスク | 中リスク | 高リスク |
|---|---|---|---|
| `observer` | log | log | log |
| `guardian` | allow | confirm | deny |
| `balanced` | allow | confirm | confirm |
| `expert` | allow | allow | confirm |

### 優先順位

CLI引数 > プロジェクト（`.clawguard.yaml`） > グローバル（`~/.config/clawguard/`） > デフォルト（`balanced`）

## セキュリティルール
## アーキテクチャ

### 2層設計

**層1 — スマート承認**（フックベース、Docker不要）
- 一度OKした操作を覚えて、次から自動で通す（SQLite）
- 確認時に「他の開発者はどうしたか」をコミュニティデータで表示（準備中）
- Adapter → Policy Engine → allow/confirm/deny（100ms以内）
- セキュリティパスポート（継続監視の証明書）

**層2 — インフラ隔離**（Docker、オプション・参考実装）
- `claw-guard docker init` で docker-compose テンプレートを取得
- 3コンテナ構成: gateway / fetcher / agent
- ネットワーク分離（agentから外部へ直接通信できない）

## 組み込みの安全網

危険な操作は自動でキャッチします。設定は不要で、最初から12のルールが入っています。

### コアルール（12件）

Expand All @@ -124,11 +91,51 @@ CLI引数 > プロジェクト（`.clawguard.yaml`） > グローバル（`~/.co
| `BASH.ROOT_PATH_OP` | bash | high | `/`（ルート）への操作 |
| `BASH.PIPE_EXEC_001` | bash | high | `curl \| bash` パイプ実行 |
| `BASH.PIPE_EXEC_002` | bash | high | `wget \| sh` パイプ実行 |
| `BASH.SSH_KEY_READ` | bash | medium | SSH鍵ファイルへのアクセス |
| `BASH.SSH_KEY_READ` | bash | high | SSH鍵ファイルへのアクセス |
| `BASH.ENV_FILE_READ` | bash | medium | `.env`ファイルへのアクセス |
| `BASH.NPM_INSTALL` | bash | medium | `npm install <パッケージ>` |
| `BASH.PIP_INSTALL` | bash | medium | `pip install <パッケージ>` |

### いつ聞いてくる？

| 条件 | 動作 | 例 |
|---|---|---|
| 前にOKした操作 | **何も聞かず自動で通す** | `npm install express`（以前OKしたもの） |
| どのルールにもひっかからない | **何も聞かずそのまま実行** | `git status`, `ls`, `npm test` |
| ルールにひっかかる + confirm設定 | データ付きで確認を出す | `npm install unknown-pkg` |
| ルールにひっかかる + deny設定 | 理由を説明してブロック | `guardian`モードでの`rm -rf /` |

### 動かないケース

| 状況 | 理由 |
|---|---|
| AIエージェント自身がコマンドを断った | エージェントがツールを呼ばないので、ClawGuardの出番がない。これは多層防御（何重にも守る仕組み）として正常な動作です。 |
| `bypassPermissions` / `dontAsk` モードで実行中 | この権限モードではClawGuardの判定をスキップします。 |
| フックが入っていない | `claw-guard init` でフックを登録してください。 |

> **動作確認:** `claw-guard test` を実行するか、JSONを `claw-guard evaluate --json` にパイプすると、ルール照合を直接テストできます。

## CLIコマンド

| コマンド | 説明 |
|---|---|
| `claw-guard init` | AIエージェント環境のセットアップ |
| `claw-guard evaluate --json` | ツールリクエストの評価（フックエントリポイント） |
| `claw-guard test` | ルール・エンジン・設定の検証 |
| `claw-guard stats` | 自動許可カウント＆判断サマリーの表示 |
| `claw-guard serve` | HTTPフックサーバー（低レイテンシ） |
| `claw-guard log` | 監査ログの閲覧 |
| `claw-guard dashboard` | Webダッシュボードを起動 |
| `claw-guard feed` | 脅威フィードの管理（`--update`, `--status`） |
| `claw-guard marketplace` | ルールパックの管理（`installed`, `install`, `remove`） |
| `claw-guard passport` | セキュリティパスポート＆GitHubバッジ |
| `claw-guard replay` | インシデントリプレイ＆因果分析 |
| `claw-guard report` | 週次安全レポート |
| `claw-guard monitor` | 誤検知モニタリング |
| `claw-guard docker` | Dockerデプロイ（`init`, `up`, `down`） |
| `claw-guard skills` | Skills AVスキャン |
| `claw-guard team` | チーム管理（serve/add/list/remove/policy） |

### ルール形式（YAML）

```yaml
Expand All @@ -155,13 +162,44 @@ CLI引数 > プロジェクト（`.clawguard.yaml`） > グローバル（`~/.co
phase: 0
```

## 料金プラン
## なぜClawGuard？

| プラン | 価格 | 主な機能 |
|---|---|---|
| **Free** | $0 | 8コアルール、週次フィード、基本リプレイ（24時間） |
| **Pro** | $12/月 | 全ルール、日次フィード、パスポート、マーケットプレイス、Skills AV |
| **Max** | $39/月 | チーム管理、クロスチーム記憶、組織パスポート |
| | 手動hooks | mcp-scan | ClawGuard |
|---|---|---|---|
| エージェント間の記憶 | - | - | **あり** — 一度OKすれば、どこでも自動許可 |
| Claude Code / Codex / MCP対応 | - | MCPのみ | **3つとも対応** |
| コミュニティの知恵 | - | - | **あり** — 他の開発者の判断が見える |
| セットアップ | 自分で書く | インストール+スキャン | `claw-guard init`（1コマンド） |
| 料金 | 無料（自作） | 無料 | **無料（MIT、全機能）** |

ClawGuardはブロッカーではなく、便利ツールです。あなたの判断を覚えて確認回数を減らし、コミュニティの知恵を共有します。セキュリティは副産物であり、売りではありません。

## 料金

完全無料のオープンソース（MIT）。全機能が制限なく使えます。ライセンスキーも課金もありません。

## テレメトリ（匿名統計）

ClawGuardは匿名の利用統計を収集し、コミュニティの知恵として還元しています。確認ダイアログで「他の開発者の85%がこの操作を許可しています」のように表示されます。

### 送信するもの（6時間ごと）

- ルールIDごとの集計（許可/拒否/合計の件数のみ）

### 送信しないもの

- コマンド内容、ファイルパス、引数
- ユーザーの身元、IPアドレス、セッション情報
- プロジェクト名やリポジトリの情報

### 無効にするには

`clawguard.yaml` に以下を追加:

```yaml
reputation:
opt_in: false
```

## プロジェクト構成

Expand All @@ -173,7 +211,7 @@ packages/
├── adapter-claude/ Claude Code PreToolUseフック
├── adapter-codex/ Codex承認ポリシー拡張
├── adapter-mcp/ MCP JSON-RPCプロキシ
├── billing/ ライセンスマネージャー、機能ゲート
├── billing/ 機能設定（全機能が無制限で利用可能）
├── feed/ 署名付き日次フィードクライアント
├── enrichment/ npmレジストリ、CVE検索
├── memory/ SQLite判断ストア
Expand All @@ -184,11 +222,14 @@ packages/
├── team/ 組織ポリシー＆メンバー管理
├── web-ui/ Reactダッシュボード
├── lp/ ランディングページ（英語＋日本語）
├── webhook/ Stripe Webhook（Cloudflare Worker）
└── docker/ 3コンテナ参考実装
├── webhook/ Webhookハンドラー（Cloudflare Worker）
├── docker/ 3コンテナ参考実装
├── api/ REST APIサーバー
├── sdk/ 組み込み用SDK
└── siem/ SIEMコネクター
rules/
├── core/ 12コアルール（Phase 0-1）
└── phase2/ 15追加ルール（Pro/Max向け）
└── phase2/ 15追加ルール
```

## 開発
Expand All @@ -200,7 +241,7 @@ npm install
# 全パッケージをビルド
npm run build

# テスト実行（375テスト）
# テスト実行（380テスト）
npm test

# リント
Expand Down
Loading
Loading