Техническое задание
Микросервис управления доверенными адресами клиентов
Self-service портал для указания клиентами доверенных IPv4-адресов и подсетей,
исключаемых из блокировки на стороне облачного провайдера во время DDoS-атак

───────────────────────────────────────────────────────────────
КРАТКОЕ ОПИСАНИЕ (пояснение к реализации)
───────────────────────────────────────────────────────────────
Сервис даёт клиентам облачного провайдера личный кабинет, где они сами указывают
свои доверенные IPv4-адреса и подсети. Эти адреса провайдер не блокирует во время
DDoS-атак — так легитимный трафик клиента не попадает под ложные срабатывания
фильтрации.

Что реализуется:

Личный кабинет клиента. Клиент входит через привычную авторизацию (Keycloak),
видит свой список доверенных адресов и управляет им сам: добавляет, редактирует,
удаляет записи с комментариями. Если пользователь работает с несколькими
компаниями — переключается между ними.

Проверка вводимых данных. Форма принимает только корректные IPv4-адреса и подсети,
отклоняет «серые» и служебные диапазоны, не допускает дубликатов и пересечений
внутри одной компании.

Ограничение по количеству. На компанию по умолчанию 15 записей. Лимит
настраивается глобально, а для отдельной компании администратор может поднять или
опустить его индивидуально.

Режим администратора (сетевые инженеры провайдера). Единое окно, где видны записи
всех компаний, с фильтрами и доступом к истории изменений. Администратор управляет
лимитами и при необходимости любыми записями.

История изменений (аудит). Каждое создание, изменение и удаление фиксируется: кто,
когда, что именно изменил. Удаление — логическое, данные физически сохраняются.

Выдача для систем фильтрации. Отдельный адрес, по которому системы защиты
автоматически забирают итоговый сводный список всех доверенных адресов (одним
txt-файлом, по строке на запись). Адреса при этом схлопываются в компактный общий
перечень.
───────────────────────────────────────────────────────────────
1. Назначение и цели
1.1. Назначение
Микросервис предоставляет клиентам облачного провайдера web-интерфейс для самостоятельного управления списком доверенных IPv4-адресов и подсетей. Записи из этого списка исключаются из автоматической блокировки сетевого взаимодействия системами фильтрации и митигации провайдера, что снижает количество ложноположительных срабатываний для легитимного трафика клиента.
1.2. Цели
Дать клиентам возможность самостоятельно поддерживать актуальный список доверенных IPv4-адресов, которые будут исключаться из фильтрации во время DDoS-атак.
Предоставить сетевым инженерам единую точку просмотра и управления списками доверенных клиентских белых IPv4-адресов.
Обеспечить машиночитаемую выдачу агрегированного (суммаризированного) списка для систем фильтрации трафика.
2. Объем работ
Web-страница / закладка в личном кабинете для управления whitelist-записями.
Авторизация через существующий экземпляр Keycloak (OIDC).
Валидация формы на стороне клиента и сервера.
Внешний endpoint выдачи агрегированного списка. Выдача txt-файлом с переносом строки. Одна строка – один объект.
Хранение записей, журнал аудита.
Административное управление лимитами по компаниям.
3. Роли и права доступа
Роли определяются на основании claims в OIDC-токене Keycloak. Соответствие claim → роль настраивается на этапе развёртывания.
Роль
Идентификация
Видимость записей
Права на изменение
Клиент (client)
clientId
Только записи компаний, к которым принадлежит пользователь.
Создание, редактирование и удаление записей своих компаний (в пределах лимита).
Администратор (admin)
clientId = WZ01112 (Нубес) и отдельный чек-бокс
Записи всех компаний.
Создание, редактирование, удаление всех записей. Изменение лимита для отдельных компаний.
3.1. Принадлежность к компании
Принадлежность пользователя к компании определяется из claim токена. Поддерживается сценарий, когда пользователь принадлежит нескольким компаниям: в этом случае в интерфейсе предусматривается переключатель активной компании, а все операции выполняются в контексте выбранной компании.
Ожидаемые claims (имена согласуются с командой Keycloak):
clientID — идентификатор компании
email — идентификация пользователя для аудита
4. Функциональные требования
4.1. Просмотр списка записей
Клиент видит таблицу записей активной компании; Администратор – записи всех компаний с фильтром по компании.
Для каждой записи отображаются: значение (адрес/подсеть), комментарий (если есть), автор(email), дата создания, дата последнего изменения.
Soft-deleted записи по умолчанию скрыты; для администратора предусмотрен фильтр для их отображения.
Отображается текущее использование лимита: «использовано X из N».
4.2. Создание записи
Форма содержит поля: значение (IPv4-адрес или подсеть CIDR) и необязательный комментарий (до 255 символов).
Значение проходит валидацию (см. раздел 5) на клиенте и обязательно повторно на сервере.
Перед сохранением проверяется: соблюдение лимита компании, отсутствие пересечений и дубликатов внутри компании, отсутствие принадлежности к запрещённым диапазонам.
При успешном сохранении создаётся запись аудита.
4.3. Редактирование записи
Редактирование значения и комментария доступно компании в рамках своих прав.
При изменении значения повторно выполняется полный набор проверок валидации и пересечений.
Изменение фиксируется в журнале аудита с сохранением прежнего и нового значения.
4.4. Удаление записи (soft delete)
Удаление выполняется как логическое (soft delete): запись помечается удалённой (deleted_at, deleted_by), но физически сохраняется.
Удалённая запись освобождает место в лимите компании и исключается из внешней агрегированной выдачи.
Действие фиксируется в журнале аудита.
4.5. Лимит записей на компанию
Действует глобальный лимит по умолчанию: 15 активных записей на компанию.
Значение глобального лимита по умолчанию задаётся конфигурацией сервиса и может быть изменено без пересборки.
Для отдельной компании администратор может задать индивидуальный лимит, переопределяющий глобальный (как в большую, так и в меньшую сторону).
При попытке превысить лимит создание блокируется с понятным сообщением; в подсчёт идут только активные записи.
Снижение лимита ниже текущего числа записей не удаляет существующие записи, но блокирует создание новых до приведения в соответствие.
4.6. Журнал аудита
Все изменяющие операции фиксируются неизменяемыми записями аудита.
Каждая запись аудита содержит: кто (пользователь), когда (timestamp), компания, тип действия, прежнее и новое состояние.
Журнал доступен для просмотра только администратору.
4.7. Внешняя выдача агрегированного списка
Подсети суммаризируются (агрегируются в минимальный набор CIDR) по всем компаниям совместно. Пересечения между разными компаниями допустимы.
Предоставляется отдельный HTTP GET endpoint, отдающий полный суммаризированный список активных записей всех компаний файлом в формате txt.
Авторизация: на старте endpoint может работать без авторизации (по сетевому ограничению / разрешенный список потребителей по ip).
5. Требования к валидации
Валидация выполняется на клиенте и обязательно дублируется на сервере. Серверная валидация является авторитетной.
Правило
Описание
Формат IPv4
Допускается одиночный адрес (например 203.0.113.10) или подсеть в нотации CIDR (например 203.0.113.0/24). Допускается использование масок /32 - /22. Маска /21 и больше не допускается.
Только IPv4
IPv6-значения или доменные имена отклоняются.
Корректность подсети
Введенный адрес с маской подсети должен нормализоваться к адресу подсети, все host-биты должны быть обнулены.
Пользователь должен быть уведомлен, что ввел адрес из хостовой части, а не адрес подсети и произошла нормализация.
Запрет серых адресов
Адреса и подсети из частных диапазонов (Приложение А) запрещены к добавлению.
Отсутствие дубликатов
В пределах одной компании запрещены полностью совпадающие записи.
Отсутствие пересечений
В пределах одной компании запрещено добавление записи, пересекающейся с уже существующей (включая вложенность подсетей). Между разными компаниями пересечения допускаются. 
Длина комментария
Не более 255 символов; поле необязательное.
Приложение А – Список запрещенных к созданию подсетей.
Назначение
Префикс
Private (RFC1918)
10.0.0.0/8
Private (RFC1918)
172.16.0.0/12
Private (RFC1918)
192.168.0.0/16
CGNAT (RFC6598)
100.64.0.0/10
Loopback
127.0.0.0/8
Link-local (APIPA)
169.254.0.0/16
IANA special block
192.0.0.0/24
TEST-NET-1 (docs)
192.0.2.0/24
TEST-NET-2 (docs)
198.51.100.0/24
TEST-NET-3 (docs)
203.0.113.0/24
Benchmarking
198.18.0.0/15
Multicast
224.0.0.0/4
Reserved (Class E)
240.0.0.0/4
Limited broadcast
255.255.255.255/32