MCP Tool Security Inspector

Объяснимый, детерминированный статический анализ метаданных инструментов Model Context Protocol.

Заявление о безопасности: MCP Tool Security Inspector — это инструмент защитного анализа. Он выявляет индикаторы, которые могут потребовать проверки, но не устанавливает, является ли MCP-инструмент или сервер однозначно вредоносным или безопасным.

Заглушки для скриншотов

• screenshots/clean-scan.png — сводка чистой каталогизации

• screenshots/suspicious-scan.png — доказательства находок и рекомендации

• screenshots/drift-comparison.png — таблица отклонений от базовой линии

Related MCP server: mcp-guardian

Проблема

ИИ-клиенты часто предоставляют модели имена MCP-инструментов, описания, схемы и метаданные. Этот каталог является границей доверия: вводящие в заблуждение инструкции, скрытые возможности, неожиданные поля учетных данных или последующие изменения схемы заслуживают проверки, даже если ни один инструмент не был запущен. mcpsec анализирует эту статическую поверхность без вызова инструментов или получения URL-адресов метаданных.

Что такое MCP и MCP-инструменты?

Model Context Protocol — это открытый протокол для подключения ИИ-приложений к серверам, предоставляющим контекст и возможности. Инструмент — это именованная вызываемая возможность с описательными метаданными и JSON-схемами для входных и необязательных выходных данных. Этот выпуск ориентирован на официальную спецификацию от 2026-07-28 и стабильный официальный Python SDK v2, при этом допускает более старые распространенные оболочки каталога.

Модель угроз и отравление инструментов

Метаданные инструментов могут влиять как на одобрение человеком, так и на выбор инструментов моделью. Злонамеренный издатель, скомпрометированный сервер, зависимость или случайная конфигурация могут добавить инструкции, направленные на модель, формулировки скрытия, привилегированные поля или обфускацию. См. модель угроз и отравление инструментов.

Возможности

• Загрузка одного инструмента, массива, прямого объекта tools и ответа JSON-RPC tools/list

• Сохранение неизвестных полей и нормализация Unicode NFC

• Стабильный канонический JSON в UTF-8 и SHA-256 полные/компонентные отпечатки

• Конфиденциальные базовые линии и классификация отклонений на уровне полей

• Детекторы переопределения инструкций, скрытия, конфиденциальных данных, схем, несоответствий, обфускации и возможностей

• Строгие правила YAML только для данных с безопасной загрузкой и ограниченным сопоставлением литералов

• Объяснимые, ограниченные оценки риска от 0 до 100

• Богатый вывод в терминал, JSON, CSV и SARIF 2.1.0

• Редактирование доказательств и защита от инъекций формул в электронных таблицах

• Пороги серьезности для CI с документированными кодами выхода

• Без телеметрии, вызовов инструментов, загрузки иконок, получения URL-адресов или выполнения метаданных

Архитектура

flowchart LR
  A["Hostile JSON catalog"] --> B["Bounded loader"]
  B --> C["Normalizer"]
  C --> D["Canonicalizer + SHA-256"]
  C --> E["Detectors + data-only rules"]
  E --> F["Capped risk engine"]
  D --> G["Baseline comparator"]
  F --> H["Terminal / JSON / CSV / SARIF"]
  G --> H

Реализация никогда не отправляет содержимое каталога модели и никогда не выполняет сканируемые значения. См. архитектуру.

Установка

python -m venv .venv
# Windows: .\.venv\Scripts\Activate.ps1
# Linux/macOS: source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
mcpsec --help

См. PREPARATION.md для проверенной среды и рекомендаций по редактору.

Быстрый старт и сканирование

mcpsec scan examples/clean_tools.json
mcpsec scan examples/suspicious_tools.json
mcpsec scan examples/mixed_tools.json --format json
mcpsec scan examples/suspicious_tools.json --format csv --output report.csv --redact
mcpsec scan examples/suspicious_tools.json --format sarif --output report.sarif
mcpsec scan examples/mixed_tools.json --rules rules/default_rules.yml --fail-on high

Структурированные отчеты не содержат ANSI-escape-последовательностей. Поля CSV, начинающиеся с символов формул электронных таблиц, предваряются апострофом.

Рабочий процесс базовой линии и отклонения схемы

mcpsec baseline examples/clean_tools.json --output baseline.json
mcpsec compare examples/clean_tools.json --baseline baseline.json
mcpsec compare examples/changed_tools.json --baseline baseline.json --verbose
mcpsec fingerprint examples/clean_tools.json

Измененный фикстур изменяет описание калькулятора и входную схему, а также добавляет unit_converter. Базовые линии хранят хэши и структурные сводки, а не полные описания, значения по умолчанию или примеры секретов. См. отклонение схемы.

Оценка риска

Каждый вклад настроенной находки умножается на уверенность. Вклады группируются и ограничиваются 35 на категорию; риски категорий объединяются с использованием 100 × (1 − Π(1 − категория/100)). Две документированные корреляции добавляют ограниченную синергию: переопределение инструкций + скрытие добавляет 10, а скрытие + язык конфиденциальных данных добавляет 7. Итоговое значение округляется и ограничивается 100.

Диапазоны: 0–19 информационный, 20–39 низкий, 40–59 средний, 60–79 высокий, 80–100 критический. Оценка приоритизирует проверку; это не вероятность и не вердикт.

Правила и объяснимость

mcpsec rules list
mcpsec rules validate rules/default_rules.yml
mcpsec explain SEC-001

Пользовательские правила позволяют задавать ID, имя, категорию, поля, литеральные шаблоны, серьезность, уверенность, оценку, рекомендацию, обоснование, допустимое использование и состояние включения. Они не могут содержать выражения Python, команды оболочки, импорты, шаблоны или исполняемые регулярные выражения. См. правила обнаружения.

Форматы вывода

Таблица терминала суммирует количество инструментов, итоги чистых/затронутых, серьезность, риск, ID правил, доказательства и рекомендации. JSON сохраняет типизированные находки; CSV удобен для анализа; SARIF предоставляет структуру, совместимую с GitHub code scanning, для будущей интеграции.

Использование в CI

Коды выхода: 0 — нет превышения настроенного порога, 1 — завершенное сканирование превышает --fail-on, 2 — недопустимый пользовательский ввод, 3 — внутренняя ошибка.

mcpsec scan catalog.json --fail-on medium

Включенный рабочий процесс GitHub Actions устанавливает Python, запускает проверки Ruff lint/format, mypy и pytest с покрытием. Он не требует секретов, не подключается к серверам и не публикует.

Тестирование

ruff check .
ruff format --check .
mypy src
python -m pytest --cov=mcpsec --cov-report=term-missing --cov-report=html

В Windows scripts\test.ps1 -q запускает правильный интерпретатор виртуальной среды, даже если среда не активирована. Используйте scripts\dev-inspector.ps1 для локального демонстрационного сервера; см. руководство по примеру сервера. Адрес /sandbox, выводимый Inspector, является внутренней конечной точкой iframe, а не основным пользовательским интерфейсом.

Тесты покрывают формы ввода, Unicode, канонизацию, хэши, базовые линии, отклонения, детекторы, ограничения риска, проверку правил, безопасный YAML, структурированные отчеты, нейтрализацию CSV и коды выхода CLI.

Модель безопасности и ложные срабатывания

Все входные данные считаются ненадежными. Файлы ограничены по размеру; строки ограничены по длине; YAML использует safe_load; содержимое схемы проверяется, но никогда не выполняется; пользовательское сопоставление является литеральным и ограниченным; байты терминальных escape-последовательностей нейтрализуются; отчеты не отображают HTML. Находка говорит «подозрительно» или «требует проверки», но никогда не утверждает компрометацию. Каждое встроенное правило документирует свое обоснование, допустимые триггеры и рекомендации через mcpsec explain.

См. SECURITY.md, правила обнаружения и ограничения.

Ограничения

Чистое сканирование не устанавливает доверие; подозрительное сканирование не доказывает злонамеренность. Статические метаданные могут отличаться от реализации во время выполнения. Эвристики не могут понять каждый язык, бизнес-контекст, ссылку на схему или вариацию инъекции подсказок. Человеческая проверка и контроль во время выполнения остаются необходимыми.

Дорожная карта

• v0.2: опциональное получение локального каталога из белого списка с использованием только SDK tools/list

• Более полная проверка x-mcp-header для MCP 2026-07-28

• Подписанные конверты базовых линий и профили политик базовых линий

• Версионирование пакетов правил, подавления с обоснованием и дельта SARIF

• Дополнительные эвристики с учетом языка и измерение ложных срабатываний на основе корпуса

Вклад и лицензия

См. CONTRIBUTING.md. Отчеты о безопасности следуют SECURITY.md. Лицензировано под MIT License.