PyGuardian - Advanced Security & Cluster Management System 🛡️

Комплексная система безопасности с централизованным управлением кластером серверов через Telegram бот.

⚡ Быстрый старт

🚀 Автоматическая установка (рекомендуется)

# Скачать и запустить установку
wget https://raw.githubusercontent.com/your-repo/PyGuardian/main/install.sh
chmod +x install.sh
sudo ./install.sh

📦 Установка из исходного кода

# Клонировать репозиторий
git clone https://github.com/your-repo/PyGuardian.git
cd PyGuardian

# Проверить систему перед установкой
./scripts/test-install.sh

# Установить (автономный режим)
sudo make install

# Или установить кластерный контроллер
sudo make controller

🐳 Docker установка

# Автоматическая Docker установка
./scripts/docker-install.sh

# Или через Docker Compose
docker-compose up -d

📖 Подробные инструкции: QUICKSTART.md

🎯 Основные возможности

🔒 Продвинутая система безопасности

• 🚨 Обнаружение вторжений - Real-time детекция атак
• 🛡️ Интеллектуальный файрвол - Автоматическая блокировка угроз
• 🔍 Мониторинг системы - Контроль ресурсов и процессов
• ⚠️ DDoS защита - Автоматическое обнаружение и блокировка
• 🔐 2FA интеграция - TOTP аутентификация через Telegram
• 👤 Stealth Mode - Скрытое обнаружение компрометации

🌐 Кластерное управление

• 🎛️ Централизованный контроль - Управление множеством серверов
• 🚀 Автоматическое развертывание - Развертывание агентов одной командой
• 📡 Синхронизация конфигураций - Единые политики безопасности
• 📊 Мониторинг кластера - Состояние всех узлов в реальном времени
• 🔄 Load Balancing - Автоматическое распределение нагрузки

💬 Продвинутый Telegram интерфейс

• 🤖 Интерактивные команды - Удобное управление через диалоги
• 📈 Real-time мониторинг - Мгновенные уведомления и алерты
• 🔧 Удаленное управление - Полный контроль через мессенджер
• 👥 Многопользовательский доступ - Ролевая модель доступа
• 🗣️ Поддержка голосовых команд - Управление голосом

🐳 Современные технологии развертывания

• 📦 Docker поддержка - Контейнеризированное развертывание
• ⚙️ systemd интеграция - Нативная интеграция с системой
• 🔧 Ansible ready - Готовые playbooks для автоматизации
• ☁️ Cloud готовность - Поддержка AWS, GCP, Azure
• 📊 Метрики и логирование - Интеграция с Grafana/Prometheus

🏗️ Архитектура системы

Режимы развертывания:

🖥️ Standalone (Автономный)

Все компоненты на одном сервере

┌─────────────────┐
│   PyGuardian    │
│ ┌─────────────┐ │
│ │ Telegram    │ │
│ │ Bot         │ │
│ └─────────────┘ │
│ ┌─────────────┐ │
│ │ Security    │ │
│ │ Monitor     │ │
│ └─────────────┘ │
│ ┌─────────────┐ │
│ │ Firewall    │ │
│ │ Manager     │ │
│ └─────────────┘ │
└─────────────────┘

🌐 Controller + Agents (Кластерный)

Центральный контроллер управляет агентами

┌─────────────────┐    ┌─────────────────┐
│   Controller    │────│     Agent 1     │
│ ┌─────────────┐ │    │ ┌─────────────┐ │
│ │ Telegram    │ │    │ │ Security    │ │
│ │ Bot         │ │    │ │ Monitor     │ │
│ └─────────────┘ │    │ └─────────────┘ │
│ ┌─────────────┐ │    └─────────────────┘
│ │ Cluster     │ │              │
│ │ Manager     │ │    ┌─────────────────┐
│ └─────────────┘ │────│     Agent 2     │
└─────────────────┘    │ ┌─────────────┐ │
                       │ │ Security    │ │
                       │ │ Monitor     │ │
                       │ └─────────────┘ │
                       └─────────────────┘

🛠️ Технологический стек

• 🐍 Python 3.10+ - Основной язык разработки
• 🤖 Telegram Bot API - Интерфейс управления
• 🗄️ SQLite/PostgreSQL - База данных
• 🔥 iptables/nftables - Управление файрволом
• 🐳 Docker - Контейнеризация
• ⚙️ systemd - Управление службами
• 🔒 cryptography - Шифрование данных
• 📡 asyncio - Асинхронное выполнение
• 📊 psutil - Мониторинг системы

📋 Требования

Минимальные требования:

• ОС: Linux (Ubuntu 20.04+, CentOS 8+, Debian 11+)
• Python: 3.10 или выше
• RAM: 512MB (автономный), 1GB (контроллер)
• Диск: 1GB свободного места
• Сеть: Доступ к Telegram API

Рекомендуемые требования:

• ОС: Ubuntu 22.04 LTS / Debian 12
• Python: 3.11+
• RAM: 2GB+ для контроллера кластера
• Диск: 10GB+ для логов и резервных копий
• Сеть: Выделенный IP для кластера

📚 Документация

• 📖 QUICKSTART.md - Быстрое руководство по установке
• ⚙️ INSTALLATION.md - Подробная установка и настройка
• 🌐 CLUSTER_SETUP.md - Настройка кластера
• ⚡ configurations.md - Примеры конфигураций
• 🤖 telegram-commands.md - Команды бота

🔧 Установка и использование

1️⃣ Автоматическая установка

# Автономная установка
sudo ./install.sh

# Контроллер кластера  
sudo ./install.sh --mode controller

# Агент кластера
sudo ./install.sh --mode agent --controller 192.168.1.10

2️⃣ Make файл

# Показать все доступные команды
make help

# Установка различных режимов
make install     # Автономный режим
make controller  # Кластерный контроллер
make agent       # Кластерный агент

3️⃣ Docker установка

# Автоматическая Docker установка
./scripts/docker-install.sh

# Ручная сборка образа
docker build -t pyguardian .
docker run -d --privileged --network host pyguardian

🎯 Примеры использования

Управление через Telegram бота:

/start          - Начать работу с ботом
/status         - Статус системы безопасности
/block IP       - Заблокировать IP адрес
/unblock IP     - Разблокировать IP адрес  
/sessions       - Показать активные сессии
/logs           - Просмотр логов
/cluster status - Статус кластера (контроллер)
/cluster add    - Добавить сервер в кластер

Кластерное управление:

# Добавление сервера в кластер через SSH
ssh-copy-id -i ~/.ssh/cluster_key.pub root@192.168.1.50

# В Telegram боте контроллера:
/cluster add
# Следовать интерактивным инструкциям

🔒 Безопасность

• 🔑 Аутентификация: Telegram user ID + опциональная 2FA
• 🔐 Шифрование: Все конфиденциальные данные зашифрованы
• 🛡️ Изоляция: Контейнеризация и изолированные процессы
• 📝 Аудит: Полное логирование всех действий
• 🚫 Принцип минимальных привилегий: Только необходимые права

📊 Мониторинг и алерты

Автоматические уведомления о:

• 🚨 Попытках взлома и атаках
• 📈 Превышении лимитов ресурсов
• 🔌 Подключении/отключении агентов кластера
• ⚠️ Ошибках в системе безопасности
• 📋 Результатах резервного копирования

Интеграция с системами мониторинга:

• Grafana/Prometheus - Метрики и дашборды
• ELK Stack - Централизованное логирование
• SIEM системы - Экспорт событий безопасности

🤝 Вклад в проект

Мы приветствуем вклад в развитие PyGuardian!

Как принять участие:

1. Fork репозитория
2. Создайте feature branch (git checkout -b feature/amazing-feature)
3. Commit изменения (git commit -m 'Add amazing feature')
4. Push в branch (git push origin feature/amazing-feature)
5. Создайте Pull Request

Области для улучшения:

• 🌐 Веб-интерфейс управления
• 📱 Мобильное приложение
• 🔌 Интеграции с облачными провайдерами
• 🤖 ИИ для детекции аномалий
• 📊 Расширенная аналитика

📄 Лицензия

Этот проект распространяется под лицензией MIT. См. файл LICENSE для подробностей.

👥 Авторы

• SmartSolTech Team - Первоначальная разработка - @SmartSolTech

🆘 Поддержка

Получить помощь:

• 📧 Email: support@smartsoltech.com
• 💬 Telegram: @PyGuardianSupport
• 🐛 Issues: GitHub Issues
• 📖 Wiki: GitHub Wiki

Перед обращением:

1. Проверьте FAQ
2. Запустите диагностику: ./scripts/test-install.sh
3. Соберите логи: /debug export в Telegram боте

---

⚡ Быстрые команды:

# Проверить статус
systemctl status pyguardian

# Просмотреть логи
journalctl -u pyguardian -f

# Перезапустить
systemctl restart pyguardian

# Обновить конфигурацию
systemctl reload pyguardian

🎉 Спасибо за использование PyGuardian! Ваша безопасность - наш приоритет. 🛡️

• Telegram: Токен бота и admin ID

🚀 Быстрая установка

1. Клонирование репозитория

git clone https://github.com/your-org/pyguardian.git
cd pyguardian

2. Автоматическая установка

sudo chmod +x install.sh
sudo ./install.sh

3. Настройка Telegram бота

Создание бота:

1. Отправьте /newbot боту @BotFather
2. Следуйте инструкциям и получите токен
3. Узнайте ваш Telegram ID через @userinfobot

Обновление конфигурации:

sudo nano /etc/pyguardian/config.yaml

telegram:
  bot_token: "YOUR_BOT_TOKEN_HERE"
  admin_id: YOUR_TELEGRAM_ID

4. Запуск сервиса

# Запуск
sudo systemctl start pyguardian

# Автозапуск
sudo systemctl enable pyguardian

# Проверка статуса
sudo systemctl status pyguardian

# Просмотр логов
sudo journalctl -u pyguardian -f

⚙️ Конфигурация

Основные параметры

Параметр	Описание	По умолчанию
max_attempts	Максимум попыток за time_window	5
time_window	Окно времени в секундах	60
unban_time	Время автоматической разблокировки	3600
auth_log_path	Путь к auth.log	/var/log/auth.log
check_interval	Интервал проверки лога	1.0

Firewall настройки

Для iptables:

firewall:
  backend: "iptables"
  chain: "INPUT"
  target: "DROP"
  iptables:
    table: "filter"

Для nftables:

firewall:
  backend: "nftables"
  nftables:
    table: "inet pyguardian"
    chain: "input"

Белый список IP

whitelist:
  - "127.0.0.1"
  - "::1"
  - "192.168.1.0/24"    # Локальная сеть
  - "10.0.0.0/8"        # VPN сеть

Конфигурация кластера

cluster:
  enabled: true
  ssh_timeout: 30
  deployment_timeout: 300
  retry_attempts: 3
  agent_port: 8081
  master_host: "192.168.1.100"
  master_port: 8080

🤖 Команды Telegram бота

Основные команды

Команда	Описание
/start	Приветствие и информация о системе
/status	Статистика атак и система
/top10	Топ-10 атакующих IP за сутки
/details <ip>	Детальная информация по IP
/ban <ip>	Ручная блокировка IP
/unban <ip>	Разблокировка IP
/list	Список всех забаненных IP
/help	Справка по командам

🚨 Новые команды управления безопасностью

Команда	Описание
/compromises	Список обнаруженных взломов
/sessions	Активные SSH сессии
/kick <user/pid>	Завершить сессию пользователя
/generate_password <user>	Сгенерировать новый пароль
/set_password <user> <pass>	Установить пароль для пользователя

🌐 Команды кластерного управления

Команда	Описание
/cluster	Статистика кластера и подключенные агенты
/add_server <name> <ip> <user>	Добавить новый сервер в кластер
/remove_server <name>	Удалить сервер из кластера
/deploy_agent <name>	Автоматически развернуть агента на сервере
/agents	Список всех агентов кластера
/check_agents	Проверить статус всех агентов

Примеры использования

/details 192.168.1.100
/ban 10.0.0.50
/unban 203.0.113.1

# Новые команды безопасности
/sessions
/kick admin
/generate_password ubuntu
/compromises

# Команды кластерного управления
/cluster
/add_server web01 192.168.1.10 ubuntu
/deploy_agent web01
/agents
/check_agents
/remove_server old_server

📊 Мониторинг и логирование

Детекция атак

Система отслеживает следующие события в auth.log:

• Failed password
• Invalid user
• authentication failure
• Too many authentication failures
• Failed publickey
• Connection closed by authenticating user

Уведомления в Telegram

• ⚠️ Автоматическая блокировка IP
• 🔓 Ручная блокировка/разблокировка
• 🟢 Автоматическая разблокировка по таймеру
• ❌ Системные ошибки
• 🚨 Критические атаки

Логи системы

# Системные логи
sudo journalctl -u pyguardian -f

# Файловые логи
sudo tail -f /var/log/pyguardian.log

# Логи ошибок
sudo journalctl -u pyguardian -p err

🔧 Управление сервисом

Основные команды

# Статус
sudo systemctl status pyguardian

# Запуск
sudo systemctl start pyguardian

# Остановка
sudo systemctl stop pyguardian

# Перезапуск
sudo systemctl restart pyguardian

# Перезагрузка конфигурации
sudo systemctl reload pyguardian

# Автозапуск
sudo systemctl enable pyguardian

# Отключить автозапуск
sudo systemctl disable pyguardian

Мониторинг ресурсов

# Использование памяти
sudo systemctl show pyguardian --property=MemoryCurrent

# Количество процессов
sudo systemctl show pyguardian --property=TasksCurrent

# Время работы
sudo systemctl show pyguardian --property=ActiveEnterTimestamp

🌐 Настройка кластера

Включение кластерного режима

1. Настройка мастер-сервера:

# В config.yaml включить кластерный режим
cluster:
  enabled: true
  master_host: "192.168.1.100"  # IP мастер-сервера
  master_port: 8080

2. Добавление серверов в кластер:

# Через Telegram бота
/add_server web01 192.168.1.10 ubuntu
/add_server db01 192.168.1.20 admin
/add_server app01 192.168.1.30 deploy

3. Автоматическое развертывание агентов:

# Развернуть агента на сервере
/deploy_agent web01

# Проверить статус всех агентов
/check_agents

Требования для кластера

• SSH доступ: Мастер-сервер должен иметь SSH доступ ко всем агентам
• Сетевые порты: Порт 8080 (мастер), 8081 (агенты)
• Ключи SSH: Настроенные SSH ключи или пароли для автоматического развертывания

Управление кластером

# Просмотр статистики кластера
/cluster

# Список всех агентов
/agents

# Удаление сервера из кластера
/remove_server old_server

🛠️ Ручная установка (альтернативный способ)

1. Подготовка системы

# Ubuntu/Debian
sudo apt update
sudo apt install python3 python3-pip python3-venv iptables

# CentOS/RHEL
sudo yum install python3 python3-pip iptables

# или
sudo dnf install python3 python3-pip iptables

2. Создание пользователя (опционально)

sudo useradd -r -s /bin/false pyguardian
sudo mkdir -p /opt/pyguardian /var/lib/pyguardian
sudo chown pyguardian:pyguardian /var/lib/pyguardian

3. Установка PyGuardian

# Клонирование
git clone https://git.smartsoltech.kr/trevor/PyGuardian.git
cd pyguardian

# Копирование файлов
sudo cp -r src/ main.py requirements.txt /opt/pyguardian/
sudo cp config/config.yaml /etc/pyguardian/
sudo cp systemd/pyguardian.service /etc/systemd/system/

# Установка зависимостей
cd /opt/pyguardian
sudo pip3 install -r requirements.txt

# Права
sudo chmod +x /opt/pyguardian/main.py
sudo chown -R root:root /opt/pyguardian

# Systemd
sudo systemctl daemon-reload

🔍 Диагностика и решение проблем

Проблемы с запуском

Ошибка "Permission denied"

# Проверить права
ls -la /opt/pyguardian/main.py

# Исправить права
sudo chmod +x /opt/pyguardian/main.py

Ошибка "Module not found"

# Переустановить зависимости
sudo pip3 install -r /opt/pyguardian/requirements.txt --force-reinstall

Ошибка доступа к auth.log

# Проверить существование файла
ls -la /var/log/auth.log

# Проверить права
sudo chmod 644 /var/log/auth.log

Проблемы с firewall

iptables не работает

# Проверить статус
sudo iptables -L -n

# Проверить модули
lsmod | grep ip_tables

# Загрузить модуль
sudo modprobe ip_tables

nftables не работает

# Проверить статус
sudo nft list ruleset

# Установить nftables
sudo apt install nftables  # Ubuntu/Debian
sudo yum install nftables  # CentOS/RHEL

Проблемы с Telegram

Бот не отвечает

# Проверить токен и ID в конфигурации
sudo cat /etc/pyguardian/config.yaml | grep -A 3 telegram

# Проверить сетевое соединение
curl -s "https://api.telegram.org/botYOUR_TOKEN/getMe"

Уведомления не приходят

# Проверить ID администратора
# Убедиться что вы написали боту /start
# Проверить логи
sudo journalctl -u pyguardian | grep -i telegram

Производительность

Высокое потребление памяти

# Настроить в config.yaml
performance:
  max_memory_mb: 50
  cleanup_interval: 1800  # 30 минут
  max_records_age: 259200 # 3 дня

Высокая нагрузка на диск

# Увеличить интервал проверки
monitoring:
  check_interval: 2.0  # Проверять каждые 2 секунды

# Настроить логирование
logging:
  log_level: "WARNING"  # Меньше логов

📈 Мониторинг производительности

Grafana + Prometheus (дополнительно)

# Пример экспорта метрик через systemd
sudo systemctl status pyguardian --output=json

Встроенная статистика

Телеграм бот предоставляет:

• Количество атак за день
• Топ атакующих IP
• Использование памяти
• Время работы системы
• Статистику обработанных событий

🔐 Безопасность

Рекомендации

1. Регулярно обновляйте конфигурацию белого списка
2. Мониторьте логи на предмет ложных срабатываний
3. Используйте VPN для доступа к серверу
4. Настройте резервное копирование конфигурации
5. Периодически проверяйте список забаненных IP

Файлы конфигурации

• /etc/pyguardian/config.yaml - основная конфигурация
• /var/lib/pyguardian/guardian.db - база данных SQLite
• /var/log/pyguardian.log - логи приложения

Права доступа

# Конфигурация (только root может читать токены)
sudo chmod 600 /etc/pyguardian/config.yaml

# База данных
sudo chmod 600 /var/lib/pyguardian/guardian.db

# Логи
sudo chmod 644 /var/log/pyguardian.log

📚 API и интеграция

Webhook уведомления (планируется)

# В будущих версиях
webhooks:
  on_ban: "https://your-domain.com/webhook/ban"
  on_unban: "https://your-domain.com/webhook/unban"

REST API (планируется)

• GET /api/stats - получение статистики
• POST /api/ban - ручной бан IP
• DELETE /api/ban/<ip> - разбан IP

🔄 Обновление

Автоматическое обновление

# Скачать новую версию
cd /tmp
git clone https://github.com/your-org/pyguardian.git
cd pyguardian

# Остановить сервис
sudo systemctl stop pyguardian

# Обновить файлы (сохраняя конфигурацию)
sudo cp -r src/ main.py requirements.txt /opt/pyguardian/
sudo pip3 install -r /opt/pyguardian/requirements.txt

# Запустить сервис
sudo systemctl start pyguardian

Миграция конфигурации

При обновлениях проверяйте совместимость конфигурации:

# Проверка конфигурации
python3 -c "import yaml; yaml.safe_load(open('/etc/pyguardian/config.yaml'))"

🤝 Вклад в проект

1. Форкните репозиторий
2. Создайте ветку для функции (git checkout -b feature/amazing-feature)
3. Зафиксируйте изменения (git commit -m 'Add amazing feature')
4. Отправьте в ветку (git push origin feature/amazing-feature)
5. Откройте Pull Request

📄 Лицензия

Distributed under the MIT License. See LICENSE for more information.

💬 Поддержка

• Issues: GitHub Issues
• Telegram: @pyguardian_support
• Email: support@pyguardian.dev

🎯 Планы развития

• Web-интерфейс (опционально)
• REST API
• Webhook уведомления
• Интеграция с облачными провайдерами
• Машинное обучение для детекции аномалий
• Поддержка IPv6
• Кластерный режим - ✅ Реализовано!
• Экспорт метрик Prometheus

---

PyGuardian - Made with ❤️ for Linux system administrators