# Документация: Описание функциональных характеристик экземпляра программного обеспечения КАПСУЛА

## 1. Общие сведения

Программное обеспечение КАПСУЛА (Комплексный Анализ Периметра и Сетевых Угроз) представляет собой комплексную систему для автоматизированного сканирования сетевой инфраструктуры, анализа уязвимостей и управления безопасностью периметра.

Система предназначена для:
- Обнаружения активных хостов и открытых портов в сетевой инфраструктуре
- Анализа уязвимостей и оценки рисков безопасности
- Генерации аналитических отчетов и документирования результатов
- Управления множественными клиентами и тенантами в рамках единой системы

## 2. Функциональные модули системы

### 2.1. Модуль сканирования периметра (Perimeter Scanning)

**Назначение:** Быстрое обнаружение активных хостов и открытых TCP-портов в заданных сетевых диапазонах.

**Функциональные характеристики:**
- **Двухэтапное сканирование:**
  - Первый этап: быстрое TCP-сканирование с помощью Masscan для обнаружения открытых портов
  - Второй этап: детальное сканирование с помощью Nmap для определения версий сервисов и дополнительной информации
- **Режимы сканирования:**
  - TCP-сканирование выбранных портов (режим `tcp`)
  - Полное TCP-сканирование всех портов (режим `all`)
- **Определение версий сервисов:** Опциональное определение названий и версий сервисов на открытых портах (опция `service-info`)
- **Поддержка IPv4 и IPv6:** Автоматическое сканирование IPv6 адресов для FQDN с поддержкой IPv6
- **Исключения:** Возможность исключения определенных хостов или подсетей из сканирования

**Технические параметры:**
- Скорость сканирования Masscan настраивается через параметр `RATE` (по умолчанию 2048 пакетов/сек)
- Тип сканирования Nmap настраивается через параметр `NMAP_SCAN_TYPE` (по умолчанию `sT` - TCP connect scan)
- Поддерживаемые типы сканирования Nmap: `sS` (SYN scan), `sT` (TCP connect scan), `sA` (ACK scan), `sW` (Window scan), `sM` (Maimon scan)

### 2.2. Модуль управления уязвимостями (Vulnerability Management, VM)

Модуль VM запускает Nmap (vulners/aggressive), Nuclei, OWASP ZAP и DursGo как **отдельные задачи очереди** (`vm_nmap`, `vm_nuclei`, `vm_zap`, `vm_dursgo`) на свободных воркерах; AI summary, оценка устойчивости и перевод findings выполняются один раз в `vm_finalize` после barrier. Список целей в каждой задаче перемешивается. Одновременная нагрузка ограничивается `VM_SCANNER_MAX_PARALLEL` (default 2).

**Назначение:** Комплексный анализ уязвимостей обнаруженных хостов и сервисов.

**Функциональные характеристики:**
- **Обнаружение CVE:** Автоматическое обнаружение известных уязвимостей (CVE) с помощью Nmap скрипта `vulners`
- **Агрессивное сканирование:** Детальное сканирование с опцией `-A` для получения максимальной информации о хостах
- **Веб-сканирование уязвимостей:** Сканирование веб-приложений и сервисов с помощью Nuclei, OWASP ZAP и DursGo (только VM); FQDN в VM добавляются как `http(s)://fqdn` после DNS-сопоставления с IP веб-хостов, найденных периметром
- **Точечные и Zero/One-day проверки (меню «Инструменты»):** Для роли `client_analyst` на **платном** тарифе (`professional` / `enterprise` / `custom`; не `free`) доступен набор инструментов проверки одного IP или FQDN (Nmap-порты, Nmap vulners, Nuclei, OWASP ZAP, DursGo, PentestAgent), а также **Zero-day и One-day проверки** — прогон одного опубликованного шаблона Nuclei по веб-целям последнего завершённого периметр-скана тенанта. На бесплатном тарифе меню и все функции Tools недоступны (UI скрыт, API 403). Перед запуском точечной проверки система проверяет, что цель входит в сети или список FQDN выбранного тенанта. Результаты выгружаются в PDF на языке интерфейса пользователя; запуск отражается в журнале аудита. Администратор на странице **Все сканирования** (вкладка **Инструменты**) может просматривать все Tool-проверки по клиентам и **останавливать** активные (`pending`/`running`); удаление ToolCheck доступно только клиенту.
- **Проверка устранения:** С вкладки Периметр (нелегитимный порт) и из VM Results (CVE/Nuclei/ZAP/DursGo) аналитик на платном тарифе может запустить точечный Tool-повтор сканера, получить вердикт «устранено / не устранено» и PDF с датами обнаружения и проверки.
- **False Positive:** Возможность помечать стабильные tenant-scoped сигнатуры CVE, Nuclei, ZAP и DursGo как False Positive. Такие находки остаются видимыми, но не учитываются в активных счетчиках, оценке защищенности, экспортных отчетах и новых AI-сводках.
- **Оценка рисков:**
  - Явные CVE из Nmap, Nuclei, OWASP ZAP и DursGo обогащаются CVSS, EPSS и percentile с сохранением источника и цели
  - Вероятность эксплуатации рассчитывается по уникальным CVE каждого хоста/нормализованной web-цели; False Positive исключаются
  - Индекс киберустойчивости получает ровно один штраф по наиболее тяжёлой активной находке любого сканера: HIGH/CRITICAL ×0.5, иначе MEDIUM ×0.75
- **AI-анализ:** Опциональная генерация аналитических сводок с помощью AI на основе всех собранных данных VM; однотипные ZAP/Nuclei/DursGo findings группируются для устойчивой работы на больших FQDN-сканированиях

**Технические параметры:**
- Настраиваемые шаблоны Nuclei через параметр `NUCLEI_TEMPLATES` (по умолчанию `http/cves,ssl`)
- Таймаут Nuclei сканирования настраивается через параметр `NUCLEI_TIMEOUT_SEC` (по умолчанию 1800 секунд)
- Поддержка SOCKS5 прокси для Nuclei через параметр `NUCLEI_SOCKS5_PROXY`
- DursGo: `DURSGO_PATH`, `DURSGO_TIMEOUT_SEC` (1800), `DURSGO_RENDER_JS` (false) и связанные флаги; модули `-s` — `VMConfig.dursgo_scanners` (пусто → `all`); без `--enable-ai`
- Параллельный fan-out сканеров: `VM_SCANNER_MAX_PARALLEL` (default 2; `<=0` = unlimited)
- EPSS API URL настраивается через параметр `EPSS_API_URL` (по умолчанию `https://api.first.org/data/v1/epss`)
- Порог значимости EPSS настраивается через параметр `EPSS_SIGNIFICANT_THRESHOLD` (по умолчанию 0.1)

### 2.3. Модуль управления данными

**Назначение:** Хранение, организация и управление данными сканирований и конфигураций.

**Функциональные характеристики:**
- **Хранение результатов:** Все результаты сканирований хранятся в базе данных PostgreSQL
- **Структурированное хранение:**
  - Результаты периметра: хосты, порты, сервисы
  - Результаты VM: уязвимости (CVE), результаты Nuclei/ZAP/DursGo, оценки рисков
  - Метаданные сканирований: время запуска, завершения, статус, режим
- **Управление тенантами:** Поддержка множественных тенантов (арендаторов) для разделения данных по клиентам
- **Управление сетями:** Возможность добавления администратором и просмотра/удаления клиентским аналитиком списков сетей (CIDR) для каждого тенанта
- **Управление исключениями:** Возможность исключения определенных хостов или подсетей из сканирования
- **Управление FQDN:** Возможность добавления администратором и просмотра/удаления клиентским аналитиком списков FQDN (Fully Qualified Domain Names) для каждого тенанта; они используются для IPv6 Nmap, VM Nmap и VM веб-сканирования Nuclei/ZAP/DursGo при совпадении resolved IP с веб-хостом периметра
- **Выгрузка конфигурации:** Клиентский пользователь может выгрузить snapshot конфигурации тенанта (TCP-порты, сети, исключения, FQDN, сохраненные False Positive) в PDF, CSV или JSON

**Технические параметры:**
- База данных: PostgreSQL 15+
- Использование GUID (UUID) для идентификации записей (безопасность от перебора ID)
- Индексы на GUID и даты для быстрой сортировки и поиска
- Оптимизация транзакций для минимизации блокировок при параллельной работе нескольких workers

### 2.4. Модуль генерации отчетов

**Назначение:** Создание документированных отчетов о результатах сканирований.

**Функциональные характеристики:**
- **Единый PDF отчет:** Комплексный отчет, включающий разделы "Периметр" и "VM"
- **Детальная информация об уязвимостях:**
  - CVE идентификаторы
  - CVSS оценки
  - EPSS оценки
  - Вероятность взлома для каждого хоста
- **Фильтрация по критичности:** Возможность фильтрации уязвимостей по уровню критичности (low, medium, high, critical)
- **Сравнение сканирований:** Генерация PDF отчетов сравнения двух сканирований для отслеживания изменений
- **AI-сводки:** Опциональная генерация аналитических сводок с помощью AI на основе результатов VM сканирования, с автоматическим compact mode при большом prompt
- **Поддержка кириллицы:** Корректное отображение кириллических символов в PDF отчетах
- **Автоматический парсинг:** Автоматический парсинг markdown таблиц в PDF отчетах

**Технические параметры:**
- Формат отчетов: PDF
- Библиотека генерации: fpdf2
- Поддержка Unicode и кириллицы
- Автоматическое форматирование таблиц и списков

### 2.5. Модуль расписаний сканирований

**Назначение:** Автоматический запуск сканирований по заданному расписанию.

**Функциональные характеристики:**
- **Cron-выражения:** Использование стандартных cron-выражений для задания расписания
- **Оценка времени сканирования:** Автоматическая оценка времени сканирования на основе максимального времени из предыдущих сканирований
- **Предупреждения:** Предупреждение администратора, если расписание предполагает более частый запуск, чем время сканирования
- **Гибкая настройка:** Возможность настройки всех параметров сканирования для расписания:
  - Режим сканирования (tcp или all)
  - TCP порты
  - Определение версий сервисов
  - Автоматический запуск VM сканирования
- **Управление расписаниями:** Возможность создания, редактирования, удаления и включения/отключения расписаний

**Технические параметры:**
- Библиотека парсинга cron: croniter
- Расчет следующего запуска на основе cron-выражения
- Отслеживание последнего и следующего запуска для каждого расписания

### 2.6. Модуль распределенного сканирования

**Назначение:** Распределение задач сканирования между несколькими сканирующими модулями (workers).

**Функциональные характеристики:**
- **Централизованная очередь задач:** Все задачи сканирования добавляются в централизованную очередь в базе данных
- **Автоматическое распределение:** Автоматическое распределение задач между доступными workers
- **Поддержка множественных workers:** Возможность запуска неограниченного количества workers одновременно
- **Горизонтальное масштабирование:** Workers могут запускаться на разных хостах и подключаться к системе через HTTPS API
- **Heartbeat механизм:** Автоматический heartbeat для поддержания активности workers
- **Приоритеты задач:** Поддержка приоритетов задач для управления порядком выполнения
- **Retry логика:** Автоматическая обработка ошибок с возможностью повторного выполнения задач

**Технические параметры:**
- Аутентификация workers через Bearer токены (безопасность)
- Polling интервал настраивается через параметр `WORKER_POLL_INTERVAL` (по умолчанию 5 секунд)
- Максимальное количество параллельных задач на worker настраивается через параметр `WORKER_MAX_CONCURRENT_TASKS` (по умолчанию 1)
- Оптимизация транзакций: долгие операции (сканирование) выполняются вне транзакций БД

### 2.7. Модуль аутентификации и авторизации

**Назначение:** Обеспечение безопасности доступа к системе и данным.

**Функциональные характеристики:**
- **HTTP Basic Authentication:** Аутентификация пользователей через HTTP Basic Auth
- **Хеширование паролей:** Пароли хранятся в базе данных в виде bcrypt хешей
- **Двухфакторная аутентификация (2FA):** Поддержка TOTP-аутентификации через Яндекс Ключ или другие TOTP-приложения
- **Роли пользователей:**
  - Администратор: полный доступ ко всем функциям системы
  - Клиент: доступ только к своим тенантам и данным
- **Проверка доступа:** Автоматическая проверка доступа к тенантам на уровне API для каждого запроса
- **Изоляция данных:** Клиенты не имеют доступа к данным других клиентов (multi-tenancy)

**Технические параметры:**
- Библиотека хеширования: bcrypt
- Библиотека TOTP: pyotp
- Генерация QR-кодов для настройки 2FA
- Проверка доступа на уровне каждого API endpoint

### 2.8. Модуль интернационализации

**Назначение:** Поддержка множественных языков интерфейса.

**Функциональные характеристики:**
- **Поддерживаемые языки:** Русский и английский
- **Индивидуальные настройки:** Язык интерфейса сохраняется индивидуально для каждого пользователя в базе данных
- **Динамическое переключение:** Возможность изменения языка интерфейса без перезагрузки страницы
- **Перевод всех элементов:** Все элементы интерфейса переведены на поддерживаемые языки

**Технические параметры:**
- Хранение предпочтений языка в таблице `user` базы данных
- Централизованная система переводов в файле `translations.ts`
- Автоматическое применение языка при входе в систему

## 3. Интерфейсы пользователя

### 3.1. Веб-интерфейс (Web Interface)

**Назначение:** Удобный графический интерфейс для управления системой через браузер.

**Функциональные характеристики:**
- **Админ-панель:** Полнофункциональная панель администратора для управления системой
- **Клиентский портал:** Упрощенный интерфейс для клиентов для работы со своими тенантами
- **Мобильный интерфейс:** Адаптированная версия интерфейса для мобильных устройств
- **Real-time обновления:** Автоматическое обновление статуса сканирований через WebSocket
- **Интерактивные элементы:**
  - Диалоговые окна для просмотра деталей
  - Формы для ввода данных
  - Таблицы с сортировкой и фильтрацией
  - Графики и визуализации результатов

**Технические параметры:**
- Технологии: React 18.2.0, TypeScript 5.3.3, Material-UI 5.15.0
- Коммуникация: HTTPS REST API и WebSocket
- Поддержка HTTPS с самоподписанными и доверенными SSL-сертификатами

### 3.2. REST API

**Назначение:** Программный доступ ко всем функциям системы через REST API.

**Функциональные характеристики:**
- **RESTful архитектура:** Стандартные HTTP методы (GET, POST, PUT, DELETE) для работы с ресурсами
- **Полный набор endpoints:** Доступ ко всем функциям системы через API
- **Документация API:** Автоматическая генерация документации через Swagger UI
- **Типизированные ответы:** Использование Pydantic схем для валидации и типизации данных
- **WebSocket поддержка:** Real-time обновления через WebSocket для отслеживания статуса

**Технические параметры:**
- Технологии: FastAPI, Uvicorn
- Формат данных: JSON
- Аутентификация: HTTP Basic Auth для пользователей, Bearer Token для workers
- Документация: Swagger UI на `/docs`

### 3.3. CLI (Command Line Interface)

**Назначение:** Командная строка для прямого управления системой.

**Функциональные характеристики:**
- **Управление тенантами:** Создание, редактирование, удаление тенантов
- **Управление сетями:** Добавление и удаление сетей для тенантов
- **Запуск сканирований:** Прямой запуск сканирований из командной строки
- **Просмотр результатов:** Просмотр результатов сканирований в консоли
- **Инициализация БД:** Инициализация схемы базы данных

**Технические параметры:**
- Библиотека CLI: Click
- Использование той же бизнес-логики и БД, что и API
- Работа параллельно с веб-интерфейсом

## 4. Производительность и масштабируемость

### 4.1. Производительность сканирования

**Характеристики:**
- Скорость сканирования Masscan настраивается (по умолчанию 2048 пакетов/сек)
- Параллельное выполнение задач на нескольких workers
- Оптимизация транзакций БД для минимизации блокировок

### 4.2. Масштабируемость

**Характеристики:**
- **Горизонтальное масштабирование:** Неограниченное количество workers на разных хостах
- **Вертикальное масштабирование:** Возможность увеличения ресурсов контейнеров
- **Масштабируемость БД:** PostgreSQL поддерживает высокую нагрузку и параллельные операции
- **Connection pooling:** Оптимизация подключений к базе данных

### 4.3. Надежность

**Характеристики:**
- **Отказоустойчивость:** Автоматический retry при ошибках выполнения задач
- **Мониторинг:** Health checks для отслеживания состояния сервисов
- **Логирование:** Подробное логирование всех операций для диагностики
- **Резервное копирование:** Поддержка стандартных механизмов резервного копирования PostgreSQL

## 5. Безопасность

### 5.1. Аутентификация

**Характеристики:**
- Хеширование паролей с использованием bcrypt
- Двухфакторная аутентификация через TOTP
- Безопасная аутентификация workers через Bearer токены

### 5.2. Авторизация

**Характеристики:**
- Разделение ролей (администратор/клиент)
- Проверка доступа на уровне каждого API endpoint
- Изоляция данных между клиентами

### 5.3. Защита данных

**Характеристики:**
- Использование GUID вместо последовательных ID (защита от перебора)
- HTTPS для всех коммуникаций
- Поддержка самоподписанных и доверенных SSL-сертификатов

## 6. Интеграции

### 6.1. Внешние API

**Характеристики:**
- **EPSS API:** Интеграция с EPSS API для оценки вероятности эксплуатации уязвимостей
- **AI API:** Опциональная интеграция с внешним AI API для генерации аналитических отчетов и перевода findings; одинаковые описания Nuclei/ZAP/DursGo переводятся один раз и переиспользуются
- **Nuclei / ZAP / DursGo:** Интеграция веб-сканеров уязвимостей (DursGo — только VM)

### 6.2. Инструменты сканирования

**Характеристики:**
- **Masscan:** Быстрое TCP-сканирование
- **Nmap:** Детальное сканирование и определение версий сервисов
- **Nuclei:** Веб-сканирование уязвимостей
- **OWASP ZAP:** Сканирование веб-приложений (VM)
- **DursGo:** Сканирование веб-приложений (только VM, http/https)

## 7. Управление конфигурацией

### 7.1. Гибкая настройка

**Характеристики:**
- Настройка через переменные окружения
- Поддержка файла `.env` для локальной конфигурации
- Приоритет настроек: файл конфигурации > `.env` > переменные окружения

### 7.2. Конфигурация сканирований

**Характеристики:**
- Настройка параметров сканирования для каждого тенанта
- Сохранение конфигураций VM сканирования
- Управление исключениями и FQDN на уровне тенанта

## 8. Заключение

Система КАПСУЛА предоставляет комплексный набор функциональных возможностей для автоматизированного сканирования сетевой инфраструктуры, анализа уязвимостей и управления безопасностью периметра. Система характеризуется:

- Высокой производительностью и масштабируемостью
- Гибкостью настройки и конфигурации
- Безопасностью и изоляцией данных
- Удобством использования через веб-интерфейс и API
- Надежностью и отказоустойчивостью

Все функциональные модули системы интегрированы в единую архитектуру и работают совместно для обеспечения комплексного анализа сетевой безопасности.

---

*Конец документа*