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
Используется для представления зоны файрвола:
```python
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
Модель для конфигурации сервиса:
```python
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
Модель для конфигурации порта с валидацией протокола:
```python
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-адреса:
```python
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
Обобщенная модель правила файрвола:
```python
class FirewallRule(BaseModel):
    zone: str
    source: Optional[FirewallSource] = None
    port: Optional[FirewallPort] = None
    service: Optional[str] = None
```
Используется для комплексных операций с правилами.

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

##### PortRule
```python
class PortRule(BaseModel):
    port: int
    protocol: str
    timeout: Optional[int] = 0
```
Используется для валидации входных данных при добавлении портов.

##### ServiceRule
```python
class ServiceRule(BaseModel):
    service: str
    timeout: Optional[int] = 0
```
Используется для валидации входных данных при добавлении сервисов.

##### SourceRule
```python
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
Получение списка всех доступных зон.

**Ответ:**
```json
[
    "public",
    "internal",
    "external",
    ...
]
```

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

#### GET /api/v1/firewalld/zones/default
Получение зоны по умолчанию.

**Ответ:**
```json
{
    "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
Получение списка сервисов в зоне.

**Ответ:**
```json
{
    "services": ["http", "https", "ssh"]
}
```

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

#### POST /api/v1/firewalld/zones/{zone}/services
Добавление сервиса в зону.

**Тело запроса:**
```json
{
    "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
Получение списка портов в зоне.

**Ответ:**
```json
{
    "ports": ["80/tcp", "443/tcp"]
}
```

#### POST /api/v1/firewalld/zones/{zone}/ports
Добавление порта в зону.

**Тело запроса:**
```json
{
    "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