Collection of network diagnostic scripts, useful for technicians.
Scan a network for hosts and host details. Since this operates via SNMP, it can provide MAC details over a layer-3 network, (ie: a VPN).
- --net: Single network to scan, in CIDR notation
- --config: Configuration file to use for this scan
- --community: SNMP community string (default: public)
- --format: Output format, either (json, csv, suitecrm, grist, openproject, glpi) (default: json)
- --debug: Include to print debug information on stderr
- --dry-run: Perform a scan without publishing results, useful for testing and debugging (no change for json/csv outputs)
- --address: Optional physical address to include in the report
- --city: Optional city to include in the report
- --state: Optional state to include in the report
- --exclude: Optional list of IP addresses to exclude from the report
- --exclude-self: Optional flag to exclude the host running the script from the report
- --fields: Comma-separated list of fields to include in the output
- Grist specific options (with --format grist)
- --grist-url: URL of the Grist instance
- --grist-account: Account token for destination account
- GLPI specific options (with --format glpi)
- --glpi-url: URL of the GLPI instance
- --glpi-token: Authorization token of the user to perform the import
- ip
- mac
- hostname
- contact
- floor
- location
- type
- manufacturer
- model
- os_version
- descr
- address
- city
- state
- ports
These fields can be modified with the --fields option to include or exclude specific fields from the output.
For complex networks, a config file can be utilized to scan multiple networks at once. This can be beneficial when switches with the ARP tables are on a separate network from hosts.
An example configuration file with 192.168.0.0/24 containing the network devices and 192.168.1.0/24 containing workstations:
Default contains the parameters to apply to all targets, and each individual target can override these parameters.
192.168.0.0 network has devices which support SNMP and ICMP, whereas devices on 192.168.1.0 has devices which only support ICMP.
default:
community: snmp-public-pass
address: 123 Here
city: Columbus
state: OH
format: json
exclude:
- 192.168.1.1
targets:
- net: 192.168.0.0/24
- net: 192.168.1.0/24
scanners:
- icmpAny command line parameter can be specified in both default and individual targets declarations.
(For parameters which contain a -, use _ instead, ie: --crm-client-id becomes crm_client_id.)
Perform a standard ping to check if hosts are online
Performed by default, but can be omitted by not including 'icmp' in target scanners
Attempt to connect to devices using SNMPv2 to retrieve host and neighbor information.
Performed by default, but can be omitted by not including 'snmp' in target scanners
Uses the HTTP scanner to connect to Trane Tracer SC+ controllers to retrieve information about HVAC controllers on the BACnet.
These store BACnet interfaces as type 22 - Prop Point-to-Point connections, so you'll need to enable them in GLPI.
The default rendering format; outputs all host discovery to JSON via stdout.
Example
network_discover --net 10.10.10.0/24 --community public --format json > network.jsonSimple usage, write scan results to a local file
network_discover --net 10.10.10.0/24 --community public --format csv > network.csv
# Generates output to stderr (some omitted for brevity)
Scanning host 10.10.10.1
Scanning host 10.10.10.2
Scanning host 10.10.10.3
Scanning host 10.10.10.4
Scanning host 10.10.10.5
Scanning host for neighbors 10.10.10.1
Scanning host for neighbors 10.10.10.2
# Generates CSV file with the following contents
ip,mac,hostname,contact,floor,location,type,manufacturer,model,os_version,descr,address,city,state
10.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,,,
1.2.3.4,00:11:22:33:44:56,,,,,,,,,,,,
1.2.3.5,00:11:22:33:44:57,,,,,,,,,,,,
10.10.10.13,00:11:22:33:44:58,,,,,,,,,,,,,
10.10.10.14,00:11:22:33:44:59,,,,,,,,,,,,,
10.10.10.21,00:11:22:33:44:60,,,,,,,,,,,,,
10.10.10.102,00:11:22:33:44:61,US24,,02,Server Room,,,,,"US-24-G1, 7.1.26.15869, Linux 3.6.5",,,
10.10.10.106,,UBNT,root@localhost,,Unknown,,,,,UAP 4.3.28.11361,,,
10.10.10.120,00:11:22:33:44:61,,,,,,,,,,,,When using compatible middleware for Grist, device information can be published automatically to your Grist database.
Set --format grist to publish to Grist and ensure to set --grist-url as the URL (ex: https://grist.yourdomain.tld) to your Grist instance
and set --grist-account to a valid account token for this scan.
As of v1.1.2, GLPI is supported as a target to store discovery data to; this saves scanned devices as network devices.
Documentation for publishing to GLPI
Sometimes, (notably with gateways that have multiple IP addresses on different subnets), you may want to exclude specific hosts from the report. (They will still be used to generate data for other hosts.)
network_discover --net=192.168.0.0/24 --exclude=192.168.0.1,192.168.0.2The reason why this is beneficial: a gateway may have an IP on its main subnet and on a guest network. For logging, you do not care about the interface on the guest, as it's only there for routing purposes for guests.
This will allow you to scan that network using the gateway as a pivot point, but will ignore it when publishing results.
Provides a command line interface to gather network diagnostics from a host device, useful for diagnosing network and infrastructure issues.
Running with no options will prompt for which interface to monitor:
Please select a network interface to diagnose:
1: enp6s0 (up,broadcast,running,multicast)
2: docker0 (up,broadcast,multicast)
3: VPN_Wireguard (up,pointopoint,running,noarp)
4: wlx6c5ab06d580e (broadcast,multicast)
Enter the number of the interface you want to diagnose:
Or specify -i (iface) to specify the interface directly when running the command.
Network Diagnostics
Interface ️✅ enp6s0
Type ️✅ ethernet
Status ️✅ UP
Speed ️✅ 1.0 Gbps
Duplex ️✅ Full Duplex
MTU ️✅ 1500
LLDP Peer ️✅ US-8-60W - Port 4 [12:34:56:78:90:ab:cd] (US-8-60W, 7.0.50.15613, Linux 3.6.5)
IP Address ️✅ 10.200.0.227/24
Routes ️✅ Default gateway 10.200.0.1, Direct access to 10.200.0.0/24
Nameservers ️✅ 10.200.0.3
Domain Name ️✅ house.local
Neighbors ️✅ 6 visible devices
WAN IP ️✅ 1.2.3.4
Internet Status ️✅ Connected
Latency ️✅ 50.17 ms
DNS Resolution ️✅ up.eval.bz -> 159.89.55.61
This UI is refreshed automatically every 2 seconds for near real-time updates.
Wifi interfaces will show additional information, such as signal strength, noise, and channel.
Specify --json as an argument to perform a single iteration of diagnostics and output the results in JSON format.
By default on Linux, the diagnostics will run as a background thread to provide real-time updates.
This can be disabled by specifying --no-threads.
Windows: Threading is not supported on Windows, so the diagnostics will always run in a single thread.
Get the code and setup the initial environment
git clone git@github.com:eVAL-Agency/net-diag.git
cd net-diag
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install --upgrade pip
pip3 install -e .[dev]Get the code running on Windows
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
git clone git@github.com:eVAL-Agency/net-diag.git
cd net-diag
python -m venv .venv
& .venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip3 install -e .[dev]
python -m pip install windows-cursesRun the application from source
source .venv/bin/activate
python src/net_diag/network_discover.py --ip 192.168.1.1 --community somestring --format json --debugThe use of the --debug flag will print all details from lookups.
Use this flag, (possibly along with --single to target the specific IP), when providing feedback
for data lookups.
Example:
python src/net_diag/network_discover.py --ip 192.168.253.100 --community somepass --format csv --single --debug
# Printed to stderr:
[1 of 1] - Scanning details for 192.168.253.100
[DEBUG] Scanning for DESCR - 1.3.6.1.2.1.1.1.0
[DEBUG] 1.3.6.1.2.1.1.1.0 = UAP-AC-Pro-Gen2 6.6.77.15402
[DEBUG] Scanning for MAC - 1.3.6.1.2.1.2.2.1.6
[DEBUG] 1.3.6.1.2.1.2.2.1.6.1 =
[DEBUG] 1.3.6.1.2.1.2.2.1.6.2 = 74:ac:b9:bc:41:fa
[DEBUG] 1.3.6.1.2.1.2.2.1.6.3 =
[DEBUG] 1.3.6.1.2.1.2.2.1.6.4 = 74:ac:b9:bd:41:fa
[DEBUG] 1.3.6.1.2.1.2.2.1.6.5 = 74:ac:b9:be:41:fa
[DEBUG] No SNMP response received before timeout
[DEBUG] Scanning for hostname - 1.3.6.1.2.1.1.5.0
[DEBUG] 1.3.6.1.2.1.1.5.0 = FL01WifiLobby
[DEBUG] Scanning for contact - 1.3.6.1.2.1.1.4.0
[DEBUG] 1.3.6.1.2.1.1.4.0 = Charlie Powell
[DEBUG] Scanning for firmware version - 1.3.6.1.2.1.16.19.2.0
[DEBUG] 1.3.6.1.2.1.16.19.2.0 = No Such Object currently exists at this OID
[DEBUG] Scanning for model - 1.3.6.1.2.1.16.19.3.0
[DEBUG] 1.3.6.1.2.1.16.19.3.0 = No Such Object currently exists at this OID
[DEBUG] Scanning for location - 1.3.6.1.2.1.1.6.0
[DEBUG] 1.3.6.1.2.1.1.6.0 = FL01 Lobby
# Printed to stdout:
ip,mac,hostname,contact,floor,location,type,manufacturer,model,os_version,descr
192.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