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

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

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

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

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

```go
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-аномалий |

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

```go
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` | Цветной бейдж уровня критичности |