# PyGuardian - Advanced Security & Cluster Management System 🛡️

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

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Docker](https://img.shields.io/badge/docker-supported-blue.svg)](https://www.docker.com/)
[![Telegram Bot](https://img.shields.io/badge/telegram-bot-blue.svg)](https://core.telegram.org/bots)

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

### 🚀 Автоматическая установка (рекомендуется)
```bash
# Скачать и запустить установку
wget https://raw.githubusercontent.com/your-repo/PyGuardian/main/install.sh
chmod +x install.sh
sudo ./install.sh
```

### 📦 Установка из исходного кода
```bash
# Клонировать репозиторий
git clone https://github.com/your-repo/PyGuardian.git
cd PyGuardian

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

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

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

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

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

**📖 Подробные инструкции:** [QUICKSTART.md](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](QUICKSTART.md)** - Быстрое руководство по установке
- **[⚙️ INSTALLATION.md](docs/INSTALLATION.md)** - Подробная установка и настройка  
- **[🌐 CLUSTER_SETUP.md](docs/CLUSTER_SETUP.md)** - Настройка кластера
- **[⚡ configurations.md](examples/configurations.md)** - Примеры конфигураций
- **[🤖 telegram-commands.md](examples/telegram-commands.md)** - Команды бота

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

### 1️⃣ Автоматическая установка
```bash
# Автономная установка
sudo ./install.sh

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

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

### 2️⃣ Make файл
```bash
# Показать все доступные команды
make help

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

### 3️⃣ Docker установка
```bash
# Автоматическая 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    - Добавить сервер в кластер
```

### Кластерное управление:
```bash
# Добавление сервера в кластер через 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](LICENSE) для подробностей.

## 👥 Авторы

- **SmartSolTech Team** - *Первоначальная разработка* - [@SmartSolTech](https://github.com/SmartSolTech)

## 🆘 Поддержка

### Получить помощь:
- 📧 **Email**: support@smartsoltech.com
- 💬 **Telegram**: @PyGuardianSupport  
- 🐛 **Issues**: [GitHub Issues](https://github.com/SmartSolTech/PyGuardian/issues)
- 📖 **Wiki**: [GitHub Wiki](https://github.com/SmartSolTech/PyGuardian/wiki)

### Перед обращением:
1. Проверьте [FAQ](https://github.com/SmartSolTech/PyGuardian/wiki/FAQ)
2. Запустите диагностику: `./scripts/test-install.sh`
3. Соберите логи: `/debug export` в Telegram боте

---

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

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

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

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

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

**🎉 Спасибо за использование PyGuardian! Ваша безопасность - наш приоритет. 🛡️**
- **Telegram**: Токен бота и admin ID

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

### 1. Клонирование репозитория
```bash
git clone https://github.com/your-org/pyguardian.git
cd pyguardian
```

### 2. Автоматическая установка
```bash
sudo chmod +x install.sh
sudo ./install.sh
```

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

#### Создание бота:
1. Отправьте `/newbot` боту [@BotFather](https://t.me/BotFather)
2. Следуйте инструкциям и получите токен
3. Узнайте ваш Telegram ID через [@userinfobot](https://t.me/userinfobot)

#### Обновление конфигурации:
```bash
sudo nano /etc/pyguardian/config.yaml
```

```yaml
telegram:
  bot_token: "YOUR_BOT_TOKEN_HERE"
  admin_id: YOUR_TELEGRAM_ID
```

### 4. Запуск сервиса
```bash
# Запуск
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:
```yaml
firewall:
  backend: "iptables"
  chain: "INPUT"
  target: "DROP"
  iptables:
    table: "filter"
```

#### Для nftables:
```yaml
firewall:
  backend: "nftables"
  nftables:
    table: "inet pyguardian"
    chain: "input"
```

### Белый список IP
```yaml
whitelist:
  - "127.0.0.1"
  - "::1"
  - "192.168.1.0/24"    # Локальная сеть
  - "10.0.0.0/8"        # VPN сеть
```

### Конфигурация кластера
```yaml
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
- 🔓 Ручная блокировка/разблокировка
- 🟢 Автоматическая разблокировка по таймеру
- ❌ Системные ошибки
- 🚨 Критические атаки

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

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

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

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

### Основные команды
```bash
# Статус
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
```

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

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

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

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

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

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

2. **Добавление серверов в кластер:**
```bash
# Через 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. **Автоматическое развертывание агентов:**
```bash
# Развернуть агента на сервере
/deploy_agent web01

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

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

### Управление кластером
```bash
# Просмотр статистики кластера
/cluster

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

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

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

### 1. Подготовка системы
```bash
# 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. Создание пользователя (опционально)
```bash
sudo useradd -r -s /bin/false pyguardian
sudo mkdir -p /opt/pyguardian /var/lib/pyguardian
sudo chown pyguardian:pyguardian /var/lib/pyguardian
```

### 3. Установка PyGuardian
```bash
# Клонирование
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"
```bash
# Проверить права
ls -la /opt/pyguardian/main.py

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

#### Ошибка "Module not found"
```bash
# Переустановить зависимости
sudo pip3 install -r /opt/pyguardian/requirements.txt --force-reinstall
```

#### Ошибка доступа к auth.log
```bash
# Проверить существование файла
ls -la /var/log/auth.log

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

### Проблемы с firewall

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

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

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

#### nftables не работает
```bash
# Проверить статус
sudo nft list ruleset

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

### Проблемы с Telegram

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

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

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

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

#### Высокое потребление памяти
```yaml
# Настроить в config.yaml
performance:
  max_memory_mb: 50
  cleanup_interval: 1800  # 30 минут
  max_records_age: 259200 # 3 дня
```

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

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

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

### Grafana + Prometheus (дополнительно)
```bash
# Пример экспорта метрик через 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` - логи приложения

### Права доступа
```bash
# Конфигурация (только 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 уведомления (планируется)
```yaml
# В будущих версиях
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

## 🔄 Обновление

### Автоматическое обновление
```bash
# Скачать новую версию
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
```

### Миграция конфигурации
При обновлениях проверяйте совместимость конфигурации:
```bash
# Проверка конфигурации
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](https://github.com/your-org/pyguardian/issues)
- **Telegram**: [@pyguardian_support](https://t.me/pyguardian_support)
- **Email**: support@pyguardian.dev

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

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

---

**PyGuardian** - Made with ❤️ for Linux system administrators