gonets/SRV/docs/firewalld.md

Документация API FirewallD

Общее описание

API предоставляет интерфейс для управления межсетевым экраном FirewallD в Linux системах. API построено на основе взаимодействия с FirewallD через D-Bus интерфейс.

Внутренняя архитектура

1. Уровни взаимодействия

[HTTP API] -> [FastAPI Router] -> [FirewallD Service] -> [D-Bus] -> [FirewallD]

2. Компоненты системы

2.1 D-Bus интерфейс

FirewallD предоставляет D-Bus интерфейс org.fedoraproject.FirewallD1 для управления. Наш сервис подключается к системной шине D-Bus и взаимодействует с FirewallD через этот интерфейс.

Основные методы D-Bus:

• getZones() - получение списка зон
• getDefaultZone() - получение зоны по умолчанию
• addService() - добавление сервиса
• removeService() - удаление сервиса и т.д.

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

В models/firewalld.py определены Pydantic модели для валидации данных:

FirewallZone

Используется для представления зоны файрвола:

class FirewallZone(BaseModel):
    name: str
    target: Optional[str] = None
    services: List[str] = Field(default_factory=list)
    ports: List[str] = Field(default_factory=list)
    sources: List[str] = Field(default_factory=list)
    interfaces: List[str] = Field(default_factory=list)

Применяется при получении настроек зоны через API.

FirewallService

Модель для конфигурации сервиса:

class FirewallService(BaseModel):
    name: str
    ports: List[str] = Field(default_factory=list)
    protocols: List[str] = Field(default_factory=list)
    modules: List[str] = Field(default_factory=list)

Используется при добавлении новых сервисов через API.

FirewallPort

Модель для конфигурации порта с валидацией протокола:

class FirewallPort(BaseModel):
    port: int
    protocol: Optional[str] = Field(default=None)
    timeout: Optional[int] = 0

Применяется в API endpoint POST /api/v1/firewalld/zones/{zone}/ports для валидации входных данных.

FirewallSource

Модель для конфигурации источника с валидацией IP-адреса:

class FirewallSource(BaseModel):
    address: str = Field(..., pattern=r'^(?:[0-9]{1,3}\.){3}[0-9]{1,3}(?:/[0-9]{1,2})?$')
    zone: Optional[str] = None

Используется в API endpoint POST /api/v1/firewalld/zones/{zone}/sources для валидации IP-адресов.

FirewallRule

Обобщенная модель правила файрвола:

class FirewallRule(BaseModel):
    zone: str
    source: Optional[FirewallSource] = None
    port: Optional[FirewallPort] = None
    service: Optional[str] = None

Используется для комплексных операций с правилами.

В API (api/v1/firewalld.py) определены дополнительные модели для запросов:

PortRule

class PortRule(BaseModel):
    port: int
    protocol: str
    timeout: Optional[int] = 0

Используется для валидации входных данных при добавлении портов.

ServiceRule

class ServiceRule(BaseModel):
    service: str
    timeout: Optional[int] = 0

Используется для валидации входных данных при добавлении сервисов.

SourceRule

class SourceRule(BaseModel):
    source: str

Используется для валидации входных данных при добавлении источников.

Все модели используют Pydantic для:

• Валидации входных данных
• Автоматической конвертации типов
• Генерации OpenAPI документации
• Проверки бизнес-правил (например, валидация протокола в FirewallPort)

2.3 Сервисный слой

FirewallService в services/firewalld_service.py обеспечивает:

• Подключение к D-Bus
• Обработку ошибок
• Преобразование данных между API и D-Bus форматами

API Endpoints

Управление зонами

GET /api/v1/firewalld/zones

Получение списка всех доступных зон.

Ответ:

[
    "public",
    "internal",
    "external",
    ...
]

Внутренняя работа:

1. Запрос поступает в FastAPI router
2. Router вызывает FirewallService.get_zones()
3. Сервис делает вызов getZones() через D-Bus
4. Результат преобразуется в JSON и возвращается клиенту

GET /api/v1/firewalld/zones/default

Получение зоны по умолчанию.

Ответ:

{
    "name": "public"
}

Внутренняя работа:

1. Вызов FirewallService.get_default_zone()
2. D-Bus запрос getDefaultZone()
3. Преобразование результата

PUT /api/v1/firewalld/zones/default/{zone}

Установка зоны по умолчанию.

Параметры:

• zone: имя зоны

Внутренняя работа:

1. Валидация имени зоны
2. Вызов FirewallService.set_default_zone()
3. D-Bus запрос setDefaultZone()

Управление сервисами

GET /api/v1/firewalld/zones/{zone}/services

Получение списка сервисов в зоне.

Ответ:

{
    "services": ["http", "https", "ssh"]
}

Внутренняя работа:

1. Проверка существования зоны
2. Вызов FirewallService.get_services()
3. D-Bus запрос getServices()

POST /api/v1/firewalld/zones/{zone}/services

Добавление сервиса в зону.

Тело запроса:

{
    "service": "http",
    "timeout": 0
}

Внутренняя работа:

1. Валидация данных через Pydantic модель
2. Вызов FirewallService.add_service()
3. D-Bus запрос addService()

DELETE /api/v1/firewalld/zones/{zone}/services/{service}

Удаление сервиса из зоны.

Внутренняя работа:

1. Проверка существования сервиса
2. Вызов FirewallService.remove_service()
3. D-Bus запрос removeService()

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

GET /api/v1/firewalld/zones/{zone}/ports

Получение списка портов в зоне.

Ответ:

{
    "ports": ["80/tcp", "443/tcp"]
}

POST /api/v1/firewalld/zones/{zone}/ports

Добавление порта в зону.

Тело запроса:

{
    "port": 80,
    "protocol": "tcp",
    "timeout": 0
}

DELETE /api/v1/firewalld/zones/{zone}/ports

Удаление порта из зоны.

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

GET /api/v1/firewalld/zones/{zone}/sources

Получение списка источников в зоне.

POST /api/v1/firewalld/zones/{zone}/sources

Добавление источника в зону.

DELETE /api/v1/firewalld/zones/{zone}/sources/{source}

Удаление источника из зоны.

Обработка ошибок

API возвращает следующие коды ошибок:

• 400: Неверный запрос (например, неверный формат данных)
• 404: Ресурс не найден (зона, сервис и т.д.)
• 500: Внутренняя ошибка сервера

При ошибке D-Bus или FirewallD, ошибка логируется и возвращается соответствующий HTTP код.

Возможные улучшения

1. Безопасность:

   • Добавить аутентификацию
   • Добавить rate limiting
   • Логирование действий

2. Функциональность:

   • Добавить поддержку rich rules
   • Управление ICMP правилами
   • Управление forward портами

3. Производительность:

   • Кэширование часто запрашиваемых данных
   • Batch операции для множественных изменений

4. Надёжность:

   • Retry механизм для D-Bus операций
   • Более детальная обработка ошибок
   • Валидация состояния FirewallD