GonetsDocs/Documentation/Tech-docs/api/services/subnet_service.md

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

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

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

{
  "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