Network Analytics Toolkit

A comprehensive Python toolkit for network discovery, scanning, traffic analysis, topology mapping, security assessment, WiFi spatial analysis, IoT device security, and AI-native integration via MCP.

Features

• Network Discovery -- ARP and ICMP host discovery with vendor identification
• Port Scanning -- SYN and connect scans with service/version detection
• Traffic Analysis -- Packet capture, pcap analysis, protocol extraction (HTTP, DNS)
• Topology Mapping -- NetworkX-based graph construction with centrality metrics, PNG/GraphML export, snapshot/diff tracking
• Mesh Topology Optimization -- Redundancy scoring, cascading-failure simulation, and link recommendations
• Security Assessment -- Vulnerability checks, risk scoring, and reporting (HTML/MD/JSON)
• WiFi Spatial Analysis -- 3D heatmaps (Plotly), CSI human presence detection, WebGL space mapping
• WiFi Security -- Client isolation bypass assessment (AirSnitch, NDSS 2026), 7-stage MitM attack chain assessment, encryption audit, rogue AP detection
• WiFi Health & Optimization -- Unified health scoring (signal, channel, security, coverage, performance), optimization engine with prioritized suggestions, interactive Plotly dashboard
• IoT Security -- ONVIF camera scanning, firmware analysis, UEFI rootkit detection, APK auditing, UART/telnet enumeration, CVE lookup via NIST NVD
• Network Wrappers -- mtr path tracing, tcpdump/ngrep/tcpflow, bandwidth monitoring (bandwhich/vnstat), iperf3 benchmarks
• Smart Home -- Device discovery, cloud token retrieval, command execution
• BLE Positioning -- Beacon scanning, trilateration, direction finding (AoA/AoD), Channel Sounding, crowd density, asset tracking
• BLE Security -- Research-paper-based vulnerability checks (BLUFFS, WhisperPair, PerfektBlue, Airoha RACE, BLURtooth, BlueScream)
• MCP Server -- 150+ tools exposed via Model Context Protocol for AI assistant integration

Installation

# Using uv (recommended)
uv sync

# Or using pip
pip install -e .

Prerequisites

Some features require elevated privileges and external tools:

• Root/sudo required for: ARP/ICMP discovery, SYN scans, packet capture.
• External tools:
  • nmap for advanced scanning (via python-nmap)
  • tshark or tcpdump for deeper packet inspection workflows

Install hints:

• macOS (Homebrew):
  • brew install nmap wireshark
  • brew install tcpdump (usually preinstalled)
• Ubuntu/Debian:
  • sudo apt install nmap tshark tcpdump
• Fedora:
  • sudo dnf install nmap wireshark-cli tcpdump

Quick Start

Network Discovery and Scanning

# Discover hosts on local network (requires root)
sudo uv run netanalytics discover 192.168.1.0/24 --method arp

# Port scan
uv run netanalytics scan 192.168.1.1 --ports 22,80,443

# Security assessment
uv run netanalytics security 192.168.1.1 --level basic

# Security risk heatmap dashboard
uv run netanalytics security-heatmap --mock --mock-hosts 8 --show

# Generate report
uv run netanalytics report 192.168.1.1 --format html

Traffic Analysis

# Capture traffic (requires root)
sudo uv run netanalytics capture en0 --count 100 -o capture.pcap

# Analyze pcap
uv run netanalytics analyze capture.pcap --protocol http

# Interactive D3.js topology visualization
uv run netanalytics topology-viz --mock --mock-nodes 20 --show

# Optimize a topology from pcap
uv run netanalytics mesh-optimize --pcap capture.pcap -o results/mesh-opt.json

WiFi and 3D Visualization

# Scan visible WiFi networks
uv run netanalytics wifi scan

# Generate 3D WebGL space map (demo mode, no hardware needed)
uv run netanalytics wifi space-map --demo --humans 5 --show

# 3D pose visualization from WiFi CSI sensing
uv run netanalytics wifi pose-viz --mock --num-people 4 --show

# CSI point cloud visualization
uv run netanalytics wifi pointcloud-viz --mock --count 200 --show

# Interactive cross-section slicer for 3D heatmaps
uv run netanalytics wifi cross-section --demo --show

# Create a survey and generate 3D heatmap
uv run netanalytics wifi survey-create office --ssid "CorpWiFi"
uv run netanalytics wifi heatmap results/wifi-surveys/survey_office.json --mode volume --show

# CSI human presence detection (mock data)
uv run netanalytics wifi csi-mock --samples 100 -o /tmp/csi.json
uv run netanalytics wifi csi-process /tmp/csi.json --detect --threshold 0.8

WiFi Health & Optimization

# Unified WiFi health assessment (mock mode)
uv run netanalytics wifi health --mock

# Health assessment with interactive Plotly dashboard
uv run netanalytics wifi health --mock --viz --show

# Generate optimization plan
uv run netanalytics wifi optimize --mock

# Optimization plan with dashboard visualization
uv run netanalytics wifi optimize --mock --viz --show

IoT Security

# Discover ONVIF/IoT devices via WS-Discovery
uv run netanalytics iot wsdiscover

# Scan ONVIF camera for auth bypass
uv run netanalytics iot onvifscan 192.168.1.100

# Analyze firmware
uv run netanalytics iot ffind firmware.bin --deep

# Audit Android APK
uv run netanalytics iot apk app.apk --decompile -o apk-analysis.json

BLE Positioning

# Scan for BLE beacons (mock)
uv run netanalytics ble scan --mock

# BLE RSSI trilateration
uv run netanalytics ble trilaterate --mock --beacon-count 8

# BLE 5.1 direction finding (MUSIC algorithm)
uv run netanalytics ble direction-find --mock --method music --array-type linear

# BLE 6.0 Channel Sounding ranging
uv run netanalytics ble channel-sound --mock --mode mode_2 --num-channels 40

Smart Home

# Discover smart home devices on the network
uv run netanalytics smarthome discover

# Get device details
uv run netanalytics smarthome info <device-id>

# Retrieve cloud service tokens
uv run netanalytics smarthome cloud-tokens

Architecture

src/netanalytics/
  cli/                Click-based CLI package (subgroups: wifi, ble, iot, smarthome)
  core/               Config, exceptions, utilities
  discovery/          ARP/ICMP/port scanning
  traffic/            Packet capture and pcap analysis
  topology/           NetworkX graph construction
  security/           Vulnerability checks and risk scoring
  wifi/               Scanning, surveys, 3D heatmaps, CSI processing, space mapper, health assessment, optimization
  ble/                BLE scanning, trilateration, direction finding, mesh topology
  fusion/             Multi-sensor EKF (WiFi + BLE + IMU)
  iot/                ONVIF, firmware, APK, UART, telnet
  wrappers/           nmap, tshark, mtr, tcpdump, ngrep, tcpflow, bandwidth, iperf3
  smarthome/          Smart home device integration
  output/             Report generation (HTML, Markdown, JSON)

mcp/netanalytics-mcp/
  netanalytics_mcp/
    server.py         FastMCP server entry point
    tools/            Tool implementations (one file per category)
    resources/        MCP resource providers

See docs/ARCHITECTURE.md for detailed module descriptions and data flow.

Configuration

The CLI reads configuration from .netanalytics.json in the current working directory by default. You can override the path with NETANALYTICS_CONFIG.

export NETANALYTICS_CONFIG=/path/to/netanalytics.json

Key settings include results_dir, scan timeouts/rate limits, capture defaults, and topology visualization options. See src/netanalytics/core/config.py for the full schema.

Utilities

The netanalytics.devtools package includes helper utilities:

• src/netanalytics/devtools/doctor.py -- environment checks (Python version, deps, external tools)
• src/netanalytics/devtools/sample_data.py -- generate sample JSON outputs for demos/tests
• src/netanalytics/devtools/bench.py -- benchmark scan throughput and latency
• src/netanalytics/devtools/report_batch.py -- batch report generation for multiple targets
• src/netanalytics/devtools/update_oui.py -- download and cache OUI vendor list
• src/netanalytics/devtools/pcap_summarize.py -- quick pcap summary without full report

Running Tests

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov

# Run a specific test file
uv run pytest tests/test_discovery.py

MCP Server

The toolkit includes an MCP server exposing 150+ tools for AI integration:

# Install MCP server
./scripts/install-mcp.sh

# Test interactively
uv run fastmcp dev mcp/netanalytics-mcp/netanalytics_mcp/server.py

See mcp/netanalytics-mcp/README.md for the full tool list and configuration.

Documentation

• Architecture -- module structure, data flow, design decisions
• Configuration -- config file schema and CLI overrides
• Roadmap -- future features and research directions
• Contributing -- development setup, code style, testing, adding features
• MCP Server -- AI integration tools and resources
• CLAUDE.md -- exhaustive CLI reference and MCP tool catalog

Requirements

• Python 3.11+
• Root/sudo for: ARP/ICMP scanning, SYN scans, packet capture

License

MIT