From da3975950cc74ff291dbd4badfda1cfd976d9038 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9CNaeel=E2=80=9D?= Date: Sat, 30 May 2026 07:10:43 +0300 Subject: [PATCH] =?UTF-8?q?docs:=20=D0=B8=D0=B7=D0=B2=D0=BB=D0=B5=D1=87?= =?UTF-8?q?=D1=91=D0=BD=20=D1=82=D0=B5=D0=BA=D1=81=D1=82=20=D0=A2=D0=97=20?= =?UTF-8?q?=D0=B8=D0=B7=20WhiteIPlist.docx?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- WhiteIPlist.txt | 120 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 120 insertions(+) create mode 100644 WhiteIPlist.txt diff --git a/WhiteIPlist.txt b/WhiteIPlist.txt new file mode 100644 index 0000000..ca5c6f4 --- /dev/null +++ b/WhiteIPlist.txt @@ -0,0 +1,120 @@ +Техническое задание +Микросервис управления доверенными адресами клиентов +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 → роль настраивается на этапе развёртывания. +Роль +Идентификация +Видимость записей +Права на изменение +Клиент (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