blast-scope

Blast Scope

用于评估 Shell 命令后果的引擎。 Blast Scope 会在 AI Agent（或你）运行命令前，评估命令实际会造成什么影响。它不会将语法与阻止列表进行模式匹配；而是找出命令的实际目标，通过安全的只读探测观察该目标，并返回包含证据的结构化风险评分。

它的核心是评估情境相关的影响范围。同一条命令根据实际作用对象的不同，评分可能截然不同：

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

两条命令可以逐字节完全相同，评分却相差四个等级。这正是它的价值所在。

不是阻止列表，不是 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 守护进程、数据库驱动或凭据），工具会退化为带标签的估算——绝不会悄悄猜测，也绝不会阻止操作。

有关各类别的表格、精确的文件系统公式和校准方法，请参阅 docs/heuristics.md。

五种命令类别

类别	评估的破坏性操作	安全（只读）探测	可逆性信号
文件系统	rm -rf、mv、> 截断	依赖关系图 + git 状态	由 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：SELECT count(*) mode=ro；事务检查	是否在事务中？备份状况如何？

新增类别可通过同一协议（triage / assess）接入 src/blast_scope/classes/；每个类别都将 assess 限定为完全无副作用的读取。

---

状态

经过校准的多类别护栏，具备命令解析和精确的依赖关系图。

能力	模块
对标志/操作数敏感的命令模型（POSIX 和 PowerShell）	command_effects.py, command_parser.py
命令解析——环境变量/波浪号/花括号/通配符扩展、未设置变量风险、脚本透明性（sh -c、npm run + 前置/后置钩子、脚本文件、Makefile 目标）、只读 $(...) 替换	resolution.py
试运行预言机——git clean -n 精确列表、reset 分歧、checkout 覆盖预览、将 find -delete 改写为 -print、sqlite 限定范围的 DELETE 计数、rsync --dry-run；预言机目标会纳入撤销快照	classes/git.py, classes/find.py, classes/rsync.py, classes/sql.py
可恢复性分类（git 状态、密钥、可重新生成的数据、珍贵数据）	recoverability.py
依赖关系图 + 加权 PageRank 中心性、增量索引	graph_resolver.py, centrality.py
基于证据的双轴文件系统评分	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

校准。 两套测试工具，均可自行运行：

• 仓库内语料库（tests/fixtures/eval_corpus.jsonl，共 58 个用例，涵盖每种 可恢复性类别、git 工作树状态、基础设施/配置、rm -rf .git、 图索引的核心模块、git/docker/pip/SQL 类别，以及 解析层——未设置变量导致的路径坍缩、通配符/环境变量目标、sh -c 负载、npm 前置钩子、不透明封装器、对已跟踪 源码的大规模破坏）——58/58 严重程度完全匹配，门控 F1 为 1.00，由 tests/test_eval.py 固定，并留有余量，确保更改不会悄悄导致回归。
• SABER——716 个真实的编码 Agent 工作区。在约 1725 个安全命令中，blast-scope 的误报率为 0.58%；在其核心能力（data_destruction）上，它能在真实工作区中捕获 82.4% 的注入攻击——依靠命令解析（环境变量/通配符绑定 + 脚本 透明性），在快速钩子路径上无需依赖图。封装器透明性还将 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 用户——一行命令即可同时配置 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)	按时间从新到旧列出撤销快照。
restore_snapshot(snapshot_id, project_root)	通过恢复快照撤销有风险的命令。

作为钩子（分级建议 + 自动快照）

在 Bash 命令运行之前进行拦截——只提供建议，绝不阻止。建议强度随风险而变化：低/中风险时静默，高风险时提供建议，严重风险时提供建议 + 快照。快照会跳过已有恢复途径的内容（Git 工作区干净、可重新生成），对于超过硬性大小上限的内容则发出警告，而不会将其打包成 tar 文件，确保撤销保护快速可靠。

钩子还会自行维护依赖关系图——无需调用 MCP：SessionStart 会在分离的后台进程中冷构建依赖关系图，每次 PreToolUse 都会在评分前增量刷新（没有变化时，stat 扫描约需 20 ms），因此即使 Agent 密集编辑后，判断仍能反映当前目录树。添加到 .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 shell（MCP 工具已支持）。
• 提供可选的、更丰富的拦截模式，超越建议模式。

完整规范、契约和设计规则请参阅 CLAUDE.md。

---

许可证

Apache 2.0（≤ 0.3.1 版本使用 MIT 许可证）。供应的 code-review-graph 源码仍遵循 MIT 许可证，并受其上游声明约束——请参阅 NOTICE。