gonets/SRV/docs/_build/markdown/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`

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

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

```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