From db1998c428e51b6eea7d064f5c903aa7dea203f9 Mon Sep 17 00:00:00 2001 From: igor04091968 Date: Tue, 5 May 2026 01:46:50 +0300 Subject: [PATCH] docs(architecture): add readable architecture diagrams - Add Mermaid diagram for high-level architecture - Add simple ASCII architecture for quick understanding - Document data flows for all monitoring scenarios - Include deployment steps and port mappings - Add quick start guide and key scenarios Generated with [Devin](https://cli.devin.ai/docs) Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- docs/architecture-diagram.md | 303 +++++++++++++++++++++++++++++++++++ docs/architecture-simple.md | 278 ++++++++++++++++++++++++++++++++ 2 files changed, 581 insertions(+) create mode 100644 docs/architecture-diagram.md create mode 100644 docs/architecture-simple.md diff --git a/docs/architecture-diagram.md b/docs/architecture-diagram.md new file mode 100644 index 0000000..fcc0ea8 --- /dev/null +++ b/docs/architecture-diagram.md @@ -0,0 +1,303 @@ +# ActivityWatch-Russian Architecture Diagram + +## High-Level Architecture + +```mermaid +graph TB + subgraph "Windows Clients" + A[ActivityWatch Watchers] + B[DLP Endpoint Collector] + C[Browser Domains Collector] + D[Email Outbound Collector] + E[Worktime Session Collector] + end + + subgraph "Linux Server" + F[ActivityWatch Server] + G[PostgreSQL Database] + H[Aggregation Scripts] + end + + subgraph "Monitoring & Integration" + I[pfSense Firewall] + J[Prometheus Exporter] + end + + subgraph "Visualization" + K[Grafana] + L[Prometheus] + M[ActivityWatch WebUI] + end + + A -->|HTTP API| F + B -->|Events| F + C -->|Events| F + D -->|Events| F + E -->|Events| F + + F -->|Store| G + F -->|API| M + + I -->|Logs| F + H -->|Read/Write| G + H -->|Read| F + + J -->|Metrics| L + L -->|Scrape| J + F -->|API| J + + K -->|Query| L + K -->|Query| G +``` + +## Component Interactions + +### Data Flow + +``` +Windows Collectors → ActivityWatch Server → PostgreSQL Database + ↓ + Aggregation Scripts + ↓ + Grafana Dashboards +``` + +### DLP Monitoring Flow + +``` +User Activity (clipboard/print/USB) + ↓ +DLP Endpoint Collector (PowerShell) + ↓ +DLP Policy Evaluation + ↓ +ActivityWatch Events (via HTTP API) + ↓ +PostgreSQL Database + ↓ +Aggregation Scripts (Python) + ↓ +Grafana DLP Dashboard +``` + +### Browser Monitoring Flow + +``` +User Browser Activity + ↓ +Browser Domains Collector (PowerShell) + ↓ +Domain Extraction & Categorization + ↓ +DLP Rule Check + ↓ +ActivityWatch Events + ↓ +WebUI Domain Dashboard +``` + +### Email Monitoring Flow + +``` +Outlook / SMTP Activity + ↓ +Email Outbound Collector (PowerShell) + ↓ +Email Policy Evaluation + ↓ +ActivityWatch Events + ↓ +Grafana Email Dashboard +``` + +### pfSense Integration Flow + +``` +pfSense Firewall Logs + ↓ +pfSense Poller (Python) + ↓ +HTTP API Query + ↓ +ActivityWatch Events + ↓ +Network Activity Dashboard +``` + +### Metrics Flow + +``` +ActivityWatch Server + ↓ +Prometheus Exporter (Python) + ↓ +HTTP Metrics Endpoint (port 9398) + ↓ +Prometheus Scraping + ↓ +Grafana Dashboards +``` + +## Component Details + +### Windows Collectors + +| Component | Language | Purpose | Output | +|-----------|----------|---------|--------| +| DLP Endpoint Collector | PowerShell | Monitor clipboard, print, USB | ActivityWatch events | +| Browser Domains Collector | PowerShell | Track visited domains | ActivityWatch events | +| Email Outbound Collector | PowerShell | Monitor sent emails | ActivityWatch events | +| Worktime Session Collector | PowerShell | Track work sessions | ActivityWatch events | + +### Server Components + +| Component | Language | Purpose | Dependencies | +|-----------|----------|---------|--------------| +| ActivityWatch Server | Rust | Core monitoring platform | SQLite/PostgreSQL | +| Aggregation Scripts | Python | Process DLP events | psycopg2, requests | +| Prometheus Exporter | Python | Export metrics to Prometheus | prometheus_client | + +### Integration Points + +| Integration | Protocol | Purpose | +|-------------|----------|---------| +| pfSense → AW | HTTP API | Firewall log collection | +| AW → Grafana | PostgreSQL | Direct database access | +| AW → Prometheus | HTTP /metrics | Metrics scraping | +| Collectors → AW | HTTP /api/buckets | Event submission | + +## Deployment Architecture + +``` +Domain Controller + ↓ (GPO / Scheduled Tasks) +Windows Workstations (user1, user2, ...) + ↓ (PowerShell Collectors) +ActivityWatch Server (Linux) + ↓ +PostgreSQL Database + ↓ +Grafana + Prometheus Stack +``` + +## File System Structure + +``` +ActivityWatch-Russian/ +├── windows/ # Windows collectors +│ ├── dlp-endpoint-signals-collector.ps1 +│ ├── browser-domains-native-collector.ps1 +│ ├── email-outbound-collector.ps1 +│ ├── worktime-session-collector.ps1 +│ ├── deploy-domain-users.ps1 # Deployment script +│ └── ActivityWatch.Windows.Common.psm1 +├── scripts/ # Server scripts +│ ├── aggregate_dlp_events.py +│ └── merge_aw_server_dbs.py +├── aw-server/ # WebUI patches +│ ├── aw-ru-patch.js +│ └── aw-sw-cleanup.js +├── pfsense/ # pfSense integration +│ └── pfsense-aw-poller.py +├── grafana-1c/ # Monitoring stack +│ ├── docker-compose.yml +│ ├── prometheus/ +│ ├── grafana/ +│ └── sql-exporter/ +│ └── collectors/ +│ └── aw_activitywatch.py +└── ansible/ # Automation + ├── playbooks/ + └── group_vars/ +``` + +## Network Ports + +| Service | Port | Protocol | Purpose | +|---------|------|----------|---------| +| ActivityWatch Server | 5600 | HTTP | WebUI & API | +| ActivityWatch Server | 5666 | HTTP | WebSocket | +| Prometheus | 9090 | HTTP | Metrics UI | +| Prometheus Exporter | 9398 | HTTP | AW metrics endpoint | +| Grafana | 3000 | HTTP | Dashboards | +| PostgreSQL | 5432 | TCP | Database | + +## Data Models + +### ActivityWatch Event Structure + +```json +{ + "timestamp": "2024-01-01T12:00:00Z", + "duration": 60.0, + "data": { + "title": "Window Title", + "url": "https://example.com", + "app": "chrome.exe", + "type": "activity" + } +} +``` + +### DLP Incident Structure + +```json +{ + "timestamp": "2024-01-01T12:00:00Z", + "type": "clipboard", + "rule": "credit_card_pattern", + "severity": "high", + "user": "user1", + "host": "WORKSTATION01", + "screenshot": "path/to/screenshot.png" +} +``` + +## Key Dependencies + +### Windows Dependencies +- PowerShell 5.1+ +- .NET Framework 4.8 +- ActivityWatch Windows binaries + +### Linux Dependencies +- Python 3.8+ +- PostgreSQL 12+ +- Docker & Docker Compose +- Rust (for AW server compilation) + +### Python Dependencies +```txt +psycopg2-binary +requests +prometheus_client +``` + +## Security Considerations + +### Data Flow Security +- Collectors → Server: HTTP (can be upgraded to HTTPS) +- Server → Database: Local connection or SSL +- pfSense → Server: HTTP over VPN +- Prometheus → Exporter: HTTP internal network + +### Access Control +- Windows collectors run as user context +- Server runs as dedicated service user +- Database access restricted to specific users +- Grafana authenticated via LDAP/Local users + +## Monitoring & Alerting + +### Metrics Collected +- Events per bucket +- Active hosts count +- Collector heartbeat status +- DLP incident rate +- Database query performance + +### Alerting Rules +- Collector offline > 30 minutes +- High DLP incident rate +- Database connection failures +- Disk space < 20% diff --git a/docs/architecture-simple.md b/docs/architecture-simple.md new file mode 100644 index 0000000..2fa54eb --- /dev/null +++ b/docs/architecture-simple.md @@ -0,0 +1,278 @@ +# ActivityWatch-Russian - Простая архитектура + +## Общая схема (сверху вниз) + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ ПОЛЬЗОВАТЕЛИ │ +│ (Windows рабочие станции) │ +└──────────────────────────┬──────────────────────────────────────┘ + │ + │ Коллекторы (PowerShell) + │ +┌──────────────────────────▼──────────────────────────────────────┐ +│ Windows Collectors (на каждой машине) │ +├──────────────────────────────────────────────────────────────────┤ +│ • DLP Endpoint Collector - буфер, печать, USB │ +│ • Browser Domains Collector - посещаемые сайты │ +│ • Email Outbound Collector - исходящая почта │ +│ • Worktime Session Collector - рабочее время │ +└──────────────────────────┬──────────────────────────────────────┘ + │ + │ HTTP API (отправка событий) + │ +┌──────────────────────────▼──────────────────────────────────────┐ +│ ActivityWatch Server (Linux) │ +├──────────────────────────────────────────────────────────────────┤ +│ • Принимает события от коллекторов │ +│ • Хранит в базе данных │ +│ • Предоставляет WebUI и API │ +└──────────────────────────┬──────────────────────────────────────┘ + │ + │ Хранение данных + │ +┌──────────────────────────▼──────────────────────────────────────┐ +│ PostgreSQL Database │ +├──────────────────────────────────────────────────────────────────┤ +│ • События активности │ +│ • DLP инциденты │ +│ • Метаданные хостов и пользователей │ +└──────────────────────────┬──────────────────────────────────────┘ + │ + │ Чтение/Обработка + │ +┌──────────────────────────▼──────────────────────────────────────┐ +│ Обработка и Агрегация │ +├──────────────────────────────────────────────────────────────────┤ +│ • aggregate_dlp_events.py - агрегация DLP событий │ +│ • pfSense Poller - логи firewall │ +│ • Prometheus Exporter - метрики для мониторинга │ +└──────────────────────────┬──────────────────────────────────────┘ + │ + │ Визуализация + │ +┌──────────────────────────▼──────────────────────────────────────┐ +│ Grafana + Prometheus Stack │ +├──────────────────────────────────────────────────────────────────┤ +│ • Prometheus - сбор метрик │ +│ • Grafana - дашборды и визуализация │ +│ • SQL Exporter - прямой доступ к PostgreSQL │ +└──────────────────────────────────────────────────────────────────┘ +``` + +## Потоки данных (по направлениям) + +### Поток 1: DLP мониторинг +``` +Пользователь → DLP Collector → Проверка правил → AW Server → PostgreSQL → Grafana +``` + +### Поток 2: Мониторинг браузеров +``` +Браузер → Browser Collector → Категоризация → AW Server → WebUI Dashboard +``` + +### Поток 3: Мониторинг почты +``` +Outlook/SMTP → Email Collector → Проверка правил → AW Server → Grafana +``` + +### Поток 4: pfFirewall логи +``` +pfSense → Poller (Python) → HTTP API → AW Server → Grafana +``` + +### Поток 5: Метрики +``` +AW Server → Exporter (Python) → /metrics → Prometheus → Grafana +``` + +## Компоненты по уровням + +### Уровень 1: Сбор данных (Windows) +``` +┌─────────────────────────────────────┐ +│ Windows Collectors (PowerShell) │ +│ ┌───────────────────────────────┐ │ +│ │ • dlp-endpoint-signals-collector│ │ +│ │ • browser-domains-collector │ │ +│ │ • email-outbound-collector │ │ +│ │ • worktime-session-collector │ │ +│ └───────────────────────────────┘ │ +└─────────────────────────────────────┘ +``` + +### Уровень 2: Хранение и обработка (Linux Server) +``` +┌─────────────────────────────────────┐ +│ ActivityWatch Server + PostgreSQL │ +│ ┌───────────────────────────────┐ │ +│ │ • aw-server (Rust) │ │ +│ │ • PostgreSQL Database │ │ +│ │ • WebUI (с RU патчами) │ │ +│ └───────────────────────────────┘ │ +└─────────────────────────────────────┘ +``` + +### Уровень 3: Интеграции и обработка +``` +┌─────────────────────────────────────┐ +│ Интеграции и Скрипты (Python) │ +│ ┌───────────────────────────────┐ │ +│ │ • aggregate_dlp_events.py │ │ +│ │ • pfsense-aw-poller.py │ │ +│ │ • aw_activitywatch_exporter │ │ +│ └───────────────────────────────┘ │ +└─────────────────────────────────────┘ +``` + +### Уровень 4: Визуализация и мониторинг +``` +┌─────────────────────────────────────┐ +│ Grafana + Prometheus (Docker) │ +│ ┌───────────────────────────────┐ │ +│ │ • Prometheus (порт 9090) │ │ +│ │ • Grafana (порт 3000) │ │ +│ │ • SQL Exporter (порт 9398) │ │ +│ └───────────────────────────────┘ │ +└─────────────────────────────────────┘ +``` + +## Развертывание + +### На Windows рабочих станциях +``` +1. Установка ActivityWatch (через InnoSetup installer) +2. Развертывание коллекторов (deploy-domain-users.ps1) +3. Настройка scheduled tasks +4. Конфигурация DLP политик +``` + +### На Linux сервере +``` +1. Установка ActivityWatch Server +2. Настройка PostgreSQL +3. Применение RU патчей к WebUI +4. Запуск скриптов агрегации +5. Запуск Prometheus Exporter +``` + +### Мониторинг стек +``` +1. Docker Compose развертывание +2. Настройка Prometheus scrape config +3. Импорт Grafana дашбордов +4. Настройка алертов +``` + +## Ключевые файлы + +``` +ActivityWatch-Russian/ +├── windows/ # Windows коллекторы +│ ├── dlp-endpoint-signals-collector.ps1 +│ ├── browser-domains-native-collector.ps1 +│ ├── email-outbound-collector.ps1 +│ └── deploy-domain-users.ps1 +│ +├── scripts/ # Серверные скрипты +│ └── aggregate_dlp_events.py +│ +├── aw-server/ # Патчи WebUI +│ └── aw-ru-patch.js +│ +├── pfsense/ # Интеграция pfSense +│ └── pfsense-aw-poller.py +│ +└── grafana-1c/ # Мониторинг стек + ├── docker-compose.yml + ├── prometheus/prometheus.yml + └── grafana/dashboards/ +``` + +## Порты + +| Компонент | Порт | Протокол | +|-----------|------|----------| +| ActivityWatch WebUI | 5600 | HTTP | +| ActivityWatch API | 5666 | WebSocket | +| Prometheus | 9090 | HTTP | +| Prometheus Exporter | 9398 | HTTP | +| Grafana | 3000 | HTTP | +| PostgreSQL | 5432 | TCP | + +## Быстрый старт + +### Запуск мониторинг стека +```bash +cd grafana-1c +docker-compose up -d +``` + +### Развертывание на Windows +```powersShell +.\windows\deploy-domain-users.ps1 +``` + +### Агрегация DLP событий +```bash +python3 scripts/aggregate_dlp_events.py +``` + +## Связи между компонентами + +``` +Windows Collectors + │ + ├─► ActivityWatch Server (HTTP API) + │ │ + │ ├─► PostgreSQL (хранение) + │ │ + │ ├─► WebUI (RU патчи) + │ │ + │ └─► Prometheus Exporter (метрики) + │ │ + │ └─► Prometheus + │ │ + │ └─► Grafana + │ +pfSense Firewall + │ + └─► pfSense Poller + │ + └─► ActivityWatch Server + │ + └─► PostgreSQL +``` + +## Основные сценарии + +### Сценарий 1: Пользователь копирует конфиденциальные данные +``` +1. Пользователь копирует текст в буфер обмена +2. DLP Collector перехватывает событие +3. Проверка по DLP правилам +4. При совпадении → скриншот + запись инцидента +5. Отправка в ActivityWatch Server +6. Сохранение в PostgreSQL +7. Отображение в Grafana DLP Dashboard +``` + +### Сценарий 2: Пользователь посещает запрещенный сайт +``` +1. Пользователь открывает сайт в браузере +2. Browser Collector определяет домен +3. Проверка по спискам и DLP правилам +4. Категоризация сайта +5. Отправка события в ActivityWatch +6. Отображение в WebUI Dashboard +``` + +### Сценарий 3: Мониторинг метрик +``` +1. Prometheus Exporter опрашивает AW API +2. Сбор метрик (события, хосты, коллекторы) +3. Экспорт в формате Prometheus +4. Prometheus scrapes endpoint /metrics +5. Grafana строит графики +```