gonets/SRV/docs/ufw.md

UFW API Documentation

Overview

API для управления файрволом UFW (Uncomplicated Firewall) в Linux. Позволяет добавлять, удалять и просматривать правила межсетевого экрана.

Архитектура

Модели данных

Protocol (Протокол)

class Protocol(str, Enum):
    TCP = "tcp"    # Только TCP протокол
    UDP = "udp"    # Только UDP протокол
    BOTH = "both"  # Оба протокола (TCP и UDP)

При указании BOTH, система автоматически создает правила для обоих протоколов, используя proto tcp/udp в команде UFW.

Action (Действие)

class Action(str, Enum):
    ALLOW = "allow"   # Разрешить трафик
    DENY = "deny"     # Запретить трафик без уведомления
    REJECT = "reject" # Запретить трафик с уведомлением отправителю

Direction (Направление)

class Direction(str, Enum):
    IN = "in"     # Входящий трафик
    OUT = "out"   # Исходящий трафик

UFWRule (Правило UFW)

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:

{
    "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:

{
    "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:

{
    "status": "success",
    "message": "Входящие правила UFW успешно добавлены"
}

POST /ufw/rules/out

Добавляет исходящие правила UFW.

Request:

{
    "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:

{
    "status": "success",
    "message": "Исходящие правила UFW успешно добавлены"
}

Удаление правил

DELETE /ufw/rules

Удаляет правила UFW по их номерам.

Request:

{
    "numbers": [1, 2, 3]
}

Response:

{
    "status": "success",
    "message": "Правила UFW успешно удалены"
}

Управление состоянием

POST /ufw/enable

Включает UFW.

Response:

{
    "status": "success",
    "message": "UFW успешно включен"
}

POST /ufw/disable

Выключает UFW.

Response:

{
    "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
   • Внутренние ошибки сервера

Формат ошибок

{
    "detail": "Описание ошибки"
}