Инициализация в новом репозитории

SRV/docs/ufw.md

@@ -0,0 +1,208 @@
+# UFW API Documentation
+
+## Overview
+
+API для управления файрволом UFW (Uncomplicated Firewall) в Linux. Позволяет добавлять, удалять и просматривать правила межсетевого экрана.
+
+## Архитектура
+
+### Модели данных
+
+#### Protocol (Протокол)
+```python
+class Protocol(str, Enum):
+    TCP = "tcp"    # Только TCP протокол
+    UDP = "udp"    # Только UDP протокол
+    BOTH = "both"  # Оба протокола (TCP и UDP)
+```
+
+При указании `BOTH`, система автоматически создает правила для обоих протоколов, используя `proto tcp/udp` в команде UFW.
+
+#### Action (Действие)
+```python
+class Action(str, Enum):
+    ALLOW = "allow"   # Разрешить трафик
+    DENY = "deny"     # Запретить трафик без уведомления
+    REJECT = "reject" # Запретить трафик с уведомлением отправителю
+```
+
+#### Direction (Направление)
+```python
+class Direction(str, Enum):
+    IN = "in"     # Входящий трафик
+    OUT = "out"   # Исходящий трафик
+```
+
+#### UFWRule (Правило UFW)
+```python
+class UFWRule(BaseModel):
+    action: Action           # Действие (allow/deny/reject)
+    direction: Direction     # Направление трафика (in/out)
+    from_ip: str            # IP-адрес источника
+    to_ip: str              # IP-адрес назначения
+    port: Union[int, str]   # Порт или диапазон портов
+    protocol: Protocol      # Протокол
+    comment: Optional[str]  # Комментарий к правилу
+```
+
+Модель выполняет следующие проверки:
+1. Валидация IP адресов:
+   - Проверяет корректность IPv4/IPv6 адресов
+   - Поддерживает CIDR нотацию
+   - Проверяет совместимость версий IP (IPv4/IPv6)
+
+2. Валидация портов:
+   - Одиночный порт: число от 1 до 65535
+   - Диапазон портов: строка вида "3000:4000"
+   - Проверяет корректность диапазона (start <= end)
+
+## API Endpoints
+
+### Получение правил
+
+#### GET /ufw/rules
+Получает список всех правил UFW.
+
+**Response:**
+```json
+{
+    "enabled": true,
+    "rules": [
+        {
+            "action": "allow",
+            "direction": "in",
+            "from_ip": "0.0.0.0/0",
+            "to_ip": "0.0.0.0/0",
+            "port": 80,
+            "protocol": "tcp",
+            "comment": "Allow HTTP"
+        }
+    ]
+}
+```
+
+### Добавление правил
+
+#### POST /ufw/rules/in
+Добавляет входящие правила UFW.
+
+**Request:**
+```json
+{
+    "rules": [
+        {
+            "action": "allow",
+            "from_ip": "0.0.0.0/0",
+            "to_ip": "0.0.0.0/0",
+            "port": 80,
+            "protocol": "tcp",
+            "comment": "Allow HTTP"
+        }
+    ]
+}
+```
+
+**Response:**
+```json
+{
+    "status": "success",
+    "message": "Входящие правила UFW успешно добавлены"
+}
+```
+
+#### POST /ufw/rules/out
+Добавляет исходящие правила UFW.
+
+**Request:**
+```json
+{
+    "rules": [
+        {
+            "action": "allow",
+            "from_ip": "192.168.1.0/24",
+            "to_ip": "0.0.0.0/0",
+            "port": 443,
+            "protocol": "tcp",
+            "comment": "Allow HTTPS outbound"
+        }
+    ]
+}
+```
+
+**Response:**
+```json
+{
+    "status": "success",
+    "message": "Исходящие правила UFW успешно добавлены"
+}
+```
+
+### Удаление правил
+
+#### DELETE /ufw/rules
+Удаляет правила UFW по их номерам.
+
+**Request:**
+```json
+{
+    "numbers": [1, 2, 3]
+}
+```
+
+**Response:**
+```json
+{
+    "status": "success",
+    "message": "Правила UFW успешно удалены"
+}
+```
+
+### Управление состоянием
+
+#### POST /ufw/enable
+Включает UFW.
+
+**Response:**
+```json
+{
+    "status": "success",
+    "message": "UFW успешно включен"
+}
+```
+
+#### POST /ufw/disable
+Выключает UFW.
+
+**Response:**
+```json
+{
+    "status": "success",
+    "message": "UFW успешно выключен"
+}
+```
+
+## Обработка ошибок
+
+### HTTP Status Codes
+
+1. Успешные операции (200):
+   - Получение списка правил
+   - Успешное добавление/удаление правил
+   - Включение/выключение UFW
+
+2. Ошибки клиента (400):
+   - UFW отключен при попытке добавления правил
+   - Некорректный IP адрес или CIDR
+   - Неверный номер порта или диапазон
+   - Несовместимые версии IP (IPv4/IPv6)
+   - Неверные значения enum (action/protocol/direction)
+
+3. Ошибки сервера (500):
+   - Ошибки выполнения команд UFW
+   - Внутренние ошибки сервера
+
+### Формат ошибок
+```json
+{
+    "detail": "Описание ошибки"
+}