nettopo-go/README.md

nettopo-go

Минимальный старт проекта сетового инвентаризатора и топологии на Go без Docker.

Что уже есть

• GET /health - проверка состояния API.
• POST /api/scans - создание задания скана.
• GET /api/scans - список сканов.
• GET /api/scans/{id} - просмотр созданного задания.
• GET /api/scans/{id}/hosts - результаты проверки хостов по скану.
• GET /api/scans/{id}/ports - результаты проверки TCP-портов по скану.
• GET /api/scans/{id}/snmp - результаты SNMP v2c (sysName, sysDescr, sysObjectID).
• GET /api/scans/{id}/lldp - LLDP соседи (если устройство отдает LLDP-MIB по SNMP).
• GET /api/scans/{id}/links - базовые связи из LLDP с попыткой сопоставления по remote_sys_name.
• Валидация CIDR и exclude IP.
• Два backend-хранилища: in-memory и PostgreSQL.
• После создания scan запускается фоновый discovery с обновлением статуса и прогресса.

Требования

• Go 1.22+

Проверка версии:

go version

Запуск локально

1. Перейдите в проект:

cd nettopo-go

2. Скопируйте переменные окружения:

cp .env.example .env

3. Запустите API:

HTTP_ADDR=:8080 go run ./cmd/server

По умолчанию используется STORE_BACKEND=memory. SNMP-проверка по умолчанию включена (SNMP_ENABLED=true, community public).

PostgreSQL без Docker

Вариант A: macOS (Homebrew)

brew install postgresql@16
brew services start postgresql@16
createdb nettopo
createuser nettopo

psql -d postgres -c "alter user nettopo with password 'nettopo';"
psql -d postgres -c "grant all privileges on database nettopo to nettopo;"

Вариант B: Ubuntu/Debian

sudo apt update
sudo apt install -y postgresql postgresql-contrib
sudo -u postgres psql -c "create user nettopo with password 'nettopo';"
sudo -u postgres psql -c "create database nettopo owner nettopo;"

Вариант C: Windows

• Установить PostgreSQL через официальный installer.
• Создать БД nettopo и пользователя nettopo (через pgAdmin или psql).

Запуск API с PostgreSQL

export STORE_BACKEND=postgres
export DB_DSN='postgres://nettopo:nettopo@localhost:5432/nettopo?sslmode=disable'
export RUN_MIGRATIONS=true
go run ./cmd/server

При первом запуске автоматически применится миграция scan_jobs.

Быстрая проверка API

Проверка health:

curl -s http://localhost:8080/health

Создать scan:

curl -s -X POST http://localhost:8080/api/scans \
  -H "Content-Type: application/json" \
  -d '{
    "name":"Office scan",
    "cidrs":["192.168.1.0/24"],
    "exclude_ips":["192.168.1.1"],
    "options":{
      "ping_timeout_ms":700,
      "ping_retries":1,
      "max_parallel_hosts":128,
      "port_scan_enabled":true,
      "ports":[22,80,443,161]
    }
  }'

Получить scan по id:

curl -s http://localhost:8080/api/scans/<scan_id>

Получить список scan jobs:

curl -s http://localhost:8080/api/scans?limit=20

В ответе у scan есть:

• status: queued, running, done, failed
• progress: 0..100
• stats.hosts_total, stats.hosts_up

Получить результаты по хостам:

curl -s http://localhost:8080/api/scans/<scan_id>/hosts?limit=200

Получить результаты по портам:

curl -s http://localhost:8080/api/scans/<scan_id>/ports?limit=500

Получить SNMP результаты:

curl -s http://localhost:8080/api/scans/<scan_id>/snmp?limit=500

Получить LLDP результаты:

curl -s http://localhost:8080/api/scans/<scan_id>/lldp?limit=1000

Получить связи:

curl -s http://localhost:8080/api/scans/<scan_id>/links?limit=1000

Запуск как сервис на Linux (systemd)

1. Собрать бинарник:

go build -o nettopo-server ./cmd/server

2. Скопировать unit-файл:

sudo cp deploy/nettopo-go.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now nettopo-go

3. Проверить статус:

systemctl status nettopo-go

Размещение за IIS на Windows

• Запускать nettopo-server.exe как Windows Service.
• На IIS настроить Reverse Proxy к http://localhost:8080.
• Требуются URL Rewrite + ARR.

Шаблон web.config лежит в deploy/web.config.example.