pyats-topology

Discover and map the physical and logical network topology using CDP, LLDP, ARP, routing protocol neighbors, and interface data.

Safety Notice

This listing is imported from skills.sh public index metadata. Review upstream SKILL.md and repository scripts before running.

Copy this and send it to your AI assistant to learn

Install skill "pyats-topology" with this command: npx skills add automateyournetwork/netclaw/automateyournetwork-netclaw-pyats-topology

Topology Discovery

Discover and map the physical and logical network topology using CDP, LLDP, ARP, routing protocol neighbors, and interface data.

When to Use

  • Building network diagrams from scratch (no documentation exists)

  • Validating existing documentation matches reality

  • Pre-change topology baseline

  • Incident response — understanding blast radius

  • New device onboarding — mapping where it connects

Discovery Procedure

Step 1: CDP Neighbors (Cisco-to-Cisco)

PYATS_TESTBED_PATH=$PYATS_TESTBED_PATH python3 $MCP_CALL "python3 -u $PYATS_MCP_SCRIPT" pyats_run_show_command '{"device_name":"R1","command":"show cdp neighbors detail"}'

Extract per neighbor:

  • Device ID (hostname)

  • Platform and model

  • IP address (management address)

  • Local interface → Remote interface (link mapping)

  • Software version

  • Native VLAN (on switch links)

  • Duplex

Build adjacency table:

Local Device | Local Interface | Remote Device | Remote Interface | Remote Platform R1 | Gi0/0/0 | SW1 | Gi1/0/1 | WS-C3850-24T R1 | Gi0/0/1 | R2 | Gi0/0/0 | ISR4431

Step 2: LLDP Neighbors (Multi-Vendor)

PYATS_TESTBED_PATH=$PYATS_TESTBED_PATH python3 $MCP_CALL "python3 -u $PYATS_MCP_SCRIPT" pyats_run_show_command '{"device_name":"R1","command":"show lldp neighbors detail"}'

LLDP is IEEE 802.1AB — works with non-Cisco devices (Arista, Juniper, Linux hosts, IP phones, APs). Same adjacency table format as CDP but may include additional TLVs.

Step 3: ARP Table (L3 Neighbor Discovery)

PYATS_TESTBED_PATH=$PYATS_TESTBED_PATH python3 $MCP_CALL "python3 -u $PYATS_MCP_SCRIPT" pyats_run_show_command '{"device_name":"R1","command":"show arp"}'

Analysis:

  • Map IP addresses to MAC addresses on each interface

  • Identify directly connected hosts (servers, endpoints, other routers)

  • Look for multiple MAC addresses on the same interface (switch segment)

  • Incomplete entries indicate devices that are configured but unreachable

Step 4: Routing Protocol Peers

OSPF neighbors = L3 adjacent routers:

PYATS_TESTBED_PATH=$PYATS_TESTBED_PATH python3 $MCP_CALL "python3 -u $PYATS_MCP_SCRIPT" pyats_run_show_command '{"device_name":"R1","command":"show ip ospf neighbor"}'

BGP peers = logical connections (may be multi-hop):

PYATS_TESTBED_PATH=$PYATS_TESTBED_PATH python3 $MCP_CALL "python3 -u $PYATS_MCP_SCRIPT" pyats_run_show_command '{"device_name":"R1","command":"show ip bgp summary"}'

EIGRP neighbors:

PYATS_TESTBED_PATH=$PYATS_TESTBED_PATH python3 $MCP_CALL "python3 -u $PYATS_MCP_SCRIPT" pyats_run_show_command '{"device_name":"R1","command":"show ip eigrp neighbors"}'

Step 5: Interface-to-Subnet Mapping

PYATS_TESTBED_PATH=$PYATS_TESTBED_PATH python3 $MCP_CALL "python3 -u $PYATS_MCP_SCRIPT" pyats_run_show_command '{"device_name":"R1","command":"show ip interface brief"}'

Build subnet map:

Interface | IP Address | Subnet | Connected Subnet Gi0/0/0 | 10.1.1.1/30 | 10.1.1.0/30 | R1 <-> SW1 transit Gi0/0/1 | 10.1.2.1/30 | 10.1.2.0/30 | R1 <-> R2 transit Loopback0 | 1.1.1.1/32 | 1.1.1.1/32 | Router ID

Step 6: VRF Topology

PYATS_TESTBED_PATH=$PYATS_TESTBED_PATH python3 $MCP_CALL "python3 -u $PYATS_MCP_SCRIPT" pyats_run_show_command '{"device_name":"R1","command":"show vrf"}'

For each VRF, identify:

  • VRF name, RD, RT import/export

  • Interfaces assigned to the VRF

  • Routes in the VRF routing table

Step 7: FHRP Group Mapping

PYATS_TESTBED_PATH=$PYATS_TESTBED_PATH python3 $MCP_CALL "python3 -u $PYATS_MCP_SCRIPT" pyats_run_show_command '{"device_name":"R1","command":"show standby brief"}'

Map virtual IPs, active/standby roles, group numbers, and tracking objects.

Building the Topology Model

Combine all discovery data into a unified model:

Topology: NetClaw Discovery - YYYY-MM-DD

Devices: R1 (C8000V, IOS-XE 17.x.x) Loopback0: 1.1.1.1/32 (Router ID) Gi1: 10.1.1.1/30 → R2:Gi1 (OSPF Area 0, cost 1) Gi2: 10.1.2.1/24 → SW1:Gi0/1 (Access VLAN 10)

R2 (ISR4431, IOS-XE 17.x.x) [discovered via CDP] Gi1: 10.1.1.2/30 → R1:Gi1 Gi2: 10.2.1.1/24 → SW2:Gi0/1

Subnets: 10.1.1.0/30 - R1-R2 transit (OSPF Area 0) 10.1.2.0/24 - R1 LAN segment (VLAN 10) 10.2.1.0/24 - R2 LAN segment (VLAN 20)

Routing Adjacencies: R1 <-> R2: OSPF (Area 0, FULL) R1 <-> ISP: BGP (AS 65001 <-> AS 65000, Established)

FHRP: VLAN 10: HSRP Group 10, VIP 10.1.2.254, Active=R1, Standby=R3

Integration with Diagram Tools

After discovery, use this data to generate:

  • Draw.io diagrams (via drawio-diagram skill) — for formal network documentation

  • Markmap mind maps (via markmap-viz skill) — for hierarchical protocol views

  • NVD CVE audit (via nvd-cve skill) — using discovered software versions

NetBox Cable Reconciliation (MISSION02 Enhancement)

When NetBox is available ($NETBOX_MCP_SCRIPT is set), reconcile discovered topology against the source of truth:

Pull NetBox Cables

python3 $MCP_CALL "python3 -u $NETBOX_MCP_SCRIPT" netbox_get_objects '{"object_type":"dcim.cables","filters":{},"limit":200}'

Pull NetBox Devices

python3 $MCP_CALL "python3 -u $NETBOX_MCP_SCRIPT" netbox_get_objects '{"object_type":"dcim.devices","filters":{},"brief":true}'

Pull NetBox Interfaces

python3 $MCP_CALL "python3 -u $NETBOX_MCP_SCRIPT" netbox_get_objects '{"object_type":"dcim.interfaces","filters":{"device":"R1"}}'

Reconciliation Categories

Compare CDP/LLDP discovered neighbors against NetBox cables:

Category Meaning Action

DOCUMENTED Link exists in both discovery and NetBox No action

UNDOCUMENTED Link found by CDP/LLDP but not in NetBox Open ServiceNow incident to update NetBox

MISSING Cable in NetBox but not seen by CDP/LLDP Investigate — may be physical disconnect

MISMATCH Endpoints differ between discovery and NetBox Investigate — possible re-patching

Color-Coded Draw.io Diagram

Generate a Draw.io topology diagram with links color-coded by reconciliation status:

  • Green: DOCUMENTED

  • Yellow: UNDOCUMENTED

  • Red: MISSING

  • Orange: MISMATCH

Fleet-Wide Discovery (pCall)

Run CDP/LLDP/ARP/routing peer collection across ALL devices simultaneously using multiple exec commands. Merge results to build the complete topology graph.

GAIT Audit Trail

Record the topology discovery in GAIT:

python3 $MCP_CALL "python3 -u $GAIT_MCP_SCRIPT" gait_record_turn '{"input":{"role":"assistant","content":"Topology discovery completed: 5 devices, 12 links. NetBox reconciliation: 10 documented, 1 undocumented, 1 missing.","artifacts":[]}}'

Source Transparency

This detail page is rendered from real SKILL.md content. Trust labels are metadata-based hints, not a safety guarantee.

Open in GitHubOpen in ClawHub

Related Skills

Related by shared tags or category signals.

General

aws-cloud-monitoring

No summary provided by upstream source.

Repository SourceNeeds Review
9-automateyournetwork
General

pyats-health-check

No summary provided by upstream source.

Repository SourceNeeds Review
9-automateyournetwork
General

grafana-observability

No summary provided by upstream source.

Repository SourceNeeds Review
9-automateyournetwork
General

subnet-calculator

No summary provided by upstream source.

Repository SourceNeeds Review
8-automateyournetwork