- name
- network-topology-discovery
- description
- >-
- license
- Apache-2.0
- metadata
- safety
- read-only
- author
- network-security-skills-suite
- version
- 1.0.0
- openclaw
- {"emoji":"🔍","safetyTier":"read-only","requires":{"bins":["ssh"],"env":[]},"tags":["topology","cdp","lldp"],"mcpDependencies":[],"egressEndpoints":[]}
Network Topology Discovery
Iterative discovery skill that builds a network topology map layer by layer. Unlike threshold-based health checks, this procedure works outward from a seed device — discovering neighbors, correlating MAC and ARP tables, analyzing routing boundaries, and consolidating a complete adjacency model across L2 and L3.
Commands are labeled [Cisco], [JunOS], or [EOS] where syntax diverges. Unlabeled statements apply to all three vendors. Detailed command syntax is in references/cli-reference.md; the full discovery methodology and data model are in references/discovery-workflow.md.
When to Use
- Building or validating a network diagram for an unfamiliar environment
- Post-acquisition network inventory where documentation is missing or stale
- Pre-change impact analysis — mapping blast radius before maintenance
- Incident response — determining the L2/L3 path between two endpoints
- Auditing discovered topology against intended design documents
- Identifying rogue or undocumented devices on the network
- Capacity planning — mapping link utilization paths between sites
- Migration planning — inventorying devices and links in a domain
Prerequisites
- SSH or console access to the seed device (read-only privilege sufficient)
- Credentials that work across devices in the discovery scope — if different
devices use different credentials, identify credential sets in advance
- CDP and/or LLDP enabled on the network (at least one protocol required)
- Knowledge of the intended discovery scope: site boundary, VRF, management
subnet, or administrative domain to avoid unbounded expansion
- A device inventory tracker (spreadsheet, CMDB, or text file) to record
discovered devices and avoid revisiting them
Procedure
Follow this procedure iteratively. Each step builds on prior data. The process expands outward from a seed device, discovering neighbors layer by layer and correlating L2 with L3 information to produce a consolidated topology.
Step 1: Seed Device Identification
Select a starting device and verify connectivity. The seed is typically a core switch, distribution switch, or router with the broadest neighbor visibility.
Confirm access and collect the device identity:
[Cisco]
show version | include hostname|uptime|Software
show cdp neighbors | count
show lldp neighbors | count[JunOS]
show version | match "Hostname|Model|Junos"
show lldp neighbors | count[EOS]
show version | include hostname|uptime|model
show lldp neighbors | countRecord: hostname, platform, software version, management IP, and neighbor count. The neighbor count sets expectations for Step 2. Add this device as the first entry in the discovery tracker with status "discovered."
Note: CDP is Cisco-proprietary and available only on Cisco and EOS devices. JunOS supports LLDP only. Use LLDP as the primary protocol for multi-vendor environments.
Step 2: L2 Neighbor Discovery
Collect all CDP and LLDP neighbors from the current device. This reveals directly connected switches, routers, phones, and access points.
[Cisco]
show cdp neighbors detail
show lldp neighbors detail[JunOS]
show lldp neighbors detail[EOS]
show lldp neighbors detail
show lldp neighbors | include SystemFor each discovered neighbor, record: remote hostname, remote platform/model, remote management IP, local interface, remote interface, and advertised capabilities (Router, Switch, Phone, AP). The capabilities field identifies device role without logging in.
Cross-reference each neighbor against the discovery tracker. New entries get status "pending" — they become the next seeds for iterative expansion. Already discovered devices are skipped.
Step 3: MAC Address Table Analysis
Collect the MAC address table to identify all connected endpoints and to distinguish trunk ports (many MACs) from access ports (few MACs).
[Cisco]
show mac address-table
show mac address-table count[JunOS]
show ethernet-switching table
show ethernet-switching table summary[EOS]
show mac address-table
show mac address-table countAnalyze port-to-MAC mappings:
- Trunk ports — multiple MACs learned, typically connecting to other
switches. These should already appear as CDP/LLDP neighbors.
- Access ports — one or a few MACs learned, typically end hosts.
- Ports with no MACs — either unused or connected to a device that has
not sent traffic. Check interface admin/oper state.
- Ports with excessive MACs (>100 on access port) — possible hub,
unmanaged switch, or misconfigured trunk.
Flag any MAC addresses on unexpected ports — this helps identify undocumented devices or cabling errors.
Step 4: ARP Table Correlation
Collect the ARP table to map IP addresses to MAC addresses, establishing the L3 identity of L2-discovered hosts.
[Cisco]
show ip arp
show ip arp vrf [name][JunOS]
show arp no-resolve
show arp interface [intf][EOS]
show ip arp
show ip arp vrf [name]For each ARP entry, record: IP address, MAC address, interface, VLAN, and entry age. Cross-reference MACs from Step 3 to assign IP addresses to previously discovered L2 endpoints.
Unresolved MACs — entries in the MAC table with no corresponding ARP entry — indicate L2-only devices (switches without management IPs on that VLAN) or devices on a different subnet reachable via a trunk. Unresolved ARPs — ARP entries with incomplete MAC — indicate reachability issues (device offline or ARP timeout).
Step 5: Routing Table Analysis
Collect routing table entries to discover L3 next-hops, remote subnets, and routing domain boundaries.
[Cisco]
show ip route summary
show ip route
show ip route vrf [name][JunOS]
show route summary
show route protocol [ospf|bgp|static]
show route table [routing-instance].inet.0[EOS]
show ip route summary
show ip route
show ip route vrf [name]Identify:
- Connected subnets — directly attached networks; these define the L3
boundaries of this device.
- Next-hop routers — IP addresses of adjacent L3 devices. Cross-reference
with ARP/MAC data to identify the physical interface and MAC of each next-hop.
- Routing protocol neighbors — OSPF/BGP/EIGRP peers reveal L3 adjacency
even when CDP/LLDP is disabled.
- Default route — points to the upstream gateway; follow it to discover
the next layer.
- VRF routes — separate routing tables indicate VRF boundaries. Repeat
discovery per VRF to map isolated routing domains.
Any next-hop IP without a corresponding ARP entry suggests an inactive or unreachable peer — flag for investigation.
Step 6: Topology Consolidation
Merge L2 and L3 discovery data into a unified topology model.
For each discovered link, confirm it from both ends where possible. A link reported by device A to device B should also appear in device B's neighbor table pointing to device A. Asymmetric entries (link visible from one end only) indicate: CDP/LLDP disabled on one end, unidirectional link, or stale neighbor entry.
Build the adjacency model:
- Deduplicate links — the same physical connection appears in both
neighbors' tables. Use the local-port/remote-port pair to match.
- Resolve L2/L3 overlap — a trunk link visible in CDP/LLDP and also
carrying multiple ARP subnets represents one physical link with multiple L3 paths.
- Classify devices — use capabilities from CDP/LLDP and routing protocol
participation to tag each device: core router, distribution switch, access switch, firewall, wireless controller, endpoint.
- Identify boundaries — devices at the edge of discovery scope (no
further neighbors, or neighbors outside the target domain) define the topology perimeter.
- Flag anomalies — undocumented devices, asymmetric links, unexpected
routing peers, and MAC addresses on wrong VLANs.
Threshold Tables
Discovery completeness and data freshness metrics. Unlike health-check thresholds, these measure how complete and current the topology data is.
Discovery Completeness:
| Metric | Complete | Partial | Incomplete |
|---|---|---|---|
| CDP/LLDP neighbors vs expected | 100% | 80–99% | <80% |
| MACs with ARP resolution | >90% | 70–90% | <70% |
| Next-hops with ARP entries | 100% | 80–99% | <80% |
| Links confirmed from both ends | >95% | 80–95% | <80% |
| Devices with routing table collected | 100% | >80% | <80% |
Data Freshness:
| Data Source | Fresh | Aging | Stale |
|---|---|---|---|
| CDP holdtime remaining | >120s | 60–120s | <60s |
| LLDP TTL remaining | >90s | 30–90s | <30s |
| ARP entry age | <300s (5min) | 300–1200s | >1200s (20min) |
| MAC entry age | Recent activity | >300s since last seen | >900s |
| Routing table age | Converged | Reconverging | Incomplete |
Decision Trees
Missing Expected Neighbor
Expected neighbor not in CDP/LLDP table
├── Is the interface admin up and oper up?
│ ├── No → Fix interface state first
│ └── Yes → Continue
├── Is CDP/LLDP enabled on local interface?
│ ├── [Cisco] show cdp interface [intf]
│ ├── [JunOS] show lldp detail | match [intf]
│ ├── [EOS] show lldp local-info interface [intf]
│ ├── Disabled → Enable CDP/LLDP on the interface
│ └── Enabled → Continue
├── Is CDP/LLDP enabled on remote device?
│ ├── Cannot verify without access → Attempt SSH to remote
│ └── Disabled on remote → Enable or use MAC/ARP as fallback
├── VLAN mismatch?
│ ├── Access port VLAN differs between ends → Fix VLAN assignment
│ └── Trunk allowed VLANs pruned → Add VLAN to trunk
└── Physical layer issue?
├── Check interface errors → See interface-health skill
└── Unidirectional link → Check fiber Tx/Rx, SFP seatingUnresolved MAC Address
MAC in table but no ARP entry
├── Is MAC on a trunk port?
│ ├── Yes → MAC is behind a downstream switch, not local
│ │ └── Discover downstream switch to find the endpoint
│ └── No → MAC is on an access port
├── Is the MAC's VLAN routed on this device?
│ ├── No → ARP is on a different L3 gateway for that VLAN
│ │ └── Check the SVI/IRB owner for ARP entry
│ └── Yes → Continue
├── Check spanning-tree state on the port
│ ├── Blocking/Discarding → Port is STP-blocked; MAC learned before
│ └── Forwarding → Continue
└── Device may not have an IP configured
└── L2-only device (unmanaged switch, printer in DHCP timeout)Asymmetric Routing View
Route visible from device A but not device B (or different next-hop)
├── Are both devices in the same VRF?
│ ├── No → Separate routing domains; route leaking required
│ └── Yes → Continue
├── Check routing protocol adjacency between A and B
│ ├── No adjacency → Protocol not configured or filtered
│ └── Adjacency up → Continue
├── Check route filters / distribute-lists
│ ├── [Cisco] show ip protocols | section Routing
│ ├── [JunOS] show policy [name]
│ ├── [EOS] show ip protocols | section Routing
│ └── Filter blocking the prefix → Adjust policy
├── Route redistribution boundary?
│ └── Prefix from one protocol not redistributed into another
└── Summarization hiding the specific route?
└── Check for area summarization or aggregate routesReport Template
NETWORK TOPOLOGY DISCOVERY REPORT
===================================
Seed Device: [hostname]
Discovery Scope: [site / VRF / subnet range / domain]
Discovery Time: [start] to [end]
Performed By: [operator/agent]
DISCOVERY SUMMARY:
- Total devices discovered: [n]
- Routers: [n] | Switches: [n] | Firewalls: [n] | Other: [n]
- Total links mapped: [n] (confirmed bilateral: [n], unilateral: [n])
- Subnets identified: [n]
- VRFs encountered: [list]
DEVICE INVENTORY:
| Hostname | Platform | Mgmt IP | Role | Discovery Method |
|----------|----------|---------|------|------------------|
| [name] | [model] | [ip] | [role] | [CDP/LLDP/ARP/routing] |
LINK MAP:
| Device A | Port A | Device B | Port B | Type | Speed |
|----------|--------|----------|--------|------|-------|
| [name] | [intf] | [name] | [intf] | [trunk/access/routed] | [1G/10G/...] |
ANOMALIES:
1. [Severity] [Category] — [Description]
Observed: [what was found]
Expected: [what design documents show]
Impact: [topology accuracy / security / operational]
Action: [recommended investigation or remediation]
COMPLETENESS ASSESSMENT:
- CDP/LLDP coverage: [%] of expected neighbors
- ARP resolution: [%] of MAC entries resolved
- Bilateral link confirmation: [%]
RECOMMENDATIONS:
- [Prioritized action list]
NEXT DISCOVERY: [Recommended refresh interval based on network change rate]Troubleshooting
CDP Neighbors Missing on JunOS Devices
CDP is Cisco-proprietary and not supported on JunOS. LLDP must be used for Juniper neighbor discovery. Ensure LLDP is enabled globally and on relevant interfaces: set protocols lldp interface all. On the Cisco/EOS side, enable LLDP alongside CDP so both protocols can exchange neighbor data with JunOS devices.
LLDP Showing Stale Neighbors
LLDP entries persist for the TTL duration (default 120s) after a neighbor disappears. If stale entries appear, check: remote device was recently powered off or rebooted, cable was disconnected, or LLDP was disabled on the remote interface. Wait for TTL expiry or clear LLDP table manually to refresh.
MAC Table Showing Thousands of Entries on Access Port
An access port learning hundreds of MACs suggests: a hub or unmanaged switch behind the port, a virtualization host with many VMs bridged to one interface, or a misconfigured trunk. Check port configuration — if it should be an access port, investigate what is connected. Consider enabling port security to limit MAC learning.
ARP Entries with Incomplete MAC
show ip arp showing "Incomplete" for a MAC address means the device sent an ARP request but received no reply. The target IP is configured on the local subnet but the host is not responding. Causes: host is offline, host firewall is blocking ARP, duplicate IP address conflict, or host is on the wrong VLAN. Verify the host is powered on and connected to the correct VLAN.
Routing Table Shows Unexpected Default Route
A default route pointing to an unknown next-hop may indicate: a rogue DHCP server providing gateway addresses, an unplanned static route, or route redistribution pulling in a default from another domain. Trace the route source — check show ip route 0.0.0.0 for the protocol and source. If OSPF or BGP, identify which peer is advertising the default.