Subnet Service¶

class services.subnet_service.DeviceInfoCollector(translations: Translations)[source]

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[source]

Получает хостнейм для указанного IP-адреса.

Пробует сначала DNS, затем NetBIOS.

Parameters:: ip (str) – IP-адрес устройства.
Returns:: Хостнейм или None, если не удалось определить.
Return type:: Optional[str]

get_vendor(mac: str) → str[source]

Получает вендора устройства по MAC-адресу.

Использует кэширование для повышения производительности.

Parameters:: mac (str) – MAC-адрес устройства.
Returns:: Название вендора или “Неизвестный” в случае ошибки.
Return type:: str

scan_nbtscan(subnet: str) → None[source]

Сканирует подсеть с помощью nbtscan для получения хостнеймов.

Сохраняет результаты в кэш и логирует процесс.

Parameters:: subnet (str) – Подсеть в формате CIDR.

class services.subnet_service.DeviceStorage(base_path: str = 'storage/subnets', translations: Translations = None)[source]

Bases: object

Класс для хранения и управления данными об устройствах.

Формат файла подсети:

{
  "devices": [Device, ...]
}

Политика очистки:

Метод _clean_old_devices удаляет оффлайн-устройства, не наблюдавшиеся более 7 дней, чтобы поддерживать актуальность списка.

get_subnet_file(subnet: str) → Path[source]

Возвращает путь к файлу для конкретной подсети.

Заменяет символы ‘/’ на ‘_’ для корректного имени файла.

Parameters:: subnet (str) – Подсеть в формате CIDR.
Returns:: Путь к файлу.
Return type:: Path

load_devices(subnet: str) → Dict[str, Device][source]

Загружает устройства для указанной подсети.

Читает данные из JSON-файла и фильтрует устаревшие устройства.

Parameters:: subnet (str) – Подсеть в формате CIDR.
Returns:: Словарь устройств с MAC как ключом.
Return type:: Dict[str, Device]

save_devices(subnet: str, devices: List[Device]) → None[source]

Сохраняет устройства для указанной подсети.

Записывает данные в JSON-файл.

Parameters:

subnet (str) – Подсеть в формате CIDR.
devices (List[Device]) – Список устройств для сохранения.

Raises:

Exception – Если произошла ошибка при сохранении.

class services.subnet_service.NetworkScanner(interface: str, translations: Translations)[source]

Bases: object

Класс для сканирования подсети с использованием ARP-запросов.

Назначение:

Обнаруживает активные устройства в локальной сети, отправляя широковещательные ARP-запросы по указанной подсети и собирая ответы (IP, MAC).

Детали реализации:

Использует scapy (Ether + ARP) для генерации пакетов и srp для отправки/получения на канальном уровне от имени заданного интерфейса.
Таймаут ожидания ответа короткий (2 секунды), ориентирован на интерактивные сценарии UI.

Ограничения и замечания:

Требуются права для отправки низкоуровневых пакетов (capabilities/root).
В сетях с фильтрацией широковещания количество обнаруженных устройств может быть ограничено.

scan(subnet: str) → List[Tuple[str, str]][source]

Сканирует подсеть с использованием 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)[source]

Bases: object

Класс для сканирования открытых портов на устройствах.

Назначение:

Плейсхолдер для будущего функционала активного сканирования TCP/UDP-портов у обнаруженных узлов. В текущей версии возвращает пустой список.

План развития:

Добавить неблокирующее сканирование наиболее распространённых портов (22, 80, 443 и т.д.) с ограничением по времени.
Настраиваемые профили глубины и скорости сканирования.

scan(ip: str) → List[str][source]

Сканирует открытые порты на указанном IP-адресе.

Пока возвращает пустой список, так как функциональность не реализована.

Parameters:: ip (str) – IP-адрес устройства для сканирования.
Returns:: Список открытых портов (пока пустой).
Return type:: List[str]

class services.subnet_service.SubnetService(translations: Translations)[source]

Bases: object

Сервис для сканирования подсетей и управления устройствами.

Роль сервиса:

Объединяет сетевое сканирование (ARP), сбор дополнительной информации (вендор, хостнейм), слияние с кэшем предыдущих результатов и персистентное хранение данных по подсетям. Предоставляет вспомогательные операции для локального узла и работы с заметками устройств.

Поток выполнения скана (scan_subnet):

Определение подсети (вручную или авто по интерфейсу).
Загрузка ранее сохранённых устройств подсети.
Добавление локального устройства (если принадлежит подсети).
ARP-сканирование и параллельная обработка узлов (обогащение данных).
Маркировка оффлайн-узлов из кэша, не встреченных в текущем скане.
Сортировка по IP и сохранение объединённого списка в JSON.

add_note(mac: str, note: str, translations: Translations) → Tuple[bool, Tuple[str, Dict] | None][source]

Добавляет заметку для устройства по 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][source]

Удаляет заметку для устройства по MAC-адресу.

Удаляет привязанную заметку, если она существует.

Parameters:

mac (str) – MAC-адрес устройства.
translations (Translations) – Объект переводов для текущего языка.

Returns:

Кортеж (успех, результат),: где результат содержит код ошибки/успеха и данные.

Return type:

Tuple[bool, Optional[Tuple[str, Dict]]]

scan_subnet(subnet: str | None = None) → SubnetScanResult[source]

Сканирует указанную подсеть и возвращает результаты.

Выполняет 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][source]

Обновляет заметку для устройства по 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))[source]

Фабричная функция для создания экземпляра SubnetService.

Использует зависимости FastAPI для получения объекта переводов и возвращает экземпляр SubnetService с текущей локализацией.

Parameters:: translations (Translations) – Объект переводов для текущего языка.
Returns:: Экземпляр сервиса для работы с подсетями.
Return type:: SubnetService