OPNsense MCP

Задавайте вопросы о вашем межсетевом экране на обычном языке.

Четыре инструмента только для чтения для OPNsense — по умолчанию только чтение, и они конкретно сообщают о том, что было проверено.

Быстрый старт · Инструменты · Руководство по настройке · Проверка · Статус

Предварительная версия: небольшой MCP-сервер, который позволяет ИИ-ассистенту проверять систему OPNsense и — только когда это явно включено — создавать или удалять один вид псевдонима межсетевого экрана в обёртке подтверждения, резервного копирования и аудита. По умолчанию он работает только на чтение. Упакованный сервер проверяется как на синтетической HTTPS-цели, так и на одноразовой виртуальной машине OPNsense 26.

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

Быстрый старт

Только чтение, около 15 минут. Требуется Node.js 22.19 или новее в пределах мажорной версии 22, на macOS или Linux.

1. Сохраните учётные данные вашего межсетевого экрана

npx -y @gabrielion/opnsense-mcp configure

Он запрашивает HTTPS-источник, ключ API и секрет, а также необязательный файл CA. Ничего не выводится на экран и ничего не передаётся в качестве аргумента процесса. Нужно сначала создать этот ключ? Руководство по настройке описывает сторону OPNsense со скриншотами.

2. Подключите вашего ассистента

claude mcp add opnsense --transport stdio --env READ_ONLY=true -- npx -y @gabrielion/opnsense-mcp

[mcp_servers.opnsense]
command = "npx"
args = ["-y", "@gabrielion/opnsense-mcp"]

[mcp_servers.opnsense.env]
READ_ONLY = "true"

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "opnsense": {
      "type": "local",
      "command": ["npx", "-y", "@gabrielion/opnsense-mcp"],
      "environment": { "READ_ONLY": "true" }
    }
  }
}

3. Задайте вопрос

Каков статус моей системы OPNsense?

Какие службы запущены на моём межсетевом экране?

Сначала выполните /mcp: сервер должен показать connected. Добавление не проверяет учётные данные, поэтому connected — это реальный сигнал.

[!TIP] Нет под рукой межсетевого экрана или не готовы направлять это на свой? npm run test:product1b запускает одноразовую виртуальную машину OPNsense, создаёт собственную учётную запись с минимальными привилегиями без ваших учётных данных, проверяет всю поверхность чтения на ней и выполняет очистку.

Related MCP server: OPNsense MCP Server

Что работает сейчас

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

• server_status проверяет процесс MCP и его состояние только для чтения.

• opn_describe объясняет видимый ресурс перед тем, как агент его использует.

• opn_get читает одиночный ресурс system.status.

• opn_list постранично перечисляет коллекционные ресурсы core.services и firewall.alias. Для псевдонимов он перечисляет только записи хостов, и указанное общее количество учитывает именно их; другие типы псевдонимов не отображаются.

Также всегда регистрируются три MCP-подсказки — diagnose_network_problem, publish_internal_service и block_domain_for_device. Они только создают план подготовки только для чтения; они ничего не выполняют.

READ_ONLY=true — значение по умолчанию, и при нём ни один инструмент записи не отображается и не может быть вызван.

Существуют два экспериментальных инструмента записи, opn_create и opn_delete, и они работают только с записями хостов firewall.alias. Три условия плюс поддерживаемый транспорт определяют, будут ли они вообще отображаться:

• READ_ONLY=false;

• ENABLED_FEATURE_FLAGS содержит experimental-alias-write;

• ALLOWED_RESOURCES явно указывает firewall.alias. Отсутствующий или пустой список разрешений разрешает все операции чтения и никакие операции записи. Список разрешений также фильтрует чтение, поэтому укажите все области, которые вам по-прежнему нужны, например ALLOWED_RESOURCES=server.status,system.status,core.services,firewall.alias;

• транспорт — stdio или Streamable HTTP. Устаревший SSE никогда не отображает и не вызывает их.

Четвёртое условие управляет вызовом, а не отображением: клиент должен согласовать формирование запроса. Клиент без этой возможности по-прежнему видит инструменты, но получает отказ с CONFIRMATION_UNAVAILABLE при каждой попытке, до любого вызова или записи.

Каждая операция записи выполняется по фиксированной схеме, в следующем порядке: авторизация, подтверждение человеком с указанием изменения, эксклюзивная блокировка цели, предварительная проверка без побочных эффектов, сокращённое намерение аудита, проверенная резервная копия до изменения, повторная проверка того, что наблюдаемое состояние не изменилось, сама запись, проверка результата, финальная запись аудита и снятие блокировки. Любой сбой после резервного копирования сохраняет его и никогда не выполняет слепое восстановление.

Эти операции записи экспериментальны не просто так. Резервная копия до изменения записывается во временный каталог, привязанный к процессу, который удаляется при завершении работы сервера, поэтому к ней нельзя обратиться впоследствии. Аудит — это кольцевой буфер в памяти, хранящий только последние 1024 записи (две на операцию записи), без постоянной формы и без инструмента для его чтения. Блокировка локальна для процесса, поэтому два сервера, направленных на один и тот же межсетевой экран, не исключают друг друга.

Что гарантирует эта схема — узко, но реально: операция записи отклоняется, если сначала не были записаны проверенная резервная копия и намерение аудита. Восстановления и отката нет — если сбой произошёл после применения изменения, изменение остаётся применённым, и восстановление выполняется вручную через собственную историю конфигурации OPNsense. Сделать это состояние постоянным — следующая веха.

Быстрая локальная проверка

Требования: Node.js 22.19 или новее в пределах мажорной версии 22, npm, macOS или Linux.

if test -x /opt/homebrew/opt/node@22/bin/node; then
  export PATH="/opt/homebrew/opt/node@22/bin:$PATH"
fi
node -e "const [major, minor] = process.versions.node.split('.').map(Number); process.exit(major === 22 && minor >= 19 ? 0 : 1)" &&
npm ci --ignore-scripts &&
npm run test:product1a &&
npm run build

npm run test:product1a создаёт чистый npm-архив, устанавливает его в изолированный проект-потребитель, подключает его к отдельно управляемой синтетической HTTPS-цели OPNsense, вызывает все три инструмента OPNsense через raw MCP stdio, проверяет, что секреты никогда не появляются, закрывается по EOF и удаляет все фикстуры.

Подключите ваш экземпляр OPNsense

Поддерживаемый способ предоставления учётных данных — интерактивная команда, которая записывает приватный файл за вас с правильными правами владения и режимами доступа. Из клона это подкоманда собранной точки входа:

if test -x /opt/homebrew/opt/node@22/bin/node; then
  export PATH="/opt/homebrew/opt/node@22/bin:$PATH"
fi
node -e "const [major, minor] = process.versions.node.split('.').map(Number); process.exit(major === 22 && minor >= 19 ? 0 : 1)" &&
node dist/main.js configure

Установленная из реестра, та же подкоманда — npx -y @gabrielion/opnsense-mcp configure.

Она запрашивает HTTPS-источник, ключ API, секрет API и необязательные файл CA и имя TLS-сервера; секреты никогда не выводятся на экран и никогда не появляются в аргументе процесса. Она отказывается работать на Windows и отклоняет любые аргументы.

Она всегда записывает в путь платформы и игнорирует OPNSENSE_CONFIG_FILE, который является переменной серверной стороны:

• macOS: ~/Library/Application Support/opnsense-mcp/config.json;

• Linux: $XDG_CONFIG_HOME/opnsense-mcp/config.json, иначе ~/.config/opnsense-mcp/config.json.

Сервер обнаруживает те же пути, поэтому переменная нужна только для чтения файла, хранящегося в другом месте. Каждый каталог, которым он владеет, создаётся с режимом 0700, а файл — с режимом 0600; символические ссылки, посторонние владельцы и небезопасные родительские каталоги отклоняются.

Два практических ограничения: он никогда не перезаписывает существующую конфигурацию, поэтому для ротации ключа сначала удалите файл; и ему требуется реальный терминал на обоих потоках, поэтому его нельзя использовать через конвейер или в CI. При каждом сбое намеренно выводится единственное слово Error — диагностика намеренно непрозрачна, чтобы ничего не утекало о приватном пути или учётных данных.

В качестве альтернативы создайте JSON-файл самостоятельно вне репозитория и защитите его режимом 0600:

{
  "url": "https://192.0.2.1",
  "apiKey": "your-dedicated-read-only-api-key",
  "apiSecret": "your-api-secret",
  "caFile": "/absolute/path/to/your-ca.pem",
  "tlsServerName": "firewall.example.internal"
}

Файл должен быть обычным файлом, не символической ссылкой, принадлежащим текущему пользователю, по абсолютному пути, с точно режимом 0600, ровно одной жёсткой ссылкой и размером не более 16 КиБ. 0400 также отклоняется. url должен быть одним точным HTTPS-источником. caFile необязателен, когда сертификат межсетевого экрана уже образует цепочку к доверенному CA. tlsServerName необязателен, когда в URL используется IP-адрес, но проверенный сертификат использует DNS-имя. Проверка TLS всегда остаётся включённой. Используйте выделенный ключ OPNsense с минимальными привилегиями; не вставляйте учётные данные в чат или аргументы команд.

Транспорты. stdio — по умолчанию и единственный транспорт, проверяемый сквозным образом упакованными доказательствами; dist/main.js всегда запускает stdio. Транспорт Streamable HTTP существует как отдельная точка входа (npm run start:http) за MCP_HTTP_ENABLED, привязанный к loopback со списком разрешённых Host/Origin и bearer-токеном MCP_HTTP_TOKEN длиной не менее 32 символов; он не покрыт клиентской проверкой, поэтому никаких заявлений о поддержке клиентов для него не делается. Устаревшая поверхность совместимости SSE существует за MCP_LEGACY_SSE_ENABLED, которая дополнительно требует MCP_HTTP_ENABLED=true — установка только её является ошибкой запуска — и никогда не предоставляет инструменты записи с подтверждением.

Для непосредственного запуска протокольно-чистого stdio-сервера:

if test -x /opt/homebrew/opt/node@22/bin/node; then
  export PATH="/opt/homebrew/opt/node@22/bin:$PATH"
fi
node -e "const [major, minor] = process.versions.node.split('.').map(Number); process.exit(major === 22 && minor >= 19 ? 0 : 1)" &&
OPNSENSE_CONFIG_FILE="/absolute/path/to/opnsense.json" READ_ONLY=true node dist/main.js

Никогда не направляйте разработку или тесты на производственный межсетевой экран. Для реальной работы используйте приведённое ниже доказательство на одноразовой виртуальной машине.

Доказательство на одноразовой OPNsense 26

На macOS или Linux установите QEMU и Node.js 22, затем выполните:

npm run vm:doctor
npm run test:product1b

vm:doctor сообщает о каждой отсутствующей зависимости хоста, не изменяя машину. test:product1b полностью владеет живым тестом: он проверяет и кэширует закреплённый официальный nano-образ OPNsense 26.7, запускает одну локальную виртуальную машину, создаёт одноразового пользователя API с минимальными привилегиями через последовательную консоль без каких-либо учётных данных оператора, упаковывает и устанавливает этот npm-пакет, вызывает server_status, opn_describe system.status, opn_get system.status и opn_list core.services через одну MCP-сессию, затем останавливает виртуальную машину и удаляет оверлей, учётные данные API, сертификат и временный пакет. Первый запуск загружает архив объёмом примерно 557 МБ и создаёт базовый образ только для чтения объёмом 3 ГиБ в пользовательском кэше.

Историческое доказательство Product 1B остаётся доказательством только для двух удалённых вызовов: GET /api/core/system/status и POST /api/core/service/search. Его очищенное машиночитаемое доказательство также фиксирует точный хост, QEMU, прошивку, транспорт и проверки очистки без сохранения данных межсетевого экрана или учётных данных.

Реализация записи псевдонимов нацелена на GET /api/core/backup/download/this для резервной копии до изменения, затем POST /api/firewall/alias/searchItem, addItem или delItem/{uuid}, затем применение reconfigure. Эти детали конечных точек имеют детерминированное покрытие на синтетической цели. Product 3 доказывает на одноразовой виртуальной машине только следующее: поверхность записи и этот точный жизненный цикл firewall.alias: отсутствует, создан, присутствует, удалён, отсутствует, с последующей очисткой виртуальной машины и проверкой отсутствия остатков. Привязанное к коммиту подтверждение виртуальной машины Product 3 фиксирует протестированный коммит и дерево, закреплённый образ прошивки, входные данные политики и фиксированные проверки жизненного цикла без сохранения данных межсетевого экрана или учётных данных. Подтверждение Product 3 не доказывает производственное использование, постоянное состояние, постоянные резервные копии, постоянный след аудита, восстановление или автоматический откат.

Цикл восстановления дополнительно отменяет ту же мутацию псевдонима непосредственно через консоль одноразовой виртуальной машины — не через API — а затем повторно наблюдает API, чтобы проверить, что мутация исчезла. Подтверждение виртуальной машины Product 3 для цикла восстановления фиксирует протестированный коммит и дерево, тот же закреплённый образ прошивки и входные данные политики, проверки жизненного цикла псевдонима и проверки восстановления из резервной копии и отката состояния, снова без сохранения данных межсетевого экрана или учётных данных, созданное с помощью node scripts/vm/product3-restore.mjs --attestation-out "$PWD/docs/evidence/product3-restore-vm.json".

Привилегии одноразовых учётных записей. Учётные записи создаются ровно с этими стандартными ACL и ничем больше. Оба профиля ACL имеют живые доказательства только в своих точных сценариях: профиль только для чтения — в Продукте 1B, а профиль записи алиасов — в Продукте 3.

• учётная запись только для чтения: page-system-status, page-status-services, user-config-readonly;

• учётная запись записи алиасов: page-system-status, page-status-services, page-diagnostics-configurationhistory, page-firewall-alias-edit.

user-config-readonly намеренно отсутствует в учётной записи записи алиасов: мы заметили, что он заставляет контроллер изменяемой модели OPNsense отклонять сохранение алиасов. page-diagnostics-configurationhistory выдаётся для запроса резервной копии конфигурации до изменения. Оба утверждения взяты из нашего собственного опыта начальной настройки, а не из цитируемого вышестоящего сопоставления.

OpenCode

Добавьте opencode.json на уровне проекта (замените оба абсолютных пути):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "opnsense": {
      "type": "local",
      "command": ["node", "/absolute/path/to/OPNSenseMCP/dist/main.js"],
      "environment": {
        "READ_ONLY": "true",
        "OPNSENSE_CONFIG_FILE": "/absolute/path/to/opnsense.json"
      }
    }
  }
}

Затем выполните opencode mcp list; opnsense должен быть подключён. Зафиксированные доказательства дымового теста охватывают только OpenCode 1.18.16 с opencode/deepseek-v4-flash-free против установленного tarball и синтетической HTTPS-цели. Они фиксируют дайджесты инструментов/результатов, а не данные межсетевого экрана или учётные данные. См. машиночитаемые доказательства.

Другие MCP-клиенты могут запускать ту же команду stdio, но никаких заявлений о поддержке конкретного клиента не делается, пока его собственный версионированный дымовой тест не пройдёт.

Как тестируется эта предварительная версия

• Строгий TypeScript, форматирование, lint, заголовки лицензий и детерминированные модульные/интеграционные тесты.

• Чистые npm pack/install плюс TLS, базовая аутентификация, проверка ответов, редактирование секретов, завершение работы и очистка против синтетической цели.

• Исторические чистые npm pack/install против одноразовой виртуальной машины OPNsense 26.1.6 для двух удалённых вызовов Продукта 1B, включая владение ВМ, целостность закреплённого образа, изолированные учётные данные, закрепление TLS и обратную очистку.

• Привязанный к коммиту прогон Продукта 3 против одноразовой виртуальной машины OPNsense 26.7 для поверхности записи и точного жизненного цикла алиасов хоста: отсутствует, создать, присутствует, удалить, отсутствует, с последующей очисткой ВМ и проверкой на отсутствие остатков.

• Герметичная установка пакета для доказательства синтетической цели и обоих раннеров ВМ: потребитель разрешает каждую зависимость из реестра npm только с обратной связью, производного от lock-файла, с пустым кэшем и недостижимыми прокси, так что доступ в Интернет не задействован, и ни один вышестоящий релиз не может изменить то, что установлено.

• Целевые проверки совместимости MCP для версий протокола 2025-11-25 и черновика 2026-07-28.

• Один реальный дымовой тест маршрутизации OpenCode 1.18.16 с использованием opencode/deepseek-v4-flash-free.

Полное состояние разработки и передача между машинами записаны в docs/project-status.md. Планируемая каноническая оценка агента указана в дизайне оценки DeepEval и OPNsense: она будет оценивать использование инструментов MCP и итоговый ответ Claude Code, отдельно требуя детерминированного чтения состояния одноразовой ВМ через MCP. Эти тесты и любой оценочный балл ещё не реализованы и не заявлены.

Вместе эти проверки охватывают пакет, синтетический путь чтения, два указанных исторических удалённых вызова Продукта 1B и не более чем ограниченный жизненный цикл, указанный выше. Они не доказывают:

• публичный DNS, ACME или HAProxy в Интернете;

• поведение против производственного межсетевого экрана;

• долговечные резервные копии или долговечный аудиторский след: оба существуют, но только на время жизни процесса;

• восстановление или любой автоматический откат применённого изменения;

• запись во что-либо, кроме записей хоста firewall.alias;

• какие-либо гарантии за пределами первых 100 алиасов хоста: дайджест состояния до изменения и чтение обратно читают одну страницу из 100, так что за этим пределом создание может сообщить о непроверенном результате, а удаление может доказать только то, что запись отсутствовала на прочитанной странице;

• нативную установку или работу клиента в Windows;

• полный агентный бенчмарк или оценочный балл.

Необработанный API-диспетчер, свободный shell/SSH, массовый IaC, панель управления и широкая совместимость с легаси отсутствуют.

Дорожная карта продукта и примеры запросов

Конверт безопасности мутаций — ограниченная авторизация, подтверждение человеком, проверенная резервная копия, редактируемый аудит, проверка результата, очистка с закрытием при сбое — реализован и доказан против синтетической HTTPS-цели. Следующая веха — сделать его состояние долговечным: постоянный корень состояния, межпроцессная блокировка, аудит только для добавления и локальная команда reconcile, чтобы гарантии переживали перезапуск. Только тогда можно будет пересмотреть метку experimental на записи алиасов.

Более поздние управляемые рабочие процессы намеренно являются целями уровня пользователя, например:

• «Мой ноутбук теряет Интернет каждый вечер. Можешь расследовать и объяснить, что ты нашёл?»

• «Заблокируй TikTok только для планшета моего ребёнка, не затрагивая другие устройства».

• «Опубликуй этот сервис внутренне с дружественным DNS-именем, внутренним сертификатом и обратным прокси».

Эти три рабочих процесса — примеры дорожной карты, а не заявления Продукта 1A. Публикация в Интернете с публичным DNS, Let's Encrypt и HAProxy — это долгосрочная лабораторная веха после безопасных записей и покрытия частных ВМ.

Статус распространения: опубликован на npm как @gabrielion/opnsense-mcp, так что npx -y @gabrielion/opnsense-mcp запускает выпущенный сервер; установка по git-URL по-прежнему собирает собственный dist/ через скрипт prepare. Упакованные доказательства в любом случае устанавливают локально собранный tarball, обслуживаемый реестром, производным от lock-файла, с обратной связью, так что они проверяют это дерево, а не любую копию реестра. Никаких гарантий версионирования или обновления пока не даётся.

Статус платформы: macOS и Linux — это в настоящее время проверенные хост-системы разработки. Нативный Windows остаётся обязательной целью продукта, но поддержка пакета и клиента не заявляется, пока не пройдёт более поздний шлюз windows-2025.

Лицензия и товарный знак

Лицензировано под AGPL-3.0-or-later; см. LICENSE. AGPL разрешает коммерческое использование, требуя доступности исходного кода, включая сетевое использование. OPNsense — товарный знак Deciso B.V. Этот независимый проект не аффилирован с Deciso B.V. или проектом OPNsense, не спонсируется ими и не одобряется ими.