PyGuardian/.history/README_20251125204558.md

# 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)

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

- **Мониторинг в реальном времени**: Отслеживание auth.log и детекция атак
- **Автоматическая защита**: Блокировка IP при превышении лимита попыток  
- **Telegram управление**: Полный контроль через бота без веб-интерфейса
- **🔥 STEALTH MODE**: Скрытое обнаружение и нейтрализация взломов
- **Session Management**: Мониторинг и управление SSH сессиями
- **Password Security**: Автоматическая смена паролей при компромиссе
- **🌐 CLUSTER MANAGEMENT**: Централизованное управление множественными серверами
- **Agent Deployment**: Автоматическое развертывание агентов по SSH
- **Multi-Server Control**: Единый Telegram-интерфейс для всех серверов
- **Поддержка firewall**: iptables и nftables
- **Автоматический разбан**: По таймеру с уведомлениями
- **Белый список**: Защита доверенных IP от блокировки
- **Статистика**: Подробная аналитика атак и успешных входов
- **Асинхронность**: Оптимизированная производительность

## 📋 Требования

- **ОС**: Linux (Ubuntu 20.04+, CentOS 8+, Debian 11+)
- **Python**: 3.10 или выше
- **Права**: root (для работы с firewall)
- **Firewall**: iptables или nftables
- **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://github.com/your-org/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