dip-ids/docs/modules.md

Описание модулей DIP-IDS

1. Модуль захвата трафика (internal/capture)

Назначение

Обеспечивает получение сетевых пакетов из двух источников: живой захват с сетевого интерфейса и чтение ранее записанных PCAP-файлов.

Файлы

Файл	Описание
capture.go	Структура Capturer, функции New, Start, Stop, ListInterfaces

Ключевые типы

type Mode string  // "live" или "pcap"

type Config struct {
    Interface   string  // имя интерфейса (для live)
    PCAPFile    string  // путь к файлу (для pcap)
    Mode        Mode
    Snaplen     int32   // максимальный размер захватываемого пакета
    Promiscuous bool    // неразборчивый режим
}

Принцип работы

Start(ctx) открывает pcap.Handle нужного типа (live или offline) и запускает горутину, которая читает пакеты в буферизованный канал chan gopacket.Packet ёмкостью 1024. При отмене контекста или достижении конца файла канал закрывается.

---

2. Движок анализа (internal/analyzer)

Назначение

Центральный компонент, который принимает пакеты и распределяет их по детекторам.

Файлы

Файл	Описание
engine.go	Структура Engine, методы Run, Reset, Stats
detector.go	Интерфейс Detector, вспомогательная структура timeWindow
portscan.go	Детектор сканирования портов
bruteforce.go	Детектор перебора паролей
dos.go	Детектор DoS/DDoS атак
arp.go	Детектор ARP-спуфинга
dns.go	Детектор DNS-аномалий

Интерфейс детектора

type Detector interface {
    Name() string                               // уникальное имя
    Analyze(pkt gopacket.Packet) []Alert        // анализ пакета, возврат алертов
    Reset()                                     // сброс внутреннего состояния
}

Sliding Window

Все детекторы используют скользящее временное окно (timeWindow) для хранения событий. При каждом обращении устаревшие записи автоматически удаляются:

Время:   t-10s ... t-5s ... t-3s ... now
События:  [old]   [old]   [keep] [keep] [keep]
                           ↑
                         cutoff = now - window_size

Дедупликация алертов

Каждый детектор хранит alerted map[string]time.Time — время последнего алерта по ключу (IP, IP:port и т.д.). Повторный алерт генерируется не чаще одного раза в 30–60 секунд на один источник.

---

3. Модуль хранения данных (internal/storage)

Назначение

Персистентное хранение алертов, статистики пакетов и сессий захвата.

Файлы

Файл	Описание
models.go	GORM-модели: Alert, PacketStat, CaptureSession
db.go	Структура DB, CRUD-методы, агрегирующие запросы

Модели данных

Alert — запись об обнаруженной угрозе:

ID | CreatedAt | Type | Severity | SrcIP | DstIP | SrcPort | DstPort | Protocol | Description | Count

PacketStat — статистика по пакетам (сохраняется каждый 10-й пакет):

ID | CreatedAt | Protocol | SrcIP | DstIP | Bytes

CaptureSession — сессия захвата трафика:

ID | CreatedAt | EndedAt | Source | Mode | Status | TotalPkts | TotalBytes

Методы агрегации

Метод	SQL-эквивалент
AlertsBySeverity()	SELECT severity, COUNT(*) GROUP BY severity
AlertsByType()	SELECT type, COUNT(*) GROUP BY type
TopSourceIPs(n)	SELECT src_ip, COUNT(*) GROUP BY src_ip ORDER BY count DESC LIMIT n
AlertsTimeline(h)	SELECT strftime('%H:00', created_at), COUNT(*) GROUP BY hour

---

4. API сервер (internal/api)

Назначение

HTTP сервер на базе Gin, предоставляет REST API для фронтенда.

Файлы

Файл	Описание
server.go	Инициализация Gin, регистрация маршрутов, CORS middleware
handlers/alerts.go	GET /api/alerts, DELETE /api/alerts, DELETE /api/alerts/:id
handlers/stats.go	GET /api/stats/summary, /timeline, /top-ips
handlers/capture.go	Управление захватом: start, stop, upload, status, sessions
handlers/reports.go	GET /api/reports/generate — скачать PDF

CORS

Сервер разрешает запросы с любого origin (*) для работы Nuxt dev-сервера на порту 3000.

Управление состоянием захвата

CaptureHandler хранит указатель active *CaptureState, который содержит context.CancelFunc для остановки текущей сессии. Одновременно может быть только одна активная сессия.

---

5. Генератор отчётов (internal/report)

Назначение

Формирование PDF-отчёта по всем накопленным данным.

Файлы

Файл	Описание
pdf.go	Структура Data, функция Generate(data) ([]byte, error)

Структура отчёта

1. Заголовок — название системы, дата формирования, версия
2. Метаданные сессии — источник трафика, режим, длительность, объём
3. Сводка по критичности — таблица с цветовой маркировкой (критический / высокий / средний / низкий)
4. Типы угроз — таблица по типам обнаруженных атак
5. Топ источников — 10 наиболее активных IP-адресов
6. Журнал инцидентов — детальная таблица до 200 алертов

Библиотека maroto v2

Grid-based компоновка: страница делится на 12 колонок, строки (row) содержат колонки (col), в колонках размещаются компоненты (text, line).

---

6. Фронтенд (frontend/)

Назначение

Веб-панель управления для мониторинга, управления захватом и просмотра статистики.

Структура

Путь	Назначение
pages/index.vue	Дашборд: карточки метрик, графики, топ IP, последние алерты
pages/alerts.vue	Журнал алертов с фильтрацией и пагинацией
pages/capture.vue	Управление захватом (live + PCAP upload), история сессий
pages/stats.vue	Статистика: timeline, распределение по типам и критичности
layouts/default.vue	Боковое меню, заголовок, индикатор статуса захвата
composables/useApi.ts	Базовый HTTP клиент (get, post, del, upload)
composables/useCaptureStatus.ts	Глобальный polling статуса захвата (каждые 3 сек)
components/MetricCard.vue	Карточка числовой метрики с иконкой
components/SeverityBadge.vue	Цветной бейдж уровня критичности