{"id":26508583,"url":"https://github.com/eval-agency/net-diag","last_synced_at":"2026-02-12T05:50:19.662Z","repository":{"id":267974163,"uuid":"902857540","full_name":"eVAL-Agency/net-diag","owner":"eVAL-Agency","description":"Collection of network scanning and diagnostic utilities for technician workstations and on-prem management boxes","archived":false,"fork":false,"pushed_at":"2025-09-08T08:13:40.000Z","size":458,"stargazers_count":1,"open_issues_count":5,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-01-29T22:34:53.893Z","etag":null,"topics":["asset-management","network-discovery","network-scanner","python","snmp"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/eVAL-Agency.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","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":"2024-12-13T12:13:42.000Z","updated_at":"2025-09-08T08:13:44.000Z","dependencies_parsed_at":null,"dependency_job_id":"b1b2085b-b0bb-455f-b611-3fe1ed03eb8f","html_url":"https://github.com/eVAL-Agency/net-diag","commit_stats":null,"previous_names":["cdp1337/net-diag","eval-agency/net-diag"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/eVAL-Agency/net-diag","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eVAL-Agency%2Fnet-diag","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eVAL-Agency%2Fnet-diag/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eVAL-Agency%2Fnet-diag/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eVAL-Agency%2Fnet-diag/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eVAL-Agency","download_url":"https://codeload.github.com/eVAL-Agency/net-diag/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eVAL-Agency%2Fnet-diag/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29359940,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-12T01:03:07.613Z","status":"online","status_checked_at":"2026-02-12T02:00:06.911Z","response_time":55,"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":["asset-management","network-discovery","network-scanner","python","snmp"],"created_at":"2025-03-21T00:35:04.874Z","updated_at":"2026-02-12T05:50:19.655Z","avatar_url":"https://github.com/eVAL-Agency.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Network Diagnostics\n\nCollection of network diagnostic scripts, useful for technicians.\n\n\n## Network Discover\n\nScan a network for hosts and host details.\nSince this operates via SNMP, it can provide MAC details over a layer-3 network, (ie: a VPN).\n\n### Options\n\n* --net: Single network to scan, in CIDR notation\n* --config: Configuration file to use for this scan\n* --community: SNMP community string (default: public)\n* --format: Output format, either (json, csv, suitecrm, grist, openproject) (default: json)\n* --debug: Include to print debug information on stderr\n* --address: Optional physical address to include in the report\n* --city: Optional city to include in the report\n* --state: Optional state to include in the report\n* --exclude: Optional list of IP addresses to exclude from the report\n* --exclude-self: Optional flag to exclude the host running the script from the report\n* --fields: Comma-separated list of fields to include in the output\n* Grist specific options (with --format grist)\n  * --grist-url: URL of the Grist instance\n  * --grist-account: Account token for destination account\n* SuiteCRM specific options (with --format suitecrm)\n  * --crm-url: URL of the SuiteCRM instance\n  * --crm-client-id: Client ID for the SuiteCRM instance\n  * --crm-client-secret: Client secret for the SuiteCRM instance\n* OpenProject specific options (with --format openproject)\n  * --openproject-url: URL of the OpenProject instance\n  * --openproject-api-key: API key for the OpenProject instance\n  * --openproject-workspace: Workspace identifier for the OpenProject instance\n\n\n### Fields provided\n\n* ip\n* mac\n* hostname\n* contact\n* floor\n* location\n* type\n* manufacturer\n* model\n* os_version\n* descr\n* address\n* city\n* state\n* ports\n\nThese fields can be modified with the `--fields` option to include or exclude specific fields from the output.\n\n\n### Configuration File\n\nFor complex networks, a config file can be utilized to scan multiple networks at once.\nThis can be beneficial when switches with the ARP tables are on a separate network from hosts.\n\nAn example configuration file with 192.168.0.0/24 containing the network devices\nand 192.168.1.0/24 containing workstations:\n\nDefault contains the parameters to apply to all targets, and each individual target can override these parameters.\n\n192.168.0.0 network has devices which support SNMP and ICMP, whereas devices on 192.168.1.0\nhas devices which only support ICMP.\n\n```yaml\ndefault:\n  community: snmp-public-pass\n  address: 123 Here\n  city: Columbus\n  state: OH\n  format: json\n  exclude:\n    - 192.168.1.1\ntargets:\n  - net: 192.168.0.0/24\n  - net: 192.168.1.0/24\n    scanners:\n      - icmp\n```\n\nAny command line parameter can be specified in both `default` and individual `targets` declarations.\n(For parameters which contain a `-`, use `_` instead, ie: `--crm-client-id` becomes `crm_client_id`.)\n\n### Scanners\n\n#### ICMP\n\nPerform a standard ping to check if hosts are online\n\nPerformed by default, but can be omitted by not including 'icmp' in target scanners\n\n#### SNMP\n\nAttempt to connect to devices using SNMPv2 to retrieve host and neighbor information.\n\nPerformed by default, but can be omitted by not including 'snmp' in target scanners\n\n#### Trane Tracer HVAC controllers\n\nConnects to the Trane Tracer SC+ API to retrieve information about HVAC controllers on the BACnet.\n\nCan be included with 'trane' in the target scanners, but is not performed by default.\n\n### Examples\n\n#### Save report to CSV\n\nSimple usage, write scan results to a local file\n\n```bash\nnetwork_discover --net 10.10.10.0/24 --community public --format csv \u003e network.csv\n\n# Generates output to stderr (some omitted for brevity)\nScanning host 10.10.10.1\nScanning host 10.10.10.2\nScanning host 10.10.10.3\nScanning host 10.10.10.4\nScanning host 10.10.10.5\nScanning host for neighbors 10.10.10.1\nScanning host for neighbors 10.10.10.2\n\n# Generates CSV file with the following contents\nip,mac,hostname,contact,floor,location,type,manufacturer,model,os_version,descr,address,city,state\n10.10.10.1,00:11:22:33:44:55,Unifi-Rack,Charlie Powell,02,Server Room,,,,,Linux eVAL-Rack 4.19.152-ui-alpine #4.19.152 SMP Mon Oct 14 10:40:15 CST 2024 aarch64,,,\n1.2.3.4,00:11:22:33:44:56,,,,,,,,,,,,\n1.2.3.5,00:11:22:33:44:57,,,,,,,,,,,,\n10.10.10.13,00:11:22:33:44:58,,,,,,,,,,,,,\n10.10.10.14,00:11:22:33:44:59,,,,,,,,,,,,,\n10.10.10.21,00:11:22:33:44:60,,,,,,,,,,,,,\n10.10.10.102,00:11:22:33:44:61,US24,,02,Server Room,,,,,\"US-24-G1, 7.1.26.15869, Linux 3.6.5\",,,\n10.10.10.106,,UBNT,root@localhost,,Unknown,,,,,UAP 4.3.28.11361,,,\n10.10.10.120,00:11:22:33:44:61,,,,,,,,,,,,\n```\n\n#### Publish discovery data to Grist\n\nWhen using [compatible middleware for Grist](https://github.com/eVAL-Agency/Grist-Scripts),\ndevice information can be published automatically to your Grist database.\n\nSet `--format grist` to publish to Grist and ensure to set `--grist-url` as the URL (ex: `https://grist.yourdomain.tld`) to your Grist instance\nand set `--grist-account` to a valid account token for this scan.\n\n#### Publish discovery data to SuiteCRM\n\nIf using the MSP plugin for SuiteCRM or another compatible library, \nusing `--format suitecrm` can sync data directly to the device database.\n\n@todo Publish the SuiteCRM MSP plugin once it's more polished.  Contact me if you want an early alpha version.\n\nThis functionality requires oauth to be configured for your instance and a client ID/secret to be provided.\n\nRequired roles are:\n\n* MSP_Devices read/list\n* MSP_Devices edit\n* MSP_Devices create\n\n```bash\nnetwork_discover --net=192.168.0.0/24 --format=suitecrm --crm-url=crm.yourdomain.tld --crm-client-id=123456-1234-1234-123456789 --crm-client-secret=oauth_secret_key -c public\n\n# Example output\nScanning host 192.168.0.100\nScanning host 192.168.0.143\nScanning host 192.168.0.150\nScanning host 192.168.0.151\nScanning host 192.168.0.152\n...\nSyncing 192.168.0.73 to SuiteCRM\nSyncing 192.168.0.75 to SuiteCRM\nSyncing 192.168.0.76 to SuiteCRM\nSyncing 192.168.0.77 to SuiteCRM\n```\n\n#### Publish discovery data to OpenProject\n\nIf using OpenProject to store device information, this format can upload scan data as work packages directly to OpenProject.\n\nRequires an API key (Account Settings -\u003e Access tokens -\u003e API), for a user with create/update permissions on the target workspace.\n\nExpects a 'Device' work package type to be configured to store the data,\nalong with some custom fields:\n\n* IP Address\n* MAC Address\n* Device Type\n* Manufacturer\n* Model\n* Serial Number\n* Floor\n* Room\n* Uplink Port\n\n```\nnetwork_discover --net=192.168.0.0/24 --format=openproject --openproject-url=project.yourdomain.tld --openproject-workspace=your-project-tag --openproject-api-key=123456789abcdef --community public\n```\n\n#### Exclude specific IP addresses from report\n\nSometimes, (notably with gateways that have multiple IP addresses on different subnets), \nyou may want to exclude specific hosts from the report.  (They will still be used to generate data for other hosts.)\n\n```bash\nnetwork_discover --net=192.168.0.0/24 --exclude=192.168.0.1,192.168.0.2\n```\n\nThe reason why this is beneficial: a gateway may have an IP on its main subnet and on a guest network.\nFor logging, you do not care about the interface on the guest, as it's only there for routing purposes for guests.\n\nThis will allow you to scan that network using the gateway as a pivot point, but will ignore it when publishing results.\n\n\n## Network Diagnostic\n\nProvides a command line interface to gather network diagnostics from a host device,\nuseful for diagnosing network and infrastructure issues.\n\n### Basic Usage\n\nRunning with no options will prompt for which interface to monitor:\n\n```\nPlease select a network interface to diagnose:\n\n1: enp6s0 (up,broadcast,running,multicast)\n2: docker0 (up,broadcast,multicast)\n3: VPN_Wireguard (up,pointopoint,running,noarp)\n4: wlx6c5ab06d580e (broadcast,multicast)\n\nEnter the number of the interface you want to diagnose: \n```\n\nOr specify `-i (iface)` to specify the interface directly when running the command.\n\n### Example Output\n\n```\nNetwork Diagnostics\n\nInterface           ️✅  enp6s0\nType                ️✅  ethernet\nStatus              ️✅  UP\nSpeed               ️✅  1.0 Gbps\nDuplex              ️✅  Full Duplex\nMTU                 ️✅  1500\nLLDP Peer           ️✅  US-8-60W - Port 4 [12:34:56:78:90:ab:cd] (US-8-60W, 7.0.50.15613, Linux 3.6.5)\nIP Address          ️✅  10.200.0.227/24\nRoutes              ️✅  Default gateway 10.200.0.1, Direct access to 10.200.0.0/24\nNameservers         ️✅  10.200.0.3\nDomain Name         ️✅  house.local\nNeighbors           ️✅  6 visible devices\nWAN IP              ️✅  1.2.3.4\nInternet Status     ️✅  Connected\nLatency             ️✅  50.17 ms\nDNS Resolution      ️✅  up.eval.bz -\u003e 159.89.55.61\n```\n\nThis UI is refreshed automatically every 2 seconds for near real-time updates.\n\nWifi interfaces will show additional information, such as signal strength, noise, and channel.\n\n### JSON Support\n\nSpecify `--json` as an argument to perform a single iteration of diagnostics and output the results in JSON format.\n\n### Threads\n\nBy default on Linux, the diagnostics will run as a background thread to provide real-time updates.\n\nThis can be disabled by specifying `--no-threads`.\n\n**Windows**: Threading is not supported on Windows, so the diagnostics will always run in a single thread.\n\n## Bundled dependencies\n\n* [Python](https://www.python.org/)\n* [python-dateutil](https://pypi.org/project/python-dateutil/)\n* [six](https://pypi.org/project/six/)\n* [ipcalc](https://pypi.org/project/ipcalc/)\n* [icmplib](https://pypi.org/project/icmplib/)\n* [dnspython](https://pypi.org/project/dnspython/)\n* [pysnmplib](https://pypi.org/project/pysnmplib/)\n* [argparse](https://pypi.org/project/argparse/)\n* [mac-vendor-lookup](https://pypi.org/project/mac-vendor-lookup/)\n\n\n## Dev setup\n\nGet the code and setup the initial environment\n\n```bash\ngit clone git@github.com:eVAL-Agency/net-diag.git\ncd net-diag\npython3 -m venv venv\nsource venv/bin/activate\npython3 -m pip install --upgrade pip\npip3 install -e .[dev]\n```\n\nGet the code running on Windows\n\n```powershell\nSet-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser\ngit clone git@github.com:eVAL-Agency/net-diag.git\ncd net-diag\npython -m venv venv\n\u0026 venv\\Scripts\\Activate.ps1\npython -m pip install --upgrade pip\npip3 install -e .[dev]\npython -m pip install windows-curses\n```\n\nRun the application from source\n\n```bash\nsource venv/bin/activate\npython src/net_diag/network_discover.py --ip 192.168.1.1 --community somestring --format json --debug\n```\n\n\n## Debugging\n\nThe use of the `--debug` flag will print all details from lookups.\nUse this flag, (possibly along with `--single` to target the specific IP), when providing feedback\nfor data lookups.\n\nExample:\n\n```bash\npython src/net_diag/network_discover.py --ip 192.168.253.100 --community somepass --format csv --single --debug\n\n# Printed to stderr:\n[1 of 1] - Scanning details for 192.168.253.100\n[DEBUG] Scanning for DESCR - 1.3.6.1.2.1.1.1.0\n[DEBUG] 1.3.6.1.2.1.1.1.0 = UAP-AC-Pro-Gen2 6.6.77.15402\n[DEBUG] Scanning for MAC - 1.3.6.1.2.1.2.2.1.6\n[DEBUG] 1.3.6.1.2.1.2.2.1.6.1 = \n[DEBUG] 1.3.6.1.2.1.2.2.1.6.2 = 74:ac:b9:bc:41:fa\n[DEBUG] 1.3.6.1.2.1.2.2.1.6.3 = \n[DEBUG] 1.3.6.1.2.1.2.2.1.6.4 = 74:ac:b9:bd:41:fa\n[DEBUG] 1.3.6.1.2.1.2.2.1.6.5 = 74:ac:b9:be:41:fa\n[DEBUG] No SNMP response received before timeout\n[DEBUG] Scanning for hostname - 1.3.6.1.2.1.1.5.0\n[DEBUG] 1.3.6.1.2.1.1.5.0 = FL01WifiLobby\n[DEBUG] Scanning for contact - 1.3.6.1.2.1.1.4.0\n[DEBUG] 1.3.6.1.2.1.1.4.0 = Charlie Powell\n[DEBUG] Scanning for firmware version - 1.3.6.1.2.1.16.19.2.0\n[DEBUG] 1.3.6.1.2.1.16.19.2.0 = No Such Object currently exists at this OID\n[DEBUG] Scanning for model - 1.3.6.1.2.1.16.19.3.0\n[DEBUG] 1.3.6.1.2.1.16.19.3.0 = No Such Object currently exists at this OID\n[DEBUG] Scanning for location - 1.3.6.1.2.1.1.6.0\n[DEBUG] 1.3.6.1.2.1.1.6.0 = FL01 Lobby\n\n# Printed to stdout:\nip,mac,hostname,contact,floor,location,type,manufacturer,model,os_version,descr\n192.168.253.100,74:ac:b9:bc:41:fa,FL01WifiLobby,Charlie Powell,01,Lobby,,Ubiquiti Networks Inc.,,,UAP-AC-Pro-Gen2 6.6.77.15402\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feval-agency%2Fnet-diag","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feval-agency%2Fnet-diag","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feval-agency%2Fnet-diag/lists"}