276 lines
9.1 KiB
Markdown
276 lines
9.1 KiB
Markdown
# Документация 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
|