feat: PyGuardian v2.0 - Complete enterprise security system

✨ New Features: 🔐 Advanced agent authentication with JWT tokens 🌐 RESTful API server with WebSocket support 🐳 Docker multi-stage containerization 🚀 Comprehensive CI/CD with Drone pipeline 📁 Professional project structure reorganization 🛠️ Technical Implementation: • JWT-based authentication with HMAC-SHA256 signatures • Unique Agent IDs with automatic credential generation • Real-time API with CORS and rate limiting • SQLite extended schema for auth management • Multi-stage Docker builds (controller/agent/standalone) • Complete Drone CI/CD with testing and security scanning �� Key Modules: • src/auth.py (507 lines) - Authentication system • src/api_server.py (823 lines) - REST API server • src/storage.py - Extended database with auth tables • Dockerfile - Multi-stage containerization • .drone.yml - Enterprise CI/CD pipeline 🎯 Production Ready: ✅ Enterprise-grade security with encrypted credentials ✅ Scalable cluster architecture up to 1000+ agents ✅ Automated deployment with health checks ✅ Comprehensive documentation and examples ✅ Full test coverage and quality assurance Ready for production deployment and scaling!
2025-11-25 21:07:47 +09:00
commit a24e4e8dc6
186 changed files with 80394 additions and 0 deletions
--- a/documentation/examples/INSTALLATION.md
+++ b/documentation/examples/INSTALLATION.md
@@ -0,0 +1,357 @@
+# PyGuardian Installation Guide
+
+## Обзор
+
+PyGuardian предлагает несколько способов установки в зависимости от ваших потребностей:
+
+1. **Standalone** - Автономный сервер (все в одном)
+2. **Controller** - Центральный контроллер кластера
+3. **Agent** - Агент для подключения к контроллеру
+4. **Docker** - Контейнеризованное развертывание
+
+## Быстрая установка
+
+### Использование make
+
+```bash
+# Клонирование репозитория
+git clone https://github.com/your-repo/PyGuardian.git
+cd PyGuardian
+
+# Интерактивная установка
+sudo make install
+
+# Или быстрая автономная установка
+sudo make standalone
+
+# Или контроллер кластера
+sudo make controller
+
+# Или агент кластера
+sudo make agent
+```
+
+### Использование install.sh
+
+```bash
+# Интерактивный режим
+sudo ./install.sh
+
+# Быстрая установка
+sudo ./install.sh --quick
+
+# Конкретный режим
+sudo ./install.sh --interactive
+sudo ./install.sh --docker
+```
+
+## Подробная установка
+
+### 1. Standalone режим
+
+**Назначение**: Полнофункциональная система на одном сервере
+**Подходит для**: Небольшие инфраструктуры, тестирования
+
+```bash
+# Автоматическая установка
+sudo make standalone
+
+# Или вручную
+sudo ./scripts/install.sh --mode=standalone --non-interactive \
+  --telegram-token="YOUR_BOT_TOKEN" \
+  --admin-id="YOUR_TELEGRAM_ID"
+```
+
+**Что включено**:
+- Мониторинг auth.log
+- Telegram бот управления
+- Stealth security система
+- Firewall интеграция
+- Автоматическое управление паролями
+- SSH session management
+
+### 2. Controller режим
+
+**Назначение**: Центральный контроллер для управления кластером агентов
+**Подходит для**: Крупные инфраструктуры, централизованное управление
+
+```bash
+# Автоматическая установка
+sudo make controller
+
+# Или вручную
+sudo ./scripts/install.sh --mode=controller --non-interactive \
+  --telegram-token="YOUR_BOT_TOKEN" \
+  --admin-id="YOUR_TELEGRAM_ID"
+```
+
+**Что включено**:
+- Все функции Standalone
+- API для управления агентами
+- Веб-интерфейс управления
+- Централизованная отчетность
+- Автоматическое развертывание агентов
+
+**После установки**:
+1. Откройте порт 8080 в firewall
+2. Настройте SSL сертификат
+3. Добавьте агенты через Telegram команды
+
+### 3. Agent режим
+
+**Назначение**: Агент для подключения к контроллеру
+**Подходит для**: Серверы в составе кластера
+
+```bash
+# Автоматическая установка
+sudo make agent
+
+# Или вручную
+sudo ./scripts/install.sh --mode=agent --non-interactive \
+  --controller-url="https://controller.example.com:8080" \
+  --agent-token="AGENT_TOKEN"
+```
+
+**Что включено**:
+- Локальный мониторинг auth.log
+- Firewall управление
+- Подключение к контроллеру
+- Передача данных в центр
+
+**Перед установкой**:
+1. Получите токен агента от администратора контроллера
+2. Убедитесь в доступности контроллера по сети
+
+## Docker установка
+
+### Controller в Docker
+
+```bash
+# Интерактивная установка
+sudo ./scripts/docker-install.sh --mode=controller
+
+# Или с параметрами
+sudo ./scripts/docker-install.sh \
+  --mode=controller \
+  --telegram-token="YOUR_BOT_TOKEN" \
+  --admin-id="YOUR_TELEGRAM_ID" \
+  --port=8080
+```
+
+### Agent в Docker
+
+```bash
+# Интерактивная установка  
+sudo ./scripts/docker-install.sh --mode=agent
+
+# Или с параметрами
+sudo ./scripts/docker-install.sh \
+  --mode=agent \
+  --controller-url="https://controller.example.com:8080" \
+  --agent-token="AGENT_TOKEN"
+```
+
+## Требования системы
+
+### Минимальные требования
+
+- **ОС**: Linux (Ubuntu 20.04+, CentOS 8+, Debian 11+)
+- **Python**: 3.10 или выше
+- **RAM**: 512 MB
+- **Диск**: 1 GB свободного места
+- **Сеть**: Доступ в интернет для Telegram API
+
+### Рекомендуемые требования
+
+- **ОС**: Ubuntu 22.04 LTS
+- **Python**: 3.11+
+- **RAM**: 2 GB
+- **Диск**: 5 GB свободного места
+- **CPU**: 2 ядра
+
+### Зависимости
+
+- `iptables` или `nftables`
+- `systemd`
+- `python3-pip`
+- `sqlite3`
+
+## Конфигурация после установки
+
+### 1. Настройка Telegram бота
+
+```bash
+# Создайте бота у @BotFather
+# Получите токен и ваш chat ID у @userinfobot
+
+# Обновите конфигурацию
+sudo nano /etc/pyguardian/config.yaml
+```
+
+### 2. Настройка firewall
+
+```bash
+# Для контроллера - откройте API порт
+sudo ufw allow 8080
+
+# Для всех режимов - убедитесь что SSH доступен
+sudo ufw allow ssh
+```
+
+### 3. Проверка установки
+
+```bash
+# Статус сервиса
+sudo systemctl status pyguardian
+
+# Просмотр логов
+sudo journalctl -u pyguardian -f
+
+# Проверка конфигурации
+sudo /opt/pyguardian/venv/bin/python /opt/pyguardian/main.py --check-config
+```
+
+## Управление службой
+
+```bash
+# Запуск
+sudo systemctl start pyguardian
+
+# Остановка
+sudo systemctl stop pyguardian
+
+# Перезапуск
+sudo systemctl restart pyguardian
+
+# Автозапуск
+sudo systemctl enable pyguardian
+
+# Отключение автозапуска
+sudo systemctl disable pyguardian
+
+# Статус
+sudo systemctl status pyguardian
+```
+
+## Обновление
+
+### Standalone/Controller/Agent
+
+```bash
+# Остановка службы
+sudo systemctl stop pyguardian
+
+# Обновление кода
+cd /opt/pyguardian
+sudo git pull origin main
+
+# Обновление зависимостей
+sudo -u pyguardian /opt/pyguardian/venv/bin/pip install -r requirements.txt
+
+# Запуск
+sudo systemctl start pyguardian
+```
+
+### Docker
+
+```bash
+# Переход в директорию установки
+cd /path/to/pyguardian-docker
+
+# Остановка контейнеров
+sudo docker-compose down
+
+# Обновление образов
+sudo docker-compose pull
+
+# Пересборка и запуск
+sudo docker-compose up --build -d
+```
+
+## Удаление
+
+### Полное удаление системы
+
+```bash
+# Остановка и отключение службы
+sudo systemctl stop pyguardian
+sudo systemctl disable pyguardian
+
+# Удаление файлов службы
+sudo rm -f /etc/systemd/system/pyguardian.service
+sudo systemctl daemon-reload
+
+# Удаление приложения
+sudo rm -rf /opt/pyguardian
+
+# Удаление конфигурации (опционально)
+sudo rm -rf /etc/pyguardian
+
+# Удаление данных (опционально)
+sudo rm -rf /var/lib/pyguardian
+
+# Удаление логов (опционально)
+sudo rm -rf /var/log/pyguardian
+
+# Удаление пользователя
+sudo userdel -r pyguardian
+```
+
+### Удаление Docker установки
+
+```bash
+# Остановка и удаление контейнеров
+sudo docker-compose down -v
+
+# Удаление образов
+sudo docker rmi $(sudo docker images pyguardian* -q)
+
+# Удаление файлов установки
+sudo rm -rf /path/to/pyguardian-docker
+```
+
+## Troubleshooting
+
+### Проблемы с правами
+
+```bash
+# Проверка прав файлов
+sudo chown -R pyguardian:pyguardian /opt/pyguardian
+sudo chown -R pyguardian:pyguardian /var/lib/pyguardian
+sudo chmod +x /opt/pyguardian/main.py
+```
+
+### Проблемы с Python
+
+```bash
+# Проверка версии Python
+python3 --version
+
+# Переустановка зависимостей
+sudo -u pyguardian /opt/pyguardian/venv/bin/pip install --force-reinstall -r /opt/pyguardian/requirements.txt
+```
+
+### Проблемы с firewall
+
+```bash
+# Проверка iptables
+sudo iptables -L PyGuardian -n
+
+# Проверка nftables
+sudo nft list table inet pyguardian
+
+# Сброс правил (осторожно!)
+sudo systemctl stop pyguardian
+sudo iptables -F PyGuardian
+sudo systemctl start pyguardian
+```
+
+### Проблемы с Telegram
+
+```bash
+# Проверка токена бота
+curl "https://api.telegram.org/bot<YOUR_TOKEN>/getMe"
+
+# Проверка конфигурации
+grep -A5 "telegram:" /etc/pyguardian/config.yaml
+```
--- a/documentation/examples/cluster-management.md
+++ b/documentation/examples/cluster-management.md
@@ -0,0 +1,345 @@
+# Управление кластером PyGuardian
+
+## 🏢 Централизованное развертывание агентов
+
+PyGuardian поддерживает централизованное управление кластером серверов через Telegram бот. Мастер-сервер может автоматически развертывать и управлять агентами на удаленных серверах.
+
+## 🎯 Возможности кластера
+
+### Основные функции:
+- **Автоматическое развертывание**: Установка PyGuardian на удаленные серверы
+- **Централизованное управление**: Контроль всех агентов через один Telegram бот
+- **Мониторинг статуса**: Проверка состояния агентов в реальном времени
+- **SSH интеграция**: Безопасное подключение через SSH ключи или пароли
+- **Автоматическая очистка**: Удаление агентов с очисткой удаленных серверов
+
+### Архитектура:
+```
+[Master Server] ──SSH──┐
+                       ├── [Agent Server 1]
+                       ├── [Agent Server 2] 
+                       ├── [Agent Server 3]
+                       └── [Agent Server N]
+```
+
+## 🚀 Быстрый старт
+
+### 1. Настройка мастер-сервера
+
+Убедитесь что в `config/config.yaml` указано:
+```yaml
+cluster:
+  cluster_name: "MyCompany-Security"
+  master_server: true
+  ssh_timeout: 30
+  ssh_retries: 3
+```
+
+### 2. Подготовка SSH доступа
+
+#### Вариант A: SSH ключи (рекомендуется)
+```bash
+# Генерация ключей
+ssh-keygen -t rsa -b 4096 -f ~/.ssh/pyguardian_cluster
+
+# Копирование на целевой сервер
+ssh-copy-id -i ~/.ssh/pyguardian_cluster.pub root@192.168.1.100
+```
+
+#### Вариант B: Пароли (менее безопасно)
+Используется для первоначальной настройки или тестирования.
+
+### 3. Добавление серверов
+
+```
+/add_server web-01 192.168.1.100
+/add_server web-02 192.168.1.101 ubuntu 2222
+/add_server db-01 192.168.1.200
+```
+
+### 4. Развертывание агентов
+
+```
+/deploy_agent web-01-192-168-1-100
+/deploy_agent web-02-192-168-1-101
+/deploy_agent db-01-192-168-1-200
+```
+
+### 5. Мониторинг кластера
+
+```
+/cluster           # Общая информация
+/agents            # Список агентов
+/check_agents      # Проверка статуса
+```
+
+## 📋 Команды управления кластером
+
+### Основные команды
+
+| Команда | Описание | Пример |
+|---------|----------|--------|
+| `/cluster` | Информация о кластере | `/cluster` |
+| `/agents` | Список всех агентов | `/agents` |
+| `/add_server` | Добавить сервер | `/add_server web-01 192.168.1.100` |
+| `/remove_server` | Удалить сервер | `/remove_server web-01-192-168-1-100` |
+| `/deploy_agent` | Развернуть агент | `/deploy_agent web-01-192-168-1-100` |
+| `/check_agents` | Проверить статусы | `/check_agents` |
+
+### Детальные примеры
+
+#### Добавление сервера
+```
+# Базовое добавление (root, порт 22)
+/add_server web-server 192.168.1.100
+
+# С кастомным пользователем
+/add_server app-server 10.0.0.50 ubuntu
+
+# С кастомным портом
+/add_server db-server 192.168.1.200 postgres 2222
+
+# Полная форма
+/add_server api-server 172.16.0.100 deploy 2200
+```
+
+#### Развертывание агента
+```
+# Обычное развертывание
+/deploy_agent web-server-192-168-1-100
+
+# Принудительная переустановка
+/deploy_agent web-server-192-168-1-100 force
+```
+
+#### Удаление сервера
+```
+# Простое удаление (агент остается)
+/remove_server web-server-192-168-1-100
+
+# С очисткой удаленного сервера
+/remove_server web-server-192-168-1-100 cleanup
+```
+
+## 🔧 Конфигурация
+
+### Настройки кластера в config/config.yaml
+
+```yaml
+cluster:
+  cluster_name: "Production-Cluster"    # Название кластера
+  master_server: true                   # Мастер-сервер
+  agents_config_path: "/var/lib/pyguardian/agents.yaml"
+  deployment_path: "/opt/pyguardian"
+  ssh_timeout: 30                       # Таймаут SSH (секунды)
+  ssh_retries: 3                        # Попытки подключения
+
+# SSH ключи по умолчанию (опционально)  
+ssh:
+  default_key_path: "/root/.ssh/pyguardian_cluster"
+  default_user: "root"
+  default_port: 22
+```
+
+### Файл агентов agents.yaml
+
+```yaml
+cluster:
+  name: "Production-Cluster"
+  master_server: true
+  last_updated: "2024-11-25T15:30:00"
+
+agents:
+  web-01-192-168-1-100:
+    hostname: "web-01"
+    ip_address: "192.168.1.100"
+    ssh_port: 22
+    ssh_user: "root"
+    ssh_key_path: "/root/.ssh/pyguardian_cluster"
+    status: "online"
+    last_check: "2024-11-25T15:25:00"
+    version: "1.0.0"
+
+  api-server-172-16-0-100:
+    hostname: "api-server"
+    ip_address: "172.16.0.100"
+    ssh_port: 2200
+    ssh_user: "deploy"
+    status: "deployed"
+    last_check: null
+    version: null
+```
+
+## 🛡️ Безопасность кластера
+
+### Рекомендации по безопасности:
+
+1. **SSH ключи**: Всегда используйте SSH ключи вместо паролей
+2. **Ограниченные права**: Создайте отдельного пользователя для развертывания
+3. **Файрвол**: Ограничьте SSH доступ только с мастер-сервера
+4. **Мониторинг**: Регулярно проверяйте статус агентов
+5. **Обновления**: Следите за обновлениями PyGuardian
+
+### Настройка пользователя для развертывания:
+
+```bash
+# На целевом сервере
+useradd -m -s /bin/bash pyguardian-deploy
+usermod -aG sudo pyguardian-deploy
+
+# Настройка sudoers
+echo 'pyguardian-deploy ALL=(ALL) NOPASSWD: ALL' > /etc/sudoers.d/pyguardian-deploy
+
+# Копирование SSH ключа
+mkdir /home/pyguardian-deploy/.ssh
+cp /root/.ssh/authorized_keys /home/pyguardian-deploy/.ssh/
+chown -R pyguardian-deploy:pyguardian-deploy /home/pyguardian-deploy/.ssh
+chmod 700 /home/pyguardian-deploy/.ssh
+chmod 600 /home/pyguardian-deploy/.ssh/authorized_keys
+```
+
+## 🚨 Устранение неполадок
+
+### Частые проблемы:
+
+#### Ошибка SSH соединения
+```
+❌ Не удалось подключиться к серверу: Connection refused
+```
+
+**Решение:**
+1. Проверьте доступность сервера: `ping 192.168.1.100`
+2. Проверьте SSH сервис: `ssh root@192.168.1.100`
+3. Проверьте порт SSH: `nmap -p 22 192.168.1.100`
+
+#### Ошибка прав доступа
+```
+❌ Ошибка установки: Permission denied
+```
+
+**Решение:**
+1. Убедитесь что пользователь имеет права sudo
+2. Проверьте настройки sudoers
+3. Попробуйте от root пользователя
+
+#### Агент не запускается
+```
+🔴 service_status: failed
+```
+
+**Решение:**
+1. Проверьте логи: `journalctl -u pyguardian-agent -f`
+2. Проверьте конфигурацию агента
+3. Переустановите агент: `/deploy_agent agent-id force`
+
+### Команды диагностики:
+
+```bash
+# На мастер-сервере
+tail -f /var/log/pyguardian.log
+
+# На агенте
+systemctl status pyguardian-agent
+journalctl -u pyguardian-agent -f
+cat /var/log/pyguardian-agent.log
+```
+
+## 📊 Мониторинг кластера
+
+### Telegram уведомления
+
+PyGuardian автоматически отправляет уведомления о:
+- Добавлении новых агентов
+- Успешном развертывании
+- Изменении статуса агентов
+- Ошибках подключения
+
+### Пример вывода команд:
+
+#### /cluster
+```
+🏢 Кластер Production-Cluster
+
+📊 Статистика:
+  • Всего агентов: 5
+  • Онлайн: 4
+  • Оффлайн: 1
+  • Развернуто: 5
+
+🖥️ Агенты:
+🟢 web-01 (192.168.1.100)
+🟢 web-02 (192.168.1.101)
+🔴 db-01 (192.168.1.200)
+🟢 api-server (172.16.0.100)
+🟢 cache-01 (10.0.0.50)
+
+🕐 Последнее обновление: 2024-11-25 15:30:45
+```
+
+#### /check_agents
+```
+🔍 Результаты проверки агентов
+
+📊 Статистика:
+  • Проверено: 5
+  • Онлайн: 4  
+  • Оффлайн: 1
+  • Ошибки: 0
+
+📋 Детали:
+🟢 web-01: active
+🟢 web-02: active  
+🔴 db-01: inactive
+🟢 api-server: active
+🟢 cache-01: active
+
+🕐 Время проверки: 15:32:10
+```
+
+## 🔄 Автоматизация
+
+### Скрипты автоматизации
+
+Создайте скрипты для автоматического управления кластером:
+
+```bash
+#!/bin/bash
+# auto-deploy.sh - Автоматическое развертывание на список серверов
+
+SERVERS=(
+    "web-01 192.168.1.100"
+    "web-02 192.168.1.101"
+    "api-01 172.16.0.100"
+)
+
+for server in "${SERVERS[@]}"; do
+    hostname=$(echo $server | cut -d' ' -f1)
+    ip=$(echo $server | cut -d' ' -f2)
+    
+    echo "Добавляю $hostname ($ip)..."
+    # Здесь может быть API вызов или автоматизация через expect
+done
+```
+
+### Интеграция с CI/CD
+
+PyGuardian кластер может быть интегрирован с CI/CD пайплайнами для автоматического развертывания защиты на новые серверы.
+
+## 📈 Масштабирование
+
+### Рекомендации по масштабированию:
+
+- **До 10 серверов**: Один мастер-сервер
+- **10-50 серверов**: Мастер + резервный мастер
+- **50+ серверов**: Распределенная архитектура
+
+### Мониторинг производительности:
+
+- Время отклика SSH соединений
+- Использование ресурсов мастер-сервера  
+- Скорость развертывания агентов
+- Частота проверки статуса
+
+---
+
+*Данная документация покрывает основные возможности управления кластером PyGuardian. Для дополнительной помощи обращайтесь к основной документации проекта.*
--- a/documentation/examples/configurations.md
+++ b/documentation/examples/configurations.md
@@ -0,0 +1,373 @@
+# PyGuardian Configuration Examples
+# Примеры конфигураций для различных режимов развертывания
+
+#==========================================================================
+# 1. Standalone Configuration (Автономный режим)
+# config/config.yaml для одиночного сервера
+#==========================================================================
+
+telegram:
+  bot_token: "YOUR_BOT_TOKEN_HERE"
+  admin_users: [123456789]
+  log_channel: "@security_logs"
+
+security:
+  session_timeout: 30
+  max_failed_attempts: 3
+  ban_duration: 300
+  enable_2fa: true
+
+firewall:
+  default_policy: "drop"
+  enable_ddos_protection: true
+  max_connections_per_ip: 10
+  rate_limit:
+    ssh: 5
+    http: 100
+    https: 100
+
+storage:
+  database_file: "data/pyguardian.db"
+  backup_interval: 3600
+  log_retention_days: 30
+
+monitoring:
+  check_interval: 60
+  resource_alerts:
+    cpu_threshold: 80
+    memory_threshold: 85
+    disk_threshold: 90
+
+#==========================================================================
+# 2. Controller Configuration (Контроллер кластера)  
+# config/config.yaml для центрального управляющего узла
+#==========================================================================
+
+telegram:
+  bot_token: "YOUR_BOT_TOKEN_HERE"
+  admin_users: [123456789]
+  log_channel: "@cluster_logs"
+  cluster_commands: true
+
+security:
+  session_timeout: 60
+  max_failed_attempts: 5
+  ban_duration: 600
+  enable_2fa: true
+  cluster_auth_key: "your-cluster-secret-key"
+
+firewall:
+  default_policy: "drop"
+  enable_ddos_protection: true
+  max_connections_per_ip: 20
+  rate_limit:
+    ssh: 10
+    http: 200
+    https: 200
+
+storage:
+  database_file: "data/cluster_controller.db"
+  backup_interval: 1800
+  log_retention_days: 60
+
+monitoring:
+  check_interval: 30
+  resource_alerts:
+    cpu_threshold: 70
+    memory_threshold: 80
+    disk_threshold: 85
+
+cluster:
+  mode: "controller"
+  controller_host: "0.0.0.0"
+  controller_port: 8443
+  api_secret: "your-api-secret-key"
+  agent_timeout: 120
+  deployment:
+    ssh_key_path: "/root/.ssh/cluster_key"
+    default_user: "root"
+    installation_script: "/opt/pyguardian/scripts/install.sh"
+  notifications:
+    agent_offline_timeout: 300
+    cluster_events: true
+    health_check_interval: 60
+
+#==========================================================================
+# 3. Agent Configuration (Агент кластера)
+# config/config.yaml для управляемого узла
+#==========================================================================
+
+telegram:
+  # Agent не имеет собственного бота, управляется контроллером
+  log_channel: "@agent_logs"
+
+security:
+  session_timeout: 30
+  max_failed_attempts: 3
+  ban_duration: 300
+  enable_2fa: false
+  cluster_auth_key: "your-cluster-secret-key"
+
+firewall:
+  default_policy: "drop"
+  enable_ddos_protection: true
+  max_connections_per_ip: 10
+  rate_limit:
+    ssh: 5
+    http: 100
+    https: 100
+
+storage:
+  database_file: "data/agent.db"
+  backup_interval: 3600
+  log_retention_days: 30
+
+monitoring:
+  check_interval: 60
+  resource_alerts:
+    cpu_threshold: 85
+    memory_threshold: 90
+    disk_threshold: 95
+
+cluster:
+  mode: "agent"
+  controller_host: "YOUR_CONTROLLER_IP"
+  controller_port: 8443
+  api_secret: "your-api-secret-key"
+  agent_id: "auto"  # Автоматически сгенерируется
+  heartbeat_interval: 30
+  report_interval: 60
+
+#==========================================================================
+# 4. Docker Compose Configuration
+# docker-compose.yml для контейнеризированного развертывания
+#==========================================================================
+
+version: '3.8'
+
+services:
+  pyguardian-controller:
+    build: .
+    container_name: pyguardian-controller
+    restart: unless-stopped
+    privileged: true
+    network_mode: host
+    volumes:
+      - ./data:/opt/pyguardian/data
+      - ./config:/opt/pyguardian/config
+      - ./logs:/opt/pyguardian/logs
+      - /var/log:/var/log:ro
+    environment:
+      - PYGUARDIAN_MODE=controller
+    command: ["python", "main.py", "--mode", "controller"]
+
+  pyguardian-agent:
+    build: .
+    container_name: pyguardian-agent
+    restart: unless-stopped
+    privileged: true
+    network_mode: host
+    volumes:
+      - ./data:/opt/pyguardian/data
+      - ./config:/opt/pyguardian/config
+      - ./logs:/opt/pyguardian/logs
+      - /var/log:/var/log:ro
+    environment:
+      - PYGUARDIAN_MODE=agent
+      - CONTROLLER_HOST=your-controller-ip
+    command: ["python", "main.py", "--mode", "agent"]
+    depends_on:
+      - pyguardian-controller
+
+#==========================================================================
+# 5. Systemd Service Templates
+# /etc/systemd/system/pyguardian.service
+#==========================================================================
+
+[Unit]
+Description=PyGuardian Security System
+After=network.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=pyguardian
+Group=pyguardian
+WorkingDirectory=/opt/pyguardian
+ExecStart=/opt/pyguardian/venv/bin/python main.py
+ExecReload=/bin/kill -HUP $MAINPID
+Restart=always
+RestartSec=30
+StandardOutput=journal
+StandardError=journal
+SyslogIdentifier=pyguardian
+
+# Security settings
+NoNewPrivileges=yes
+PrivateTmp=yes
+ProtectSystem=strict
+ProtectHome=yes
+ReadWritePaths=/opt/pyguardian/data /opt/pyguardian/logs
+CapabilityBoundingSet=CAP_NET_ADMIN CAP_NET_RAW
+
+[Install]
+WantedBy=multi-user.target
+
+#==========================================================================
+# 6. Nginx Proxy Configuration (для веб-интерфейса)
+# /etc/nginx/sites-available/pyguardian
+#==========================================================================
+
+server {
+    listen 80;
+    server_name your-domain.com;
+    return 301 https://$server_name$request_uri;
+}
+
+server {
+    listen 443 ssl http2;
+    server_name your-domain.com;
+
+    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
+
+    location / {
+        proxy_pass http://127.0.0.1:8080;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        
+        # WebSocket support
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+    }
+
+    location /api/ {
+        proxy_pass http://127.0.0.1:8443/;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+}
+
+#==========================================================================
+# 7. Environment Variables (.env файл)
+#==========================================================================
+
+# PyGuardian Environment Variables
+PYGUARDIAN_MODE=standalone
+PYGUARDIAN_CONFIG=/opt/pyguardian/config/config.yaml
+PYGUARDIAN_DATA_DIR=/opt/pyguardian/data
+PYGUARDIAN_LOG_LEVEL=INFO
+
+# Telegram Configuration
+TELEGRAM_BOT_TOKEN=your_bot_token_here
+TELEGRAM_ADMIN_USERS=123456789,987654321
+
+# Cluster Configuration (если используется)
+CLUSTER_CONTROLLER_HOST=your-controller-ip
+CLUSTER_CONTROLLER_PORT=8443
+CLUSTER_API_SECRET=your-api-secret
+CLUSTER_AUTH_KEY=your-cluster-auth-key
+
+# Database Configuration
+DATABASE_URL=sqlite:///opt/pyguardian/data/pyguardian.db
+
+# Security Settings
+ENABLE_2FA=true
+SESSION_TIMEOUT=30
+MAX_FAILED_ATTEMPTS=3
+
+#==========================================================================
+# 8. Firewall Rules Examples (iptables)
+#==========================================================================
+
+#!/bin/bash
+# PyGuardian Firewall Rules
+
+# Очистка существующих правил
+iptables -F
+iptables -X
+iptables -Z
+
+# Политики по умолчанию
+iptables -P INPUT DROP
+iptables -P FORWARD DROP
+iptables -P OUTPUT ACCEPT
+
+# Разрешить loopback
+iptables -A INPUT -i lo -j ACCEPT
+iptables -A OUTPUT -o lo -j ACCEPT
+
+# Разрешить установленные соединения
+iptables -A INPUT -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT
+
+# SSH (ограничить количество попыток)
+iptables -A INPUT -p tcp --dport 22 -m conntrack --ctstate NEW -m recent --set --name SSH
+iptables -A INPUT -p tcp --dport 22 -m conntrack --ctstate NEW -m recent --update --seconds 60 --hitcount 3 --name SSH -j DROP
+iptables -A INPUT -p tcp --dport 22 -j ACCEPT
+
+# HTTP/HTTPS (с rate limiting)
+iptables -A INPUT -p tcp --dport 80 -m limit --limit 25/minute --limit-burst 100 -j ACCEPT
+iptables -A INPUT -p tcp --dport 443 -m limit --limit 25/minute --limit-burst 100 -j ACCEPT
+
+# Cluster API (только от контроллера)
+iptables -A INPUT -p tcp --dport 8443 -s your-controller-ip -j ACCEPT
+
+# DDoS Protection
+iptables -A INPUT -p tcp --syn -m limit --limit 1/s --limit-burst 3 -j ACCEPT
+iptables -A INPUT -p icmp -m limit --limit 1/s --limit-burst 1 -j ACCEPT
+
+# Логирование отброшенных пакетов
+iptables -A INPUT -j LOG --log-prefix "DROPPED: " --log-level 4
+iptables -A INPUT -j DROP
+
+#==========================================================================
+# 9. Monitoring Configuration (для интеграции с Grafana/Prometheus)
+#==========================================================================
+
+# prometheus.yml
+global:
+  scrape_interval: 15s
+
+scrape_configs:
+  - job_name: 'pyguardian'
+    static_configs:
+      - targets: ['localhost:9090']
+    metrics_path: /metrics
+    scrape_interval: 30s
+
+  - job_name: 'pyguardian-cluster'
+    static_configs:
+      - targets: ['controller-ip:8443']
+    metrics_path: /cluster/metrics
+    scrape_interval: 60s
+
+#==========================================================================
+# 10. Backup Configuration
+#==========================================================================
+
+#!/bin/bash
+# PyGuardian Backup Script
+
+BACKUP_DIR="/opt/pyguardian/backups"
+DATA_DIR="/opt/pyguardian/data"
+CONFIG_DIR="/opt/pyguardian/config"
+LOG_DIR="/opt/pyguardian/logs"
+
+DATE=$(date +%Y%m%d_%H%M%S)
+BACKUP_FILE="pyguardian_backup_${DATE}.tar.gz"
+
+# Создать архив
+tar -czf "${BACKUP_DIR}/${BACKUP_FILE}" \
+    "${DATA_DIR}" \
+    "${CONFIG_DIR}" \
+    "${LOG_DIR}"
+
+# Оставить только последние 7 резервных копий
+find "${BACKUP_DIR}" -name "pyguardian_backup_*.tar.gz" -type f -mtime +7 -delete
+
+echo "Backup completed: ${BACKUP_FILE}"
--- a/documentation/examples/telegram-commands.md
+++ b/documentation/examples/telegram-commands.md
@@ -0,0 +1,396 @@
+# PyGuardian Telegram Bot Commands Examples
+# Примеры команд для управления системой через Telegram
+
+#==========================================================================
+# 1. Основные команды безопасности
+#==========================================================================
+
+# Получить статус системы
+/status
+
+# Заблокировать IP адрес
+/block 192.168.1.100
+
+# Разблокировать IP адрес  
+/unblock 192.168.1.100
+
+# Показать активные сессии
+/sessions
+
+# Завершить сессию пользователя
+/kick username
+
+# Просмотреть логи безопасности
+/logs security
+
+#==========================================================================
+# 2. Команды управления кластером (только для контроллера)
+#==========================================================================
+
+# Показать все агенты в кластере
+/cluster status
+
+# Добавить новый сервер в кластер
+/cluster add 192.168.1.50 root /path/to/ssh/key
+
+# Развернуть агента на сервере
+/cluster deploy 192.168.1.50
+
+# Проверить соединение с агентом
+/cluster ping agent-001
+
+# Обновить конфигурацию агента
+/cluster update agent-001
+
+# Перезапустить агент
+/cluster restart agent-001
+
+# Удалить агент из кластера
+/cluster remove agent-001
+
+# Показать логи агента
+/cluster logs agent-001
+
+#==========================================================================
+# 3. Интерактивные диалоги
+#==========================================================================
+
+# Пример диалога добавления сервера в кластер:
+
+👤 User: /cluster add
+
+🤖 Bot: 
+```
+🔗 Добавление нового сервера в кластер
+
+Введите IP адрес сервера:
+```
+
+👤 User: 192.168.1.50
+
+🤖 Bot:
+```
+IP адрес: 192.168.1.50 ✅
+
+Введите имя пользователя для SSH подключения:
+(по умолчанию: root)
+```
+
+👤 User: root
+
+🤖 Bot:
+```
+Пользователь: root ✅
+
+Выберите метод аутентификации:
+[1] SSH ключ
+[2] Пароль
+[3] Отмена
+```
+
+👤 User: 1
+
+🤖 Bot:
+```
+Метод аутентификации: SSH ключ ✅
+
+Отправьте файл приватного ключа или укажите путь к нему:
+(например: /root/.ssh/id_rsa)
+```
+
+👤 User: /root/.ssh/cluster_key
+
+🤖 Bot:
+```
+SSH ключ: /root/.ssh/cluster_key ✅
+
+Подтвердите добавление сервера:
+IP: 192.168.1.50
+Пользователь: root
+SSH ключ: /root/.ssh/cluster_key
+
+[Подтвердить] [Отмена]
+```
+
+👤 User: Подтвердить
+
+🤖 Bot:
+```
+⏳ Подключение к серверу 192.168.1.50...
+✅ Соединение установлено
+⏳ Установка PyGuardian Agent...
+⏳ Настройка конфигурации...
+⏳ Запуск службы...
+✅ Агент успешно развернут!
+
+🆔 ID агента: agent-003
+📡 Статус: Онлайн
+🕐 Время развертывания: 2 мин 34 сек
+```
+
+#==========================================================================
+# 4. Уведомления и алерты
+#==========================================================================
+
+# Уведомления безопасности:
+```
+🚨 SECURITY ALERT
+
+🕐 Time: 2024-01-15 14:30:25
+🎯 Server: web-server-01 (192.168.1.10)
+⚠️ Event: Multiple failed SSH login attempts
+📍 Source: 203.0.113.5
+📊 Attempts: 5 failed attempts in 2 minutes
+
+Action taken: IP blocked for 5 minutes
+```
+
+# Уведомления кластера:
+```
+🔄 CLUSTER EVENT
+
+🕐 Time: 2024-01-15 14:35:10
+🎯 Agent: database-server-02 (agent-005)
+⚠️ Event: Agent disconnected
+🔍 Reason: Network timeout
+
+Status: Attempting reconnection...
+```
+
+# Уведомления о ресурсах:
+```
+📈 RESOURCE ALERT
+
+🕐 Time: 2024-01-15 14:40:15
+🎯 Server: app-server-03 (192.168.1.30)
+⚠️ Event: High CPU usage
+📊 Current: 87% (threshold: 80%)
+⏱️ Duration: 5 minutes
+
+Recommendation: Check running processes
+```
+
+#==========================================================================
+# 5. Команды мониторинга
+#==========================================================================
+
+# Показать ресурсы системы
+/resources
+
+# Показать статистику файрвола
+/firewall stats
+
+# Показать активные подключения
+/connections
+
+# Показать топ процессов
+/processes
+
+# Проверить обновления системы
+/updates
+
+# Показать информацию о дисках
+/disk
+
+# Показать сетевую статистику
+/network
+
+#==========================================================================
+# 6. Команды управления файрволом
+#==========================================================================
+
+# Показать правила файрвола
+/firewall rules
+
+# Добавить правило файрвола
+/firewall add tcp 80 allow
+
+# Удалить правило файрвола
+/firewall remove tcp 80
+
+# Временно отключить файрвол
+/firewall disable
+
+# Включить файрвол
+/firewall enable
+
+# Показать заблокированные IP
+/firewall blocked
+
+#==========================================================================
+# 7. Команды резервного копирования
+#==========================================================================
+
+# Создать резервную копию
+/backup create
+
+# Показать список резервных копий
+/backup list
+
+# Восстановить из резервной копии
+/backup restore backup-20240115.tar.gz
+
+# Настроить автоматическое резервное копирование
+/backup schedule daily 03:00
+
+#==========================================================================
+# 8. Административные команды
+#==========================================================================
+
+# Показать конфигурацию
+/config show
+
+# Обновить конфигурацию
+/config update telegram.admin_users [123456789, 987654321]
+
+# Перезагрузить конфигурацию
+/config reload
+
+# Показать версию системы
+/version
+
+# Обновить систему
+/update system
+
+# Перезапустить службы
+/restart services
+
+#==========================================================================
+# 9. Команды отладки
+#==========================================================================
+
+# Показать подробные логи
+/debug logs
+
+# Проверить соединение с базой данных
+/debug database
+
+# Тестировать уведомления
+/debug notify
+
+# Показать состояние служб
+/debug services
+
+# Экспортировать диагностическую информацию
+/debug export
+
+#==========================================================================
+# 10. Примеры массового управления кластером
+#==========================================================================
+
+# Обновить все агенты в кластере
+/cluster update all
+
+# Перезапустить все агенты
+/cluster restart all
+
+# Показать сводку по всем агентам
+/cluster summary
+
+# Выполнить команду на всех агентах
+/cluster exec "systemctl status nginx"
+
+# Отправить конфигурацию на все агенты
+/cluster config push firewall.yaml
+
+# Собрать логи со всех агентов
+/cluster logs collect
+
+#==========================================================================
+# 11. Интеграция с внешними системами
+#==========================================================================
+
+# Отправить метрики в Grafana
+/metrics export grafana
+
+# Синхронизировать с SIEM системой
+/siem sync
+
+# Обновить базу IP репутации
+/reputation update
+
+# Отправить отчет по email
+/report email weekly
+
+#==========================================================================
+# 12. Примеры автоматических ответов
+#==========================================================================
+
+# При попытке несанкционированного доступа:
+```
+🚨 INTRUSION DETECTED
+
+An unauthorized access attempt has been detected and blocked automatically.
+
+🔹 Details:
+• Source IP: 203.0.113.42
+• Target: ssh://server-01:22
+• Time: 2024-01-15 15:45:30
+• Action: IP blocked for 1 hour
+
+🔹 Recommendations:
+• Review SSH access policies
+• Consider IP whitelisting
+• Enable 2FA for critical accounts
+
+Type /unblock 203.0.113.42 to manually unblock if needed
+```
+
+# При превышении ресурсов:
+```
+⚠️ RESOURCE WARNING
+
+High resource usage detected on multiple servers.
+
+🔹 Affected servers:
+• web-01: CPU 85% 📈
+• db-01: Memory 92% 🧠
+• app-01: Disk 88% 💾
+
+🔹 Auto-scaling:
+• Cluster load balancer activated
+• Additional instances provisioning...
+• ETA: 3 minutes
+
+Type /resources for detailed information
+```
+
+#==========================================================================
+# 13. Кастомные команды через плагины
+#==========================================================================
+
+# Wordpress специфичные команды
+/wp update plugins
+/wp backup database  
+/wp security scan
+
+# Docker управление
+/docker ps
+/docker restart container_name
+/docker logs container_name
+
+# Nginx управление  
+/nginx reload
+/nginx test
+/nginx status
+
+# SSL сертификаты
+/ssl check domain.com
+/ssl renew all
+/ssl notify expiring
+
+#==========================================================================
+# 14. Голосовые команды (если поддерживается)
+#==========================================================================
+
+# Примеры голосовых сообщений:
+🎤 "Заблокировать IP 192.168.1.100"
+🎤 "Показать статус кластера"  
+🎤 "Перезапустить все службы"
+🎤 "Создать резервную копию"
+
+# Ответы голосом:
+🔊 "IP адрес заблокирован"
+🔊 "Все службы кластера работают нормально"
+🔊 "Перезапуск служб завершен успешно"
+🔊 "Резервная копия создана"