From f46d3242b67fd26af7a73b1fc2070702f86f8650 Mon Sep 17 00:00:00 2001
From: Ilya Chernishev <d3m0k1d1337@gmail.com>
Date: Sun, 11 Jan 2026 17:51:48 +0300
Subject: [PATCH] docs: write comprehensive README with project overview and
 roadmap

---
 README.md | 149 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 149 insertions(+)

diff --git a/README.md b/README.md
index e69de29..6a84325 100644
--- a/README.md
+++ b/README.md
@@ -0,0 +1,149 @@
+# BanForge
+
+**BanForge** — это современная система защиты от атак на базе Linux, разработанная как облегченная альтернатива fail2ban с поддержкой реал-тайм мониторинга и расширяемой архитектурой.
+
+## 🎯 Назначение
+
+BanForge автоматически обнаруживает и блокирует подозрительную активность на сервере путём анализа логов сервисов в реальном времени и применения правил через встроенные бан-провайдеры (UFW, iptables и т.д.).
+
+## 🔧 Технический стек
+
+- **Язык**: Go 1.21+
+- **ОС**: Linux (Alpine, Debian, Ubuntu, Arch)
+- **Основные возможности**: 
+  - Логирование и конфигурация
+  - Системные вызовы для управления файрволом
+  - Real-time file watching
+
+## 📁 Структура проекта
+
+```
+BanForge/
+├── cmd/banforge/          # Основное CLI приложение
+│   └── main.go           # Точка входа
+├── internal/             # Внутренние пакеты
+│   ├── firewall/        # Реализации бан-провайдеров (UFW, iptables)
+│   ├── logger/          # Система логирования
+│   ├── monitor/         # Мониторинг логов в реальном времени
+│   └── config/          # Парсинг конфигурации
+├── .gitea/workflows/    # CI/CD pipeline (Gitea Actions)
+├── go.mod              # Go модули
+├── Makefile            # Утилиты для сборки
+└── LICENSE             # GPL 3.0
+```
+
+## 🚀 Быстрый старт
+
+### Требования
+
+- Linux система с установленным Go 1.21+
+- UFW или iptables для управления правилами файрвола
+- Root привилегии для запуска демона
+
+### Сборка
+
+```bash
+git clone https://gitea.d3m0k1d.ru/d3m0k1d/BanForge.git
+cd BanForge
+make build
+```
+
+### Запуск
+
+```bash
+# Развёртывание демона
+sudo ./bin/banforge daemon init
+
+# Просмотр логов
+journalctl -u banforge -f
+```
+
+## 🏗️ Архитектура
+
+### Модульная система провайдеров
+
+BanForge использует интерфейс-ориентированный подход для работы с файрволами:
+
+```go
+type BanProvider interface {
+    Ban(ip string) error
+    Unban(ip string) error
+    Status(ip string) (bool, error)
+}
+```
+
+Текущие реализации:
+- **UFW** — встроенный файрвол Ubuntu/Debian
+- **iptables** — базовая поддержка нативного Linux файрвола
+
+### Real-time мониторинг
+
+Система использует file watchers для отслеживания изменений в логах сервисов без постоянного полинга диска.
+
+## 📋 Roadmap
+
+### v0.1 (текущая разработка)
+- [x] Базовая архитектура с интерфейсами
+- [x] Реализация UFW провайдера
+- [x] Система инициализации демона
+- [ ] **Real-time Nginx log monitoring** — следующий приоритет
+- [ ] Unit тесты и интеграционные тесты
+
+### v0.2 (планируется)
+- [ ] Поддержка Apache, OpenSSH логов
+- [ ] Пользовательские правила с regex
+- [ ] REST API для управления
+
+### v1.0 (видение)
+- [ ] TUI интерфейс для управления
+- [ ] Prometheus метрики
+- [ ] Clustering поддержка
+- [ ] Веб-дашборд
+
+## 💾 Релизы на Gitea вместо GitHub
+
+**Почему релизы и артефакты находятся на self-hosted Gitea?**
+
+GitHub Actions имеет ограничения:
+- **Лимиты на хранилище артефактов** (35 дней)
+- **Лимиты на размер бинариев** в одном релизе
+- **Rate limiting** для автоматизированных загрузок
+- **Недостаточная гибкость** при работе с большими файлами
+- **Отсутствие полного контроля** над инфраструктурой
+
+**На self-hosted Gitea:**
+- ✅ Полный контроль над хранилищем
+- ✅ Неограниченные размеры артефактов
+- ✅ Собственные CI/CD pipelines
+- ✅ Приватные релизы если нужны
+- ✅ Быстрые загрузки в локальной сети
+
+Исходный код доступен на GitHub для удобства, но binary releases публикуются на **[Gitea](https://gitea.d3m0k1d.ru/d3m0k1d/BanForge)**.
+
+## 🤝 Разработка
+
+### Запуск тестов
+
+```bash
+make test
+```
+
+### Сборка для разных платформ
+
+```bash
+make build-linux-amd64
+make build-linux-arm64
+```
+
+## 📞 Поддержка
+
+- **Issues & Discussions**: [GitHub Issues](https://github.com/d3m0k1d/BanForge/issues)
+- **Releases & Artifacts**: [Gitea Releases](https://gitea.d3m0k1d.ru/d3m0k1d/BanForge)
+
+## 📄 Лицензия
+
+GNU General Public License v3.0 — см. [LICENSE](./LICENSE)
+
+---
+
+**BanForge** — созданный для автоматизации защиты Linux серверов с минимальными накладными расходами на ресурсы.