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

The network discovery backend uses Diode Go SDK to ingest discover IP Address entities with Global VRF and allows defining Description, Comments and Tags for them.

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

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

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

Current supported defaults:

The scope defines a list of targets to be scanned.

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

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)

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.

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.

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

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

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