Инициализация в новом репозитории
This commit is contained in:
commit
eb1f18f53e
374 changed files with 226678 additions and 0 deletions
276
SRV/docs/firewalld.md
Normal file
276
SRV/docs/firewalld.md
Normal file
|
|
@ -0,0 +1,276 @@
|
|||
# Документация 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
|
||||
Loading…
Add table
Add a link
Reference in a new issue