Network Discovery

The network discovery backend leverages NMAP to scan networks and discover IP information.

Diode Entities

The network discovery backend uses Diode Go SDK to ingest the following entities:

• IP Address

IP addresses support VRF, Tenant, Role, Description, Comments and Tags via defaults.

The name a reverse lookup returns for an address becomes the IP's dns_name, lowercased. NetBox accepts only letters, digits, hyphens and underscores in a label. nmap, which does the lookup, prints an asterisk in place of any character it will not pass, a space inside a DNS label for instance, and lets a few others through that NetBox rejects; every such character becomes a hyphen, so a name nmap printed as abc1234-vendor*model*unit.example.net arrives as abc1234-vendor-model-unit.example.net. A name with no form NetBox accepts, one with an empty label, longer than 255 characters or left with no letter or digit, is left off; the address is still sent, and a dns_name NetBox already holds for it stays as it is. In either case the name as nmap gave it is kept under hostnames in the IP's comments, unless the policy sets defaults.comments, which the backend does not add to. A name that needed no change is not recorded, so this changes nothing in the comments of an IP whose name was already acceptable. Each run logs how many names it replaced or left off. A name that was already accepted with an asterisk, which NetBox allows as a leading wildcard label, changes on the next run, since nmap's asterisk never marks a wildcard.

Configuration

The network_discovery backend does not require any special configuration, though overriding host and port values can be specified. The backend will use the diode settings specified in the common subsection to forward discovery results.

orb:
  backends:
    common:
      diode:
        target: grpc://192.168.0.100:8080/diode
        client_id: ${DIODE_CLIENT_ID}
        client_secret: ${DIODE_CLIENT_SECRET}
        agent_name: agent01
    network_discovery:
      host: 192.168.5.11 # default 0.0.0.0
      port: 8863 # default 8073
      log_level: ERROR # default INFO
      log_format: JSON # default TEXT

Policy

Network discovery policies are broken down into two subsections: config and scope.

Config

Config defines data for the whole scope and is optional overall.

Defaults

Current supported defaults:

Scope

The scope defines a list of targets to be scanned.

Sample

A sample policy including all parameters supported by the network discovery backend.

orb:
  ...
  policies:
    network_discovery:
      discovery_1:
        config:
          schedule: "* * * * *"
          timeout: 5
          defaults:
            description: IP discovered by network discovery
            tags: [net-discovery, orb-agent]
        scope:
          targets: 
            - 192.168.7.32
            - 192.168.7.30-40 # IP range
            - 192.168.7.0/24 # IP subnet
            - google.com # dns lookup
          fast_mode: True
          max_retries: 0

⚠️ Warning

Be AWARE that executing a policy with only targets defined is equivalent to running nmap <targets>, which in turn is the same as executing nmap -sS -p1-1000 --open -T3 <target>:

• -sS → SYN scan (stealth scan, requires root privileges)
• -p1-1000 → Scans the top 1000 most common ports
• --open → Only shows open ports
• -T3 → Uses the default timing template (T3 is the standard speed)

Rootless Podman Deployment

Network discovery can be run with podman in two modes: privileged (with sudo) or rootless (without sudo). The choice depends on your security requirements and the scan types you need.

Limitations

NMAP's default behavior uses privileged network operations that require raw socket access:

• SYN scans (-sS) require CAP_NET_RAW capability
• ICMP host discovery (ping scans) requires raw socket creation
• Rootless containers cannot obtain true privileged capabilities, even with --privileged flag

When running podman without root privileges, these operations will fail with "Operation not permitted" errors.

Option 1: Privileged Mode (with sudo)

For full NMAP functionality including SYN scans, ICMP discovery, and OS detection, run podman with sudo:

sudo podman run -d --privileged --net=host \
  --name orb \
  -v /home/user/orb:/opt/orb \
  -e DIODE_CLIENT_ID \
  -e DIODE_CLIENT_SECRET \
  netboxlabs/orb-agent:latest run -c /opt/orb/agent.yaml

Advantages:

• All NMAP scan types available
• ICMP host discovery works
• OS detection supported
• No configuration restrictions

Disadvantages:

• Requires sudo/root access
• Higher security risk

Option 2: Rootless Mode (without sudo)

For rootless operation, use TCP connect scans which don't require raw sockets:

podman run -d --privileged --net=host \
  --name orb \
  -v /home/user/orb:/opt/orb \
  -e DIODE_CLIENT_ID \
  -e DIODE_CLIENT_SECRET \
  netboxlabs/orb-agent:latest run -c /opt/orb/agent.yaml

Required Configuration:

Your policy must include these settings:

orb:
  policies:
    network_discovery:
      rootless_policy:
        scope:
          targets: [192.168.1.0/24]
          scan_types: [connect]  # TCP connect scan only
          skip_host: true         # Skip ICMP host discovery
          # fast_mode must be false (default) or omitted
          ports: [22, 80, 443, 8080]  # Recommended: specify ports

Critical Requirements:

1. scan_types: [connect] - Uses TCP connect scan (-sT) which doesn't require raw sockets
2. skip_host: true - Skips ICMP host discovery (-Pn flag), assumes all hosts are up
3. fast_mode must be false or omitted - Fast mode triggers operations requiring privileges

Advantages:

• No sudo/root required
• Lower security risk
• Suitable for restricted environments

Disadvantages:

• TCP connect scan only (slower, more detectable)
• No ICMP host discovery
• No OS detection
• Must manually specify or skip certain scan options

Troubleshooting

Error: "Couldn't open a raw socket. Error: Operation not permitted"

• Cause: NMAP trying to use privileged scan types in rootless mode
• Solution: Ensure scan_types: [connect] and skip_host: true are set

Error: "dnet: Failed to open device eth0"

• Cause: NMAP attempting ICMP or privileged operations
• Solution: Add skip_host: true to skip host discovery

Error: "exit status 1" in logs

• Cause: NMAP command failed, often due to privilege issues
• Solution: Check that fast_mode is not set to true, verify rootless configuration

Scan completes but finds no hosts:

• Cause: skip_host: false (default) attempts ICMP discovery which fails silently
• Solution: Set skip_host: true to assume all targets are up