Andrey Lutsenko
e9452dcc0a
Probe configured ports for alive hosts, persist port states, and expose scan port results via REST. Made-with: Cursor
176 lines
4.2 KiB
Markdown
176 lines
4.2 KiB
Markdown
# 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-портов по скану.
|
||
- Валидация CIDR и exclude IP.
|
||
- Два backend-хранилища: in-memory и PostgreSQL.
|
||
- После создания scan запускается фоновый discovery с обновлением статуса и прогресса.
|
||
|
||
## Требования
|
||
|
||
- Go 1.22+
|
||
|
||
Проверка версии:
|
||
|
||
```bash
|
||
go version
|
||
```
|
||
|
||
## Запуск локально
|
||
|
||
1. Перейдите в проект:
|
||
|
||
```bash
|
||
cd nettopo-go
|
||
```
|
||
|
||
2. Скопируйте переменные окружения:
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
3. Запустите API:
|
||
|
||
```bash
|
||
HTTP_ADDR=:8080 go run ./cmd/server
|
||
```
|
||
|
||
По умолчанию используется `STORE_BACKEND=memory`.
|
||
|
||
## PostgreSQL без Docker
|
||
|
||
### Вариант A: macOS (Homebrew)
|
||
|
||
```bash
|
||
brew install postgresql@16
|
||
brew services start postgresql@16
|
||
createdb nettopo
|
||
createuser nettopo
|
||
```
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
curl -s http://localhost:8080/health
|
||
```
|
||
|
||
Создать scan:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
curl -s http://localhost:8080/api/scans/<scan_id>
|
||
```
|
||
|
||
Получить список scan jobs:
|
||
|
||
```bash
|
||
curl -s http://localhost:8080/api/scans?limit=20
|
||
```
|
||
|
||
В ответе у scan есть:
|
||
|
||
- `status`: `queued`, `running`, `done`, `failed`
|
||
- `progress`: 0..100
|
||
- `stats.hosts_total`, `stats.hosts_up`
|
||
|
||
Получить результаты по хостам:
|
||
|
||
```bash
|
||
curl -s http://localhost:8080/api/scans/<scan_id>/hosts?limit=200
|
||
```
|
||
|
||
Получить результаты по портам:
|
||
|
||
```bash
|
||
curl -s http://localhost:8080/api/scans/<scan_id>/ports?limit=500
|
||
```
|
||
|
||
## Запуск как сервис на Linux (systemd)
|
||
|
||
1. Собрать бинарник:
|
||
|
||
```bash
|
||
go build -o nettopo-server ./cmd/server
|
||
```
|
||
|
||
2. Скопировать unit-файл:
|
||
|
||
```bash
|
||
sudo cp deploy/nettopo-go.service /etc/systemd/system/
|
||
sudo systemctl daemon-reload
|
||
sudo systemctl enable --now nettopo-go
|
||
```
|
||
|
||
3. Проверить статус:
|
||
|
||
```bash
|
||
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`.
|