Docker images / prepare-release (push) Successful in 12s
Docker images / backend-test (push) Successful in 13m33s
Docker images / backend-image (push) Canceled after 0s
Docker images / frontend-image (push) Canceled after 3s
Docker images / updater-image (push) Canceled after 0s
Docker images / netflow-agent-image (push) Canceled after 0s
Docker images / publish-release (push) Canceled after 0s
Docker images / notify-webhook (push) Canceled after 0s
338 lines
30 KiB
Markdown
338 lines
30 KiB
Markdown
# Включение MCP: наблюдение → подтверждения → ограниченная автономность
|
||
|
||
Инструкция для администратора Manager. Она описывает, как дать внешнему AI-клиенту доступ через MCP в три шага, с проверкой на каждом шаге:
|
||
|
||
1. Наблюдение: агент только читает.
|
||
2. Подтверждения: агент готовит изменения, человек одобряет каждое.
|
||
3. Ограниченная автономность: агент применяет изменения сам, в узкой области и в пределах лимитов.
|
||
|
||
**По умолчанию всё выключено.** После установки:
|
||
|
||
- MCP выключен;
|
||
- профили Route AI выключены;
|
||
- автоматическое восстановление маршрутов выключено.
|
||
|
||
Это закреплено тестом на свежей базе (`integration.test.ts`). Подключений нет, пока администратор их не создаст.
|
||
|
||
Названия в кавычках «…» — надписи в интерфейсе, раздел «Система» → «MCP» в Manager. Общее описание MCP — [mcp.md](mcp.md).
|
||
|
||
## Перед началом
|
||
|
||
### Права в портале
|
||
|
||
| Право | Что даёт в разделе MCP |
|
||
| --- | --- |
|
||
| `mm:mcp:read` | открыть раздел, смотреть подключения, обращения, планы и операции; «Обновить мои права» для своего подключения; разрешить OAuth-доступ |
|
||
| `mm:mcp:approve` | «Подтвердить план» и «Отклонить». Нужны ещё права самой операции: например, для изменения сети — `mm:network:write` |
|
||
| `mm:mcp:pause` | «Остановить автоматические изменения» на вкладке «Обзор» |
|
||
| `mm:mcp:admin` | всё остальное: настройки, подключения, защиты, Route AI, OAuth-клиенты, сверка и восстановление |
|
||
| `mm:settings:admin` | включает все права `mm:mcp:*`; кроме того, восстановление базы приложения |
|
||
|
||
Подключению можно передать только те права, которые есть у его владельца. Иначе сохранение отклоняется: «Нельзя делегировать отсутствующие права». Менять политику подключения может только его владелец.
|
||
|
||
### Настройки сервера
|
||
|
||
- **`MCP_PUBLIC_URL`** — внешний адрес MCP, например `https://manager.example/mcp`.
|
||
- Путь — ровно `/mcp`, без query и без логина в адресе.
|
||
- Нужен HTTPS. HTTP допускается только для `localhost`, `127.0.0.1` и `[::1]`.
|
||
- При нарушении любого из правил MCP отвечает `INVALID_CONFIGURATION` (503).
|
||
- **`MCP_STATE_DIR`** — каталог ключей и поколения доступа. Храните его на постоянном томе.
|
||
- Если каталог потерян, при старте создаётся новое поколение.
|
||
- Тогда все выданные токены и все неприменённые планы перестают действовать.
|
||
- **Аудит.** Изменения начинаются только при доступном аудите, иначе вызов получает `AUDIT_UNAVAILABLE`.
|
||
|
||
## Шаг 0. Разрешить обращения MCP
|
||
|
||
1. «Настройки» → «Настройки MCP» → включите «Разрешить обращения MCP».
|
||
2. Там же задайте сроки хранения:
|
||
- «Хранение обращений, дней»: от 1 до 365, по умолчанию 30;
|
||
- «Хранение аудита, дней»: от 30 до 3650, по умолчанию 180.
|
||
|
||
Пока флаг выключен:
|
||
|
||
- любой токен получает `MCP_DISABLED` (503);
|
||
- воркер не запускает контроллер Route AI и не проверяет расхождения конфигурации.
|
||
|
||
## Шаг 1. Наблюдение
|
||
|
||
**Цель:** узнать, что агент читает и как часто, не давая ему ничего менять.
|
||
|
||
### Создать подключение
|
||
|
||
«Подключения» → «Выдать доступ». Откроется окно «Новое подключение». В нём:
|
||
|
||
- **«Название»** — по нему подключение видно в журналах.
|
||
- **«Срок действия (UTC)»** — не больше года. Для первого шага достаточно нескольких дней.
|
||
- **«Режим управления»** — «Наблюдатель». Он же выбран по умолчанию.
|
||
- **Серверы и операции** — только те, что нужны агенту.
|
||
- Операция, не выданная подключению, получает `OPERATION_DENIED`.
|
||
- Сервер вне списка получает `SERVER_DENIED`.
|
||
- Глобальные операции работают только с «Разрешить выбранные глобальные операции».
|
||
- **Права** — только на чтение, например `mm:servers:read`.
|
||
- **Лимиты.** На этом шаге хватит значений по умолчанию:
|
||
|
||
| Поле | По умолчанию | Отказ при превышении |
|
||
| --- | --- | --- |
|
||
| «Вызовов в минуту» | 60 | `RATE_LIMITED` |
|
||
| «Одновременных чтений» | 4 | `RATE_LIMITED` |
|
||
| «Изменений в час» | 10 | `BUDGET_EXCEEDED` |
|
||
| «Серверов на план» | 5 | `PLAN_LIMIT_EXCEEDED` |
|
||
| «Объектов на план» | 100 | `PLAN_LIMIT_EXCEEDED` |
|
||
|
||
После сохранения появится «Одноразовый токен MCP». Он показывается один раз:
|
||
|
||
1. Скопируйте токен в секреты AI-клиента.
|
||
2. Нажмите «Закрыть и скрыть токен».
|
||
|
||
Токен действует до срока подключения. «Новый токен» выпускает замену, старый токен сразу перестаёт работать. OAuth-токены и временные допуски при этом остаются: если токен утёк, используйте «Отозвать».
|
||
|
||
### Подключить клиента
|
||
|
||
Подходит любой MCP-клиент с транспортом Streamable HTTP. Настройки клиента:
|
||
|
||
- адрес: `MCP_PUBLIC_URL`;
|
||
- заголовок: `Authorization: Bearer <токен>`.
|
||
|
||
Формат настроек зависит от клиента. Держите токен в переменной окружения, а не в файле настроек.
|
||
|
||
**Вход через OAuth вместо токена:**
|
||
|
||
1. «Настройки» → «OAuth-клиенты»: зарегистрируйте клиента. В поле «Redirect URI, по одному на строку» укажите адреса точно.
|
||
2. При запросе доступа владелец видит «Разрешение OAuth-доступа» и выбирает подключение.
|
||
3. Клиент получает доступ ровно этого подключения, не шире.
|
||
|
||
### Права владельца
|
||
|
||
Подключение действует, пока подтверждены права его владельца. Подтверждение длится до истечения токена портала, с которым владелец подтвердил права, но не дольше 24 часов. Обновление сессии в портале этот срок не продлевает. Права подтверждаются:
|
||
|
||
- при создании подключения;
|
||
- при сохранении окна «Изменить разрешения»;
|
||
- кнопкой «Обновить мои права».
|
||
|
||
Оба срока видны в строке подключения: «Доступ до» и «Права владельца до».
|
||
|
||
Когда срок прошёл, любой вызов получает `UNAUTHORIZED` (401): «Подключение недействительно или требуется подтверждение прав владельца». Права подтверждает только сам владелец.
|
||
|
||
«Обновить мои права» аннулирует все неприменённые планы подключения и выключает его профили Route AI. Подтверждайте права до того, как агент начнёт готовить планы.
|
||
|
||
Если в портале отозвать сессии пользователя, Manager отзывает и его подключения MCP вместе с токенами и временными допусками.
|
||
|
||
### Сервисное подключение
|
||
|
||
В «Подключения» → «Выдать доступ» администратор MCP может выбрать «Сервисное — бессрочный автономный доступ». Выберите нужные серверы и операции. Доступ действует до отзыва и переживает истечение обычной сессии портала. Опасные операции всегда требуют подтверждения человеком, а лимиты и защита объектов действуют как обычно.
|
||
|
||
Сервисный токен можно заменить, приостановить вместе с подключением или отозвать. Явный отзыв прав выдавшего доступ администратора в портале также отзывает его сервисные подключения. Чтобы сменить тип подключения, выдайте новый токен через новое подключение.
|
||
|
||
### Что агент может на этом шаге
|
||
|
||
- **Может** вызывать операции чтения: каталоги, состояние, журналы.
|
||
- Диагностику `mm_server_terminal_diagnostic` (ping и подобное). Она требует права `mm:servers:write`, хотя ничего не меняет.
|
||
- Контрольные ping и traceroute пути `mm_route_path_verify`.
|
||
- **Не может** ничего менять. Все `*_plan`, включая нагрузочный тест полосы `mm_routing_measurement_plan`, получают `OBSERVER_WRITE_DENIED`. План при этом не создаётся.
|
||
|
||
### Где смотреть
|
||
|
||
- «Обзор»: вызовы за 24 часа, ошибки и отказы.
|
||
- «Обращения»: каждый вызов с результатом и причиной отказа. Есть фильтры по подключению, серверу и времени.
|
||
- «Подключения» → «Проверка подключения и временные допуски» → «Проверить готовность доступа». Это проверочное чтение возможностей от имени подключения.
|
||
|
||
### Когда переходить к шагу 2
|
||
|
||
- Вы знаете, какие операции и серверы нужны агенту.
|
||
- На вкладке «Обращения» нет неожиданных отказов `OPERATION_DENIED`, `SERVER_DENIED` и `RATE_LIMITED`.
|
||
|
||
## Шаг 2. Подтверждения
|
||
|
||
**Цель:** агент готовит изменения, а человек видит каждое до записи на роутер.
|
||
|
||
### Перевести подключение
|
||
|
||
«Подключения» → строка подключения → «Разрешения». Откроется окно «Изменить разрешения»:
|
||
|
||
- **«Режим управления»** — «С подтверждением».
|
||
- **Операции записи** — добавьте нужные `*_plan`.
|
||
- **Права** — добавьте права записи.
|
||
- **«Изменений в час».** Бюджет считает изменяемые объекты, а не вызовы.
|
||
- Бюджет расходуется при применении плана и обнуляется в начале каждого часа по часам сервера.
|
||
- Остаток проверяется дважды: при подготовке плана и при применении. Не хватает — `BUDGET_EXCEEDED`.
|
||
- Пример: удаление сервера IPsec на стенде меняет 11 объектов, при значении 10 оно не пройдёт никогда.
|
||
- Ставьте значение не меньше суммы объектов всех планов, которые агент применяет за час.
|
||
|
||
Сохранение не меняет токен. Оно увеличивает версию политики и аннулирует все неприменённые планы подключения. Возврат на шаг 1 делается так же: сменить режим на «Наблюдатель».
|
||
|
||
### Как проходит изменение
|
||
|
||
1. Агент вызывает `*_plan`. Manager читает роутер, строит план и проверяет политику.
|
||
2. План получает состояние `awaiting-approval`. Он виден в «Планы и операции» → «Планы изменений», а на вкладке «Обзор» растёт счётчик «Ожидают подтверждения».
|
||
3. Человек с `mm:mcp:approve` открывает план, проверяет изменения и нажимает «Подтвердить план» или «Отклонить». Подтверждение относится ровно к показанному плану.
|
||
4. Агент вызывает `mm_change_apply` с ID плана. Без подтверждения применение отклоняется с `APPROVAL_REQUIRED`. Администратор (`mm:mcp:admin`) может применить подтверждённый план и сам: «Применить план».
|
||
5. Ход записи — в «Выполнение операций»: «Записано намерение», «Применена», «Результат проверен». Агент читает то же через `mm_operation_get`.
|
||
|
||
**У плана есть срок:**
|
||
|
||
- 5 минут для операций раздела `network` в каталоге операций;
|
||
- 15 минут для остальных;
|
||
- для `servers.poll` и `routing.community.switch` — меньше, если раньше истекают данные, на которых построен план.
|
||
|
||
Истёкший план не применяется: «Срок плана истёк. Подготовьте новый план».
|
||
|
||
Переключение постоянного профиля Route AI подтверждает только владелец подключения.
|
||
|
||
### Защита объектов
|
||
|
||
«Разрешения» → «Защищённые объекты» → «Добавить защиту». Варианты:
|
||
|
||
- **«Запрет изменений»** — любой план, который затрагивает объект, отклоняется с `PROTECTED_OBJECT`.
|
||
- **«Подтверждение человеком»** — такой план требует подтверждения в любом режиме, в том числе в автономном.
|
||
|
||
Защита не ограничивает чтение.
|
||
|
||
Ставьте защиту до перехода к шагу 3, в первую очередь:
|
||
|
||
- на интерфейсы и адреса, через которые Manager управляет роутером;
|
||
- на маршруты к нему.
|
||
|
||
«Проверка разрешений» на той же вкладке показывает решение политики для операции и объекта без выполнения.
|
||
|
||
### Если результат не тот
|
||
|
||
«Планы и операции» → «Сверка и восстановление»:
|
||
|
||
1. Укажите UUID операции и нажмите «Сверить состояние операции». Manager прочитает роутер.
|
||
2. «Подготовить обратный план» создаёт отдельный план возврата. Он проходит те же проверки и подтверждение. Если объект после операции изменили извне, Manager откажет.
|
||
|
||
### Когда переходить к шагу 3
|
||
|
||
- Планы агента совпадают с тем, что вы ожидали.
|
||
- Отклонённых планов нет или почти нет.
|
||
- Операции доходят до «Результат проверен».
|
||
- «Планы и операции» → «Расхождения конфигурации» пусты.
|
||
- Защиты стоят на всём, что агент менять не должен.
|
||
|
||
## Шаг 3. Ограниченная автономность
|
||
|
||
**Цель:** агент применяет повторяющиеся изменения сам, в узкой области.
|
||
|
||
### Перевести подключение
|
||
|
||
«Изменить разрешения» → «Режим управления» → «Автономный». Сразу сузьте остальное:
|
||
|
||
- **серверы и операции** — только те, что агент применял на шаге 2;
|
||
- **«Срок действия (UTC)»** — короткий;
|
||
- **«Изменений в час»** и «Объектов на план» — по фактическому размеру планов шага 2, без лишнего запаса;
|
||
- **«Опасные действия»** — оставьте «Всегда подтверждать».
|
||
- «Автономно для явно выбранных действий» снимает подтверждение только с отмеченных опасных операций.
|
||
- Какие операции опасные, видно в каталоге операций и в панели «Проверка разрешений».
|
||
|
||
### Что по-прежнему требует человека
|
||
|
||
План без подтверждения не применяется. Подтверждение остаётся обязательным:
|
||
|
||
- для объектов с защитой «Подтверждение человеком». «Запрет изменений» по-прежнему запрещает;
|
||
- для опасных операций, кроме явно выбранных;
|
||
- для операций, которые сами требуют человека: Manager помечает весь сервер или операцию защитой «Подтверждение человеком». Такой план остаётся в состоянии `awaiting-approval`.
|
||
|
||
### Временный допуск
|
||
|
||
«Подключения» → «Проверка подключения и временные допуски» → «Выдать временный допуск». Допуск:
|
||
|
||
- получает отдельный токен;
|
||
- только сужает основной доступ: серверы, операции, глобальные действия;
|
||
- действует не дольше 24 часов («Срок допуска, минут»);
|
||
- снимается кнопкой «Отозвать допуск».
|
||
|
||
Удобно для разовой автономной работы: основное подключение остаётся в «С подтверждением», автономный режим — только у узкого допуска.
|
||
|
||
### Срок работы без человека
|
||
|
||
Автономная работа ограничена правами владельца: до истечения токена портала, с которым он последний раз подтвердил права, и не дольше 24 часов после этого. Дольше агент без человека не работает. Это намеренно.
|
||
|
||
Продление — «Обновить мои права». Оно аннулирует неприменённые планы, поэтому делайте его между задачами агента, а не во время.
|
||
|
||
## Постоянный контроллер Route AI
|
||
|
||
Отдельная функция: контроллер сам переключает маршруты по профилю.
|
||
|
||
«Route AI» → «Постоянный контроллер Route AI» → «Создать профиль».
|
||
|
||
**Требования к подключению:**
|
||
|
||
- режим не «Наблюдатель»;
|
||
- у владельца и у подключения есть `mm:network:read`, `mm:network:write` и `mm:filters:write`;
|
||
- серверы профиля входят в область подключения.
|
||
|
||
**Требования к допуску:**
|
||
|
||
- «Допуск действует до (UTC, максимум 24 часа)»;
|
||
- срок не позже срока токена, подключения и прав владельца.
|
||
|
||
Порядок: сначала «Обновить мои права», потом выдавайте допуск профилю. Подтверждение прав после выдачи выключит контроллер.
|
||
|
||
**Профиль отдельной таблицы или VRF:**
|
||
|
||
- нужна явная BGP-привязка;
|
||
- у каждого пути — контрольная проба с исходным адресом.
|
||
|
||
**Автоматическое восстановление недоступно.** Включить профиль с ним нельзя: `UNSUPPORTED_CAPABILITY` с причиной `ROUTE_RECOVERY_EXECUTOR_UNAVAILABLE`. Если такой профиль всё же оказался включён, контроллер сразу останавливается. Причина: нет источника событий RouterOS, который замечает пропуски.
|
||
|
||
**Контроллер останавливается сам:**
|
||
|
||
- когда истёк допуск;
|
||
- при любом изменении политики подключения: сохранение «Разрешения», «Пауза», «Отозвать»;
|
||
- при «Обновить мои права» владельца подключения;
|
||
- при отзыве токена, с которым выдан допуск;
|
||
- при ошибке проверки состояния;
|
||
- при обнаружении расхождения конфигурации у операций этого подключения;
|
||
- при «Остановить автоматические изменения».
|
||
|
||
Пока MCP выключен, контроллер не работает.
|
||
|
||
Проверить путь вручную, без переключения: «Контрольная проверка пути».
|
||
|
||
## Остановить, приостановить, отозвать
|
||
|
||
| Действие | Где | Что происходит | Обратимо |
|
||
| --- | --- | --- | --- |
|
||
| «Пауза» | «Подключения» | Токены подключения не принимаются, неприменённые планы аннулируются | да, «Включить» |
|
||
| «Отозвать» | «Подключения» | Подключение и все его токены отозваны, неприменённые планы аннулируются | нет: `CONNECTION_REVOKED` |
|
||
| «Новый токен» | «Подключения» | Старый токен перестаёт работать. OAuth-токены и временные допуски остаются | — |
|
||
| «Отозвать допуск» | «Проверка подключения и временные допуски» | Временный допуск и его токен перестают действовать | нет |
|
||
| Снять «Разрешить обращения MCP» | «Настройки» | Все вызовы получают `MCP_DISABLED`, контроллер и проверка расхождений не работают. Токены не отзываются | да: после включения токены снова работают |
|
||
| «Остановить автоматические изменения» | «Обзор», право `mm:mcp:pause` | MCP выключается, все профили Route AI выключаются. Начатые записи завершаются или сверяются | частично: MCP включается флагом, профили Route AI включают заново вручную |
|
||
| «Отключить и отозвать токены» | «Настройки» → «OAuth-клиенты» | OAuth-клиент отключён, его токены отозваны | нет |
|
||
|
||
После работы с агентом, которому доступ больше не нужен, — «Отозвать», а не «Пауза».
|
||
|
||
## Частые отказы
|
||
|
||
| Код | Причина | Что делать |
|
||
| --- | --- | --- |
|
||
| `MCP_DISABLED` | MCP выключен | «Разрешить обращения MCP» |
|
||
| `UNAUTHORIZED` | Токен неверный, отозван или истёк, подключение на паузе, права владельца не подтверждены или сменилось поколение доступа | проверить подключение, «Обновить мои права», при необходимости «Новый токен» |
|
||
| `OPERATION_DENIED` | Операция не выдана подключению | добавить операцию в окне «Изменить разрешения» |
|
||
| `OWNER_PERMISSION_MISSING`, `CONNECTION_PERMISSION_MISSING` | Нет права у владельца или у подключения | выдать право в портале или подключению |
|
||
| `SERVER_DENIED`, `GLOBAL_DENIED` | Сервер вне области, глобальные операции не разрешены | расширить область, если это нужно |
|
||
| `GRANT_INACTIVE`, `GRANT_SCOPE_DENIED` | Временный допуск истёк или запрос шире допуска | новый допуск |
|
||
| `RATE_LIMITED` | Минутный лимит вызовов или одновременных чтений | поднять лимит или замедлить клиента |
|
||
| `OBSERVER_WRITE_DENIED` | Изменение в режиме «Наблюдатель» | перейти на шаг 2 |
|
||
| `BUDGET_EXCEEDED` | План не помещается в часовой бюджет изменений | подождать или поднять «Изменений в час» |
|
||
| `PLAN_LIMIT_EXCEEDED` | Слишком много серверов или объектов в плане | разбить план или поднять лимит |
|
||
| `PROTECTED_OBJECT` | Объект под «Запрет изменений» | снять защиту, если изменение действительно нужно |
|
||
| `AUDIT_UNAVAILABLE` | Аудит недоступен | восстановить базу или аудит; изменения до этого не выполняются |
|
||
| `APPROVAL_REQUIRED` | Применение плана без подтверждения человеком | подтвердить план в «Планы и операции» |
|
||
| `PLAN_EXPIRED` | Истёк срок плана или исходных данных | подготовить новый план |
|
||
| `CONFIGURATION_BUSY` | Глобальная конфигурация занята другой операцией дольше 30 секунд | повторить позже |
|
||
|
||
## Что проверено
|
||
|
||
Доказательства и статусы по каждому критерию — в [mcp-final-manifest.md](mcp-final-manifest.md).
|
||
|
||
- **Режим «С подтверждением» проверен на стенде.**
|
||
- IPsec: пять прогонов подряд, в каждом 4 подтверждения в интерфейсе. Применение без подтверждения отклонено.
|
||
- Маршрутизация A3: 2 подтверждения.
|
||
- Выдача токена в интерфейсе, подтверждение плана и подписанный отзыв в настоящих Manager и Portal — EXT-1.
|
||
- **Режимы «Наблюдатель» и «Автономный», защиты, бюджет и лимиты** покрыты тестами политики (`policy.test.ts`). В документах стенда доказательств их отдельной проверки нет.
|
||
- **Сама инструкция** сверена с кодом: надписи — с `components/mcp/*.tsx`, числа и коды — с backend и контрактами. По интерфейсу её целиком не проходили.
|
||
- **Раздел MCP в интерфейсе** проверен частично: выдача ограниченного доступа, отказы, фильтры и пагинация на стенде не проверялись (UI-1).
|
||
- **Автоматическое восстановление маршрутов** не реализовано и выключено (этап 4 плана завершения).
|