Сканирование портов (discovery)

Сканирование портов (port discovery) отвечает на вопрос «какие TCP-порты вообще открыты на этом хосте?». Notifly перебирает указанный диапазон портов, параллельно дёргает каждый и собирает список открытых. В отличие от порт-монитора, который непрерывно следит за известным набором портов, скан — это разовая (или периодическая) инвентаризация: вы ещё не знаете, что слушает на хосте, и хотите это выяснить.

Типичный путь: запустили скан → посмотрели найденные порты → одним запросом превратили результат в непрерывный порт-монитор, который будет алёртить, если какой-то из этих портов вдруг закроется.

Как это работает

создаёте задачу скана  →  status=pending
   └─▶ Cloud Function port-monitor берёт задачу
       └─▶ батчами продвигает cursor по диапазону [rangeFrom..rangeTo]
           параллельный TCP-dial с per-port таймаутом timeoutSec
           открытые порты накапливаются в foundPorts (CSV) live
       └─▶ дошли до rangeTo  →  status=completed, push с отчётом

• Скан выполняется serverless-функцией Notifly из Yandex Cloud, поэтому хост должен быть доступен из публичного интернета (или из приватной сети YC).
• cursor показывает прогресс — последний просканированный порт; по нему в админке видно, на сколько процентов диапазон уже пройден.
• foundPorts (CSV открытых портов) накапливается на лету — частичный результат виден ещё до завершения скана.
• При повторном запуске прежний результат сохраняется в prevFoundPorts, что позволяет увидеть diff (появившиеся/исчезнувшие порты).
• По завершении приходит обычное push-уведомление Notifly с отчётом — через тот канал (appid), который вы указали при создании.

Профили и диапазон

Диапазон портов можно задать профилем (profile) — пресетом — либо вручную через rangeFrom/rangeTo. Если профиль не указан, он выводится автоматически: полный диапазон 1–65535 → full, иначе → quick.

profile	Что сканирует	Портов
quick	nmap top-100 наиболее частых TCP-портов	100
standard	порты 1–1024 + популярные порты выше 1024	~1080
full	весь диапазон 1–65535	65535
custom	произвольный rangeFrom–rangeTo (по умолчанию 1–65535)	задаёте сами

Для custom диапазон берётся из ваших rangeFrom/rangeTo; для пресетных профилей сервер сам подставит нужные порты, и переданный диапазон будет переопределён.

Параметры и лимиты значений

• name — название задачи, 1–200 символов (обязательно).
• appid — канал/приложение, через которое придёт отчёт (обязательно).
• host — имя хоста или IP (обязательно), без / и пробелов.
• rangeFrom / rangeTo — границы диапазона, каждая в [1, 65535], rangeFrom ≤ rangeTo. По умолчанию 1 и 65535.
• timeoutSec — per-port таймаут TCP-dial, по умолчанию 2, максимум 10.
• repeatIntervalSec — 0 = одноразовый скан; > 0 = повторять каждые N секунд, минимум 3600 (1 час).
• alertTitle / alertMessage / alertMessageMarkdown / alertPriority — оформление push-отчёта; alertPriority в [0, 10].

Полный скан: cooldown 24 часа

Для профиля full (весь диапазон 1–65535) действует cooldown: повторный полный скан того же хоста раньше чем через 24 часа вернёт 429. Для частых проверок выбирайте quick/standard или задайте конкретный custom-диапазон.

Один активный скан на хост

Нельзя запустить параллельно два скана одного хоста: попытка вернёт 409 — сначала дождитесь завершения или отмените текущий. Аналогично нельзя создать монитор из скана, если для этого хоста уже есть активный порт-монитор.

Дневная квота

Число скан-задач в сутки ограничено вашим тарифом (portScansPerDay). Когда суточный счётчик исчерпан, создание нового скана возвращает 429:

План	Сканов в день
Free	10
Pro	100
Business	1000

Подробнее о квотах и тарифах — Квоты и тарифы.

Приватные хосты

Если хост приватный (адрес из приватной сети), Notifly автоматически создаёт для него подтверждение владения — отдельная верификация не требуется.

Создание скана

Через админку

1. Откройте app.notifly.ru → Мониторы → Сканирование портов.
2. Нажмите «Просканировать хост», заполните название, хост, профиль (или ручной диапазон), таймаут и канал для отчёта.
3. Запустите — прогресс (cursor) и найденные порты (foundPorts) обновляются в реальном времени.

Через REST API

# Быстрый скан (top-100 портов), одноразовый
curl -X POST "$NOTIFLY_URL/port-scan" \
     -H "Content-Type: application/json" \
     -H "X-Notifly-Key: <client-token>" \
     -d '{
       "appid": 12345,
       "name": "Инвентаризация prod-хоста",
       "host": "prod.example.com",
       "profile": "quick",
       "timeoutSec": 2,
       "alertTitle": "Скан завершён",
       "alertMessage": "Найдены открытые порты на prod.example.com",
       "alertPriority": 5
     }'

# Произвольный диапазон, повторять раз в сутки
curl -X POST "$NOTIFLY_URL/port-scan" \
     -H "Content-Type: application/json" \
     -H "X-Notifly-Key: <client-token>" \
     -d '{
       "appid": 12345,
       "name": "Веб-порты db-хоста",
       "host": "db.internal",
       "profile": "custom",
       "rangeFrom": 8000,
       "rangeTo": 9000,
       "timeoutSec": 3,
       "repeatIntervalSec": 86400,
       "alertMessage": "Диапазон 8000–9000 на db.internal просканирован"
     }'

Ответ — созданный объект скана со status: "pending", cursor, foundPorts (пока пусто) и присвоенным id.

Просмотр результата

# Список всех скан-задач
curl "$NOTIFLY_URL/port-scan" -H "X-Notifly-Key: <client-token>"

# Один скан — прогресс и найденные порты
curl "$NOTIFLY_URL/port-scan/777" -H "X-Notifly-Key: <client-token>"

В ответе смотрите status (pending → running → completed/failed/cancelled), cursor (докуда дошли), foundPorts (CSV открытых портов) и prevFoundPorts (результат прошлого запуска для diff). При failed причина — в lastError.

Отмена и перезапуск

# Отменить ещё не завершённый скан (pending/running)
curl -X POST "$NOTIFLY_URL/port-scan/777/cancel" \
     -H "X-Notifly-Key: <client-token>"

# Перезапустить завершённый/отменённый/упавший скан заново
curl -X POST "$NOTIFLY_URL/port-scan/777/restart" \
     -H "X-Notifly-Key: <client-token>"

• Отмена доступна только для активного скана; уже completed/cancelled скан отменить нельзя (400).
• Перезапуск доступен для завершённого скана: предыдущий foundPorts уезжает в prevFoundPorts, cursor сбрасывается, скан стартует заново. Если скан ещё активен (running/pending) — сначала отмените его (400); если по этому хосту уже идёт другой скан — 409.
• Редактировать настройки скана (PATCH) можно, только пока он не в статусе running.

Превратить скан в монитор

Главная фишка discovery: завершённый скан можно одним запросом превратить в непрерывный порт-монитор. Найденные порты (foundPorts) становятся expectedPorts нового монитора в режиме closed — он будет алёртить, если любой из обнаруженных портов закроется.

curl -X POST "$NOTIFLY_URL/port-scan/777/to-monitor" \
     -H "Content-Type: application/json" \
     -H "X-Notifly-Key: <client-token>" \
     -d '{
       "name": "Порты prod.example.com",
       "intervalSec": 300,
       "timeoutSec": 5,
       "alertTitle": "Port alert: prod.example.com",
       "alertMessage": "Закрылся ожидаемый порт на prod.example.com",
       "alertPriority": 7
     }'

Тело запроса необязательно — у каждого поля есть значение по умолчанию: name = Monitor <host>, intervalSec = 300, timeoutSec = 5, alertTitle = Port alert: <host>, alertMessage = Port closed on <host>. Монитор наследует appid и host исходного скана.

Ограничения:

• Скан должен быть completed (иначе 400).
• В скане должны быть найдены открытые порты — пустой foundPorts даст 400.
• Для хоста не должно быть уже активного порт-монитора — иначе 409.

REST endpoints

Все endpoints требуют клиентский токен (или MCP-токен с правом write); Basic Auth тоже принимается.

Метод	Путь	Описание
GET	/port-scan	Список скан-задач пользователя
GET	/port-scan/:id	Один скан: статус, прогресс (cursor), foundPorts
POST	/port-scan	Создать скан (429 при превышении дневной квоты или 24ч-cooldown полного скана; 409 если для хоста уже идёт скан)
PATCH	/port-scan/:id	Изменить настройки (нельзя для running-скана)
DELETE	/port-scan/:id	Удалить скан-задачу
POST	/port-scan/:id/cancel	Отменить активный (pending/running) скан
POST	/port-scan/:id/restart	Перезапустить завершённый скан заново
POST	/port-scan/:id/to-monitor	Создать порт-монитор из найденных портов