ratchet

Name: ratchet
Author: iversonwuwei

Local

github.comSecurity0Updated 6w ago

Repository Visit website

About ratchet

ratchet is a local, read-only audit tool for inspecting agent configurations and tool inventories, then deriving least-privilege policies from observations. It also packages reports and hashes so recipients can verify audit artifacts independently.

Key features

01Read-only MCP configuration scans
02Find servers without pinned versions
03Derive policies from tool inventories
04Policy checks with decision rationale
05Build reports and SHA-256 manifests

Use cases

01Inventory MCP servers on a machine
02Identify configurations with unpinned versions
03Draft permissions from observed tool use
04Deliver independently verifiable audit artifacts

MCP support

ratchet can run as a stdio MCP server, exposing the ratchet_scan, ratchet_policy, and ratchet_check tools.

Configuration

Local server config is the same for every client. Copy it into your client’s MCP config file.

mcp.json · Universal config

{
  "mcpServers": {
    "iversonwuwei-ratchet": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/suhui-organization/ratchet:v0.12.1"
      ]
    }
  }
}

Run commanddocker run -i --rm ghcr.io/suhui-organization/ratchet:v0.12.1

Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.

Packages

ocighcr.io/suhui-organization/ratchet:v0.12.1stdio

Tools

No tool list yet

Local servers expose tools only once running on your machine, and the maintainer has not provided a tool list.

Details

From the project README

Ratchet

从 agent 的真实行为编译最小权限策略，并给出收货方能自己验证的证据。

curl -fsSL https://github.com/suhui-organization/ratchet/releases/latest/download/install.sh | sh

macOS / Linux 上也可以用 Homebrew（formula 钉住每个平台的 sha256）：

brew install suhui-organization/tap/ratchet

Claude Desktop 用户可以直接装本地 server（一键安装包，不需要命令行）：

下载 ratchet-0.12.0.mcpb 并打开它，Claude Desktop 会完成安装。包内是四个平台的原生二进制 + 一份 manifest.json （MCPB 规范），不需要 Node 或 Python 运行时。

Linux / macOS（amd64 · arm64）。装完先跑这一条——只读配置，不执行任何东西：

ratchet scan --home ~

它会在十秒内告诉你：这台机器上有几个 MCP server，其中几个没锁版本。（我自己的机器：16 个里 12 个没锁。）

棘轮只能往一个方向转：权限可以收紧，放宽必须显式。

这是什么

一个跑在你自己机器上的工具：它读 agent 用到的工具清单，编译出一份最小权限策略，再把这次审计的产物打成一份 收货方不需要信任你、也不需要装任何东西就能验证的交付目录。

这不是什么

不是沙箱、不是容器运行时；
不是 prompt 内容过滤器；
不是企业控制台（不做 dashboard、不做多租户、不做 SaaS 依赖）；
不要求你把日志传到哪里去。

为什么值得存在

市场上的产品要么让你自己手写策略（Cedar / CEL / 自然语言），要么要你相信它的日志。Ratchet 做的是这两件之间缺失的一步： 策略由观测编译，证据由收货方自己算哈希。

一个例子

# 1) 编译：从工具清单得到一份保守的最小权限策略
ratchet policy draft --from examples/inventory.json --out policy.json

# 2) 出交付物：报告 + 逐文件 sha256 清单
ratchet-report build --dir ./delivery --policy policy.json

# 3) 收货方验证（不需要装 ratchet）
python3 verify.py ./delivery

仓库结构

目录	语言	是什么
`cmd/` `internal/`	Go	机器上的引擎：工具清单 → 能力判定 → 最小权限策略。编译成单个静态二进制，目标机器不需要任何运行时
`service/`	Python	交付物侧：合规映射、sha256 清单、以及只用标准库的独立验证器
`web/`	Nuxt 4 + Vue 3 + Tailwind	公开页面：落地页 + 收货方在浏览器里自己算哈希的验证页
`docs/`	—	设计与计划（`DESIGN.md` / `PLAN.md` / `DECISIONS.md`）

状态

0.12.0 — developer preview，链路已经整条打通（本机实测：16 个 MCP server、 12 个未锁版本、164 个工具、策略 allow 43 / approve 106 / deny 15）：

命令	做什么
`ratchet scan [--introspect] [--share page.html]`	读 harness 配置列出 MCP server（只读，不执行）；加 `--introspect` 才连上去列工具
`ratchet ingest` / `observe`	采集真实调用（hook 出错静默退出），并对照清单看出哪些工具从没被用过
`ratchet policy draft` / `check`	编译三态策略（每条带判定依据），并试跑一次假设调用
`ratchet deliver` / `report build`	一条命令出交付目录：策略 + 报告 + sha256 清单
`ratchet mcp`	以 stdio MCP server 形态跑（`ratchet_scan` / `ratchet_policy` / `ratchet_check`）
`ratchet feedback`	把去标识化结果整理成 issue 正文供你复制；没有遥测，不会自动发

拿到它的方式：curl -fsSL https://github.com/suhui-organization/ratchet/releases/latest/download/install.sh | sh、 brew install suhui-organization/tap/ratchet、容器 ghcr.io/suhui-organization/ratchet，或官方 MCP Registry 里的 io.github.iversonwuwei/ratchet。

清楚的边界：能力判定是名称/描述的启发式，会双向出错（仓里有两条已知误判的测试）；它不是沙箱、运行时不拦调用；判定不了的会单独列出来请人确认，而不是猜一个结论。详见 docs/PLAN.md 与 docs/DELIVERY-0.14.0.md。

许可证

Apache-2.0，见 LICENSE。

开发

make test          # 三端全部测试
make go-test
make py-test
make web-test

Comments

Markdown supported

New to MCP?

From what the protocol is to installing your first server, these answers cover most first questions.

Read the getting-started guide

An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.