Skip to content

Discovery

Auto-discovery scans the customer network, identifies devices via SNMP sysOID/sysDescr, suggests profiles.

Prerequisites

  • At least one collector in the customer network. See Collector.
  • nmap on the collector — auto-installed by the installer
  • SNMP community or SNMPv3 credentials for target devices

Workflow

flowchart LR
    UI[Discovery UI] -->|Start scan| API
    API --> Q[(Queue: collector_config)]
    C[Collector] -->|fetch scans| API
    C --> NMAP[nmap -sT/-sP]
    NMAP --> SNMP[SNMP sysOID/sysDescr]
    SNMP --> R[Result: IP, MAC, profile suggestion]
    R --> API
    API --> UI
    UI -->|Bulk add| API
    API --> H[Hosts created]

Start a scan

Discovery → New scan:

Field Example
Name Acme HQ Subnet
Collector acme-collector-01
CIDR 192.168.10.0/24
SNMP community public
Timeout per IP 5 s

The collector polls config every ~60 s. As soon as the scan job is registered, it starts. Progress visible at /discovery.

Results

Per IP found:

Field Meaning
IP found address
MAC + vendor from ARP / nmap vendor DB
Hostname from reverse DNS or SNMP sysName
sysOID for profile match
sysDescr plaintext description
Suggested profile best match from profiles.sysoid_patterns
Existing host? when IP is already assigned

Auto-matching

Profiles have patterns:

sysoid_patterns:
  - "^.1.3.6.1.4.1.8072.3.2.10"     # Net-SNMP / Linux
sysdescr_patterns:
  - "^Linux"

On scan result, the backend matches sysOID against patterns; on hit, the profile is suggested. Multiple matches → more specific wins (longer OID prefix).

Add as host

Per result:

  1. Tick checkbox
  2. Confirm or change profile
  3. Optional: tenant, tags
  4. Create host

Bulk select: Add multiple as hosts opens a batch dialog with shared tenant + tags.

Existing hosts are shown as „already created" and not selectable — prevents duplicates.

Discovery lifecycle

stateDiagram-v2
    [*] --> Pending: scan created
    Pending --> Running: collector picks up
    Running --> Done: scan complete
    Running --> Failed: error (timeout, no nmap)
    Done --> [*]: results in /results

discovery_scans and discovery_results are in migration 035. Auto-cleanup deletes results older than 30 days.

Tips

  • Subnet size: /24 is fine, /16 takes hours via nmap — split it
  • SNMP timeout at 3–5 s, otherwise scan hangs on unreachable devices
  • Re-scan regularly — new devices show up immediately
  • Discovery via cron: POST /api/v1/discovery/network-scan is scriptable

Discovery for agent-capable hosts

Discovery detects the existence of a Linux/Windows server (ICMP, SSH banner, SNMP if active), but can't install an agent. Workflow: create host → generate agent token → roll out token on the machine.

Next