NetMapper V5

NetMapper V5 is a network discovery scanner written in Python that discovers hosts, open ports, banners, and inferred roles across IP ranges. It optionally enriches results via SSH, WinRM, and SNMP collectors, stores snapshots in SQLite, and produces a built-in static web UI plus iTOP 3.2.x-compatible CSV import files.

Table of Contents

1. Features
2. Architecture Overview
3. Prerequisites
4. Installation & Deployment
5. Running NetMapper
6. Menu-Driven Interface
7. CLI Reference
8. Scan Examples
9. Diff & List Examples
10. Collector Details
11. iTOP 3.2.x CSV Export
12. Output Files
13. Web UI
14. Troubleshooting
15. Security Notes

Features

• IP Range & CIDR Scanning: Supports dash ranges (192.168.1.1-192.168.1.254) and CIDR notation (192.168.1.0/24). Automatically excludes .0 (network) and .255 (broadcast) addresses.
• Port Discovery: Probes a configurable port list (default: 22, 53, 80, 88, 135, 139, 389, 443, 445, 636, 1433, 1521, 3306, 3389, 5432, 5985, 5986, 8000, 8080, 8443, 9000).
• Banner Grabbing: HTTP-aware banner collection with role inference (IIS, Apache, Nginx, Synology, etc.).
• Role Classification: Automatically tags hosts as web, windows, rdp, directory, dns, ssh, mssql, mysql, postgres, oracle, winrm, iis, reverse-proxy, nas, printer, switch, router, firewall, ups, snmp-managed, and more.
• OS Inference: Identifies windows-ish, linux-ish, network-device, nas, printer, ups, and unknown.
• SSH Collector: Linux/Unix enrichment — hostname, kernel, OS release, running services, listening sockets, routes.
• WinRM Collector: Windows enrichment — hostname, OS info, running services, listening TCP sockets, computer info (domain, architecture, HAL).
• SNMP Collector: Comprehensive MIB-II and HOST-RESOURCES-MIB walker covering system info, interfaces, IP addresses, routes, ARP, TCP/UDP endpoints, storage, devices, processes, and installed software.
• SQLite Snapshot Database: All scan results persist in snapshots.db for historical comparison and trending.
• Diff Engine: Compare any two snapshots to detect added, removed, and changed hosts with field-level deltas.
• Static Web UI: Zero-dependency HTML dashboard (netmapper-v5-ui.html) that loads snapshots directly from the SQLite database in the browser via sql.js.
• iTOP 3.2.x CSV Export: Ready-to-import class-specific CSVs with standard iTOP reconciliation keys and -> notation for external keys.
• Interactive Credential Prompts: If credentials are omitted, the tool prompts at runtime so secrets never need to be hard-coded in scripts.
• Menu-Driven Interface: Double-click Run.cmd on Windows to launch an interactive text menu — no CLI memorization required.
• Backward-Compatible CLI: Power users can still pass all arguments via command line for automation and scheduling.

Architecture Overview

Operator / Scheduled Task / Run.cmd
         |
         v
  +-----------------+
  |  Menu or CLI    |
  |  (argparse)     |
  +--------+--------+
           |
  +--------v--------+
  |  IP Expansion   |
  |  (range/CIDR)   |
  +--------+--------+
           |
  +--------v------------------------+
  |  ThreadPoolExecutor             |
  |  (default 128 workers)          |
  |                                 |
  |  +---------+  +---------+       |
  |  |  Ping   |  |  TCP    |       |
  |  |  Probe  |  |  Probe  |       |
  |  +----+----+  +----+----+       |
  |       |            |            |
  |  +----v------------v----+        |
  |  | Optional Collectors   |        |
  |  | SSH / WinRM / SNMP  |        |
  |  +-----------+-----------+        |
  +--------------+------------------+
                 |
  +--------------v------------------+
  |  Role / OS Classification       |
  +--------------+------------------+
                 |
  +--------------v------------------+
  |  SQLite Store (snapshots.db)     |
  +--------------+------------------+
                 |
  +--------------v------------------+
  |  Export Layer                    |
  |  - snapshot-*.json               |
  |  - snapshot-*-hosts.csv           |
  |  - itop_import/*.csv              |
  |  - netmapper-v5-ui.html          |
  +----------------------------------+

Prerequisites

• Python 3.10+ (Windows, Linux, or macOS)
• pip for dependency management
• Windows: Run.cmd requires Python to be available in PATH (typically installed via python.org installer with "Add to PATH" checked)
• Optional but recommended:
  • paramiko — for SSH collector
  • pywinrm — for WinRM collector
  • pysnmp + pyasn1 — for SNMP collector

Installation & Deployment

Step 1: Clone or Extract

Place all files in a deployment directory, e.g.:

C:\Tools\NetMapperV5\
  |- netmapper_v5.py
  |- requirements.txt
  |- Run.cmd
  |- README.md

Step 2: Install Dependencies

# Windows (PowerShell or Command Prompt)
python -m pip install -r requirements.txt

Or individually:

python -m pip install paramiko pywinrm pysnmp pyasn1

If a collector dependency is missing, the scan continues but that collector is skipped with a logged warning.

Step 3: Verify Installation

python -m py_compile netmapper_v5.py
python netmapper_v5.py list --db test.db

If list returns without error, the core scanner is functional.

Step 4: Configure for Your Environment

No configuration file is required. All scan parameters are provided at runtime via the menu or CLI. However, you may wish to:

• Ensure the output directory exists and is writable
• Confirm firewall rules allow outbound ICMP (ping) and TCP to target ports
• For WinRM collection: ensure target Windows hosts have WinRM enabled and allow NTLM/Basic authentication from the scanning host
• For SSH collection: ensure key-based or password authentication is available
• For SNMP collection: verify community strings match target device configurations

Step 5: Run via Menu (Recommended for Operators)

On Windows, double-click Run.cmd. This launches the interactive menu. The menu will prompt for:

• Target IP range (default: 192.168.100.1-192.168.109.253)
• Scan label
• Database file (default: snapshots.db)
• Output directory (default: .)
• Worker threads (default: 128)
• Skip ping toggle (default: Yes for speed)
• SNMP enable + community string
• SSH enable + interactive username/password
• WinRM enable + interactive username/password
• iTOP organization, location, brand, model

Step 6: Run via CLI (Recommended for Automation / Scheduled Tasks)

Use Task Scheduler on Windows or cron on Linux to run scans unattended. Pass all arguments explicitly:

python netmapper_v5.py scan "192.168.100.1-192.168.109.253" `
  --label "Nightly Discovery" `
  --db snapshots.db `
  --outdir C:\NetMapper\Outputs `
  --workers 128 `
  --skip-ping `
  --enable-snmp --snmp-community public `
  --itop-org "My Organization"

Step 7: Review Outputs

After each scan, check the output directory for:

• snapshot-{id}.json — full structured data
• snapshot-{id}-hosts.csv — flat host summary
• itop_import/ — class-specific CSVs for iTOP
• netmapper-v5-ui.html — open in any browser to visualize results

Running NetMapper

Method A: Menu-Driven (Interactive)

1. Double-click Run.cmd on Windows (or run python netmapper_v5.py with no arguments anywhere).
2. Choose 1. Run Scan from the menu.
3. Accept defaults or enter custom values at each prompt.
4. If SSH or WinRM is enabled, the scanner will prompt for credentials after the scan parameters are collected.
5. Wait for the scan to complete. Progress is printed to the console.
6. Review files in the output directory.

Method B: Command-Line (Scripted / Automated)

Pass a subcommand (scan, list, diff) with arguments. Use --help for details:

python netmapper_v5.py scan --help
python netmapper_v5.py diff --help
python netmapper_v5.py list --help

Menu-Driven Interface

When launched without a subcommand, NetMapper presents:

==================================================
  NetMapper V5 - Menu
==================================================
1. Run Scan
2. List Snapshots
3. Diff Snapshots
4. Quit
==================================================
Choice:

Scan Menu Prompts

Prompt	Default	Description
Target range	192.168.100.1-192.168.109.253	Dash range or CIDR
Label	Scan	Descriptive snapshot name
Database file	snapshots.db	SQLite path
Output directory	.	Where artifacts are written
Workers	128	Concurrent threads
Skip ping	Yes	Skip ICMP; port-probe only (faster)
Enable SNMP	Yes	Walk MIBs if port 161/UDP is open
SNMP community	public	Read community string
Enable SSH	No	Collect Linux/Unix details
SSH credentials	Interactive	Prompted if enabled
Enable WinRM	No	Collect Windows details
WinRM credentials	Interactive	Prompted if enabled
iTOP Organization	Demo	Reconciliation org name
iTOP Location	(blank)	Optional location
iTOP Brand	(blank)	Optional brand
iTOP Model	(blank)	Optional model

Invalid inputs are rejected gracefully; the menu returns after each action.

CLI Reference

scan — Discover and save a snapshot

scan targets [targets ...]
  --db DB_PATH                    Default: snapshots.db
  --outdir OUTDIR                 Default: .
  --label LABEL                   Snapshot label
  --notes NOTES                   Free-form notes
  --workers N                     Default: 128
  --ping-timeout MS               Default: 800
  --port-timeout SEC              Default: 0.5
  --skip-ping                     Skip ICMP; use TCP probes only
  --ports P1,P2,...               Custom port list (default: common set)

  --enable-ssh                    Enable SSH collector
  --ssh-user USERNAME
  --ssh-pass PASSWORD
  --ssh-key PATH
  --ssh-timeout SEC               Default: 5

  --enable-winrm                  Enable WinRM collector
  --winrm-user USERNAME
  --winrm-pass PASSWORD
  --winrm-ssl                     Use HTTPS (port 5986)
  --winrm-port PORT               Override port
  --winrm-timeout SEC             Default: 8

  --enable-snmp                   Enable SNMP collector
  --snmp-community STRING         Default: public
  --snmp-port PORT                Default: 161
  --snmp-timeout SEC              Default: 5

  --itop-org NAME                 Default: Demo
  --itop-location NAME
  --itop-brand NAME
  --itop-model NAME

If credentials are omitted for SSH or WinRM, the tool interactively prompts at runtime. Press Enter to skip that collector for hosts where it is unavailable.

list — Show saved snapshots

list --db DB_PATH                 Default: snapshots.db

diff — Compare two snapshots

diff --db DB_PATH --old ID --new ID [--outdir OUTDIR]

Produces diff-{old}-to-{new}.json and diff-{old}-to-{new}.csv.

Scan Examples

Basic discovery (no enrichment)

python netmapper_v5.py scan "192.168.1.0/24" `
  --label "Baseline" --db snapshots.db --outdir . --workers 256

SNMP-only enrichment (no credentials needed)

python netmapper_v5.py scan "192.168.100.1-192.168.100.254" `
  --enable-snmp --snmp-community public `
  --label "SNMP-only" --db snapshots.db --outdir .

SSH with prompted credentials

python netmapper_v5.py scan "192.168.100.1-192.168.100.254" `
  --enable-ssh --label "SSH scan" --db snapshots.db --outdir .

You will be prompted:

--- SSH credentials ---
Enter SSH username (or press Enter to skip ssh): admin
Enter SSH password (or press Enter to skip): ********

WinRM with inline credentials (for automation)

python netmapper_v5.py scan "192.168.100.1-192.168.100.254" `
  --enable-winrm --winrm-user "DOMAIN\svc_scan" --winrm-pass "Secret123" `
  --label "WinRM scan" --db snapshots.db --outdir .

Full combined scan (enterprise baseline)

python netmapper_v5.py scan "192.168.100.1-192.168.109.253" `
  --label "Full Enriched Scan" `
  --db snapshots.db --outdir C:\NetMapper\Outputs `
  --workers 128 --skip-ping `
  --enable-snmp --snmp-community public `
  --enable-ssh --ssh-user admin --ssh-key C:\Users\admin\.ssh\id_rsa `
  --enable-winrm --winrm-user "DOMAIN\svc_scan" --winrm-pass "Secret123" `
  --itop-org "My Organization" --itop-location "Main DC"

Diff & List Examples

List all snapshots

python netmapper_v5.py list --db snapshots.db

Output:

   3  2026-05-07T10:27:41.965916-04:00  Full Enriched Scan  192.168.100.1-192.168.109.253
   2  2026-05-06T14:12:33.112233-04:00  Baseline            192.168.1.0/24
   1  2026-05-05T09:00:00.000000-04:00  Initial             192.168.100.1-192.168.100.254

Diff two snapshots

python netmapper_v5.py diff --db snapshots.db --old 1 --new 3 --outdir .

Produces:

• diff-1-to-3.json — structured additions, removals, and per-field changes
• diff-1-to-3.csv — flat change log for spreadsheet review

Collector Details

SSH Collector (Linux / Unix)

Runs the following commands remotely:

Command	Purpose
hostname	System hostname
uname -sr	Kernel name and version
cat /etc/os-release	Operating system identification
ss -tulpen or netstat -tulpen	Listening TCP/UDP sockets with process info
systemctl list-units --type=service --state=running or service --status-all	Running services
ip route	IPv4 routing table

Requires:

• Python paramiko library
• Target host reachable on TCP/22
• Valid username + password or SSH private key
• Non-interactive sudo not required (commands run as the authenticated user)

WinRM Collector (Windows)

Executes a PowerShell script remotely via NTLM over HTTP(S) that returns:

Data	Source
HOSTNAME	$env:COMPUTERNAME
OS	Get-CimInstance Win32_OperatingSystem
SERVICES	Get-Service (running only, top 50)
TCP	Get-NetTCPConnection (Listen state, top 100)
COMPINFO	Get-ComputerInfo (product name, version, HAL, architecture, domain)

Requires:

• Python pywinrm library
• Target host reachable on TCP/5985 (HTTP) or TCP/5986 (HTTPS)
• Windows Remote Management enabled (winrm quickconfig)
• NTLM authentication allowed (or Basic if SSL is used)

SNMP Collector (MIB-II + HOST-RESOURCES-MIB)

Walks the following OID trees:

OID Base	Table	Data Extracted
1.3.6.1.2.1.1	System	sysDescr, sysObjectID, sysUpTime, sysContact, sysName, sysLocation
1.3.6.1.2.1.2.2.1	Interfaces	Description, type, speed, MAC, status
1.3.6.1.2.1.4.20.1	IP Address Table	IP addresses, netmasks
1.3.6.1.2.1.4.21.1	IP Route Table	Destinations, next hops, route types
1.3.6.1.2.1.4.22.1	ARP Table	MAC-to-IP mappings
1.3.6.1.2.1.6.13.1	TCP Connections	Connection states
1.3.6.1.2.1.7.5.1	UDP Endpoints	Local addresses and ports
1.3.6.1.2.1.25.2.3.1	Storage	Descriptions, size, used
1.3.6.1.2.1.25.3.2.1	Devices	Device descriptions and status
1.3.6.1.2.1.25.4.2.1	Processes	Process names, paths, parameters
1.3.6.1.2.1.25.6.3.1	Software	Installed software names and types

Requires:

• Python pysnmp and pyasn1 libraries
• Target host reachable on UDP/161
• Matching SNMP community string (read-only sufficient)
• SNMP agent configured to expose standard MIB-II and HOST-RESOURCES-MIB

iTOP 3.2.x CSV Export

After every scan, NetMapper writes itop_import/*.csv files ready for iTOP's Data Import wizard.

Supported iTOP Classes

NetMapper Role	iTOP Class	Reconciliation Key(s)
General alive host	Server	name
Host with PC-like roles	PC	name
Host tagged printer	Printer	name
Host tagged switch, firewall, router, ups	NetworkDevice	name
All alive hosts	PhysicalInterface	name + connectableci_id->name

CSV Column Reference

Server name, org_id->name, status, business_criticity, location_id->name, brand_id->name, model_id->name, serialnumber, asset_number, managementip, osfamily_id->name, osversion_id->name, cpu, ram, description

PC Same as Server plus type (set to desktop).

Printer name, org_id->name, status, business_criticity, location_id->name, brand_id->name, model_id->name, serialnumber, asset_number, description

NetworkDevice Same as Server plus networkdevicetype_id->name (inferred from roles: Switch, Router, Firewall, UPS).

PhysicalInterface name, connectableci_id->name, ipaddress, macaddress, ipgateway, ipmask, speed, comment

Import Procedure

1. Run the scan with your iTOP organization (and optionally location/brand/model):

   python netmapper_v5.py scan "192.168.100.1-192.168.109.253" `
     --label "iTOP Import" --outdir . --workers 128 --skip-ping `
     --enable-snmp --itop-org "My Organization" --itop-location "HQ"

2. Open iTOP Admin tools > CSV Import.
3. For each class, choose the matching CSV from itop_import/:
   • Import Server, PC, Printer, and NetworkDevice first (the parent CIs).
   • Import PhysicalInterface last so connectableci_id->name resolves to existing CIs.
4. In the iTOP import wizard:
   • Search for existing: Use name as the reconciliation key.
   • Field mapping: Verify org_id->name, location_id->name, and other -> fields resolve to existing iTOP organizations/locations/brands/models. If they do not exist in iTOP, create them first or leave them blank.
5. Review the import simulation, then execute.

Important iTOP Notes

• If org_id->name does not match an existing Organization in iTOP, the import row will fail unless you pre-create it or set it to blank.
• connectableci_id->name in PhysicalInterface must exactly match the name field of the already-imported Server/PC/Printer/NetworkDevice.
• MAC addresses are extracted from SNMP interface_macs if available; otherwise the field is blank.
• Subnet masks and interface speeds are populated from SNMP ip_masks and interface_speeds when the device responds to SNMP.

Output Files

After each scan, the output directory contains:

File	Purpose
snapshots.db	SQLite database with all historical snapshots
snapshot-{id}.json	Complete JSON dump of the selected snapshot
snapshot-{id}-hosts.csv	Flat CSV: IP, alive, hostname, OS, roles, ports, latency, collector status
itop_import/Server.csv	iTOP import for Server CIs
itop_import/PC.csv	iTOP import for PC CIs (only if mapped)
itop_import/Printer.csv	iTOP import for Printer CIs (only if mapped)
itop_import/NetworkDevice.csv	iTOP import for NetworkDevice CIs (only if mapped)
itop_import/PhysicalInterface.csv	iTOP import for interface attachments (always generated for alive hosts)
netmapper-v5-ui.html	Standalone browser dashboard; open directly, no web server required

After a diff, the output directory additionally contains:

File	Purpose
diff-{old}-to-{new}.json	Structured diff with added/removed/changed hosts
diff-{old}-to-{new}.csv	Flat change log suitable for Excel review

Web UI

netmapper-v5-ui.html is a zero-dependency static HTML file that uses sql.js to read snapshots.db directly in the browser.

How to use

1. Open netmapper-v5-ui.html in any modern browser (Chrome, Edge, Firefox).
2. Click Load files and select snapshots.db.
3. The snapshots list populates automatically. Click any snapshot to view:
   • KPIs: total hosts, alive count, unique roles, collector hits, diff changes
   • Role summary: sorted frequency list
   • Host table: searchable and filterable by IP, hostname, role, port, or collector
4. To view a diff, load a diff-*.json file into the Load files panel alongside the database.

No web server, no backend, no JavaScript build step required.

Troubleshooting

"paramiko not installed" or "pywinrm not installed" or "pysnmp not installed"

Install the missing library:

python -m pip install paramiko pywinrm pysnmp pyasn1

Collector prompts appear but I want to skip them

Press Enter at the username prompt to skip SSH/WinRM for that run. For SNMP, press Enter to accept the default community.

No hosts discovered

• Verify the target range is correct: 192.168.1.1-192.168.1.254 (not 192.168.1.0-192.168.1.255; .0 and .255 are auto-excluded)
• Try without --skip-ping if ICMP is allowed
• Increase --port-timeout if the network is latent
• Reduce --workers if the target network has aggressive rate-limiting

SNMP returns no data

• Confirm the target is reachable on UDP/161: Test-NetConnection -ComputerName 192.168.1.1 -Port 161 -Udp
• Verify the community string matches the device configuration
• Check that the SNMP agent exposes MIB-II and HOST-RESOURCES-MIB
• Some firewalls block SNMP; verify outbound UDP/161 is open from the scanning host

WinRM connection fails

• On the target Windows host, run winrm quickconfig as Administrator
• Verify the scanning host can reach TCP/5985 (HTTP) or TCP/5986 (HTTPS)
• Check that the WinRM service is running: Get-Service WinRM
• For cross-domain or workgroup scenarios, ensure NTLM is permitted or use SSL with explicit credentials

SSH key authentication fails

• Ensure the private key is in PEM format (OpenSSH format is supported by modern Paramiko)
• Verify the corresponding public key is in ~/.ssh/authorized_keys on the target
• Use --ssh-key with the full path to the key file

Database is locked

• Only one NetMapper process should write to snapshots.db at a time
• If the web UI is open in a browser with the same DB file selected, close the UI tab before running a new scan

iTOP import fails with "org_id->name not found"

• Create the Organization in iTOP first (Data administration > Organizations > New)
• Or leave --itop-org blank and map the field manually during import

Security Notes

• Credentials: The tool prompts for passwords interactively when not provided via CLI. Passwords are not logged to disk or output files. However, they exist in memory during the scan and are passed to underlying libraries (Paramiko, pywinrm). Do not run on shared systems where memory inspection is a concern.
• Key Files: If using --ssh-key, ensure the key file has restrictive permissions (600 on Unix; NTFS ACLs on Windows).
• Output Files: snapshot-*.json contains full collector output including hostnames, services, and routes. Store these files securely and limit read access.
• Network Impact: Default 128 threads can be aggressive on small networks. Reduce --workers for sensitive or bandwidth-constrained environments.
• WinRM SSL: When using --winrm-ssl, the tool ignores certificate validation (server_cert_validation='ignore'). This simplifies self-signed certificate scenarios but reduces MITM protection. Use only on trusted networks.
• SNMP Community: The default is public. Change this immediately in production environments and use SNMPv3 if the target devices support it.