Initial commit

2026-04-12 22:26:26 +04:00
commit 68f9a01ed5
44 changed files with 7134 additions and 0 deletions
@@ -0,0 +1,131 @@
+# Архитектура системы DIP-IDS
+
+## 1. Общая схема
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                         Пользователь                                │
+│                    браузер → localhost:3000                          │
+└───────────────────────────┬─────────────────────────────────────────┘
+                            │ HTTP
+┌───────────────────────────▼─────────────────────────────────────────┐
+│                     Nuxt 3 Frontend                                 │
+│                                                                     │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────────────┐   │
+│  │Dashboard │  │ Alerts   │  │ Capture  │  │    Stats         │   │
+│  └──────────┘  └──────────┘  └──────────┘  └──────────────────┘   │
+│  Nuxt UI · vue-chartjs · Chart.js                                   │
+└───────────────────────────┬─────────────────────────────────────────┘
+                            │ REST API (proxy /api/*)
+┌───────────────────────────▼─────────────────────────────────────────┐
+│                     Go Backend (:8080)                              │
+│                                                                     │
+│  ┌──────────────────────────────────────────────────────────────┐  │
+│  │                      Gin HTTP Router                         │  │
+│  │  /api/alerts  /api/stats  /api/capture  /api/reports         │  │
+│  └──────────────────────────┬───────────────────────────────────┘  │
+│                             │                                       │
+│  ┌──────────────────────────▼───────────────────────────────────┐  │
+│  │                    Analyzer Engine                           │  │
+│  │                                                              │  │
+│  │  ┌────────────┐  ┌────────────┐  ┌────────────┐            │  │
+│  │  │PortScan    │  │BruteForce  │  │    DoS     │            │  │
+│  │  │Detector    │  │Detector    │  │  Detector  │            │  │
+│  │  └────────────┘  └────────────┘  └────────────┘            │  │
+│  │  ┌────────────┐  ┌────────────┐                             │  │
+│  │  │ARPSpoof    │  │DNS Anomaly │                             │  │
+│  │  │Detector    │  │Detector    │                             │  │
+│  │  └────────────┘  └────────────┘                             │  │
+│  └──────────────────────────────────────────────────────────────┘  │
+│                                                                     │
+│  ┌──────────────┐        ┌─────────────┐     ┌─────────────────┐  │
+│  │   Capture    │        │   Storage   │     │  PDF Report     │  │
+│  │  (gopacket)  │        │  (SQLite)   │     │  (maroto v2)    │  │
+│  │  live / pcap │        │    GORM     │     │                 │  │
+│  └──────────────┘        └─────────────┘     └─────────────────┘  │
+└─────────────────────────────────────────────────────────────────────┘
+                            │
+              ┌─────────────┴──────────────┐
+              │                            │
+     ┌────────▼────────┐         ┌─────────▼────────┐
+     │  Сетевой        │         │   PCAP файлы     │
+     │  интерфейс      │         │   (.pcap/.pcapng)│
+     │  (eth0, wlan0)  │         │                  │
+     └─────────────────┘         └──────────────────┘
+```
+
+## 2. Поток данных
+
+```
+Сетевой интерфейс / PCAP файл
+        │
+        ▼
+  pcap.Handle (gopacket)
+        │  chan gopacket.Packet (буфер 1024)
+        ▼
+  Analyzer Engine.Run()
+        │  fan-out: каждый пакет → все детекторы
+        ├──▶ PortScanDetector.Analyze(pkt)
+        ├──▶ BruteForceDetector.Analyze(pkt)
+        ├──▶ DoSDetector.Analyze(pkt)
+        ├──▶ ARPSpoofDetector.Analyze(pkt)
+        └──▶ DNSAnomalyDetector.Analyze(pkt)
+                    │  []storage.Alert
+                    ▼
+              storage.DB.CreateAlert()
+                    │
+                    ▼
+              SQLite (nids.db)
+                    │
+              ┌─────┴──────┐
+              ▼            ▼
+          REST API    PDF Report
+          (Gin)       (maroto v2)
+              │
+              ▼
+        Nuxt Frontend
+```
+
+## 3. Компоненты и их ответственность
+
+| Компонент | Пакет | Ответственность |
+|---|---|---|
+| `Capturer` | `internal/capture` | Открывает pcap handle (live или файл), читает пакеты в канал |
+| `Engine` | `internal/analyzer` | Принимает пакеты из канала, фанаутит детекторам, сохраняет алерты |
+| `Detector` (интерфейс) | `internal/analyzer` | Контракт: `Analyze(pkt) []Alert`, `Reset()` |
+| `DB` | `internal/storage` | CRUD алертов, статистики, сессий через GORM + SQLite |
+| `Server` | `internal/api` | Gin HTTP сервер, CORS, маршрутизация |
+| `handlers/*` | `internal/api/handlers` | Обработчики REST эндпоинтов |
+| `report.Generate` | `internal/report` | Генерация структурированного PDF через maroto v2 |
+
+## 4. Модель конкурентности
+
+```
+main goroutine
+    │
+    ├── srv.Run()          ← HTTP сервер (Gin, внутренние goroutines)
+    │
+    └── при старте захвата:
+            │
+            ├── capture goroutine  ← читает пакеты → chan
+            │
+            └── engine goroutine   ← engine.Run(ctx, pkts)
+                    │
+                    └── обрабатывает пакеты синхронно (детекторы потокобезопасны через sync.Mutex)
+```
+
+Остановка захвата — через отмену `context.Context` (cancel функция хранится в `CaptureState`).
+
+## 5. Выбор технологий
+
+| Технология | Обоснование |
+|---|---|
+| **Go** | Системный язык, оптимален для сетевых инструментов; компилируется в один бинарник |
+| **gopacket** | Стандарт де-факто для захвата пакетов в Go; оборачивает libpcap |
+| **Gin** | Минималистичный HTTP фреймворк с высокой производительностью |
+| **GORM + SQLite** | Не требует отдельного сервера БД; достаточно для демо и небольших сетей |
+| **maroto v2** | Grid-based PDF генератор; создаёт структурированные деловые отчёты |
+| **Nuxt 3** | SSR/SPA фреймворк на Vue 3; удобная файловая маршрутизация |
+| **Nuxt UI** | Официальная UI библиотека Nuxt; Tailwind CSS, тёмная тема из коробки |
+| **Chart.js + vue-chartjs** | Зрелая библиотека графиков; хорошая интеграция с Vue 3 |
+| **Bun** | Быстрый JavaScript runtime и пакетный менеджер; замена npm/yarn |