VisionMap

VisionMap is a visualization and analysis tool for network scan results. It parses Nmap, masscan, Nessus, and CSV scan output, builds interactive network graphs, flags risky services, and generates reports - all from the browser or the command line.

Features

• Interactive 2D and 3D Network Graphs - Zoom, pan, click nodes for details. Dark-themed plotly rendering in the browser.
• Risk Analysis - Automatically flags dangerous services (telnet, exposed databases, Redis without auth, SMB, FTP) with severity ratings. No CVE database needed.
• Scan Diff - Compare two scans side by side. See new hosts, removed hosts, opened/closed ports, and changed services at a glance.
• Host Detail Panel - Click any node to see full port table, OS info, vendor, risk findings, and diff annotations.
• Report Generation - One-click HTML report with network diagram, host inventory, risk findings table, and diff summary.
• Multiple Input Formats - Nmap XML, masscan (XML and JSON), Nessus v2 XML, and CSV with flexible column detection.
• Service-Based Coloring - Color nodes by dominant service type (web, database, mail, file, remote) instead of just port count.
• Five Layout Algorithms - Spring, Kamada-Kawai, circular, shell, hierarchical. Auto-downgrades for large graphs.
• Scalable - Hierarchical LOD with collapsible subnets, scale-aware rendering, layout caching (memory + disk).
• Search with Highlight - Type an IP, hostname, or service to highlight matching nodes without filtering the rest away.
• Session Persistence - Save your analysis state (scan, filters, layout, expanded subnets) to a .visionmap file and reload it later.
• CLI Export - JSON, CSV, PNG, SVG, and interactive HTML from the command line.
• IPv4 and IPv6 - Full support for both address families with proper subnet grouping.
• Traceroute Visualization - Directed hop edges when traceroute data is present.

Installation

Requires Python 3.10 or later.

git clone https://github.com/prodrom3/VisionMap.git
cd VisionMap
pip install -r requirements.txt

Or install as a package:

pip install .

Usage

Web UI

# Launch the web UI (opens browser automatically)
python -m visionmap

# Load a scan file on startup
python -m visionmap scan.xml

# Use a custom port
python -m visionmap scan.xml --server-port 8080

The web UI provides:

• Upload area for scan files (Nmap XML, masscan, Nessus, CSV) and diff scans
• Layout/dimension/coloring controls in the sidebar
• Live search bar that highlights matching nodes
• Port/OS/subnet filters with debounced live updates
• Click any host to open the detail panel with full port table and risk findings
• Click any subnet to expand/collapse it (LOD)
• Export Report button for a self-contained HTML report
• Save/Load Session for persisting your analysis

Command-Line Mode

# Export to interactive HTML
python -m visionmap --cli -i scan.xml -o network.html

# Export to PNG (requires kaleido: pip install kaleido)
python -m visionmap --cli -i scan.xml -o network.png

# Export to SVG
python -m visionmap --cli -i scan.xml -o network.svg --layout kamada_kawai

# JSON output
python -m visionmap --cli -i scan.xml --json

# CSV output (one row per port per host)
python -m visionmap --cli -i scan.xml --csv

# Filter by port and OS
python -m visionmap --cli -i scan.xml -o filtered.html --port 80 --os Linux

# Custom dimensions and verbose logging
python -m visionmap --cli -i scan.xml -o large.png --width 2560 --height 1440 --verbose

Supported Input Formats

Format	Extensions	Auto-detected
Nmap XML	.xml	Yes (default for XML)
Masscan XML	.xml	Yes (by scanner="masscan" attribute)
Masscan JSON	.json	Yes
Nessus v2	.xml, .nessus	Yes (by NessusClientData_v2 root)
CSV	.csv	Yes

CSV files are parsed flexibly - columns can be named ip/host/address, port/portid, service/svc_name, etc.

CLI Flags

Flag	Description
input_file	Scan file (positional, opens web UI)
-v, --version	Show version and exit
--verbose	Enable verbose logging
--cli	Command-line mode (no web UI)
-i, --input	Input scan file
-o, --output	Output file (.png, .svg, .html)
--layout	Algorithm: spring, kamada_kawai, circular, shell, hierarchical
--3d	Force 3D visualization
--width	Image width in pixels (default: 1920, max: 7680)
--height	Image height in pixels (default: 1080, max: 4320)
--dpi	Image DPI (default: 150, max: 600)
--title	Title for the visualization
--json	Output parsed data as JSON
--csv	Output parsed data as CSV
--port	Filter: hosts with this port open
--os	Filter: hosts matching OS (case-insensitive)
--subnet	Filter: hosts in this subnet prefix
--server-port	Web UI port (default: 5000)

Architecture

visionmap/
  __init__.py       Package init, version
  __main__.py       Entry point, CLI/web dispatch, logging
  cli.py            Argument parsing
  parser.py         Streaming Nmap XML parser (iterparse), dataclasses
  formats.py        Multi-format loader (Nmap, masscan, Nessus, CSV)
  graph.py          Hierarchical graph model, GraphContext, filtering, LOD
  layout.py         Layout algorithms, auto-scaling, caching (memory + disk)
  renderer.py       Unified plotly renderer (2D + 3D), service coloring
  theme.py          Shared constants, enums, colors, risk/service categories
  risks.py          Risk analysis engine (14 rules, no CVE DB needed)
  diff.py           Scan comparison (new/removed/changed hosts and ports)
  report.py         HTML report generation
  session.py        Session save/load (.visionmap files)
  export.py         PNG/SVG/HTML export pipeline
  server.py         Flask web UI with REST API

Dependencies

Required:

• Python >= 3.10
• networkx >= 3.0
• plotly >= 5.0
• defusedxml >= 0.7
• flask >= 3.0

Optional:

• kaleido >= 0.2 (PNG/SVG static image export)
• scipy >= 1.10 (Kamada-Kawai layout)
• pandas >= 2.0 (data handling)
• geopy >= 2.0 (IP geocoding)

Testing

# Run all tests (141 tests)
python -m unittest discover -s tests -v

# Run a single module
python -m unittest tests.test_risks -v

Test coverage includes: XML parsing (Nmap, masscan, CSV), graph construction and filtering, layout algorithms and caching, risk analysis, scan diffing, service classification, report generation, session persistence, CLI argument parsing, renderer output, web API endpoints, and Flask integration.

Contributing

Contributions to VisionMap are welcome! Please review the CONTRIBUTING.md file for guidelines on how to submit issues, feature requests, and code patches.

Author

Created by prodrom3 / radamic

License

VisionMap is released under the MIT License. See the LICENSE file for more details.