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.

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

get_vendor(mac: str) → str[source]¶

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

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

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

scan_nbtscan(subnet: str) → None[source]¶

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

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

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

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

Bases: object

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

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

JSON-структура вида {

“devices”: [Device, …]

}

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

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

get_subnet_file(subnet: str) → Path[source]¶

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

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

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

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

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

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

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

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

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

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

Args:: 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).

Args:: subnet (str): Подсеть в формате CIDR (например, “10.1.1.0/24”).
Returns:: List[Tuple[str, str]]: Список кортежей (IP-адрес, MAC-адрес) обнаруженных устройств.
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-адресе.

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

Args:: ip (str): IP-адрес устройства для сканирования.
Returns:: 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-адресу.

Привязывает заметку к устройству, если оно существует.

Args:

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

Returns:

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

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

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

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

Args:

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

Returns:

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

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

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

Выполняет ARP-сканирование, собирает информацию о устройствах и сохраняет данные.

Args:

subnet (Optional[str]): Подсеть в формате CIDR (например, “10.1.1.0/24”).: Если None или пустая строка, определяется автоматически.

Returns:

SubnetScanResult: Объект с результатами сканирования, содержащий список: устройств или сообщение об ошибке.

Raises:

Exception: Если произошла ошибка сканирования.

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

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

Изменяет существующую заметку, если она есть.

Args:

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

Returns:

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

services.subnet_service.get_subnet_service(translations: Translations = Depends(translations_dependency))[source]¶

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

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

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