Generate Sphinx docs in markdown
This commit is contained in:
Merelden
parent
bc4e9caacb
commit
81ff7959f7
84 changed files with 2873 additions and 29 deletions
272
SRV/docs/_build/markdown/api/services/subnet_service.md
vendored
Normal file
272
SRV/docs/_build/markdown/api/services/subnet_service.md
vendored
Normal file
|
|
@ -0,0 +1,272 @@
|
|||
# Subnet Service
|
||||
|
||||
### *class* services.subnet_service.DeviceInfoCollector(translations: Translations)
|
||||
|
||||
Bases: `object`
|
||||
|
||||
Класс для сбора информации об устройствах, включая вендоров и хостнеймы.
|
||||
|
||||
Источники данных:
|
||||
: - MacLookup: сопоставление префикса MAC (OUI) с названием производителя.
|
||||
- DNS: gethostbyaddr с малым таймаутом для обратного разрешения имени.
|
||||
- NetBIOS (nbtscan): опрос сегмента сети для извлечения NetBIOS‑имён.
|
||||
|
||||
Политика кэширования:
|
||||
: - Результаты get_vendor кэшируются с помощью functools.lru_cache.
|
||||
- Результаты nbtscan аккумулируются в словарях nbtscan_cache/nbtscan_results
|
||||
на время жизни экземпляра.
|
||||
|
||||
#### get_hostname(ip: str) → str | None
|
||||
|
||||
Получает хостнейм для указанного IP-адреса.
|
||||
|
||||
Пробует сначала DNS, затем NetBIOS.
|
||||
|
||||
* **Parameters:**
|
||||
**ip** (*str*) – IP-адрес устройства.
|
||||
* **Returns:**
|
||||
Хостнейм или None, если не удалось определить.
|
||||
* **Return type:**
|
||||
Optional[str]
|
||||
|
||||
#### get_vendor(mac: str) → str
|
||||
|
||||
Получает вендора устройства по MAC-адресу.
|
||||
|
||||
Использует кэширование для повышения производительности.
|
||||
|
||||
* **Parameters:**
|
||||
**mac** (*str*) – MAC-адрес устройства.
|
||||
* **Returns:**
|
||||
Название вендора или “Неизвестный” в случае ошибки.
|
||||
* **Return type:**
|
||||
str
|
||||
|
||||
#### scan_nbtscan(subnet: str) → None
|
||||
|
||||
Сканирует подсеть с помощью nbtscan для получения хостнеймов.
|
||||
|
||||
Сохраняет результаты в кэш и логирует процесс.
|
||||
|
||||
* **Parameters:**
|
||||
**subnet** (*str*) – Подсеть в формате CIDR.
|
||||
|
||||
### *class* services.subnet_service.DeviceStorage(base_path: str = 'storage/subnets', translations: Translations = None)
|
||||
|
||||
Bases: `object`
|
||||
|
||||
Класс для хранения и управления данными об устройствах.
|
||||
|
||||
Формат файла подсети:
|
||||
|
||||
```default
|
||||
{
|
||||
"devices": [Device, ...]
|
||||
}
|
||||
```
|
||||
|
||||
Политика очистки:
|
||||
|
||||
- Метод \_clean_old_devices удаляет оффлайн‑устройства, не наблюдавшиеся более 7 дней,
|
||||
чтобы поддерживать актуальность списка.
|
||||
|
||||
#### get_subnet_file(subnet: str) → Path
|
||||
|
||||
Возвращает путь к файлу для конкретной подсети.
|
||||
|
||||
Заменяет символы ‘/’ на ‘_’ для корректного имени файла.
|
||||
|
||||
* **Parameters:**
|
||||
**subnet** (*str*) – Подсеть в формате CIDR.
|
||||
* **Returns:**
|
||||
Путь к файлу.
|
||||
* **Return type:**
|
||||
Path
|
||||
|
||||
#### load_devices(subnet: str) → Dict[str, Device]
|
||||
|
||||
Загружает устройства для указанной подсети.
|
||||
|
||||
Читает данные из JSON-файла и фильтрует устаревшие устройства.
|
||||
|
||||
* **Parameters:**
|
||||
**subnet** (*str*) – Подсеть в формате CIDR.
|
||||
* **Returns:**
|
||||
Словарь устройств с MAC как ключом.
|
||||
* **Return type:**
|
||||
Dict[str, Device]
|
||||
|
||||
#### save_devices(subnet: str, devices: List[Device]) → None
|
||||
|
||||
Сохраняет устройства для указанной подсети.
|
||||
|
||||
Записывает данные в JSON-файл.
|
||||
|
||||
* **Parameters:**
|
||||
* **subnet** (*str*) – Подсеть в формате CIDR.
|
||||
* **devices** (*List* *[**Device* *]*) – Список устройств для сохранения.
|
||||
* **Raises:**
|
||||
**Exception** – Если произошла ошибка при сохранении.
|
||||
|
||||
### *class* services.subnet_service.NetworkScanner(interface: str, translations: Translations)
|
||||
|
||||
Bases: `object`
|
||||
|
||||
Класс для сканирования подсети с использованием ARP-запросов.
|
||||
|
||||
Назначение:
|
||||
: Обнаруживает активные устройства в локальной сети, отправляя широковещательные
|
||||
ARP‑запросы по указанной подсети и собирая ответы (IP, MAC).
|
||||
|
||||
Детали реализации:
|
||||
: - Использует scapy (Ether + ARP) для генерации пакетов и srp для
|
||||
отправки/получения на канальном уровне от имени заданного интерфейса.
|
||||
- Таймаут ожидания ответа короткий (2 секунды), ориентирован на интерактивные
|
||||
сценарии UI.
|
||||
|
||||
Ограничения и замечания:
|
||||
: - Требуются права для отправки низкоуровневых пакетов (capabilities/root).
|
||||
- В сетях с фильтрацией широковещания количество обнаруженных устройств
|
||||
может быть ограничено.
|
||||
|
||||
#### scan(subnet: str) → List[Tuple[str, str]]
|
||||
|
||||
Сканирует подсеть с использованием ARP-запросов.
|
||||
|
||||
Отправляет ARP-пакеты для обнаружения активных устройств и возвращает
|
||||
список кортежей (IP, MAC).
|
||||
|
||||
* **Parameters:**
|
||||
**subnet** (*str*) – Подсеть в формате CIDR (например, “10.1.1.0/24”).
|
||||
* **Returns:**
|
||||
Список кортежей (IP-адрес, MAC-адрес) обнаруженных устройств.
|
||||
* **Return type:**
|
||||
List[Tuple[str, str]]
|
||||
* **Raises:**
|
||||
**Exception** – Если произошла ошибка сканирования.
|
||||
|
||||
### *class* services.subnet_service.PortScanner(interface: str, translations: Translations)
|
||||
|
||||
Bases: `object`
|
||||
|
||||
Класс для сканирования открытых портов на устройствах.
|
||||
|
||||
Назначение:
|
||||
: Плейсхолдер для будущего функционала активного сканирования TCP/UDP‑портов
|
||||
у обнаруженных узлов. В текущей версии возвращает пустой список.
|
||||
|
||||
План развития:
|
||||
: - Добавить неблокирующее сканирование наиболее распространённых портов
|
||||
(22, 80, 443 и т.д.) с ограничением по времени.
|
||||
- Настраиваемые профили глубины и скорости сканирования.
|
||||
|
||||
#### scan(ip: str) → List[str]
|
||||
|
||||
Сканирует открытые порты на указанном IP-адресе.
|
||||
|
||||
Пока возвращает пустой список, так как функциональность не реализована.
|
||||
|
||||
* **Parameters:**
|
||||
**ip** (*str*) – IP-адрес устройства для сканирования.
|
||||
* **Returns:**
|
||||
Список открытых портов (пока пустой).
|
||||
* **Return type:**
|
||||
List[str]
|
||||
|
||||
### *class* services.subnet_service.SubnetService(translations: Translations)
|
||||
|
||||
Bases: `object`
|
||||
|
||||
Сервис для сканирования подсетей и управления устройствами.
|
||||
|
||||
Роль сервиса:
|
||||
: Объединяет сетевое сканирование (ARP), сбор дополнительной информации
|
||||
(вендор, хостнейм), слияние с кэшем предыдущих результатов и персистентное
|
||||
хранение данных по подсетям. Предоставляет вспомогательные операции для
|
||||
локального узла и работы с заметками устройств.
|
||||
|
||||
Поток выполнения скана (scan_subnet):
|
||||
: 1. Определение подсети (вручную или авто по интерфейсу).
|
||||
2. Загрузка ранее сохранённых устройств подсети.
|
||||
3. Добавление локального устройства (если принадлежит подсети).
|
||||
4. ARP‑сканирование и параллельная обработка узлов (обогащение данных).
|
||||
5. Маркировка оффлайн‑узлов из кэша, не встреченных в текущем скане.
|
||||
6. Сортировка по IP и сохранение объединённого списка в JSON.
|
||||
|
||||
#### add_note(mac: str, note: str, translations: Translations) → Tuple[bool, Tuple[str, Dict] | None]
|
||||
|
||||
Добавляет заметку для устройства по MAC-адресу.
|
||||
|
||||
Привязывает заметку к устройству, если оно существует.
|
||||
|
||||
* **Parameters:**
|
||||
* **mac** (*str*) – MAC-адрес устройства.
|
||||
* **note** (*str*) – Текст заметки.
|
||||
* **translations** (*Translations*) – Объект переводов для текущего языка.
|
||||
* **Returns:**
|
||||
Кортеж (успех, результат),
|
||||
: где результат содержит код ошибки/успеха и данные.
|
||||
* **Return type:**
|
||||
Tuple[bool, Optional[Tuple[str, Dict]]]
|
||||
|
||||
#### delete_note(mac: str, translations: Translations) → Tuple[bool, Tuple[str, Dict] | None]
|
||||
|
||||
Удаляет заметку для устройства по MAC-адресу.
|
||||
|
||||
Удаляет привязанную заметку, если она существует.
|
||||
|
||||
* **Parameters:**
|
||||
* **mac** (*str*) – MAC-адрес устройства.
|
||||
* **translations** (*Translations*) – Объект переводов для текущего языка.
|
||||
* **Returns:**
|
||||
Кортеж (успех, результат),
|
||||
: где результат содержит код ошибки/успеха и данные.
|
||||
* **Return type:**
|
||||
Tuple[bool, Optional[Tuple[str, Dict]]]
|
||||
|
||||
#### scan_subnet(subnet: str | None = None) → SubnetScanResult
|
||||
|
||||
Сканирует указанную подсеть и возвращает результаты.
|
||||
|
||||
Выполняет ARP-сканирование, собирает информацию о устройствах и сохраняет данные.
|
||||
|
||||
* **Parameters:**
|
||||
**subnet** (*Optional* *[**str* *]*) – Подсеть в формате CIDR (например, “10.1.1.0/24”).
|
||||
Если None или пустая строка, определяется автоматически.
|
||||
* **Returns:**
|
||||
Объект с результатами сканирования, содержащий список
|
||||
: устройств или сообщение об ошибке.
|
||||
* **Return type:**
|
||||
SubnetScanResult
|
||||
* **Raises:**
|
||||
**Exception** – Если произошла ошибка сканирования.
|
||||
|
||||
#### update_note(mac: str, note: str, translations: Translations) → Tuple[bool, Tuple[str, Dict] | None]
|
||||
|
||||
Обновляет заметку для устройства по MAC-адресу.
|
||||
|
||||
Изменяет существующую заметку, если она есть.
|
||||
|
||||
* **Parameters:**
|
||||
* **mac** (*str*) – MAC-адрес устройства.
|
||||
* **note** (*str*) – Новый текст заметки.
|
||||
* **translations** (*Translations*) – Объект переводов для текущего языка.
|
||||
* **Returns:**
|
||||
Кортеж (успех, результат),
|
||||
: где результат содержит код ошибки/успеха и данные.
|
||||
* **Return type:**
|
||||
Tuple[bool, Optional[Tuple[str, Dict]]]
|
||||
|
||||
### services.subnet_service.get_subnet_service(translations: Translations = Depends(translations_dependency))
|
||||
|
||||
Фабричная функция для создания экземпляра SubnetService.
|
||||
|
||||
Использует зависимости FastAPI для получения объекта переводов и возвращает
|
||||
экземпляр SubnetService с текущей локализацией.
|
||||
|
||||
* **Parameters:**
|
||||
**translations** (*Translations*) – Объект переводов для текущего языка.
|
||||
* **Returns:**
|
||||
Экземпляр сервиса для работы с подсетями.
|
||||
* **Return type:**
|
||||
SubnetService
|
||||
Loading…
Add table
Add a link
Reference in a new issue