Перейти к основному содержимому

Работа в консоли qf

Руководство описывает повседневную работу с политиками, хостами и сетевыми событиями в Web UI. Установка и настройка инфраструктуры описаны в руководстве по развёртыванию.

Подробности о правилах и политиках, селекторах, группах объектов и хостов и статусах хостов вынесены в отдельные гайды. Здесь описаны только операции в интерфейсе.

1. Вход и обзор (Dashboard)​

Консоль доступна по адресу https://<cp-host>/app/. После входа по паролю или через SSO открывается Dashboard со статусами хостов и последними событиями.

Слева — навигация: Hosts, Policies, Object Groups, Host Groups, Verdicts, Flows, Audit Log, Tokens, Users. Переключатель темы и меню пользователя — справа сверху.

Учётная запись и её роль admin, editor или auditor общие для всей инсталляции. Логин и email уникальны среди неархивных пользователей, включая отключённых. admin имеет доступ ко всем тенантам; редактору и аудитору нужны явные назначения. При входе выбирается доступный tenant: начальный tenant CP, если он назначен, иначе первый доступный по slug. При отсутствии назначений доступен только профиль. POST /auth/tenant с tenant_id переключает сессию после проверки назначения. Refresh сохраняет выбор; отзыв доступа требует повторного входа и не переводит пользователя в другой tenant автоматически.

Раздел Users доступен только администратору с пользовательской сессией. API /users показывает глобальный каталог. Создание пользователя принимает tenant_ids; без этого поля назначения пусты. GET/PUT /users/{id}/tenants читают и заменяют явные назначения. GET /tenants возвращает доступные тенанты, POST /tenants создаёт tenant по slug и name (только admin). В ответе tenant содержит status (active, suspended, archived) и status_changed_at. Admin видит все состояния; editor и auditor — назначенные активные тенанты. При входе и переключении можно выбрать только активный tenant.

Глобальный admin управляет состояниями через API:

ЗапросДействие
PATCH /tenants/{id} с nameИзменение отображаемого имени; slug сохраняется
POST /tenants/{id}/suspendПриостановка активного тенанта
POST /tenants/{id}/resumeВозобновление приостановленного тенанта
POST /tenants/{id}/archiveАрхивирование активного или приостановленного тенанта
POST /tenants/{id}/restoreВосстановление архивного тенанта в приостановленное состояние

Повтор уже выполненного перехода успешен и сохраняет время смены состояния. Архивный tenant сначала восстанавливается, затем возобновляется. Данные, назначения и машинные credentials сохраняются; сроки хранения телеметрии продолжают действовать. default подчиняется тем же правилам. Перезапуск CP не открывает закрытый tenant и не создаёт отсутствующий default заново. Глобальное управление доступно admin и без активного тенанта; роль и состояние учётной записи проверяются при запросе.

Глобальный аудит доступен admin через GET /audit-log/global; tenant-аудит GET /audit-log содержит только действия выбранного tenant. API-токены не управляют пользователями, даже с ролью admin. Смена роли действует на всю учётную запись и отзывает access/refresh. Logout завершает все действующие сессии пользователя. Отключение, архивирование и изменение назначений также требуют нового входа. REST, WS/SSE и аналитика прекращают затронутый доступ за пять секунд после сохранения изменения; при недоступном источнике прав доступ запрещается.

Suspend/archive закрывают агентские соединения, enrollment, передачу новых команд и приём телеметрии. Last-good policy и management path сохраняются; обычный watchdog может откатить ещё неподтверждённый bundle. После resume действующие API/bootstrap токены и сертификаты снова работают; отдельно отозванные и истёкшие — нет. Прежние пользовательские сессии закрытого tenant после resume не действуют. В шапке консоли переключатель показывает только активные tenant. Кнопка Тенанты у глобального admin открывает каталог всех состояний с поиском и фильтром. Клик по строке открывает просмотр, редактирование имени и глобальную историю. Slug неизменяем. Действия доступны через меню строки и в карточке; восстановление из архива оставляет tenant приостановленным до отдельного возобновления. Окончательное удаление доступно только в архиве и требует ввода точного slug. В форме пользователя назначения закрытым tenant сохраняются и помечаются состоянием.

Открытая консоль проверяет доступ каждые две секунды и при возвращении во вкладку. После отзыва она очищает формы и подписки полной перезагрузкой. Запоздалый ответ не восстанавливает данные. Сетевой сбой показывается как невозможность проверки доступа. Другой tenant автоматически не выбирается: после восстановления доступа нужен новый вход. Admin может управлять tenant и пользователями с действующей глобальной сессией даже при закрытом выбранном tenant; после истечения сессии нужен вход.

2. Энролмент нового хоста​

Хост подключается по enrollment-токену. Токен может назначить хосту лейблы и добавить его в группу.

Шаги​

  1. Tokens → New token.

  2. Тип bulk (для массового энролла) или single_host.

  3. Задать Label key/value — например role=web. Эти лейблы получит каждый хост, энролленный токеном (определяют, какие политики к нему применятся).

  4. TTL и Max uses — срок и лимит использований.

  5. Create.

  6. UI покажет токен один раз и базовый agent.conf.

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

QF_ENDPOINT=cp.example.com
QF_ENROLL_TOKEN=PASTE_ENROLL_TOKEN_HERE
QF_ENROLL_CA=/etc/qf/ca.crt

CA-файл нужно получить по доверенному каналу до первого запуска. Вместо PEM-файла можно использовать пин по отпечатку или получение CA через публично доверенный REST API. Все варианты описаны в гайде по ручному энролменту.

Запуск агента:

sudo systemctl enable --now qf-agent

Агент проверяет CA, получает клиентский сертификат и подключается к Control Plane. После подтверждения конфигурации хост появляется в Hosts со статусом Active и лейблами из токена.

Вкладка API Tokens — отдельные токены для CI/автоматизации (роли admin/editor/auditor).

3. Обзор хостов и статус​

Hosts — список флота: статус, лейблы, IP, версия агента, поколение (gen), последний heartbeat. Фильтр по hostname/лейблу и по статусам сверху.

Статусы: Active (на связи, конфиг подтверждён), Pending (применяет изменения), Degraded (долго не подтверждает), Stale (нет heartbeat).

Клик по хосту → детальная страница:

  • Agent info — версия, ядро, поколения (desired/confirmed), heartbeat.
  • Datapath & capabilities — режим attach (TCX/classic), лимит правил (2048; eBPF-фичи bpf_loop+ringbuf, mainline ≥5.17 или бэкпорт), ОС, CPU, наличие Cilium, ip_forward.
  • Interfaces — интерфейсы, адреса, какой приаттачен.
  • Вкладки: Policies, Ruleset (эффективные правила), Verdicts, Flows, Counters, Groups.

4. Создание политики​

Политика объединяет селектор хостов и набор правил.

Шаги​

  1. Policies → New policy.
  2. Имя, описание, приоритет (меньше число = выше при first-match).
  3. Селектор хостов → Лейблы — например role=web. Политика применяется ко всем хостам с этим эффективным лейблом, включая унаследованные от групп.
  4. Добавить правило — для каждого правила:
    • Direction: ingress / egress.
    • Action: allow / deny / log.
    • Match: протокол, порты (одиночные 443 и диапазоны 8080-8090), CIDR, или ссылка на object group; опционально TCP-флаги и conntrack-state.
    • Log + rate-limit — логировать срабатывания.
  5. Сохранить политику. При создании отдельного предпросмотра нет, поэтому для широкой области сначала используется действие log.

⚠️ deny без match блокирует весь поддерживаемый трафик, а блокировка порта 22 может закрыть SSH. Агент сохраняет исходящие соединения к IPv4-адресам Control Plane, разрешённым при его старте, но не защищает другие административные каналы. Перед широким запретом нужны разрешающие правила для них и этап наблюдения с действием log. Default action = ALLOW: без явного deny трафик проходит.

Политика с пустым (match-all) селектором требует подтверждения вводом её имени — защита от случайного применения на весь флот.

Версии и откат​

Изменения существующей политики выполняются во вкладке Редактирование. Действие Зафиксировать изменение и посмотреть зону влияния создаёт черновик и показывает затронутые хосты и различия правил. Enforcement меняется только после действия Применить.

Вкладка История хранит снимок каждого применения. Действие Откатить создаёт новую текущую версию на основе выбранного снимка, после чего Control Plane пересчитывает конфигурации затронутых хостов.

5. Группы хостов​

Группа задаёт общие лейблы для своих членов — удобно для «всех web-серверов».

  1. Host Groups → New group.
  2. Имя, лейблы (role=web, env=prod), приоритет.
  3. Добавить членов (хосты).

Лейблы группы наследуются хостами; прямые лейблы хоста перекрывают групповые. Изменение лейбла группы пересчитывает политики для всех её членов. Селектор role=web выбирает членов группы, у которых итоговый набор лейблов содержит это значение.

Новая группа сохраняется сразу. Изменение существующей группы сначала создаётся как черновик действием Зафиксировать изменение и посмотреть зону влияния. Лейблы и состав участников меняются только после действия Применить.

6. Object Groups (переиспользуемые наборы)​

Чтобы не дублировать списки IP/портов в правилах:

  1. Object Groups → New.
  2. Тип:
    • ipset — список CIDR/IP (203.0.113.0/24).
    • portset — порты и диапазоны (443, 8080-8090).
    • hostset — селектор → динамически резолвится в IP подходящих хостов.
  3. В правиле политики сослаться на набор через соответствующее поле IP-, port- или host-set.

Правка набора пересчитывает все политики, где он используется. Набор, на который ссылается правило, нельзя удалить. Пустые ipset и portset отклоняются при сохранении. Если динамический hostset временно не находит хосты, пустое значение не превращается в ANY. Затронутый хост сохраняет last-good generation, пока набор снова не станет непустым.

Новый набор сохраняется сразу. Изменение существующего набора проходит через черновик, Зону влияния и действие Применить.

7. Наблюдаемость​

Flows — какие соединения идут​

Flows при включённой отправке flow-событий показывает соединения, адреса, протокол и объём данных. Доступны поиск по порту, сортировка и фильтры.

Включить на хосте: на странице хоста переключатель Flow events.

Verdicts — сработавшие правила​

Verdicts показывает срабатывания логируемых правил, в том числе deny: время, правило, направление, адреса и порты. По этим данным определяется правило, остановившее трафик.

Counters​

Вкладка Counters на хосте — счётчики попаданий по каждому правилу (пакеты/байты). Глобальные pass/drop и заполнение карт видны в метриках хоста (heartbeat).

8. Разбор инцидента (deny)​

Типовой сценарий «почему не идёт трафик»:

  1. Hosts → хост → Ruleset — посмотреть эффективные правила (что реально применено).
  2. Verdicts — найти deny-события по порту/адресу: какое правило сработало.
  3. Counters — подтвердить рост счётчика этого правила.
  4. Исправить лишнее правило или порядок правил. Меньшее значение Priority проверяется раньше.

9. Audit Log​

Audit Log показывает, кто, что и когда менял: мутации политик, групп, токенов и хостов с состоянием до и после и именем автора. Доступ к журналу есть только у роли admin.

10. Правила безопасной работы​

  • Default ALLOW — фильтруется только явный deny; забыть правило = трафик пройдёт, а не упадёт.
  • deny без match и ограничения порта 22 вводятся только после разрешающих правил для административного доступа, проверки зоны влияния и этапа log.
  • Зона влияния проверяется перед применением изменений существующей политики с широким selector.
  • Сначала log-правило (понаблюдать в Verdicts), потом deny.
  • Токены показываются один раз — хранить безопасно, отзывать при утечке.
  • Число эффективных правил должно укладываться в лимит, указанный в Datapath & capabilities для конкретного хоста.

Scope API-токена​

API-токен создаётся в активном tenant и сохраняет этот scope до удаления. Список, отзыв, восстановление и purge также относятся к активному tenant. Заголовок X-Tenant-ID не переносит токен в другой tenant. Даже роль admin токена не даёт доступа к глобальным /users, /tenants и /audit-log/global; нужна пользовательская сессия. При работе с несколькими tenants в Terraform используйте отдельные токены.

Тенант в консоли​

Переключатель в шапке показывает доступные тенанты. Admin создаёт тенант кнопкой «Создать тенант» и задаёт название и неизменяемый slug. В форме создания и редактирования пользователя выберите доступные ему тенанты. У admin доступ ко всем тенантам появляется автоматически; назначения нужны editor и auditor.

Переключение перезагружает консоль: незавершённая форма закрывается, данные и подписки загружаются заново. Активный тенант общий для вкладок браузера. Старые вкладки обновляются; запрос старой формы с несовпадающим X-Expected-Tenant-ID получает 409. Заголовок проверяет ожидание клиента и не расширяет доступ.

Без назначений консоль показывает «Нет активного тенанта». После назначения нажмите «Обновить доступ» и выберите тенант. Если сессия истекла, войдите повторно.

Окончательное удаление тенанта​

Глобальный admin может удалить только архивный tenant: POST /tenants/{id}/purge с JSON {"confirm_slug":"точный-slug"}. Это необратимая операция без периода ожидания. Указанный UUID и slug проверяются вместе. Повтор уже выполненного запроса возвращает 204; неверное состояние или slug — 409, неизвестный UUID — 404.

Удаляются хосты, правила и группы, версии и черновики, телеметрия, назначения, bootstrap/API-токены, сертификаты и tenant-аудит. Общие пользователи и PKI-ключи, другие тенанты и глобальный журнал сохраняются. Событие tenant.purged содержит автора, UUID, slug и название. Оно фиксируется в одной транзакции с удалением; ошибка откатывает всю операцию. Повтор не создаёт второго свидетельства.

Доступ уже закрыт архивированием. Очереди повторно проверяют tenant перед записью и отправкой; кэши имён CP обновляются за 30 секунд, analytics удаляет снимки за пять минут. Старые credentials не получают доступ к новому tenant с прежним slug: у него другой UUID. Удалённый default не создаётся заново при перезапуске.

Перед использованием purge обновите все реплики CP: прежние workers не имеют транзакционной защиты от отложенной записи. Дисковый буфер пересылки требует подготовки при обновлении. Удаление в qf не удаляет уже доставленные копии во внешнем SIEM.