gonets/SRV/docs/ufw.md

# 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": "Описание ошибки"
}