@aimarket/warden 0.14.0 → 0.16.0

package/docs/scan.ru.md

@@ -133,17 +133,35 @@ repos:
 
 Что отправляется: адрес эндпоинта — только схема, хост и путь (без query, без имени пользователя и пароля) — и дайджест набора инструментов по [MTL/1](https://github.com/alexar76/awr). Ни описаний инструментов, ни заголовков. Эндпоинты на частных хостах и адресах, а также пути, похожие на содержащие ключ, не отправляются вовсе; отчёт объясняет почему.
 
-Stdio-сервер, запущенный из публичного реестра npm или PyPI (`npx`, `bunx`, `npm exec`, `pnpm dlx`, `uvx`, `uv tool run`, `pipx run`), называется по пакету — `npm:<имя>` или `pypi:<имя>`, без версии — с тем же дайджестом. HISTOR ставит каждую опубликованную версию такого пакета в песочнице gVisor (приманки вместо секретов, без маршрута наружу; каждый инструмент вызывается один раз с подставными аргументами, ни на что настоящее не действуя) и записывает его инструменты и то, что он делал и записывает его инструменты, поэтому `previously-observed` здесь значит, что у вас более старая версия, а `different` — версия, до которой HISTOR ещё не дошёл, или пакет, который не совпадает с опубликованным. Локальный путь, git- или tarball-адрес, частный реестр (`--registry`, `--index-url`) или простой запуск `node`/`python` не отправляются никогда. Для пакета HISTOR также сообщает, рекомендательными находками, не подражает ли его имя популярному (`HISTOR_PACKAGE_LOOKALIKE`: на один символ, то же имя под другим scope или с другими разделителями, при том что популярный скачивают хотя бы в 100 раз чаще) и нет ли у прочитанной версии признаков украденного токена публикации: `HISTOR_PACKAGE_PROVENANCE_LOST` (нет подтверждённой сборки в CI, хотя у предыдущей версии была), `HISTOR_PACKAGE_INSTALL_SCRIPTS` (появились установочные скрипты), `HISTOR_PACKAGE_PUBLISHER_CHANGED`, `HISTOR_PACKAGE_NEW_DEPENDENCIES`. И что пакет делал в песочнице: `HISTOR_PACKAGE_READS_SECRETS` (открыл приманки — SSH-ключи, токены облаков или реестров, кошелёк — при установке, при запуске или при вызове инструмента), `HISTOR_PACKAGE_PERSISTENCE` (писал туда, где пережил бы сессию, например в `.bashrc` или `authorized_keys`), `HISTOR_PACKAGE_STARTUP_NETWORK` (выходил в сеть до вызова любого инструмента), `HISTOR_PACKAGE_STARTS_PROGRAMS`, `HISTOR_PACKAGE_INSTALL_BEHAVIOUR` (что делают его установочные скрипты). Загрузка `.env` из рабочей папки и обращения к собственному API во время вызова инструмента находками не считаются. Почему пакет не запустился — по тому, что он напечатал: `HISTOR_PACKAGE_SDK_INCOMPATIBLE` (medium — написан под MCP SDK 1.x, поэтому свежая установка с `mcp` 2.x падает при импорте; если HISTOR запускал его и с `mcp<2`, — сколько инструментов он тогда отдал), `HISTOR_PACKAGE_NEEDS_CONFIG` (info — ключ или настройка, которые он потребовал, либо то, что его инструменты прочитаны с заглушками для них) и `HISTOR_PACKAGE_KEY_SENT_TO` (low — куда он отправил ключ-заглушку HISTOR; проверьте, что это собственный API сервиса). Все находки песочницы получены в одних условиях: Linux под gVisor, без интернета, приманки вместо секретов ([условия проверки](https://histor.modelmarket.dev/#conditions)). С `--histor` отчёт также даёт ссылку на ленту HISTOR с изменениями тех просканированных серверов, которые HISTOR знает (`historWatch` в `--json`): на неё можно подписаться в любом читателе лент.
+Stdio-сервер, запущенный из публичного реестра npm или PyPI (`npx`, `bunx`, `npm exec`, `pnpm dlx`, `uvx`, `uv tool run`, `pipx run`), называется по пакету — `npm:<имя>` или `pypi:<имя>`, без версии — с тем же дайджестом. HISTOR ставит каждую опубликованную версию такого пакета в песочнице gVisor (приманки вместо секретов, без маршрута наружу; каждый инструмент вызывается один раз с подставными аргументами, ни на что настоящее не действуя) и записывает его инструменты и то, что он делал, поэтому `previously-observed` здесь значит, что у вас более старая версия, а `different` — версия, до которой HISTOR ещё не дошёл, пакет, чьи инструменты зависят от того, что есть на вашей машине и чего нет в песочнице (запускатель, который передаёт работу установленной локально программе, настоящий ключ или настройка), или пакет, который не совпадает с опубликованным. В находке указано число инструментов с обеих сторон. Локальный путь, git- или tarball-адрес, частный реестр (`--registry`, `--index-url`) или простой запуск `node`/`python` не отправляются никогда. Для пакета HISTOR также сообщает, рекомендательными находками, не подражает ли его имя популярному (`HISTOR_PACKAGE_LOOKALIKE`: на один символ, то же имя под другим scope или с другими разделителями, при том что популярный скачивают хотя бы в 100 раз чаще) и нет ли у прочитанной версии признаков украденного токена публикации: `HISTOR_PACKAGE_PROVENANCE_LOST` (нет подтверждённой сборки в CI, хотя у предыдущей версии была), `HISTOR_PACKAGE_INSTALL_SCRIPTS` (появились установочные скрипты), `HISTOR_PACKAGE_PUBLISHER_CHANGED`, `HISTOR_PACKAGE_NEW_DEPENDENCIES`. И что пакет делал в песочнице: `HISTOR_PACKAGE_READS_SECRETS` (открыл приманки — SSH-ключи, токены облаков или реестров, кошелёк — при установке, при запуске или при вызове инструмента), `HISTOR_PACKAGE_PERSISTENCE` (писал туда, где пережил бы сессию, например в `.bashrc` или `authorized_keys`), `HISTOR_PACKAGE_STARTUP_NETWORK` (выходил в сеть до вызова любого инструмента), `HISTOR_PACKAGE_STARTS_PROGRAMS`, `HISTOR_PACKAGE_INSTALL_BEHAVIOUR` (что делают его установочные скрипты). Загрузка `.env` из рабочей папки и обращения к собственному API во время вызова инструмента находками не считаются. Почему пакет не запустился — по тому, что он напечатал: `HISTOR_PACKAGE_SDK_INCOMPATIBLE` (medium — написан под MCP SDK 1.x, поэтому свежая установка с `mcp` 2.x падает при импорте; если HISTOR запускал его и с `mcp<2`, — сколько инструментов он тогда отдал), `HISTOR_PACKAGE_NEEDS_CONFIG` (info — ключ или настройка, которые он потребовал, либо то, что его инструменты прочитаны с заглушками для них) и `HISTOR_PACKAGE_KEY_SENT_TO` (low — куда он отправил ключ-заглушку HISTOR; проверьте, что это собственный API сервиса). Все находки песочницы получены в одних условиях: Linux под gVisor, без интернета, приманки вместо секретов ([условия проверки](https://histor.modelmarket.dev/#conditions)). С `--histor` отчёт также даёт ссылку на ленту HISTOR с изменениями тех просканированных серверов, которые HISTOR знает (`historWatch` в `--json`): на неё можно подписаться в любом читателе лент.
 
 | Ответ | Значение |
 |---|---|
 | `same` | Вам отдали тот набор, который HISTOR видит сейчас |
-| `different` | HISTOR никогда не видел этот набор: он изменился после последнего ежедневного обхода, или сервер отдаёт вам не то, что публичному краулеру. Попадает в отчёт как рекомендательная находка `HISTOR_UNSEEN_TOOLSET` |
+| `different` | HISTOR никогда не видел этот набор: он изменился после последнего ежедневного обхода, или сервер отдаёт вам не то, что публичному краулеру. Для пакета ещё: его инструменты зависят от того, что есть на вашей машине (см. выше). Попадает в отчёт как рекомендательная находка `HISTOR_UNSEEN_TOOLSET` |
 | `previously-observed` | Набор, который HISTOR видел раньше, но не текущий. Рекомендательная находка `HISTOR_OLDER_TOOLSET` |
 | `not-listed`, `not-observed` | HISTOR не знает этот эндпоинт или ещё ни разу не прочитал его успешно |
 
+Если полученный набор издатель сервера заявляет в своей записи в реестре ([как издатель заявляет набор](https://github.com/alexar76/histor/blob/main/docs/api.ru.md)) — например, инструменты запускателя там, где установлена его программа, — находка будет `HISTOR_DECLARED_TOOLSET` вместо `HISTOR_UNSEEN_TOOLSET`: low, или info, если у HISTOR нет своего набора, с условием издателя его словами. Это слово издателя, а не наблюдение, и все остальные проверки по-прежнему читают инструменты.
+
 Ответы HISTOR никогда не блокируют. Если HISTOR недоступен, это попадает в отчёт, а проверка продолжается.
 
+## Для издателей: заявите наборы инструментов своего сервера
+
+HISTOR может записать только те инструменты, которые ваш сервер отдаёт в его песочнице. Если там, где установлено то, чего в песочнице нет, — раннер запускателя, по одному на ОС, настоящий ключ, — сервер отдаёт другие, заявите эти наборы, и те, кто их получает, увидят `HISTOR_DECLARED_TOOLSET` (low) вместо `HISTOR_UNSEEN_TOOLSET` (medium). На машине, которая получает набор:
+
+```bash
+npx -y @aimarket/warden declare --when "runner 1.4, macOS" --out mcp-tool-sets.json -- npx -y @acme/launcher
+```
+
+WARDEN запускает сервер так же, как клиент, считает дайджест его `tools/list` (MTL/1) и добавляет набор в `mcp-tool-sets.json`, сохраняя уже записанные наборы и заменяя тот же дайджест. Повторите на каждой ОС и версии раннера. Затем:
+
+1. Опубликуйте файл на домене, который реестр проверил для пространства имён вашего сервера, — `ai.acme/launcher` → `acme.ai` или поддомен; `io.github.<user>/…` → `<user>.github.io` или ваши raw-файлы на GitHub, — например по адресу `https://acme.ai/.well-known/mcp-tool-sets.json`.
+2. Один раз сошлитесь на него из записи в реестре: `npx -y @aimarket/warden declare --server-json --link <url>` печатает блок `_meta` для `server.json`; опубликуйте эту версию в реестре.
+3. Проверьте: `npx -y @aimarket/warden declare --check <url> --name ai.acme/launcher` читает файл так же, как прочтёт HISTOR, и говорит, что HISTOR из него возьмёт.
+
+Дальше для выпуска раннера нужны только `declare --out` и повторная загрузка файла: HISTOR перечитывает его каждый час. Набор, который вы убрали из файла, отзывается; файл, который HISTOR не смог прочитать, сохраняет заявленное. Без файла `--server-json` с сервером после `--` кладёт набор прямо в запись, до 8 наборов. Правила, которые применяет HISTOR: [заявленные наборы](https://github.com/alexar76/histor/blob/main/docs/api.ru.md). Заявление — слово издателя, а не наблюдение: WARDEN по-прежнему выполняет все проверки над инструментами, которые получил.
+
 ## Необязательный классификатор
 
 Правила WARDEN работают офлайн и детерминированно, и они пропускают то, что не названо ни одним правилом: перефразировку, инструкцию на другом языке. `--classifier-url` и `--classifier-model` добавляют второе мнение модели, которую выбираете вы, через любой OpenAI-совместимый адрес: локальный Ollama, vLLM или LM Studio либо облачный API.

package/docs/scan.zh.md

@@ -133,17 +133,35 @@ repos:
 
 发送的内容：端点（只有协议、主机和路径，不含 query、用户名或密码），以及工具集的 [MTL/1](https://github.com/alexar76/awr) 摘要。不发送任何工具描述或请求头。私有主机或地址上的端点，以及看起来带有密钥的路径，根本不会发送；报告会说明原因。
 
-从公共 npm 或 PyPI 注册表启动的 stdio 服务器（`npx`、`bunx`、`npm exec`、`pnpm dlx`、`uvx`、`uv tool run`、`pipx run`）以其软件包命名——`npm:<名称>` 或 `pypi:<名称>`，不带版本——并附上同样的摘要。HISTOR 会在 gVisor 沙箱中（诱饵凭据、无对外路由；每个工具用金丝雀参数调用一次，不作用于任何真实对象）并记录其工具及其行为安装这类软件包的每个已发布版本并记录其工具，因此这里的 `previously-observed` 表示你运行的是较旧的版本，`different` 表示 HISTOR 尚未覆盖到的版本，或者与已发布版本不一致的软件包。本地路径、git 或 tarball 地址、私有注册表（`--registry`、`--index-url`）以及直接用 `node`/`python` 启动的服务器，永远不会被发送。 对于软件包，HISTOR 还会以提示性发现告诉你：它的名称是否在模仿热门软件包（`HISTOR_PACKAGE_LOOKALIKE`：相差一个字符、在另一个 scope 下同名或仅分隔符不同，且热门软件包的下载量至少高 100 倍），以及所观察的版本是否带有发布令牌被盗的迹象：`HISTOR_PACKAGE_PROVENANCE_LOST`（上一个版本有经证明的 CI 构建，这个版本没有）、`HISTOR_PACKAGE_INSTALL_SCRIPTS`（新增安装脚本）、`HISTOR_PACKAGE_PUBLISHER_CHANGED`、`HISTOR_PACKAGE_NEW_DEPENDENCIES`。 以及软件包在沙箱中的行为：`HISTOR_PACKAGE_READS_SECRETS`（在安装、启动或工具被调用时打开了诱饵凭据——SSH 密钥、云或注册表令牌、钱包），`HISTOR_PACKAGE_PERSISTENCE`（写入了会在会话之后留存的位置，例如 `.bashrc` 或 `authorized_keys`），`HISTOR_PACKAGE_STARTUP_NETWORK`（在调用任何工具之前就访问了网络），`HISTOR_PACKAGE_STARTS_PROGRAMS`，`HISTOR_PACKAGE_INSTALL_BEHAVIOUR`（其安装脚本做了什么）。从工作目录加载 `.env`、在工具调用期间访问其自身 API，都不算发现。软件包为何没有启动——依据它打印的内容：`HISTOR_PACKAGE_SDK_INCOMPATIBLE`（medium——为 MCP SDK 1.x 编写，因此用 `mcp` 2.x 全新安装会在导入时失败；如果 HISTOR 也用 `mcp<2` 运行过它，则给出当时列出的工具数量）、`HISTOR_PACKAGE_NEEDS_CONFIG`（info——它要求的密钥或设置，或其工具是在占位值下读取的）以及 `HISTOR_PACKAGE_KEY_SENT_TO`（low——它把 HISTOR 设置的占位密钥发送到了哪里；请确认那是该服务自己的 API）。所有沙箱发现都来自相同的条件：gVisor 下的 Linux、无互联网、诱饵机密（[测试条件](https://histor.modelmarket.dev/#conditions)）。 使用 `--histor` 时，报告还会给出一个 HISTOR 订阅源链接，包含 HISTOR 已知的被扫描服务器的变更（`--json` 中的 `historWatch`）：可在任意订阅阅读器中订阅。
+从公共 npm 或 PyPI 注册表启动的 stdio 服务器（`npx`、`bunx`、`npm exec`、`pnpm dlx`、`uvx`、`uv tool run`、`pipx run`）以其软件包命名——`npm:<名称>` 或 `pypi:<名称>`，不带版本——并附上同样的摘要。HISTOR 会在 gVisor 沙箱中（诱饵凭据、无对外路由；每个工具用金丝雀参数调用一次，不作用于任何真实对象）安装这类软件包的每个已发布版本，并记录其工具及其行为，因此这里的 `previously-observed` 表示你运行的是较旧的版本，`different` 表示 HISTOR 尚未覆盖到的版本、工具取决于你的机器上有而沙箱里没有的东西的软件包（把工作交给本地已安装程序的启动器、真实的密钥或设置），或者与已发布版本不一致的软件包。该发现会给出双方各自的工具数量。本地路径、git 或 tarball 地址、私有注册表（`--registry`、`--index-url`）以及直接用 `node`/`python` 启动的服务器，永远不会被发送。 对于软件包，HISTOR 还会以提示性发现告诉你：它的名称是否在模仿热门软件包（`HISTOR_PACKAGE_LOOKALIKE`：相差一个字符、在另一个 scope 下同名或仅分隔符不同，且热门软件包的下载量至少高 100 倍），以及所观察的版本是否带有发布令牌被盗的迹象：`HISTOR_PACKAGE_PROVENANCE_LOST`（上一个版本有经证明的 CI 构建，这个版本没有）、`HISTOR_PACKAGE_INSTALL_SCRIPTS`（新增安装脚本）、`HISTOR_PACKAGE_PUBLISHER_CHANGED`、`HISTOR_PACKAGE_NEW_DEPENDENCIES`。 以及软件包在沙箱中的行为：`HISTOR_PACKAGE_READS_SECRETS`（在安装、启动或工具被调用时打开了诱饵凭据——SSH 密钥、云或注册表令牌、钱包），`HISTOR_PACKAGE_PERSISTENCE`（写入了会在会话之后留存的位置，例如 `.bashrc` 或 `authorized_keys`），`HISTOR_PACKAGE_STARTUP_NETWORK`（在调用任何工具之前就访问了网络），`HISTOR_PACKAGE_STARTS_PROGRAMS`，`HISTOR_PACKAGE_INSTALL_BEHAVIOUR`（其安装脚本做了什么）。从工作目录加载 `.env`、在工具调用期间访问其自身 API，都不算发现。软件包为何没有启动——依据它打印的内容：`HISTOR_PACKAGE_SDK_INCOMPATIBLE`（medium——为 MCP SDK 1.x 编写，因此用 `mcp` 2.x 全新安装会在导入时失败；如果 HISTOR 也用 `mcp<2` 运行过它，则给出当时列出的工具数量）、`HISTOR_PACKAGE_NEEDS_CONFIG`（info——它要求的密钥或设置，或其工具是在占位值下读取的）以及 `HISTOR_PACKAGE_KEY_SENT_TO`（low——它把 HISTOR 设置的占位密钥发送到了哪里；请确认那是该服务自己的 API）。所有沙箱发现都来自相同的条件：gVisor 下的 Linux、无互联网、诱饵机密（[测试条件](https://histor.modelmarket.dev/#conditions)）。 使用 `--histor` 时，报告还会给出一个 HISTOR 订阅源链接，包含 HISTOR 已知的被扫描服务器的变更（`--json` 中的 `historWatch`）：可在任意订阅阅读器中订阅。
 
 | 回答 | 含义 |
 |---|---|
 | `same` | 你收到的就是 HISTOR 当前观察到的工具集 |
-| `different` | HISTOR 从未见过这个工具集：它在最近一次每日抓取之后发生了变化，或者服务器给你的内容与给公开爬虫的不同。以仅作建议的发现 `HISTOR_UNSEEN_TOOLSET` 报告 |
+| `different` | HISTOR 从未见过这个工具集：它在最近一次每日抓取之后发生了变化，或者服务器给你的内容与给公开爬虫的不同。对于软件包，还可能是：它的工具取决于你的机器上有什么（见上文）。以仅作建议的发现 `HISTOR_UNSEEN_TOOLSET` 报告 |
 | `previously-observed` | HISTOR 以前见过、但不是当前的工具集。仅作建议的发现 `HISTOR_OLDER_TOOLSET` |
 | `not-listed`、`not-observed` | HISTOR 不认识这个端点，或尚未成功读取过它 |
 
+如果你拿到的工具集是服务器发布者在其注册表条目中声明的工具集（[发布者如何声明工具集](https://github.com/alexar76/histor/blob/main/docs/api.zh.md)），例如启动器在其程序已安装的机器上给出的工具，发现会是 `HISTOR_DECLARED_TOOLSET` 而不是 `HISTOR_UNSEEN_TOOLSET`：low，当 HISTOR 没有自己的工具集时为 info，并附上发布者原话写的条件。这是发布者的说法，不是观测，其他所有检查仍会读取这些工具。
+
 HISTOR 的回答从不阻止。HISTOR 没有响应时会在报告中注明，扫描继续进行。
 
+## 面向发布者：声明你的服务器的工具集
+
+HISTOR 只能记录你的服务器在其沙箱中列出的工具。如果在安装了沙箱所没有的东西的地方——启动器的运行器、每个操作系统各一个、真实的密钥——它列出的是别的工具，就声明这些工具集，拿到它们的人看到的将是 `HISTOR_DECLARED_TOOLSET`（low），而不是 `HISTOR_UNSEEN_TOOLSET`（medium）。在能拿到该工具集的机器上：
+
+```bash
+npx -y @aimarket/warden declare --when "runner 1.4, macOS" --out mcp-tool-sets.json -- npx -y @acme/launcher
+```
+
+WARDEN 会像客户端一样启动服务器，计算其 `tools/list` 的摘要（MTL/1），并把该工具集加入 `mcp-tool-sets.json`，保留已有的工具集并替换相同的摘要。在每个操作系统和每个运行器版本上重复。然后：
+
+1. 把文件发布到注册表为你的服务器命名空间验证过的域名上——`ai.acme/launcher` → `acme.ai` 或其子域名；`io.github.<user>/…` → `<user>.github.io` 或你在 GitHub 上的 raw 文件——例如 `https://acme.ai/.well-known/mcp-tool-sets.json`。
+2. 让注册表条目指向它，只需一次：`npx -y @aimarket/warden declare --server-json --link <url>` 打印 `server.json` 的 `_meta` 块；把这个版本发布到注册表。
+3. 检查：`npx -y @aimarket/warden declare --check <url> --name ai.acme/launcher` 按 HISTOR 的方式读取文件，并说明 HISTOR 会从中采用什么。
+
+此后，发布新的运行器只需要 `declare --out` 并重新上传文件：HISTOR 每小时读取一次。从文件中删去的工具集会被撤回；HISTOR 无法读取的文件会保留其声明。不使用文件时，`--server-json` 加上 `--` 之后的服务器会把工具集直接放进条目，最多 8 个。HISTOR 采用的规则：[声明工具集](https://github.com/alexar76/histor/blob/main/docs/api.zh.md)。声明是发布者的说法，不是观测：WARDEN 仍会对拿到的工具执行全部检查。
+
 ## 可选的分类器
 
 WARDEN 的规则离线、确定性地运行，也会漏掉任何规则都没提到的内容：改写的说法、另一种语言的指令。`--classifier-url` 和 `--classifier-model` 通过任意 OpenAI 兼容端点，加入你所选模型的第二意见：本地的 Ollama、vLLM 或 LM Studio，或托管 API。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aimarket/warden",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "WARDEN — MCP security firewall. Stdio wrap proxy, inspection tools and library. Vets definitions before model exposure. Zero runtime dependencies.",
   "type": "module",
   "license": "MIT",
@@ -15,7 +15,7 @@
     "url": "https://github.com/alexar76/warden/issues"
   },
   "bin": {
-    "warden-mcp": "./dist/mcp-server.js"
+    "warden-mcp": "dist/mcp-server.js"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",