ipwhitelist-app/docs/ТЗ.md

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

1. Назначение и цели

1.1. Назначение

Микросервис предоставляет клиентам облачного провайдера web-интерфейс для самостоятельного управления списком доверенных IPv4-адресов и подсетей. Записи из этого списка исключаются из автоматической блокировки сетевого взаимодействия системами фильтрации и митигации провайдера, что снижает количество ложноположительных срабатываний для легитимного трафика клиента.

1.2. Цели

• Дать клиентам возможность самостоятельно поддерживать актуальный список доверенных IPv4-адресов, которые будут исключаться из фильтрации во время DDoS-атак.
• Предоставить сетевым инженерам единую точку просмотра и управления списками доверенных клиентских белых IPv4-адресов.
• Обеспечить машиночитаемую выдачу агрегированного (суммаризированного) списка для систем фильтрации трафика.

2. Объем работ

• Web-страница / закладка в личном кабинете для управления whitelist-записями.
• Авторизация через существующий экземпляр Keycloak (OIDC).
• Валидация формы на стороне клиента и сервера.
• Внешний endpoint выдачи агрегированного списка. Выдача txt-файлом с переносом строки. Одна строка – один объект.
• Хранение записей, журнал аудита.
• Административное управление лимитами по компаниям.

3. Роли и права доступа

Роли определяются на основании claims в OIDC-токене Keycloak. Соответствие claim → роль настраивается на этапе развёртывания.

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. Требования к валидации

Валидация выполняется на клиенте и обязательно дублируется на сервере. Серверная валидация является авторитетной.

Приложение А – Список запрещенных к созданию подсетей.

Роль	Идентификация	Видимость записей	Права на изменение
Клиент (client)	clientId	Только записи компаний, к которым принадлежит пользователь.	Создание, редактирование и удаление записей своих компаний (в пределах лимита).
Администратор (admin)	clientId = WZ01112 (Нубес) и отдельный чек-бокс	Записи всех компаний.	Создание, редактирование, удаление всех записей. Изменение лимита для отдельных компаний.

Правило	Описание
Формат 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