awatch-rus/AWatch-rus
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(architecture): add readable architecture diagrams

Browse Source 
- 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>
This commit is contained in:
igor04091968
2026-05-05 01:46:50 +03:00
co-authored by Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
parent f6074facf5
commit db1998c428
2 changed files with 581 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/architecture-diagram.md
+303
View File
@@ -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%
docs/architecture-simple.md
+278
View File
@@ -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 строит графики
```