272 lines
12 KiB
Markdown
272 lines
12 KiB
Markdown
# 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
|