
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
Комплекс многоуровневой защиты для 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 в архиве фиксирует набор и корректировки манифеста.
Что это даёт
Три уровня, подключаемые по частям:
- Библиотечный API — готовые к использованию
guardExec/guardSpawn, которые вы вызываете из собственного MCP-сервера. Список разрешений по принципу запрета по умолчанию, профили песочницы, окно воспроизведения. - CLI аудита —
mcp-shellguard-audit scan <path>обходит AST и сообщает о 12 антипаттернах от LOW (no timeout) до CRITICAL (exec(\...${userInput}...`)`). - Эталонный 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 | Бюджет FD | cgroup-v2 |
|---|---|---|---|---|---|
strict | 5 с | 1 МБ | 256 КБ | 32 | да (cpu/memory) |
standard (по умолчанию) | 30 с | 10 МБ | 1 МБ | 256 | да |
permissive | 5 мин | 100 МБ | 10 МБ | 1024 | нет |
Вызывающая сторона может ужесточить ограничения через timeoutMs / fdBudget для каждого вызова. Вызывающая сторона не может расширить
их сверх профиля.
Уровни доверия
| Уровень | Условие |
|---|---|
| LOW | инструмент не зарегистрирован (запрет по умолчанию) |
| MEDIUM | зарегистрирован, но argsPatterns пуст (разрешены любые args) |
| HIGH | argsPatterns задан, но песочница или трекер воспроизведения неактивны |
| CRITICAL | argsPatterns + песочница + воспроизведение все активны |
Повышение с 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 неэкранированными открывающими группирующими символами ((, {, [). Входные данные, превышающие эти лимиты, вызывают контролируемую ошибку до начала сопоставления.