{"id":30105859,"url":"https://github.com/bigevilbeard/sdwan_device_location","last_synced_at":"2025-08-10T00:20:19.954Z","repository":{"id":304205686,"uuid":"1018104358","full_name":"bigevilbeard/sdwan_device_location","owner":"bigevilbeard","description":"Quick script to find location of sd-wan devices in network hierarchy","archived":false,"fork":false,"pushed_at":"2025-07-11T16:06:28.000Z","size":21,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-11T18:30:43.401Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bigevilbeard.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-11T16:00:47.000Z","updated_at":"2025-07-11T16:31:58.000Z","dependencies_parsed_at":"2025-07-11T18:40:58.495Z","dependency_job_id":null,"html_url":"https://github.com/bigevilbeard/sdwan_device_location","commit_stats":null,"previous_names":["bigevilbeard/sdwan_device_location"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/bigevilbeard/sdwan_device_location","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bigevilbeard%2Fsdwan_device_location","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bigevilbeard%2Fsdwan_device_location/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bigevilbeard%2Fsdwan_device_location/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bigevilbeard%2Fsdwan_device_location/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bigevilbeard","download_url":"https://codeload.github.com/bigevilbeard/sdwan_device_location/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bigevilbeard%2Fsdwan_device_location/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269657668,"owners_count":24454906,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-09T02:00:10.424Z","response_time":111,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-10T00:20:18.795Z","updated_at":"2025-08-10T00:20:19.784Z","avatar_url":"https://github.com/bigevilbeard.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cisco SD-WAN Site Hierarchy Extractor with Geocoding\n\nA Python tool that extracts site hierarchy information from Cisco SD-WAN Manager API and maps GPS coordinates to human-readable addresses using reverse geocoding.\n\n## Problem Statement\n\nCisco SD-WAN Manager does not provide a single API endpoint to retrieve the complete site hierarchy from the Network Hierarchy section. This tool solves that limitation by orchestrating multiple API calls to reconstruct the site structure with enhanced location information.\n\n## Features\n\n- **Multi-API Site Extraction**: Combines multiple SD-WAN API endpoints to build complete site hierarchy\n- **Reverse Geocoding**: Converts GPS coordinates to city/state/country addresses\n- **Site Categorization**: Automatically categorizes sites as Control Plane or Branch sites\n- **Network Topology**: Includes TLOC connection information for each device\n- **Professional Output**: Clean, enterprise-ready reporting format\n- **Data Export**: Saves results in structured JSON format\n\n## Requirements\n\n```bash\npip install requests urllib3\n```\n\n## Configuration\n\nUpdate the configuration section in the script, example uses [DevNet SD-WAN v20.10 Sandbox](https://devnetsandbox.cisco.com/DevNet/catalog/SD-WAN-Always-On_sd-wan-always-on)\n\n```python\n# Configuration\nBASE_URL = \"https://your-sdwan-manager.com\"\nUSERNAME = \"your-username\"\nPASSWORD = \"your-password\"\n```\n\n## Usage\n\n```bash\npython3 sdwan_geocoding_clean.py\n```\n\n## API Endpoints Used\n\nThe tool orchestrates the following Cisco SD-WAN Manager API endpoints:\n\n1. **Primary Data Source**: `GET /dataservice/device`\n   - Returns all devices with site-id, location coordinates, and device details\n   - Main source for building site hierarchy structure\n\n2. **Network Topology**: `GET /dataservice/device/tloc`\n   - Provides network connection information\n   - Links to devices via system-ip for connectivity details\n\n3. **Geocoding Service**: OpenStreetMap Nominatim API\n   - Converts GPS coordinates to human-readable addresses\n   - Free service with 1 request/second rate limiting\n\n## Sample Output\n\n```\nCisco SD-WAN Site Hierarchy Extraction with Geocoding\nTarget: https://sandbox-sdwan-2.cisco.com\n\nAuthenticating...\nSUCCESS: Authentication successful\n\nExtracting sites with location mapping...\nGetting device data...\nGetting TLOC data...\nProcessing devices and geocoding locations...\nProcessing device 1/7: vmanage\n   Geocoding 37.666684, -122.777023...\nProcessing device 2/7: vsmart\n   Geocoding 37.666684, -122.777023...\nProcessing device 3/7: vbond\n   Geocoding 37.666684, -122.777023...\nProcessing device 4/7: dc-cedge01\n   Geocoding 37.411, -121.932...\nProcessing device 5/7: site1-cedge01\n   Geocoding 35.852, -78.869...\nProcessing device 6/7: site2-cedge01\n   Geocoding 53.277, -8.932...\nProcessing device 7/7: site3-vedge01\n   Geocoding 53.408, -2.228...\n\n================================================================================\nCISCO SD-WAN SITES WITH GEOCODED LOCATIONS\n================================================================================\n\nSummary: 5 sites discovered\n   Control Plane Sites: 1\n   Branch Sites: 4\n\nCONTROL PLANE SITES\n----------------------------------------\n\nSite 101 (3 devices)\n   Location: United States\n   City: Unknown City, Unknown State, United States US\n   Coordinates: 37.666684, -122.777023\n   [ONLINE] vmanage (vmanage)\n      System IP: 10.10.1.1, Model: vmanage\n      Version: 20.10.1, Platform: x86_64\n   [ONLINE] vsmart (vsmart)\n      System IP: 10.10.1.5, Model: vsmart\n      Version: 20.10.1, Platform: x86_64\n   [ONLINE] vbond (vbond)\n      System IP: 10.10.1.3, Model: vedge-cloud\n      Version: 20.10.1, Platform: x86_64\n\nBRANCH SITES\n----------------------------------------\n\nSite 100 (1 devices)\n   Device GPS: San Jose, California, United States\n   City: San Jose, California, United States US\n   Postal Code: 95134\n   Coordinates: 37.411, -121.932\n   [OFFLINE] dc-cedge01 (vedge)\n      System IP: 10.10.1.11, Model: vedge-C8000V\n      Version: 17.10.01.0.1479, Platform: x86_64\n      Network Connections:\n        public-internet: 0 control, 0 BFD\n        mpls: 0 control, 0 BFD\n\nSite 1001 (1 devices)\n   Device GPS: Morrisville, North Carolina, United States\n   City: Morrisville, North Carolina, United States US\n   Postal Code: 27560\n   Coordinates: 35.852, -78.869\n   [ONLINE] site1-cedge01 (vedge)\n      System IP: 10.10.1.13, Model: vedge-C8000V\n      Version: 17.10.01.0.1479, Platform: x86_64\n      Network Connections:\n        public-internet: 2 control, 0 BFD\n        mpls: 1 control, 0 BFD\n\nSite 1002 (1 devices)\n   Device GPS: Éire / Ireland\n   City: Unknown City, Unknown State, Éire / Ireland IE\n   Postal Code: H91 NN76\n   Coordinates: 53.277, -8.932\n   [ONLINE] site2-cedge01 (vedge)\n      System IP: 10.10.1.15, Model: vedge-C8000V\n      Version: 17.10.01.0.1479, Platform: x86_64\n      Network Connections:\n        public-internet: 1 control, 6 BFD\n        mpls: 2 control, 6 BFD\n\nSite 1003 (1 devices)\n   Device GPS: Manchester, England, United Kingdom\n   City: Manchester, England, United Kingdom GB\n   Postal Code: M20 2SP\n   Coordinates: 53.408, -2.228\n   [ONLINE] site3-vedge01 (vedge)\n      System IP: 10.10.1.17, Model: vedge-cloud\n      Version: 20.10.1, Platform: x86_64\n      Network Connections:\n        public-internet: 1 control, 6 BFD\n        mpls: 2 control, 6 BFD\n\nLOCATION SUMMARY\n----------------------------------------\n\nCountries (3):\n   United Kingdom: Site 1003\n   United States: Site 101, Site 100, Site 1001\n   Éire / Ireland: Site 1002\n\nCities (5):\n   Manchester, England, United Kingdom: Site 1003\n   Morrisville, North Carolina, United States: Site 1001\n   San Jose, California, United States: Site 100\n   Unknown City, Unknown State, United States: Site 101\n   Unknown City, Unknown State, Éire / Ireland: Site 1002\n\nSites with geocoded locations saved to: /Users/stuartclark/Downloads/sdwan_sites_geocoded_clean.json\n```\n\n## Output Data Structure\n\nThe tool generates a JSON file with the following structure:\n\n```json\n{\n  \"101\": {\n    \"devices\": [\n      {\n        \"hostname\": \"vmanage\",\n        \"system_ip\": \"10.10.1.1\",\n        \"device_type\": \"vmanage\",\n        \"device_model\": \"vmanage\",\n        \"reachability\": \"reachable\",\n        \"version\": \"20.10.1\",\n        \"platform\": \"x86_64\",\n        \"location\": {\n          \"latitude\": 37.666684,\n          \"longitude\": -122.777023,\n          \"is_device_gps\": false,\n          \"geocoded\": {\n            \"display_name\": \"United States\",\n            \"city\": \"Unknown City\",\n            \"state\": \"Unknown State\",\n            \"country\": \"United States\",\n            \"country_code\": \"US\",\n            \"postcode\": \"\",\n            \"formatted_address\": \"United States\"\n          }\n        }\n      }\n    ],\n    \"location\": {\n      \"latitude\": 37.666684,\n      \"longitude\": -122.777023,\n      \"is_device_gps\": false,\n      \"geocoded\": {\n        \"display_name\": \"United States\",\n        \"city\": \"Unknown City\",\n        \"state\": \"Unknown State\",\n        \"country\": \"United States\",\n        \"country_code\": \"US\",\n        \"postcode\": \"\",\n        \"formatted_address\": \"United States\"\n      }\n    },\n    \"geocoded_location\": {\n      \"display_name\": \"United States\",\n      \"city\": \"Unknown City\",\n      \"state\": \"Unknown State\",\n      \"country\": \"United States\",\n      \"country_code\": \"US\",\n      \"postcode\": \"\",\n      \"formatted_address\": \"United States\"\n    },\n    \"site_type\": \"control_plane\"\n  }\n}\n```\n\n## Implementation Details\n\n### Multi-Step Process\n\n1. **Authentication**: Authenticate with SD-WAN Manager using form-based login\n2. **Device Data Extraction**: Retrieve all devices with location coordinates\n3. **Site Grouping**: Group devices by site-id to create site structure\n4. **Geocoding**: Convert GPS coordinates to human-readable addresses\n5. **Site Categorization**: Classify sites based on device types\n6. **Network Topology**: Add TLOC connection information\n7. **Report Generation**: Create formatted output and JSON export\n\n### Geocoding Options\n\nThe tool uses OpenStreetMap Nominatim (free) by default, but can be extended to support:\n\n- **Google Maps Geocoding API** ($5 per 1000 requests)\n- **HERE Geocoding API** (250k/month free tier)\n- **MapBox Geocoding API** ($0.50 per 1000 requests)\n- **Azure Maps** (Various pricing tiers)\n\n### Rate Limiting\n\n- Implements 1-second delays between geocoding requests\n- Caches geocoding results to avoid duplicate API calls\n- Includes error handling for failed geocoding requests\n\n## Key Insights\n\n- **No Single API**: SD-WAN Manager lacks a dedicated Network Hierarchy API endpoint\n- **Site-ID Grouping**: Sites are reconstructed by grouping devices with the same site-id\n- **Implicit Hierarchy**: Site structure is implicit in device data, not explicitly defined\n- **Location Enhancement**: Geocoding significantly improves location readability\n- **Multi-API Requirement**: Complete site picture requires orchestrating multiple API calls\n\n\n## Security Considerations\n\n- Store credentials securely (environment variables recommended)\n- Use HTTPS for all API communications\n- Implement proper error handling for authentication failures\n- Consider API rate limiting and throttling\n- Validate and sanitize all input data\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests if applicable\n5. Submit a pull request\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## Disclaimer\n\nThis tool is provided as-is for educational and operational purposes. Always test in a non-production environment first. Ensure compliance with your organization's security policies and Cisco's API usage guidelines.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbigevilbeard%2Fsdwan_device_location","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbigevilbeard%2Fsdwan_device_location","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbigevilbeard%2Fsdwan_device_location/lists"}