# Cisco Network Map

> Generate Python scripts that discover and map network topology using ping, traceroute, ARP, CDP, LLDP, and routing tables. Use when the user wants to discover devices, map network topology, visualize network diagrams, or build a network inventory from live discovery.

- Skill: `bradmccloskey/cisco-network-map` (Agent Skill)
- Install (CLI): `npx skillmds@latest add bradmccloskey/cisco-network-map`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bradmccloskey/cisco-network-map/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: bradmccloskey (https://skillmd.com/u/bradmccloskey)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/bradmccloskey/cisco-network-map

---


## Cisco Network Discovery & Mapping Scripts

Write Python scripts that discover and map network topology from live devices. Follow these standards:

### Discovery Methods

#### Ping Sweep
- ICMP sweep across subnets to find live hosts
- Use `concurrent.futures` or `asyncio` for parallel pings
- Record response time and TTL (TTL helps identify device type/hop count)
- Support CIDR input (e.g., `10.0.1.0/24`) and ranges
- Identify likely network devices vs endpoints by TTL values (64=Linux/endpoint, 128=Windows, 255=Cisco)

#### Traceroute
- Trace paths between known endpoints to discover intermediate hops
- Build hop-by-hop path maps
- Identify asymmetric routing (trace both directions)
- Detect multiple paths (ECMP) by running repeated traces
- Record per-hop latency for path quality analysis

#### ARP Table Collection
- Pull `show ip arp` from routers/L3 switches
- Map IP addresses to MAC addresses
- Identify MAC vendor (OUI lookup) to determine device manufacturer
- Detect duplicate IPs or MAC flapping
- Cross-reference with CAM/MAC address tables for port mapping

#### CDP (Cisco Discovery Protocol)
- Pull `show cdp neighbors detail` from all Cisco devices
- Extract: device ID, platform, IP, local/remote interface, software version, capabilities
- Build adjacency graph from CDP data
- Crawl the network: start at seed device, discover neighbors, SSH to each, repeat
- Identify device roles from capabilities field (R=Router, S=Switch, T=Trans Bridge, etc.)

#### LLDP (Link Layer Discovery Protocol)
- Pull `show lldp neighbors detail` for multi-vendor environments
- Extract: system name, system description, management IP, port ID, capabilities
- Use alongside CDP for complete visibility (non-Cisco devices only speak LLDP)
- Parse TLVs for additional info (VLAN, power, link aggregation)

#### Routing Table Analysis
- Pull `show ip route` from all L3 devices
- Map all known subnets and next-hops
- Build a subnet-level topology (which device owns which subnet)
- Identify routing domains (OSPF areas, BGP AS numbers, EIGRP AS)
- Detect default route paths and internet egress points
- Pull `show ip ospf neighbor`, `show ip bgp summary`, `show ip eigrp neighbors` for protocol-level adjacency

### Discovery Workflow

```
1. Start with seed device(s) or subnet
2. Ping sweep to find live hosts
3. SSH to seed device → collect CDP/LLDP neighbors
4. Crawl: SSH to each discovered neighbor → repeat CDP/LLDP collection
5. Collect ARP tables from all L3 devices found
6. Collect routing tables from all routers found
7. Run traceroutes between key endpoints
8. Correlate all data into unified topology model
9. Output: topology map, device inventory, subnet map
```

### Data Model

```python
# Build a graph-based topology model
# Nodes = devices (router, switch, firewall, endpoint)
# Edges = links (with interface names, speed, subnet)

class Device:
    hostname: str
    ip_addresses: list       # management + interface IPs
    platform: str            # e.g., "Cisco ISR 4451"
    device_type: str         # router, switch, firewall, endpoint
    software: str            # IOS version
    interfaces: list         # name, ip, mac, status, speed, neighbor
    discovered_via: str      # cdp, lldp, arp, ping, routing

class Link:
    source_device: str
    source_interface: str
    target_device: str
    target_interface: str
    subnet: str
    speed: str
    protocol: str            # cdp, lldp, or inferred
```

### Network Crawl Safety
- Maintain a visited set to avoid loops
- Set a max hop depth (default: 10) to prevent runaway crawls
- Allow include/exclude filters by IP range or hostname pattern
- Respect rate limits (don't hammer devices with rapid SSH connects)
- Add delay between device connections (configurable, default 1 second)
- Set SSH timeout and retry limits
- Support read-only mode (only show commands, never config changes)

### Output Formats

#### Text Report
- Device inventory table (hostname, IP, platform, IOS version)
- Interface-to-interface adjacency list
- Subnet map (which subnets on which devices)
- Routing summary per device

#### Structured Data
- JSON topology export (nodes + edges)
- CSV device inventory
- YAML topology for use with cisco-gns3 skill to rebuild in lab

#### Visual Diagram
- Use `graphviz` (dot format) for topology diagrams
- Use `networkx` + `matplotlib` for programmatic graph layout
- Use `draw.io` XML export for editable diagrams
- Label nodes with hostname and IP
- Label edges with interface names and subnet
- Color code by device type (routers=blue, switches=green, firewalls=red)
- Group devices by site/subnet/routing domain

### Libraries to Use
- `netmiko` for SSH command execution
- `pyats` + `genie` for structured show command parsing (preferred)
- `textfsm` / `ntc-templates` as parsing alternative
- `scapy` for custom ping/traceroute if ICMP from script host
- `subprocess` for system ping/traceroute commands
- `ipaddress` for subnet math
- `netaddr` for MAC OUI vendor lookup
- `networkx` for graph building and analysis
- `graphviz` for diagram generation
- `matplotlib` for visualization
- `concurrent.futures` for parallel device polling
- `rich` for progress bars and formatted console output
- `macvendors` or OUI database for MAC-to-vendor resolution

### Example Usage Patterns

#### Quick subnet scan
```
/cisco-network-map ping-sweep 10.0.0.0/24
```

#### Full crawl from seed device
```
/cisco-network-map crawl 192.168.1.1
```

#### Map routing topology
```
/cisco-network-map routing-topology R1,R2,R3
```

#### Generate diagram from collected data
```
/cisco-network-map diagram topology.json
```

### Security Requirements
- NEVER hardcode credentials
- Use environment variables or `.env` files (gitignored)
- Read-only operations only (no config commands)
- Log all devices accessed and commands run
- Support `--dry-run` to show what would be discovered without connecting