OPNsense MCP

Удалённый сервер Model Context Protocol для MVC-API OPNsense с упором на безопасность. Он предоставляет удалённым агентам транспорт Streamable HTTP с сохранением состояния, использует собственную HTTP Basic-аутентификацию API при обращении к OPNsense и блокирует запрос в безопасном режиме (fail closed), когда не может однозначно определить, что команда OPNsense предназначена только для чтения.

Один экземпляр сервера соответствует одному межсетевому экрану OPNsense. URL межсетевого экрана и учётные данные API остаются в окружении сервера; агенты аутентифицируются в MCP с помощью отдельного bearer-токена и не могут перенаправлять запросы на произвольные сетевые цели. При управлении несколькими устройствами разворачивайте по одному изолированному экземпляру на каждый межсетевой экран.

Архитектура

Remote agent --HTTPS + MCP bearer token--> OPNsense MCP --HTTPS + API key/secret--> OPNsense

Конечная точка MCP использует актуальный транспорт Streamable HTTP по пути /mcp. Сеансы сохраняют состояние, поэтому одноразовые планы изменений остаются привязанными к MCP-сеансу агента. Число сеансов ограничено, они истекают после бездействия и проходят аутентификацию при каждом HTTP-запросе.

Встроенный HTTP-листенер предназначен для размещения за обратным TLS-прокси, контроллером входящего трафика, VPN или защищённой overlay-сетью. Не открывайте его порт с обычным HTTP напрямую в недоверенную сеть.

Модель API OPNsense

OPNsense направляет запросы API следующим образом:

/api/<module>/<controller>/<command>/<parameter...>

Важные с точки зрения автоматизации особенности:

• Ключи API используют проверку подлинности HTTP Basic: ключ — как имя пользователя, секрет — как пароль.

• Доступ по-прежнему ограничивается привилегиями ACL OPNsense владельца ключа.

• Запросы и большинство ответов имеют формат JSON. Скачиваемые файлы и потоки могут быть не JSON.

• GET и POST не сопоставляются напрямую с безопасными и небезопасными операциями. Некоторые операции чтения используют POST, а некоторые изменения — GET.

• Контроллеры изменяемых моделей обычно предоставляют операции get, search, add, set, del и toggle.

• Записи моделей-массивов используют UUID. Запрос get без UUID часто возвращает пустую запись, заполненную значениями по умолчанию.

• Успешное изменение модели обычно записывает отложенную (staged) конфигурацию. Для её активации нужен отдельный вызов apply или reconfigure.

• Записи моделей возвращают значения вида {"result":"saved"} или {"result":"failed","validations":...}; HTTP 200 сам по себе не доказывает успех на уровне семантики.

• Блокировка конфигурации OPNsense, проверка моделей, контекст ревизий и проверки ACL выполняются на стороне сервера, и их не следует обходить.

Официальные справочники:

• https://docs.opnsense.org/development/api.html

• https://docs.opnsense.org/development/how-tos/api.html

• https://docs.opnsense.org/development/architecture.html

• https://docs.opnsense.org/development/frontend/controller.html

• https://docs.opnsense.org/development/frontend/models_fieldtypes.html

• https://github.com/opnsense/core

• https://github.com/opnsense/plugins

Модель безопасности

opnsense_request принимает только команды, отнесённые к операциям чтения. Команда, на которой работает классификация, зависит от самой команды, а не от её HTTP-метода.

Изменяющие операции выполняются двумя инструментами:

• opnsense_plan_change сообщает точный запрос и его риск, не обращаясь к OPNsense.

• opnsense_execute_change требует соответствующий одноразовый токен, истекающий через пять минут.

Классы риска разделяют отложенные записи, активацию, разрушительные операции с сервисами и прошивкой, а также катастрофические операции сброса/восстановления. Неизвестные команды считаются мутациями и переводят систему в безопасный режим отказа (fail closed).

Режим записи управляется вне агента:

• disabled разрешает только чтение.

• plan разрешает анализ мутаций, но никогда не создаёт токен выполнения.

• enabled разрешает выполнение при наличии подходящего токена.

Используйте выделенного пользователя OPNsense и предоставьте ему только те результатные привилегии, которые требуются вашим инструментам. В развертываниях только с чтением также добавьте OPNsense разрешение System: Deny config write (user-config-readonly).

Курируемые инструменты чтения

Защищённый универсальный клиент дополнен фиксированными инструментами чтения для типовых задач:

• opnsense_get_firewall_logs читает структурированные события пакетного фильтра.

• opnsense_get_logs читает ограниченные страницы из основных журналов и журналов служб, включая системные журналы, configd, шлюзов, VPN, DNS, DHCP, IDS, маршрутизации и веб-интерфейса.

• opnsense_list_firewall_rules читает правила фильтрации, доступные API автоматизации.

• opnsense_list_nat_rules читает правила трансляции для адреса назначения, источника, схемы один-к-одному или NPT.

• opnsense_get_route_table читает либо текущую таблицу маршрутизации ядра, либо настроенные статические маршруты.

These tools напрямую обращаются к фиксированным конечным точкам запросов. Они не могут выбирают сопутствующие изменяющие действия, такие как очистка журналов, сброс сессий, изменение правил или применение конфигурации. Результаты по-прежнему ограничены привилегиями ACL пользователя API в OPNsense.

Настройка

npm install
npm run build

Настройте окружение по образцу .env.example. Файлы окружения не загружаются автоматически и игнорируются Git. Сгенерируйте отдельный MCP-токен командой openssl rand -hex 32; не повторно используйте учётные данные OPNsense API.

Предпочтение отдавайте публичному доверенному сертификату, либо задайте OPNSENSE_CA_FILE, указав сертификат частного удостоверяющего центра. Параметр OPNSENSE_TLS_VERIFY=false предназначен только для изолированной разработки.

Запустите удалённый сервер на loopback-адресе для локального TLS-прокси:

OPNSENSE_URL=https://firewall.example \
OPNSENSE_API_KEY=... \
OPNSENSE_API_SECRET=... \
MCP_AUTH_TOKEN=<random-token-at-least-32-characters> \
node dist/index.js

URL MCP — http://127.0.0.1:3000/mcp. Опубликуйте его как HTTPS через обратный прокси и передавайте токен так:

Authorization: Bearer <MCP_AUTH_TOKEN>

Пример конфигурации удалённого клиента для клиентов с поддержкой URL и произвольных заголовков:

{
  "mcpServers": {
    "opnsense": {
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${MCP_AUTH_TOKEN}"
      }
    }
  }
}

Форматы конфигурации клиентов различаются. Храните токен в секретном хранилище клиента, а не в конфигурационном файле.

Docker Compose

compose.yaml привязывает порт 3000 к loopback-адресу хоста, что позволяет обратному п Proxy безопасно завершать TLS.

export OPNSENSE_URL=https://firewall.example
export OPNSENSE_API_KEY=...
export OPNSENSE_API_SECRET=...
export MCP_AUTH_TOKEN="$(openssl rand -hex 32)"
export MCP_ALLOWED_HOSTS=mcp.example.com
docker compose up -d --build

При прямом подключении к localhost:3000 во время разработки включайте localhost в переменную MCP_ALLOWED_HOSTS. Неаутентифицированная конечная точка проверки состояния доступна по пути /health и не раскрывает сведения о целевом сервере или учётных данных.

Безопасность удалённого доступа

• MCP_AUTH_TOKEN обязателен для HTTP-транспорта и должен содержать минимум 32 символа.

• MCP_ALLOWED_HOSTS обязателен привязке к адресу за пределами loopback и предотвращает DNS-ребендинг через заголовок Host.

• Запросы с браузерным заголовком Origin отклоняются, если в MCP_ALLOWED_ORIGINS нет точного значения источника.

• MCP_MAX_SESSIONS, MCP_SESSION_TTL_MS и MCP_RATE_LIMIT_PER_MINUTE ограничивают потребление ресурсов удалёнными клиентами.

• Сохраняйте OPNSENSE_TLS_VERIFY=true. Для внутреннего удостоверяющего центра используйте OPNSENSE_CA_FILE, а не отключение проверки.

• Сохраняйте OPNSENSE_WRITE_MODE=disabled для развёртываний только для мониторинга.

• Ограничьте пользователя API OPNsense действующими привилегиями ACL и используйте user-config-readonly, где это уместно.

• Размещайте конечную точку MCP за HTTPS, политикой межуточного экрана и, желательно, VPN или частной сетью.

MCP_ALLOW_UNAUTHENTICATED=true существует только для изолированной локальной разработки и не должен использоваться на удалённо доступном листенере.

Совместимость со Stdio

Local клиенты могут по-прежнему запускать сервер как подпроцесс:

OPNSENSE_URL=https://firewall.example \
OPNSENSE_API_KEY=... \
OPNSENSE_API_SECRET=... \
MCP_TRANSPORT=stdio \
node dist/index.js

Конфигурация

• OPNSENSE_URL: фиксированный базовый URL межсетевого экрана.

• OPNSENSE_API_KEY: API-ключ для выделенного пользователя OPNsense.

• OPNSENSE_API_SECRET: API-секрет для этого ключа.

• OPNSENSE_WRITE_MODE: disabled, plan или enabled.

• OPNSENSE_CA_FILE: необязательный PEM-файл частного удостоверяющего центра.

• OPNSENSE_TLS_VERIFY: по умолчанию true.

• MCP_TRANSPORT: по умолчанию http или stdio.

• MCP_HOST: адрес листенера, по умолчанию 127.0.0.1.

• MCP_PORT: порт листенера, по умолчанию 3000.

• MCP_PATH: путь конечной точки MCP, по умолчанию /mcp.

• MCP_AUTH_TOKEN: Bearer-токен для удалённого агента.

• MCP_ALLOWED_HOSTS: список имён хостов через запятую, допустимых в HTTP-заголовке Host.

• MCP_ALLOWED_ORIGINS: допустимые sources браузера через запятую; пустое значение отклоняет браузерные запросы.

• MCP_MAX_SESSIONS: максимум одновременных сеансов, по умолчанию 100.

• MCP_SESSION_TTL_MS: время бездействия сеанса до завершения, по умолчанию один час.

• MCP_RATE_LIMIT_PER_MINUTE: лимит HTTP-запросов клиента в минуту, по умолчанию 120.

Например, для чтения информации о состоянии системаили через один из инструментов используется:

{
  "module": "core",
  "controller": "system",
  "command": "status"
}

Текущие ограничения

• OPNsense не опубликовывает полную спецификацию OpenAPI. Сгенерированный перечень определяет маршруты и вероятные методы, но обычно не содержит схемы тел запросов.

• Конечные точки плагинов доступны только при установленных пакетах и разрешающих их ACL-правилах.

• Семантическая проверка ответов ещё не привязана к конкретным конечным точкам.

• Лексический классификатор риска сознательно консервативен. Курируемые инструменты в перспективе должны опираться на проверенный манифест endpoints с явными схемами запросов и ответов.

• Плановые токены снижают риск случайного и несоответствующего выполнения, но MCP-хосты должны по-прежнему выносить утверждение разрушительных инструментов на решение человека.

• Удалённая аутентификация сейчас использует единый статический Bearer-токен для всего развёртывания, а не отдельный сервер авторизации OAuth. Для агентов с разными идентификаторами используйте отдельные развёрт или аутентифицирующий обратный прокси.

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