Назад к обновлениям
New releaseAug 21, 2026

mcp-stdio-shellguard v0.1.2

Комплексная защита для MCP stdio серверов: готовые обёртки guardExec/guardSpawn, CLI для аудита AST, эталонный MCP сервер. Закрывает класс уязвимостей stdio-RCE в 200k серверах от Ox-Security (LiteLLM CVE-2025-69256). MIT, TypeScript, Node >= 20.

Поделиться

Часть StudioMeyer MCP Stack — Создано на Майорке 🌴 · ⭐ если вы это используете

mcp-stdio-shellguard

npm version npm downloads License Last commit GitHub stars

Комплекс многоуровневой защиты для MCP stdio-серверов. Оборачивает `child_process.exec/spawn`

с помощью allowlist + sandbox + обнаружения повторов, а также включает CLI-аудит на основе AST (mcp-shellguard-audit), который сканирует исходники MCP-серверов на наличие несанитизированных вызовов оболочки. Закрывает класс уязвимостей MCP stdio-RCE, описанный Ox-Security (200 тыс. уязвимых серверов, раскрытие в мае 2026 г.).

  • Спецификация MCP: 2025-06-18
  • SDK: @modelcontextprotocol/sdk ^1.29.0
  • Node: >= 20
  • Лицензия: MIT
  • Автор: Matthias Meyer (StudioMeyer)

Установка

npm install mcp-stdio-shellguard

Или запустите CLI аудита напрямую без установки:

npx -y -p mcp-stdio-shellguard mcp-shellguard-audit scan ./src

Содержимое пакета и сопровождение

Версия 0.1.3 включает пакет зависимостей, описанный ниже.

Пакет поставляется с @typescript-eslint/typescript-estree, а также TypeScript и необходимым замыканием зависимостей парсера через bundledDependencies. Переопределение npm только на уровне корня не ограничивает дерево зависимостей установленного пакета; включённое замыкание передаёт проверенные версии потребителям. Подготовка пакета проверяет @typescript-eslint/typescript-estree 8.72.1 и minimatch 11.0.3, затем изменяет только диапазон зависимости в манифесте парсера с minimatch ^10.2.2 на ^11.0.3. Исходные файлы сторонних разработчиков и номера версий пакетов не изменяются. Аудит AST вызывает typescript-estree.parse напрямую, при этом TypeScript включён явно для удовлетворения дерева зависимостей парсера; среда выполнения ESLint не требуется.

Измеренный архив составляет примерно 4,92 МБ в сжатом виде и 26,04 МБ в распакованном (десятичные МБ). Объединение в пакет увеличивает объём загрузки и использование диска; обновление безопасности включённой зависимости требует обновлённого архива пакета.

Для сопровождения выполните npm ci и npm run test:consumer из рабочей копии репозитория. npm pack автоматически запускает prepack: он собирает пакет и подготавливает объявленный набор. Проверка потребителя упаковывает дважды, проверяет идентичность байтов, устанавливает фактический архив в новый проект, проверяет npm ls и оба аудита зависимостей, а также проверяет работу установленного CLI или среды выполнения. Просматривайте обновления зависимостей вместе с зафиксированным набором и подтверждениями лицензий перед распространением нового архива. Файл dist/bundled-dependencies.json в архиве фиксирует набор и корректировки манифеста.

Что это даёт

Три уровня, подключаемые по частям:

  1. Библиотечный API — готовые к использованию guardExec / guardSpawn, которые вы вызываете из собственного MCP-сервера. Список разрешений по принципу запрета по умолчанию, профили песочницы, окно воспроизведения.
  2. CLI аудита — mcp-shellguard-audit scan <path> обходит AST и сообщает о 12 антипаттернах от LOW (no timeout) до CRITICAL (exec(\...${userInput}...`)`).
  3. Эталонный MCP-сервер — mcp-stdio-shellguard-demo предоставляет 8 инструментов, чтобы MCP Inspector / Claude Desktop могли напрямую управлять набором.

Инструменты (эталонный сервер)

ИнструментТипНазначение
guard_execдеструктивныйЗащищённый child_process.exec. Принудительно использует вектор args[], список разрешений + песочницу + воспроизведение. Возвращает stdout, stderr, exitCode, canonicalHash, isReplay, trustTier.
guard_spawnдеструктивныйЗащищённый child_process.spawn. Возвращает SHA-256 хеши stdout/stderr вместо полных тел. Жёстко отклоняет shell:true.
register_allowlistизменяющийРегистрирует имя инструмента с исполняемым файлом + регулярным выражением args. Без регистрации применяется запрет по умолчанию.
audit_sourceтолько чтениеСканирует путь TS/JS на антипаттерны shell-инъекций. Возвращает AuditFinding[] + сводку.
audit_reportтолько чтениеФорматирует результат аудита как markdown / json / SARIF 2.1.0.
replay_checkтолько чтениеВычисляет канонический SHA-256 хеш для вызова и сообщает, находится ли он уже в окне воспроизведения.
sandbox_statusтолько чтениеСообщает активный профиль песочницы + конкретные лимиты + флаг активности cgroup-v2.
trust_tierтолько чтениеОпределяет уровень LOW/MEDIUM/HIGH/CRITICAL для зарегистрированного инструмента плюс подсказки по улучшению.

Профили песочницы

ПрофильТайм-аутМакс. stdoutМакс. stderrБюджет FDcgroup-v2
strict5 с1 МБ256 КБ32да (cpu/memory)
standard (по умолчанию)30 с10 МБ1 МБ256да
permissive5 мин100 МБ10 МБ1024нет

Вызывающая сторона может ужесточить ограничения через timeoutMs / fdBudget для каждого вызова. Вызывающая сторона не может расширить их сверх профиля.

Уровни доверия

УровеньУсловие
LOWинструмент не зарегистрирован (запрет по умолчанию)
MEDIUMзарегистрирован, но argsPatterns пуст (разрешены любые args)
HIGHargsPatterns задан, но песочница или трекер воспроизведения неактивны
CRITICALargsPatterns + песочница + воспроизведение все активны

Повышение с LOW → CRITICAL путём регистрации инструмента + настройки argsPatterns + запуска через guardExec/guardSpawn (которые всегда активируют песочницу + воспроизведение).

Быстрый старт библиотеки

import {
  AllowlistRegistry,
  ReplayWindow,
  guardExec,
} from "mcp-stdio-shellguard";

const registry = new AllowlistRegistry();
const replay = new ReplayWindow();

registry.register({
  toolName: "git-log",
  executable: "/usr/bin/git",
  argsPatterns: ["^log$", "^--oneline$", "^-n$", "^\\d+$"],
  sandboxProfile: "strict",
});

const result = await guardExec(
  {
    toolName: "git-log",
    command: "/usr/bin/git",
    args: ["log", "--oneline", "-n", "10"],
  },
  { registry, replay },
);

console.log(result.stdout); // → commit lines
console.log(result.trustTier); // → "CRITICAL"
console.log(result.canonicalHash); // → 64-char SHA-256

Audit CLI

mcp-shellguard-audit scan ./src
mcp-shellguard-audit scan ./src --format sarif --output audit.sarif
mcp-shellguard-audit scan ./src --severity-floor HIGH    # CI gate

Коды выхода:

  • 0 — чисто (нет находок на уровне порога или выше)
  • 1 — есть находки
  • 2 — ошибки разбора / ввода-вывода

Пользовательские ignoreGlobs, передаваемые в scanPath или в MCP-инструмент audit_source, принимают не более 128 строк. Каждая строка ограничена 1024 кодовыми единицами UTF-16 и 16 неэкранированными открывающими группирующими символами ((, {, [). Входные данные, превышающие эти лимиты, вызывают контролируемую ошибку до начала сопоставления.

Библиотека антипаттернов (12 правил)

Категории