98 lines
12 KiB
Markdown
98 lines
12 KiB
Markdown
Техническое задание
|
|
Микросервис управления доверенными адресами клиентов
|
|
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 |
|