blast-scope

Blast Scope

シェルコマンドの結果を評価するエンジンです。 Blast Scope は、AI エージェント（またはユーザー）がコマンドを実行する前に、そのコマンドが実際に何をするのかを評価します。構文をブロックリストと照合するのではなく、コマンドの実際の対象を特定し、その対象を安全な読み取り専用プローブで確認して、根拠を添えた構造化リスクスコアを返します。

重要なのは、状況に応じた影響範囲です。同じコマンドでも、実際に何を対象とするかによってスコアは大きく変わります。

COMMAND                            SEVERITY   WHY                                          ADVICE
─────────────────────────────────  ────────   ──────────────────────────────────────────  ───────
rm -rf ./logs                      LOW        0 importers · regenerable · outside src      proceed
rm -rf ./config                    CRITICAL   8 modules import it · high PageRank hub      block
git reset --hard   (clean tree)    LOW        nothing uncommitted to discard               proceed
git reset --hard   (4 dirty files) HIGH       would throw away 4 files of uncommitted work confirm
git push --force   (protected)     CRITICAL   would orphan commits on a protected branch   block
docker volume rm cache  (absent)   LOW        volume doesn't exist — nothing to remove     proceed
docker volume rm pgdata (in use)   CRITICAL   holds data · in use · no image to rebuild    block
pip uninstall flask     (uv.lock)  LOW        regenerable — exact version pinned in lock   proceed
DROP TABLE users        (42 rows)  CRITICAL   schema + 42 rows · irreversible              block
DELETE FROM logs        (in txn)   HIGH       no WHERE — but inside a txn, ROLLBACK-able    confirm

2つのコマンドはバイト単位で同一でも、スコアに4段階の差が生じることがあります。この差こそが、この製品の価値です。

ブロックリストではありません。Shellfirm の代替ではありません。システムコールの監視ツールでもありません。 構造的な影響を評価するもので、あくまで助言を行い、実行をブロックすることはありません。また、まれに重大なコマンドについては、先に元に戻すためのスナップショットを取得します。

---

仕組み

コマンドは低コストの絞り込み処理を通ります。ほとんどのコマンドはマイクロ秒単位で非破壊的と認識され、何も通知せずに処理を終えます。フラグが付いた破壊的な候補だけがプローブの対象になります。

  shell command
      │   split chains (&& || ; |) · de-alias PowerShell · parse flags/targets
      ▼
  ┌──────────────────────────────────────────────────────────────────────┐
  │  STAGE 1 · triage  (near-free regex — runs on every command)          │
  │     which class?   git · docker · pip/uv · sql · else filesystem       │
  │     destructive?   `git status` → no.   `git reset --hard` → yes ↓     │
  └───────────────────────────────┬──────────────────────────────────────┘
                    destructive candidate │   (everything else exits here, silent)
                                          ▼
  ┌──────────────────────────────────────────────────────────────────────┐
  │  ELIGIBILITY FILTER   safe read-only probe?   AND   undo authorable?   │
  └──────────────┬──────────────────────────────────────┬─────────────────┘
         yes, probe it │                       no probe here / now │
                       ▼                                           ▼
   STAGE 2 · safe probe (read-only)                    heuristic estimate
     git  status · reflog · rev-list                   from a static per-class
     docker  inspect · ps · ls                          table — and LABELED
     sqlite  SELECT count(*)  [mode=ro]                  "(estimated)" so you
     pip/uv  read lockfiles                              know it wasn't probed
                       │                                           │
                       └─────────────────────┬─────────────────────┘
                                              ▼
        blast radius  ×  reversibility   (combined PER CLASS — no global formula)
        filesystem also folds in: dependency-graph centrality + recoverability
                                              ▼
              score 0.0–1.0  →  severity (low / medium / high / critical)
                                              ▼
        PreToolUse hook:  silent (low/med) · advise (high) · advise + snapshot (critical)

適格性フィルターが設計上の境界です。 コマンドクラスがライブプローブの対象となるのは、次の両方を満たす場合に限られます。（1）影響を副作用が厳密に発生しない読み取り（HTTP GET のようなもの。状態を評価するために状態を変更することはありません）で観測できること。（2）元に戻す方法が十分に確立され、静的テーブルに記述できること。ここでプローブを実行できない場合（Docker デーモン、DB ドライバー、認証情報がないなど）、ツールはラベル付きの推定値に切り替えます。黙って推測することも、実行をブロックすることもありません。

クラス別のテーブル、正確なファイルシステムの計算式、キャリブレーションについては、docs/heuristics.md をご覧ください。

5つのコマンドクラス

クラス	評価対象の破壊的な操作	安全な（読み取り専用）プローブ	可逆性の判断材料
ファイルシステム	rm -rf、mv、> による切り詰め	依存関係グラフ + git status	Git で追跡されているか？再生成可能か？シークレットか？重要なデータか？
Git	reset --hard、push --force、branch -D、clean -fdx	status · reflog · rev-list · rev-parse @{u}	reflog の保持期間 · リモート側の先行状況 · 保護ブランチ
Docker	volume rm、system prune -a、rm -f	volume inspect · ps -a · volume ls	ボリューム → なし · コンテナー → イメージから再作成可能
pip / uv	pip uninstall、uv pip uninstall	ロックファイル / マニフェストを読み取り（サブプロセスなし）	ロックファイルがあれば → 完全に再生成可能
SQL	DROP、TRUNCATE、WHERE なしの DELETE	SQLite：mode=ro で SELECT count(*) を実行；トランザクションを確認	トランザクション内か？バックアップの状況は？

新しいクラスは、単一のプロトコル（triage / assess）に従って src/blast_scope/classes/ に追加できます。各クラスの assess では、副作用が厳密に発生しない読み取りだけを行います。

---

ステータス

コマンド解決と精密な依存関係グラフを備えた、キャリブレーション済みのマルチクラス・ガードレールです。

機能	モジュール
フラグ／オペランドを考慮したコマンドモデル（POSIX および PowerShell）	command_effects.py、command_parser.py
コマンド解決 — env／チルダ／波かっこ／glob の展開、未設定変数の危険性、スクリプトの透過的な解析（sh -c、npm run と pre/post フック、スクリプトファイル、Makefile ターゲット）、読み取り専用の $(...) 置換	resolution.py
ドライランのオラクル — git clean -n の正確な一覧、reset の差分、checkout による上書きのプレビュー、find -delete から -print への書き換え、sqlite の対象範囲を限定した DELETE の件数、rsync の --dry-run。オラクルの対象は undo スナップショットに反映されます	classes/git.py、classes/find.py、classes/rsync.py、classes/sql.py
復元可能性の分類（git の状態、シークレット、再生成可能なデータ、貴重なデータ）	recoverability.py
依存関係グラフ + 重み付き PageRank 中心性、増分インデックス作成	graph_resolver.py、centrality.py
2 軸の、根拠に基づいたファイルシステムのスコアリング	risk_scorer.py
コマンドクラスのプローブ — git／docker／pip・uv／SQL を単一のプロトコルの背後で提供	classes/
グラフ外の パスアナライザー（インフラ／パスによる設定）+ git ベース	consequences.py、vcs.py、infra.py、config_refs.py
PreToolUse フック + tarball による スナップショット／復元	hook.py、snapshot.py
評価ハーネス + ラベル付きコーパス + キャリブレーション	eval.py、tests/fixtures/eval_corpus.jsonl

キャリブレーション。 2 つのハーネスを、どちらも自分で実行できます。

• リポジトリ内のコーパス（tests/fixtures/eval_corpus.jsonl、あらゆる復元可能性カテゴリ、git の作業ツリー状態、インフラ／設定、rm -rf .git、グラフでインデックス化された中心的なモジュール、git／docker／pip／SQL クラス、解決レイヤー（未設定変数による置換の崩れ、glob／環境変数の対象、sh -c のペイロード、npm の pre フック、不透明なラッパー、追跡対象のソースの大量破壊）にわたる 58 件） — 重大度の完全一致 58/58、ゲート F1 1.00。変更による意図しない性能低下を防ぐため、tests/test_eval.py で固定されています。
• SABER — 実際のコーディングエージェントのワークスペース 716 件。約 1725 件の安全なコマンドに対して、blast-scope の誤検知率は 0.58%です。中核となる能力（data_destruction）では、現実的なワークスペースに対する攻撃の注入を 82.4% 検知します。グラフが不要な高速フック経路でこれを実現できるのは、コマンド解決（環境変数／glob の対応付けとスクリプトの透過的な解析）のおかげです。ラッパーの透過的な解析により、code_tampering の検知率も約 0% から 50% に向上します。カテゴリ別の再現率には意図的にばらつきがあり、そのことは表にも示されています。blast-scope が評価するのは破壊的な影響、つまりファイルシステム／データの損失と git／docker／pip／SQL の状態です。ネットワークへの持ち出しや永続化は異なる脅威モデルであり、設計上の対象範囲外です。未完成の領域ではありません。これは意図的に定めた境界です。詳細は bench/ を参照してください。

uv run python -m blast_scope.eval                 # in-repo corpus
python bench/saber_eval.py --tasks <saber>/dataset/data/tasks.jsonl   # SABER

---

インストール

あらゆる MCP クライアントで最も手早く使う方法は、uvx によるインストール不要の実行です（クローンも仮想環境も不要です）。

uvx blast-scope        # runs the MCP server on stdio

Claude Code ユーザー — 1 行で MCP ツールとアドバイザリーフックの両方を設定できます。

/plugin marketplace add Atharva-Jayappa/blast-scope
/plugin install blast-scope

開発時、またはチェックアウトを固定する場合は次のようにします。

git clone https://github.com/Atharva-Jayappa/blast-scope.git
cd blast-scope && uv sync --all-extras

---

使用方法

MCP サーバーとして

MCP クライアントの設定に追加します（例：Claude Code の settings.json）。

{
  "mcpServers": {
    "blast-scope": { "command": "uvx", "args": ["blast-scope"], "type": "stdio" }
  }
}

公開されるツール：

ツール	目的
assess_command(command, cwd?, project_root?)	（連結されている可能性のある）コマンドをスコアリングします。スコア、重大度、根拠、証拠、復元可能性、影響を受けるノード、およびセグメントごとの chain 内訳を返します。
index_project(project_root)	依存関係グラフを強制的に再構築します（それ以外の場合は初回使用時に自動構築されます）。
list_snapshots(project_root)	undo スナップショットを新しい順に一覧表示します。
restore_snapshot(snapshot_id, project_root)	スナップショットを復元して、リスクのあるコマンドを取り消します。

フックとして（段階的なアドバイス＋自動スナップショット）

Bash コマンドの実行前にインターセプトします。助言のみで、実行をブロックすることはありません。リスクに応じて対応の強さが変わります。低・中リスクでは通知なし、高リスクではアドバイス、重大なリスクではアドバイス＋スナップショットを行います。スナップショットでは、すでに復旧可能なもの（git-clean、再生成可能なもの）を除外し、ハードサイズ上限を超えるものはアーカイブせず警告します。そのため、取り消しの備えをすばやく、信頼できる状態に保てます。

フックは依存関係グラフも自動で維持するため、MCP の呼び出しは不要です。SessionStart が切り離されたバックグラウンドプロセスで初回のビルドを行い、各 PreToolUse がスコアリング前にグラフを差分更新します（変更がない場合、stat の走査は約 20 ms）。そのため、エージェントによる編集が立て続けに行われた後も、判定は現在のツリーを反映します。.claude/settings.json に追加してください。

{
  "hooks": {
    "SessionStart": [
      { "hooks": [{ "type": "command", "command": "python -m blast_scope.hook" }] }
    ],
    "PreToolUse": [
      { "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "python -m blast_scope.hook" }] }
    ]
  }
}

詳細と取り消しの流れについては、docs/hook.md を参照してください。

---

出力例

依存関係グラフに基づいてスコアリングされたファイルシステムコマンド：

// assess_command("rm -rf ./config", project_root="/proj")
{
  "score": 0.93,
  "severity": "critical",
  "recommendation": "block",
  "recoverability": "untracked",
  "rationale": "rm targets config. 8 direct importer(s), 14 total affected. not git-tracked. recursive deletion. CRITICAL risk.",
  "evidence": [
    "8 importer(s), 14 affected node(s)",
    "high centrality (PageRank 0.91) — a hub other code routes through",
    "untracked — not in git history",
    "recursive — applies to every file underneath"
  ],
  "affected_nodes": [ /* ... */ ],
  "chain": [ /* per-segment breakdown */ ]
}

プローブできなかったコマンドクラスの例です。ラベル付き推定値に注目してください（Postgres ドライバーがなく、サーバーがリモートの可能性もあるため、ツールは黙って推測することを避けます）。

// assess_command('psql -c "DROP TABLE users"')
{
  "score": 0.9,
  "severity": "critical",
  "recommendation": "block",
  "evidence": [
    "drops users — its schema and all rows, irreversible (estimated — no read-only probe for postgres)"
  ]
}
// the same DROP against a local SQLite file probes for real:
//   "drops users — its schema and 42 row(s), irreversible"   (estimated: false)

---

開発

uv sync --all-extras
uv run pytest -q              # full suite
uv run python -m blast_scope.eval   # scoring accuracy report

プロジェクト構成

blast-scope/
├── src/blast_scope/
│   ├── server.py            # MCP server + tools (assess, index, snapshots)
│   ├── command_parser.py    # shell → structured intent (POSIX + PowerShell)
│   ├── command_effects.py   # command/flag/operand → intent + weight
│   ├── recoverability.py    # path → how recoverable if destroyed
│   ├── graph_resolver.py    # paths → dependency-graph impact (+ PageRank)
│   ├── centrality.py        # pure-Python weighted PageRank
│   ├── risk_scorer.py       # signals → score + severity + evidence
│   ├── classes/             # command-class probes behind one protocol
│   │   ├── __init__.py      #   Candidate · ConsequenceClass · registry
│   │   ├── git.py           #   reflog / upstream-divergence / protected branch
│   │   ├── docker.py        #   volume / container / system-prune probes
│   │   ├── packages.py      #   pip·uv uninstall vs. lockfile presence
│   │   └── sql.py           #   DROP/TRUNCATE/DELETE — SQLite probe + estimates
│   ├── consequences.py      # coordinator: class probes + path analyzers
│   ├── vcs.py / infra.py / config_refs.py   # git base + path analyzers
│   ├── hook.py              # PreToolUse advisory hook
│   ├── snapshot.py          # tarball snapshot / restore / list
│   ├── eval.py              # evaluation harness + metrics
│   └── vendor/crg/          # vendored from code-review-graph (MIT)
├── tests/                   # 298 tests incl. eval regression guard
│   └── fixtures/eval_corpus.jsonl   # labeled calibration corpus
└── docs/
    ├── heuristics.md        # scoring model + per-class tables + calibration
    └── hook.md              # hook registration + undo

---

ロードマップ

• 破壊的な操作のクラスに対する再現率を向上します（追跡対象ファイルに対する glob の対象指定、find ベースの削除パターン）。SABER のカテゴリ別テーブルが作業リストです。
• ドライバーポリシーが確定したら、Postgres/MySQL のオプションのライブプローブを導入します（プロセス内、読み取り専用）。現在、これらのエンジンではラベル付き推定値にフォールバックします。
• フック経由での PowerShell シェル認識に対応します（MCP ツールではすでにサポートされています）。
• 助言以外の、より高度なインターセプトモードをオプションで追加します。

仕様、契約、設計ルールの全容については、CLAUDE.md を参照してください。

---

ライセンス

Apache 2.0（0.3.1 以下のバージョンは MIT）。ベンダーとして含まれる code-review-graph のソースは、上流の通知に基づき引き続き MIT です。 NOTICE を参照してください。