Network Discovery

Overview

Network Discovery automates the process of finding and cataloging devices on your network. Instead of manually adding each switch, router, and firewall, NetStacks can discover devices using industry-standard protocols and add them to your inventory with accurate metadata including hostname, IP address, platform, software version, and neighbor relationships.

Discovery Methods

• SNMP LLDP/CDP -- primary discovery method using Link Layer Discovery Protocol and Cisco Discovery Protocol neighbor tables via SNMP queries
• CLI neighbor tables -- fallback method that connects to devices via SSH and parses show lldp neighbors and show cdp neighbors output
• Nmap fingerprinting -- supplemental discovery using network scanning to identify devices by open ports and service fingerprints
• Netdisco/LibreNMS integration -- import device inventory from existing network management platforms for enrichment

How It Works

Discovery Method Hierarchy

NetStacks uses a tiered approach to discovery, starting with the most reliable protocol and falling back to alternatives:

1. SNMP LLDP/CDP (primary) -- queries LLDP and CDP MIB tables on seed devices to discover directly connected neighbors. Returns structured data including system name, management IP, platform description, and port information.
2. CLI neighbor tables (fallback) -- if SNMP is unavailable, NetStacks connects via SSH and parses the output of show lldp neighbors detail and show cdp neighbors detail using platform-specific parsers.
3. Nmap fingerprinting (supplemental) -- scans IP ranges for responsive hosts, identifies services, and fingerprints operating systems. Useful for discovering devices that do not support LLDP or CDP.

Discovery Workflow

1. Seed devices -- you provide one or more seed devices (known devices to start discovery from) or IP ranges for scanning
2. Neighbor crawl -- NetStacks queries each seed device for its neighbors, then queries those neighbors for their neighbors, iteratively building the topology
3. Deduplication -- discovered devices are deduplicated by management IP and hostname to avoid duplicates
4. Staging -- discovered devices appear in the Discovery Results queue for review and approval before being imported into the managed inventory

Integration Enrichment

When Netdisco or LibreNMS integration is configured, NetStacks can cross-reference discovered devices with data from these platforms, enriching the device record with additional details like location, contact information, and interface inventory.

Step-by-Step Guide

Workflow 1: Configure SNMP Credentials and Run Discovery

1. Navigate to Credentials → SNMP Communities and add your SNMP v2c community strings or v3 credentials
2. Go to Device Management → Discovery
3. Click New Discovery Scan
4. Enter seed devices (hostnames or IPs) or an IP range (e.g., 10.0.0.0/24)
5. Select the SNMP credential to use and set the hop limit (how many neighbor hops to crawl)
6. Click Start Scan -- progress is shown in real time

Workflow 2: Review and Import Discovered Devices

1. After the scan completes, navigate to Discovery Results
2. Review each discovered device -- hostname, IP, platform, and how it was discovered
3. Select devices to import and click Add to Inventory
4. Assign credentials and device groups during import

Workflow 3: Schedule Automatic Rediscovery

1. In Discovery Settings, enable scheduled rediscovery
2. Set the scan interval (e.g., daily, weekly) and the seed devices or ranges
3. Configure notifications for newly discovered devices
4. New devices appear in the Discovery Results queue for review

Code Examples

SNMP v3 Credential Configuration

{
  "name": "snmpv3-network-ops",
  "version": "v3",
  "security_level": "authPriv",
  "username": "netstacks-discovery",
  "auth_protocol": "SHA-256",
  "auth_password": "********",
  "priv_protocol": "AES-256",
  "priv_password": "********"
}

Discovery Scan Configuration

# Start a discovery scan via API
POST /api/v1/discovery/scans
Content-Type: application/json
{
  "name": "DC1 Core Discovery",
  "seeds": [
    { "host": "core-rtr-01.dc1", "type": "hostname" },
    { "host": "core-rtr-02.dc1", "type": "hostname" }
  ],
  "methods": ["snmp-lldp", "snmp-cdp", "cli-fallback"],
  "credential_id": "cred_snmpv3_001",
  "ssh_credential_id": "cred_ssh_001",
  "hop_limit": 3,
  "timeout_seconds": 30,
  "options": {
    "exclude_ranges": ["10.0.99.0/24"],
    "include_only_ranges": ["10.0.0.0/16"]
  }
}

Nmap Scan Profile

# Nmap discovery profile for network devices
{
  "name": "Network Device Fingerprint",
  "scan_type": "nmap",
  "targets": "10.0.0.0/24",
  "options": {
    "port_scan": "22,23,80,443,161",
    "os_detection": true,
    "service_version": true,
    "timing": "T3"
  }
}

Discovery Results Example

{
  "scan_id": "scan_abc123",
  "status": "completed",
  "duration_seconds": 142,
  "devices_found": 24,
  "results": [
    {
      "hostname": "dist-sw-01.dc1",
      "management_ip": "10.0.1.10",
      "platform": "Cisco NX-OS",
      "version": "9.3(8)",
      "discovered_via": "snmp-cdp",
      "discovered_from": "core-rtr-01.dc1",
      "interfaces_found": 48,
      "neighbors": ["access-sw-01", "access-sw-02", "core-rtr-01"]
    },
    {
      "hostname": "access-sw-01.dc1",
      "management_ip": "10.0.2.10",
      "platform": "Cisco IOS",
      "version": "15.2(7)E3",
      "discovered_via": "snmp-lldp",
      "discovered_from": "dist-sw-01.dc1",
      "interfaces_found": 24,
      "neighbors": ["dist-sw-01", "dist-sw-02"]
    }
  ]
}

Netdisco Integration

# Configure Netdisco integration
PUT /api/v1/integrations/netdisco
{
  "enabled": true,
  "base_url": "https://netdisco.example.com",
  "api_key": "nd_api_key_here",
  "sync_interval_minutes": 60,
  "import_options": {
    "include_locations": true,
    "include_contacts": true,
    "include_interfaces": true
  }
}

Q&A

Q: What protocols does network discovery support?

A: NetStacks supports SNMP-based discovery using LLDP and CDP MIB tables (both SNMPv2c and SNMPv3), CLI-based discovery by parsing show lldp neighbors and show cdp neighbors output over SSH, and Nmap-based network scanning for host detection and OS fingerprinting.

Q: How do I discover devices that do not support SNMP?

A: Use the CLI fallback method, which connects to the device via SSH and parses neighbor table output. For devices that support neither SNMP nor SSH neighbor discovery, use Nmap scanning to detect them by IP range and service fingerprint. You can also import devices from Netdisco or LibreNMS.

Q: Can I schedule automatic rediscovery?

A: Yes. In Discovery Settings, configure a schedule (daily, weekly, or custom cron expression) with seed devices and IP ranges. Rediscovery runs automatically and new devices appear in the Discovery Results queue for review. Notifications alert you when new devices are found.

Q: How does NetStacks integrate with Netdisco and LibreNMS?

A: NetStacks can import device inventory from Netdisco and LibreNMS via their APIs. Configure the integration with the platform URL and API key. Imported data enriches device records with location, contact, and interface information. Sync runs on a configurable interval.

Q: What information is captured during discovery?

A: Discovery captures the device hostname, management IP address, platform type (e.g., Cisco IOS, NX-OS, Juniper JunOS), software version, interface count, and neighbor relationships. This data is used to populate the device record when imported into the inventory.

Q: How do I filter or limit the discovery scope?

A: Set a hop limit to control how many neighbor hops the crawler traverses from seed devices. Use include and exclude IP ranges to restrict scanning to specific subnets. You can also filter by device platform or hostname pattern in the Discovery Results view.

Troubleshooting

SNMP Discovery Not Finding Devices

• Verify SNMP credentials are correct -- test with snmpwalk -v3 -u username -l authPriv target_ip
• Check that SNMP traffic (UDP 161) is allowed through firewalls between NetStacks and target devices
• Ensure LLDP or CDP is enabled on the devices -- some platforms disable these by default
• Increase the SNMP timeout value if devices are responding slowly

Incomplete Discovery Results

• Increase the hop limit to crawl further from seed devices
• Add more seed devices in different network segments to ensure coverage
• Check that all devices have LLDP/CDP enabled -- the discovery chain breaks at devices without neighbor protocol support

Duplicate Devices in Results

• Devices with multiple management IPs may appear as duplicates. Merge them in the Discovery Results view before importing
• Check for hostname mismatches caused by DNS vs. SNMP sysName differences

Credential Issues During Discovery

• SNMP credentials are tested against each discovered device. Devices with different credentials will fail SNMP queries but may still be discovered via CLI fallback
• Configure multiple SNMP credential sets and NetStacks will try each one in order until one succeeds

Related Features

• Adding Devices -- manually add devices to complement discovery results
• Device Types -- understand how discovered devices are categorized by platform
• NetBox Integration -- sync discovered devices with NetBox for source-of-truth management
• SNMP Communities -- configure the SNMP credentials used for discovery
• Network Topology -- visualize the network graph built from discovery data