API и инструменты MCP
Веб-интерфейс работает через REST API, которое b4 обслуживает на порту веб-сервера по путям /api/. Справочник API на этом сайте перечисляет все точки доступа с параметрами и ответами. Если в поле B4 Instance указан адрес работающего b4, страница отправляет запросы этому экземпляру, а без адреса только показывает справочник.
Авторизация
Пока в Настройки > Система > Веб-сервер заданы имя пользователя и пароль, каждый запрос к /api/ требует токена входа, кроме запросов к /api/auth/ и /api/version. Без имени пользователя и пароля токен не нужен.
| Шаг | Запрос |
|---|---|
| Вход | POST /api/auth/login с {"username": "...", "password": "..."} возвращает {"token": "..."} |
| Использование токена | Заголовок Authorization: Bearer <токен> в каждом запросе. Соединения WebSocket к /api/ws/ могут вместо этого передать его в параметре запроса token |
| Выход | POST /api/auth/logout отзывает токен |
Токен входа действует, пока им пользуются хотя бы раз в 24 часа, и сбрасывается при перезапуске b4. После нескольких неудачных попыток входа с одного адреса b4 какое-то время отвечает 429. У точки доступа MCP свой токен, см. MCP-сервер.
Точки доступа, на которые ссылается документация
| Запрос | Что делает |
|---|---|
GET /api/metrics | Снимок данных дашборда |
GET /api/metrics/summary | Краткая сводка снимка с итогами соединений после последнего сброса счётчиков |
/api/ws/metrics | WebSocket: полный снимок, затем одно обновление в секунду, как их получает дашборд |
POST /api/metrics/reset | Сбросить счётчики на дашборде |
POST /api/escalations/clear | Очистить на панели Активные эскалации дашборда: все хосты в эскалации возвращаются в свои сеты |
/api/ws/logs | WebSocket: живой лог, который показывает страница Логи |
POST /api/logs/trace/start, POST /api/logs/trace/stop | Начать трассировку и Остановить и сохранить на странице Логи |
GET /api/logs/trace/status | Идёт ли запись трассировки |
GET /api/logs/trace/download | Последний файл трассировки, как его сохраняет Скачать последнюю трассировку |
GET /api/config/download | Конфигурация как есть, как её сохраняет Скачать как есть в Настройки > Система > Бэкап |
GET /api/config/download?safe=true | Безопасная копия, как её сохраняет Скачать безопасную копию |
GET /api/system/addresses | Порты, которые открыли переключатели Доступ из интернета, их цепочки файрвола и ошибки, а также причина, по которой включённый переключатель ничего не открыл |
GET /api/watchdog/status | Состояние мониторинга для каждого отслеживаемого сета и домена с кодами причин |
POST /api/discovery/start | Запускает Дискавери. Запуск для сета, который маршрутизирует трафик, отклоняется с 400 и кодом routed_set |
POST /api/mcp | MCP-сервер, см. ниже |
Коды причин мониторинга
Мониторинг сообщает, почему сет находится в своём состоянии или чем закончилось последнее восстановление, одним из этих кодов. Страница Мониторинг показывает те же причины словами.
| Код | Значение |
|---|---|
not_owned | Адреса сета обрабатывает другой сет или никакой, поэтому стратегия, записанная в этот сет, на них не влияет |
escalated | Эскалация отправляет адреса в другой сет |
unusable | Ошибка сертификата, обязательный клиентский сертификат или частный либо локальный адрес. Не восстанавливается |
current_works | При отдельной проверке собственная стратегия сета открывает адреса, но живая проверка не проходит |
not_needed | При отдельной проверке адреса открываются без обхода, но живая проверка не проходит |
partial | Поиск нашёл стратегию только для части адресов, поэтому ничего не записано |
none | Поиск не нашёл рабочей стратегии |
incomplete | Поиск закончился без подтверждённого результата |
budget | Поиск шёл дольше 20 минут и был отменён |
start_failed | Запуск Дискавери не удался |
verify_failed | Записанная стратегия не прошла живую проверку и была отменена |
edited | Сет изменился во время проверки или поиска, поэтому ничего не записано |
busy | Среду выполнения занимает другой запуск Дискавери, и восстановление ждёт |
Причины для переключателей доступа
Для включённого переключателя Доступ из интернета, который ничего не открыл, GET /api/system/addresses называет причину: no_auth, web_no_auth, open_relay, shared_port, loopback, invalid_bind или not_listening. Условия каждого переключателя описаны на странице Защита веб-интерфейса.
MCP-сервер
POST /api/mcp обслуживает Model Context Protocol для ИИ-приложений: JSON-RPC 2.0 поверх HTTP. Настройка описана на странице Подключение ИИ-ассистента. Обслуживается только POST: GET и DELETE возвращают 405, и для этого транспорта это нормально.
| Ситуация | Ответ |
|---|---|
| Включить MCP-сервер выключено | 404, mcp server is disabled |
| MCP-токен задан, а запрос несёт другой или никакого | 401, invalid or missing MCP token |
| MCP-токен не задан | Требуется токен входа в веб-интерфейс, как для остального API, пока заданы имя пользователя и пароль |
Запрос несёт неразрешённый заголовок Origin | 403 |
Запрос с заголовком Origin принимается, если этот origin - собственный адрес b4, записанный как IP-адрес или localhost, или если он есть в system.web_server.mcp.allowed_origins, где одиночная * принимает любой origin. Имя хоста автоматически не принимается никогда: при DNS-ребиндинге страница на имени атакующего обращается к b4 с совпадающими заголовками Origin и Host. ИИ-приложения заголовок Origin не отправляют.
Инструменты
Сервер предлагает инструменты по двум переключателям разрешений на карточке MCP-сервер и пересобирает список при их изменении, без перезапуска. Неразрешённый инструмент не предлагается вовсе, а сервер сообщает модели, какое разрешение выключено, и модель может назвать, что включить.
| Разрешено | Инструментов |
|---|---|
| Ничего (по умолчанию) | 13 |
| Разрешить изменение настроек | 17 |
| Разрешить активные проверки | 15 |
| Оба | 19 |
| Инструмент | Что делает | Что требует |
|---|---|---|
b4_status | Версия, движок захвата, бэкенд файрвола, сколько сетов есть и включено, состояние «Telegram через WebSocket», время работы, соединения после последнего сброса счётчиков и какие разрешения включены | - |
b4_metrics | Соединения за последнюю полную минуту, в сетах и вне сетов, итоги после последнего сброса, отброшенные RST, заблокированные DNS-запросы и соединения, загрузка CPU и память b4. Соединения считаются так же, как на дашборде | - |
b4_get_config | Конфигурация целиком или один её раздел | - |
b4_list_sets | Все сеты в порядке приоритета с числом доменов и основной стратегией | - |
b4_get_set | Один сет целиком | - |
b4_check_domain | Какие сеты нацелены на домен, как совпало и включён ли сет | - |
b4_recent_connections | Соединения, обработанные b4, с совпавшим сетом | - |
b4_logs_tail | Хвост errors.log, а с file=update - хвост update.log | - |
b4_diagnostics | ОС, ядро, интерфейсы, бэкенд файрвола и установленные b4 группы правил | - |
b4_get_topic | Описание настройки, см. Описания настроек | - |
b4_list_writable_paths | Какие настройки можно менять, с типами, текущими и допустимыми значениями | - |
b4_geo_lookup | Какие категории GeoSite и GeoIP существуют, что в одной из них и какие покрывают домен или адрес | - |
b4_watchdog | Вердикты мониторинга и его действия, см. ниже | Зависит от действия |
b4_set_config_value | Меняет одну настройку, сразу применяет её и сообщает прежнее и новое значение | Разрешить изменение настроек |
b4_revert_last_change | Восстанавливает конфигурацию, какой она была до последнего изменения через MCP | Разрешить изменение настроек |
b4_edit_set_targets | Добавляет и убирает домены, адреса, гео-категории, ASN и устройства-источники одного сета | Разрешить изменение настроек |
b4_manage_set | Создаёт, копирует, перемещает, включает, удаляет и сбрасывает сет | Разрешить изменение настроек |
b4_test_domain_now | Загружает домен через b4 и ещё раз в обход b4 и говорит, какой из двух вариантов работает | Разрешить активные проверки |
b4_find_bypass_strategy | Запускает Дискавери для домена, URL или сета и применяет результат | Разрешить активные проверки для запуска, Разрешить изменение настроек для применения |
b4_check_domain отвечает, настроен ли домен в сете. b4_recent_connections отвечает, дошёл ли трафик по нему и какой сет совпал. Разница между ответами отличает ошибку в целях от ошибки в маршрутизации.
Вместе с инструментами публикуется готовый промпт diagnose_domain. Он принимает домен и по порядку проводит модель через статус, покрытие, конфигурацию и правила файрвола. Приложения, которые поддерживают промпты, показывают его отдельно.
b4_watchdog
Чтение вердиктов мониторинга не выпускает трафик и ничего не меняет, поэтому инструмент предлагается на любом уровне, а каждое действие разрешается отдельно. Без set действия работают со старым списком доменов и общим переключателем мониторинга:
| Действие | Что делает | Что требует |
|---|---|---|
status | Последний вердикт по каждому отслеживаемому сету и домену | - |
add | Добавляет домен в список | Разрешить изменение настроек и Разрешить активные проверки |
remove | Убирает домен из списка | Разрешить изменение настроек |
enable | Включает общий переключатель мониторинга, для отслеживаемых сетов и для списка | Разрешить изменение настроек и Разрешить активные проверки |
disable | Выключает общий переключатель мониторинга | Разрешить изменение настроек |
check | Проверяет домен из списка сейчас | Разрешить активные проверки |
С set, идентификатором или точным названием сета, действия работают с собственным мониторингом этого сета и его адресами Дискавери, которые передаются в url:
Действие с set | Что делает | Что требует |
|---|---|---|
status | Статус мониторинга сета, причина и результаты по адресам | - |
enable | Включает мониторинг сета и назначает проверку; отклоняется, если сет нельзя отслеживать | Разрешить изменение настроек и Разрешить активные проверки |
disable | Выключает мониторинг сета | Разрешить изменение настроек |
add | Добавляет url в адреса Дискавери сета | Разрешить изменение настроек и Разрешить активные проверки |
remove | Удаляет url из них | Разрешить изменение настроек |
check | Назначает проверку всех адресов отслеживаемого сета и сбрасывает паузу | Разрешить активные проверки; прекращение поиска сбрасывается, только если включено и Разрешить изменение настроек |
b4_find_bypass_strategy
domains принимает до пяти доменов или полных URL через запятую, как поле ввода Дискавери: домен запрашивается как https://<домен>/, URL - как есть. Хост, который только раздаёт файлы, например CDN картинок или видео, может отвечать на / ошибкой HTTP 400, и тогда запуску нечего проверять. Такой хост проверяется по URL файла, который он отдаёт. Запуск также пробует стратегии, которые хаб сообщества публикует для этих доменов, как запуск со страницы Дискавери при включённом хабе.
action=start с set запускает Дискавери для этого сета: на переданных доменах или на адресах Дискавери сета, не больше пяти. Текущая стратегия сета проверяется первой, а поиск останавливается на первой стратегии, подтверждённой на всех адресах. action=status сообщает вердикт, а action=apply с set записывает результат в сет, только стратегию и только при вердикте covered. То же действует для action=apply без set, если запуск, на который он указывает, был запуском для сета. Сет, который action=apply создаёт для произвольных доменов, сохраняет адреса, на которых они найдены, как свои адреса Дискавери. Сет с включённой маршрутизацией отклоняется.
Изменение настроек
При включённом Разрешить изменение настроек доступными для записи становятся:
- все настройки внутри сета: цели, фрагментация, фейкинг, TCP и UDP, DNS, эскалация и маршрутизация;
- настройки MTProto и SOCKS5, в том числе переключатель «Telegram через WebSocket»
system.mtproto.bridge.enabled; - настройки логирования, чтобы модель могла поднять уровень лога, воспроизвести проблему и прочитать результат.
b4_list_writable_paths сообщает точные пути с типами, текущими и допустимыми значениями. Изменение проходит те же проверки и тот же путь применения, что и сохранение в веб-интерфейсе. Недопустимый результат отклоняется, и ничего не сохраняется, а принятый применяется сразу, включая правила файрвола. Запись списка, например доменов сета, заменяет весь список, поэтому модель сначала читает текущее значение и возвращает его целиком.
b4_edit_set_targets, наоборот, добавляет и убирает отдельные записи, а kind называет список: sni_domains, ip, geosite_categories, geoip_categories, asns или source_devices. Запись asns задаётся как AS15169 или 15169 и хранится как голый номер; зарезервированные номера отклоняются. ASN, чьи префиксы b4 ещё не загрузил, добавляется всё равно и сразу загружается, а ответ называет его: пока загрузка не пройдёт, сет не совпадает ни с одним из его адресов.
При любых переключателях отклоняются учётные данные веб-интерфейса, SOCKS5, MTProto и вышестоящего прокси сета, а также:
| Что отклоняется | Почему |
|---|---|
| Настройки веб-сервера | Перенос или блокировка интерфейса убирает способ отменить изменение |
| Настройки MCP | Модель не может расширить собственные права |
| Движок захвата и TUN | Переключение под работающей сетью может отрезать машину |
| Бэкенд файрвола | Неверное значение оставляет машину вообще без правил |
| Все переключатели Доступ из интернета и любая запись, которая открыла бы порт, пока один из них включён, например включение MTProto-прокси или смена его порта | Открытый порт сразу доступен всему интернету, а отмена не отменяет того, что успело до него дойти |
| Метки пакетов и таблицы маршрутизации | От них зависит собственный трафик b4 |
Задать DSCP (system.tables.dscp) и собственный DSCP сета (sets[].dscp) | По значению действуют правила на следующем роутере, и неверное значение может отправить трафик другим маршрутом |
| Идентификатор сета | На него ссылаются цели эскалации |
| Адреса Дискавери сета и переключатель его мониторинга | И то, и другое заставляет роутер загружать сайты по расписанию; b4_watchdog с set меняет их по своим разрешениям |
| Каталог логов и расположение файлов геоданных | Неверный каталог логов тихо прекращает запись в файл, а неверный путь к геоданным разом опустошает все категории |
Граница проходит по обратимости: неверное значение внутри сета ломает часть сайтов, заметно и обратимо, а неверный порт веб-сервера или движок захвата может оставить машину недоступной. Области для записи заданы целыми поддеревьями, а исключения помечены на самих полях, поэтому настройка, добавленная в b4 позже, недоступна для записи, пока её не разрешат отдельно. Отклонённое расположение не закрывает содержимое: b4_logs_tail читает оба файла логов, куда бы ни указывал каталог.
b4_revert_last_change восстанавливает конфигурацию, какой она была до последнего изменения через MCP с момента запуска b4, и применяет её. Повторный вызов уходит дальше назад. Откат отклоняется, а изменение остаётся в списке, если после него конфигурация менялась: восстановлением мониторинга, в веб-интерфейсе или другим инструментом. Откат отклоняется и тогда, когда включил бы мониторинг сета или общий мониторинг либо вернул бы домены мониторинга или адреса Дискавери отслеживаемого сета, пока Разрешить активные проверки выключено.
Описания настроек
У некоторых настроек b4 имя читается не так, как они работают, а ноль обычно означает «использовать фиксированное значение», а не «выключено». b4 несёт с собой описание таких настроек, и сервер велит модели прочитать его, прежде чем объяснять или менять что-либо. Описания берутся из src/ai/topics.json и встроены в бинарник; объяснения AI-помощника в веб-интерфейсе используют тот же текст.
Описания публикуются дважды:
- инструмент
b4_get_topicпринимаетtopicдля точного ключа,pathдля настройки, которую называет путьb4_set_config_value(в путиsets[video].tcp.win.modeсет игнорируется), илиqueryдля поиска. Без аргументов он перечисляет все документированные ключи; - ресурсы
b4://topics/<ключ>содержат тот же текст.
Большинство приложений не показывает модели ресурсы: LM Studio и мосты, совместимые с OpenAI, перечисляют их для пользователя. Инструмент делает текст доступным модели. Запрос о настройке без описания возвращает пометку об этом и список документированных настроек рядом. Пометка велит модели сказать, что она не уверена, а не выводить единицу измерения, значение по умолчанию или смысл настройки из её имени.
Что b4 записывает
Каждый вызов инструмента пишет в лог b4 одну строку, видную на странице Логи: инструмент, адрес вызывающего и время выполнения. Отклонённый вызов пишется как предупреждение. Запрос, отклонённый на самой точке доступа, тоже попадает в лог: сервер выключен, токен неверен или отсутствует, origin браузера не разрешён. Сам токен не пишется никогда. Повторные отказы сворачиваются в одну строку раз в 30 секунд со счётчиком. Эти строки идут в живой лог и в консоль, но не в errors.log, где лежат только ошибки.
Изменение через MCP и его отмена появляются также в Последние изменения на дашборде как ИИ-агент изменил настройку, с путём настройки и без её значения.
Что вырезается
Вывод инструментов может быть передан сторонней модели, поэтому b4 удаляет из него эти значения или заменяет их на [redacted]:
- имя пользователя и пароль веб-интерфейса;
- MCP-токен;
- имя пользователя и пароль SOCKS5;
- имена и значения секретов MTProto;
- токен IPinfo;
- ссылку на сохранённый API-ключ AI-помощника;
- имя пользователя и пароль вышестоящего прокси сета;
- путь к TLS-ключу веб-сервера.
Имена хостов и URL возвращаются как настроены. Скачать безопасную копию в Настройки > Система > Бэкап скрывает и их. В b4_diagnostics учётных данных нет, но он сообщает имя хоста, все адреса интерфейсов и действующий набор правил файрвола, и этого достаточно, чтобы опознать сеть.