257 lines
9.6 KiB
Markdown
257 lines
9.6 KiB
Markdown
# ActivityWatch-Russian: Knowledge Graph Documentation
|
||
|
||
## Что такое Knowledge Graph?
|
||
|
||
**Knowledge Graph** (граф знаний) - это визуальное представление связей между компонентами программного проекта. Для ActivityWatch-Russian граф показывает:
|
||
|
||
- **Функции и модули** как узлы (nodes)
|
||
- **Вызовы и зависимости** как связи (edges)
|
||
- **Кластеры** как сообщества связанных функций (communities)
|
||
|
||
## Зачем это нужно?
|
||
|
||
1. **Понимание архитектуры** - увидеть структуру проекта без чтения кода
|
||
2. **Поиск зависимостей** - понять, какие компоненты влияют друг на друга
|
||
3. **Выявление изоляции** - найти функции, которые не связаны с остальным кодом
|
||
4. **Документация** - автоматическая генерация обзора системы
|
||
|
||
## Как был построен граф?
|
||
|
||
Граф построен с помощью инструмента **graphify** методом **AST extraction**:
|
||
|
||
1. **Сканирование файлов** - найдено 29 кодовых файлов (PowerShell, Python, JavaScript)
|
||
2. **Анализ синтаксиса** - извлечены функции, классы, вызовы
|
||
3. **Построение графа** - 404 узла (функции), 933 связи (вызовы)
|
||
4. **Кластеризация** - 27 сообществ по схожести связей
|
||
|
||
## Структура проекта по сообществам
|
||
|
||
### 1. DLP Endpoint Monitoring (62 nodes)
|
||
**Мониторинг конечных точек DLP**
|
||
|
||
Функции для отслеживания:
|
||
- **Clipboard** - буфер обмена
|
||
- **Print** - задания на печать
|
||
- **USB** - запись на USB накопители
|
||
|
||
Ключевые файлы:
|
||
- `windows/dlp-endpoint-signals-collector.ps1`
|
||
- `windows/dlp-policy-test.json`
|
||
|
||
### 2. WebUI Russian Localization & Patches (56 nodes)
|
||
**Русификация веб-интерфейса**
|
||
|
||
Патчи для ActivityWatch WebUI:
|
||
- Перевод интерфейса на русский язык
|
||
- Скрытие лишних элементов навигации
|
||
- Инъекция стилей для RU локали
|
||
- Поддержка кириллицы
|
||
|
||
Ключевые файлы:
|
||
- `aw-server/aw-ru-patch.js`
|
||
- `aw-server/aw-sw-cleanup.js`
|
||
|
||
### 3. Browser Domains Monitoring (54 nodes)
|
||
**Мониторинг доменов браузеров**
|
||
|
||
Отслеживание посещаемых сайтов:
|
||
- Определение домена из URL
|
||
- Категоризация веб-ресурсов
|
||
- Проверка DLP правил для доменов
|
||
- Скриншоты при нарушениях
|
||
|
||
Ключевые файлы:
|
||
- `windows/browser-domains-native-collector.ps1`
|
||
|
||
### 4. DLP Events Aggregation (38 nodes)
|
||
**Агрегация событий DLP**
|
||
|
||
Сбор и обработка инцидентов:
|
||
- Чтение событий из ActivityWatch buckets
|
||
- Нормализация данных
|
||
- Запись в PostgreSQL
|
||
- Генерация отчетов
|
||
|
||
Ключевые файлы:
|
||
- `scripts/aggregate_dlp_events.py`
|
||
|
||
### 5. DLP Review Center (34 nodes)
|
||
**Центр просмотра инцидентов DLP**
|
||
|
||
WebUI компоненты для:
|
||
- Просмотра списка инцидентов
|
||
- Управления правилами DLP
|
||
- Архивирования событий
|
||
- Фильтрации по хостам
|
||
|
||
### 6. Email Outbound Monitoring (34 nodes)
|
||
**Мониторинг исходящей почты**
|
||
|
||
Отслеживание email:
|
||
- Outlook Sent Items
|
||
- SMTP соединения
|
||
- Проверка DLP правил для email
|
||
- Блокировка нарушений
|
||
|
||
Ключевые файлы:
|
||
- `windows/email-outbound-collector.ps1`
|
||
|
||
### 7. Prometheus Metrics Exporter (12 nodes)
|
||
**Экспорт метрик для Prometheus**
|
||
|
||
Сбор метрик ActivityWatch:
|
||
- Количество событий по buckets
|
||
- Активность хостов
|
||
- Статистика collectors
|
||
- HTTP endpoint для Prometheus
|
||
|
||
Ключевые файлы:
|
||
- `grafana-1c/sql-exporter/collectors/aw_activitywatch.py`
|
||
|
||
### 8. pfSense Firewall Integration (12 nodes)
|
||
**Интеграция с pfSense**
|
||
|
||
Сбор данных с firewall:
|
||
- HTTP API опрос
|
||
- Парсинг логов pfSense
|
||
- Нормализация данных
|
||
- Отправка в ActivityWatch
|
||
|
||
Ключевые файлы:
|
||
- `pfsense/pfsense-aw-poller.py`
|
||
|
||
### 9. Migration Scripts (14 nodes)
|
||
**Скрипты миграции**
|
||
|
||
Обновление путей и конфигураций:
|
||
- Перенос данных между версиями
|
||
- Обновление конфигурационных файлов
|
||
- Конвертация путей
|
||
|
||
Ключевые файлы:
|
||
- `windows/migrate-awatch-rus-paths.ps1`
|
||
|
||
### 10. Worktime Session Tracking (10 nodes)
|
||
**Отслеживание рабочих сессий**
|
||
|
||
Учет рабочего времени:
|
||
- Определение начала/конца сессии
|
||
- Учет перерывов
|
||
- Агрегация по дням
|
||
|
||
Ключевые файлы:
|
||
- `windows/worktime-session-collector.ps1`
|
||
|
||
### 11. Deployment Automation (6 nodes)
|
||
**Автоматизация развертывания**
|
||
|
||
Скрипты деплоя:
|
||
- `windows/deploy-domain-users.ps1` - доменная развертка
|
||
- `windows/deploy-single-user.ps1` - одиночный пользователь
|
||
- `windows/deploy-ensemble.ps1` - групповое развертывание
|
||
|
||
## Как пользоваться графом?
|
||
|
||
### Интерактивная визуализация
|
||
Откройте файл `graphify-out/index.html` в браузере:
|
||
|
||
- **Zoom** - колесо мыши
|
||
- **Pan** - перетаскивание
|
||
- **Click node** - детали узла
|
||
- **Search** - поиск по названию функции
|
||
|
||
### Фильтрация по сообществам
|
||
Каждое сообщество имеет свой цвет:
|
||
- Синий - DLP мониторинг
|
||
- Зеленый - WebUI патчи
|
||
- Красный - Collectors
|
||
- Желтый - Утилиты
|
||
|
||
### Поиск зависимостей
|
||
1. Найдите функцию в графе
|
||
2. Посмотрите на исходящие связи (что вызывает)
|
||
3. Посмотрите на входящие связи (кто вызывает)
|
||
|
||
## Интерпретация связей
|
||
|
||
### Высокая связность (hub nodes)
|
||
Функции с большим количеством связей:
|
||
- `*_get_deploymentconfig` - чтение конфигурации
|
||
- `*_invoke_awjsonpost` - отправка данных в ActivityWatch
|
||
- `*_ensure_bucket` - создание bucket
|
||
|
||
### Изолированные компоненты
|
||
Маленькие сообщества (1-3 nodes) могут быть:
|
||
- Утилитными функциями
|
||
- Зависимостями от внешних библиотек
|
||
- Устаревшим кодом
|
||
|
||
## Статистика проекта
|
||
|
||
| Метрика | Значение |
|
||
|---------|----------|
|
||
| Всего файлов | 29 кодовых файлов |
|
||
| Всего функций | 404 |
|
||
| Всего связей | 933 |
|
||
| Сообществ | 27 |
|
||
| Средний размер сообщества | 15 nodes |
|
||
| Самое большое сообщество | 62 nodes (DLP Endpoint) |
|
||
|
||
## Технологии по типам файлов
|
||
|
||
- **PowerShell (.ps1)** - Windows collectors, deployment
|
||
- **Python (.py)** - aggregation, exporters, pfSense integration
|
||
- **JavaScript (.js)** - WebUI patches
|
||
- **JSON** - конфигурации, policies
|
||
|
||
## Рекомендации по архитектуре
|
||
|
||
### Сильные стороны
|
||
1. **Четкая модульность** - каждый collector в своем сообществе
|
||
2. **Изоляция DLP** - отдельные компоненты для разных типов мониторинга
|
||
3. **Унификация** - общие паттерны в collector'ах
|
||
|
||
### Возможные улучшения
|
||
1. **Дублирование** - несколько сообществ с похожими функциями (WebUI patches)
|
||
2. **Интеграция** - слабые связи между некоторыми компонентами
|
||
3. **Документация** - не все функции имеют явные назначения
|
||
|
||
## Обновление графа
|
||
|
||
Для пересборки графа после изменений кода:
|
||
|
||
```bash
|
||
cd <PROJECT_ROOT>
|
||
graphify .
|
||
```
|
||
|
||
Для инкрементального обновления (только измененные файлы):
|
||
|
||
```bash
|
||
graphify . --update
|
||
```
|
||
|
||
## Полезные запросы
|
||
|
||
### Найти путь между функциями
|
||
```bash
|
||
graphify path "dlp_endpoint_signals_collector_get_deploymentconfig" "aggregate_dlp_events_main"
|
||
```
|
||
|
||
### Объяснить функцию
|
||
```bash
|
||
graphify explain "browser_domains_native_collector_get_hostfromurl"
|
||
```
|
||
|
||
### Поиск по вопросу
|
||
```bash
|
||
graphify query "Как работает мониторинг clipboard?"
|
||
```
|
||
|
||
## Ссылки
|
||
|
||
- **Интерактивный граф**: `graphify-out/index.html`
|
||
- **Отчет**: `graphify-out/GRAPH_REPORT.md`
|
||
- **JSON граф**: `graphify-out/graph.json`
|
||
- **Graphify документация**: https://github.com/brevity-x/graphify
|