Reorganize project structure: move code to src/, docs to docs/, config to config/, scripts to scripts/, results to results/, tests to tests/. Keep only main script and latest scan results in root.

scripts/EXAMPLES.sh

@@ -0,0 +1,265 @@
+#!/bin/bash
+# Example usage scenarios for the network scanner
+
+echo "=========================================="
+echo "Network Scanner - Usage Examples"
+echo "=========================================="
+echo ""
+
+cat << 'EOF'
+# SCENARIO 1: Quick Network Overview
+# -----------------------------------
+# Scan your local network and get a basic overview
+
+./network_scanner.py -v -o quick_scan.json
+
+
+# SCENARIO 2: Complete Network Documentation
+# -------------------------------------------
+# Full scan with pfSense integration and SVG generation
+
+./integrated_scanner.py -c config.json -o full_network.json --generate-svg -v
+
+# View the diagram:
+firefox full_network.svg
+
+
+# SCENARIO 3: pfSense Deep Dive
+# ------------------------------
+# Detailed scan of a specific pfSense firewall
+
+./pfsense_scanner.py 192.168.1.1 -u root -k ~/.ssh/id_rsa -o pfsense_main.json
+
+# View the results:
+cat pfsense_main.json | jq '.vpn'  # Show VPN info
+cat pfsense_main.json | jq '.routes'  # Show routing table
+
+
+# SCENARIO 4: Multi-Network Scan with VPN
+# ----------------------------------------
+# Create a config for multiple networks
+
+cat > my_network_config.json << 'CONFIG'
+{
+  "ssh_user": "root",
+  "ssh_key_path": "/home/user/.ssh/id_rsa",
+  "timeout": 3,
+  "additional_networks": [
+    "192.168.1.0/24",      # Main network
+    "192.168.2.0/24",      # Guest network
+    "10.8.0.0/24",         # OpenVPN network
+    "10.0.0.0/24"          # WireGuard VPN
+  ],
+  "special_devices": {
+    "192.168.1.1": {
+      "name": "Main pfSense Firewall",
+      "type": "firewall",
+      "os": "pfSense"
+    },
+    "192.168.2.1": {
+      "name": "Guest Network Router",
+      "type": "router"
+    }
+  }
+}
+CONFIG
+
+./integrated_scanner.py -c my_network_config.json -o multi_network.json --generate-svg
+
+
+# SCENARIO 5: Scheduled Network Monitoring
+# -----------------------------------------
+# Add to crontab for daily network documentation
+
+# Create wrapper script
+cat > /usr/local/bin/network-scan-daily.sh << 'SCRIPT'
+#!/bin/bash
+DATE=$(date +%Y%m%d)
+OUTPUT_DIR="/var/log/network-scans"
+mkdir -p "$OUTPUT_DIR"
+
+cd /path/to/network_scanner
+./integrated_scanner.py \
+    -o "$OUTPUT_DIR/scan_$DATE.json" \
+    --generate-svg
+
+# Keep only last 30 days
+find "$OUTPUT_DIR" -name "scan_*.json" -mtime +30 -delete
+find "$OUTPUT_DIR" -name "scan_*.svg" -mtime +30 -delete
+SCRIPT
+
+chmod +x /usr/local/bin/network-scan-daily.sh
+
+# Add to crontab (run at 2 AM daily):
+# 0 2 * * * /usr/local/bin/network-scan-daily.sh
+
+
+# SCENARIO 6: Compare Network Changes
+# ------------------------------------
+# Scan and compare with previous results
+
+# Initial scan
+./integrated_scanner.py -o baseline.json
+
+# After changes
+./integrated_scanner.py -o current.json
+
+# Compare device counts
+echo "Baseline devices:"
+cat baseline.json | jq '[.segments[].devices[].ip] | length'
+echo "Current devices:"
+cat current.json | jq '[.segments[].devices[].ip] | length'
+
+# Find new devices
+comm -13 \
+    <(cat baseline.json | jq -r '.segments[].devices[].ip' | sort) \
+    <(cat current.json | jq -r '.segments[].devices[].ip' | sort) \
+    | sed 's/^/NEW: /'
+
+# Find removed devices
+comm -23 \
+    <(cat baseline.json | jq -r '.segments[].devices[].ip' | sort) \
+    <(cat current.json | jq -r '.segments[].devices[].ip' | sort) \
+    | sed 's/^/REMOVED: /'
+
+
+# SCENARIO 7: Extract Specific Information
+# -----------------------------------------
+# Use jq to extract specific data from scan results
+
+# List all SSH-accessible devices
+cat network_scan.json | jq -r '.segments[].devices[] | select(.ssh_accessible==true) | .ip'
+
+# List all routers/firewalls
+cat network_scan.json | jq -r '.segments[].devices[] | select(.device_type=="router" or .device_type=="firewall") | "\(.ip) - \(.hostname // "unknown")"'
+
+# List all devices with their OS
+cat network_scan.json | jq -r '.segments[].devices[] | "\(.ip)\t\(.os_type // "unknown")\t\(.hostname // "unknown")"'
+
+# Export to CSV
+echo "IP,Hostname,Type,OS" > devices.csv
+cat network_scan.json | jq -r '.segments[].devices[] | "\(.ip),\(.hostname // ""),\(.device_type // ""),\(.os_type // "")"' >> devices.csv
+
+
+# SCENARIO 8: Integration with Documentation
+# -------------------------------------------
+# Generate markdown documentation from scan
+
+cat > generate_docs.py << 'PYTHON'
+#!/usr/bin/env python3
+import json
+import sys
+
+with open(sys.argv[1]) as f:
+    data = json.load(f)
+
+print("# Network Documentation")
+print(f"\nGenerated: {data.get('scan_timestamp', 'N/A')}")
+print("\n## Network Segments\n")
+
+for segment in data['segments']:
+    print(f"### {segment['name']}")
+    print(f"- CIDR: `{segment['cidr']}`")
+    print(f"- Devices: {len(segment['devices'])}")
+    if segment.get('is_vpn'):
+        print("- Type: VPN Network")
+    print("\n#### Devices\n")
+    print("| IP | Hostname | Type | OS |")
+    print("|---|---|---|---|")
+    
+    for device in segment['devices']:
+        ip = device['ip']
+        hostname = device.get('hostname', '-')
+        dtype = device.get('device_type', '-')
+        os = device.get('os_type', '-')
+        print(f"| {ip} | {hostname} | {dtype} | {os} |")
+    
+    print()
+PYTHON
+
+chmod +x generate_docs.py
+./generate_docs.py network_scan.json > NETWORK_DOCS.md
+
+
+# SCENARIO 9: Security Audit
+# ---------------------------
+# Check for common security issues
+
+# Find devices with Telnet open
+cat network_scan.json | jq -r '.segments[].devices[] | select(.open_ports[]? == 23) | "⚠️  Telnet open on \(.ip) (\(.hostname // "unknown"))"'
+
+# Find devices without SSH access
+cat network_scan.json | jq -r '.segments[].devices[] | select(.device_type=="router" or .device_type=="firewall") | select(.ssh_accessible==false) | "⚠️  No SSH access to \(.ip) (\(.hostname // "unknown"))"'
+
+# List devices with many open ports
+cat network_scan.json | jq -r '.segments[].devices[] | select((.open_ports | length) > 5) | "ℹ️  \(.ip) has \(.open_ports | length) open ports"'
+
+
+# SCENARIO 10: WireGuard Topology Mapping
+# ----------------------------------------
+# Extract WireGuard tunnel information from pfSense
+
+./pfsense_scanner.py 192.168.1.1 -o pfsense.json
+
+# List all WireGuard peers
+cat pfsense.json | jq -r '.vpn.wireguard[] | "Peer: \(.peer // "N/A") -> \(.allowed_ips // "N/A")"'
+
+# Check tunnel status
+cat pfsense.json | jq -r '.vpn.wireguard[] | select(.latest_handshake) | "Active tunnel to \(.endpoint) (handshake: \(.latest_handshake)s ago)"'
+
+
+# SCENARIO 11: Network Capacity Planning
+# ---------------------------------------
+# Analyze network usage and plan capacity
+
+# Count devices per segment
+cat network_scan.json | jq -r '.segments[] | "\(.cidr): \(.devices | length) devices"'
+
+# Calculate subnet utilization
+cat network_scan.json | jq -r '.segments[] | 
+    if .cidr | contains("/24") then 
+        "\(.cidr): \(.devices | length)/254 = \((.devices | length) * 100 / 254 | floor)% utilized"
+    else 
+        "\(.cidr): \(.devices | length) devices"
+    end'
+
+
+# SCENARIO 12: Quick Health Check
+# --------------------------------
+# Create a health check script
+
+cat > health_check.sh << 'HEALTH'
+#!/bin/bash
+SCAN_FILE="latest_scan.json"
+
+echo "Network Health Check"
+echo "===================="
+echo ""
+
+# Total devices
+TOTAL=$(cat $SCAN_FILE | jq '[.segments[].devices[]] | length')
+echo "Total devices: $TOTAL"
+
+# SSH accessible
+SSH_OK=$(cat $SCAN_FILE | jq '[.segments[].devices[] | select(.ssh_accessible==true)] | length')
+echo "SSH accessible: $SSH_OK"
+
+# By type
+echo ""
+echo "Device Types:"
+cat $SCAN_FILE | jq -r '.segments[].devices[].device_type' | sort | uniq -c | sort -rn
+
+# Segments
+echo ""
+echo "Network Segments:"
+cat $SCAN_FILE | jq -r '.segments[] | "  \(.name): \(.devices | length) devices"'
+HEALTH
+
+chmod +x health_check.sh
+./integrated_scanner.py -o latest_scan.json
+./health_check.sh
+
+EOF
+
+echo ""
+echo "For more examples, see README.md"

scripts/quickstart.sh

@@ -0,0 +1,181 @@
+#!/bin/bash
+# Quick Start Script for Network Scanner
+# This script helps you get started quickly
+
+set -e
+
+echo "================================"
+echo "Network Scanner - Quick Start"
+echo "================================"
+echo ""
+
+# Check for Python
+if ! command -v python3 &> /dev/null; then
+    echo "❌ Error: Python 3 is not installed"
+    exit 1
+fi
+
+echo "✓ Python 3 found"
+
+# Create config if it doesn't exist
+if [ ! -f config.json ]; then
+    echo ""
+    echo "📝 Creating configuration file..."
+    
+    # Try to detect default SSH key
+    SSH_KEY=""
+    if [ -f ~/.ssh/id_rsa ]; then
+        SSH_KEY="$HOME/.ssh/id_rsa"
+    elif [ -f ~/.ssh/id_ed25519 ]; then
+        SSH_KEY="$HOME/.ssh/id_ed25519"
+    fi
+    
+    # Get current user
+    CURRENT_USER=$(whoami)
+    
+    # Try to detect local network
+    LOCAL_NET=$(ip route | grep -oP 'src \K[\d.]+' | head -1)
+    if [ -n "$LOCAL_NET" ]; then
+        # Convert to /24 network
+        NET_PREFIX=$(echo $LOCAL_NET | cut -d. -f1-3)
+        LOCAL_NET="${NET_PREFIX}.0/24"
+    else
+        LOCAL_NET="192.168.1.0/24"
+    fi
+    
+    cat > config.json << EOF
+{
+  "ssh_user": "$CURRENT_USER",
+  "ssh_key_path": "$SSH_KEY",
+  "timeout": 2,
+  "additional_networks": [
+    "$LOCAL_NET"
+  ],
+  "special_devices": {
+  },
+  "scan_options": {
+    "max_workers": 10,
+    "ping_timeout": 2,
+    "port_scan_timeout": 1
+  }
+}
+EOF
+    
+    echo "✓ Created config.json"
+    echo "  Local network detected: $LOCAL_NET"
+    [ -n "$SSH_KEY" ] && echo "  SSH key detected: $SSH_KEY"
+    echo ""
+    echo "  Please edit config.json to customize for your network!"
+    echo ""
+else
+    echo "✓ config.json already exists"
+fi
+
+# Ask what to do
+echo ""
+echo "What would you like to do?"
+echo ""
+echo "1) Run a quick scan (current network only)"
+echo "2) Run a full scan with pfSense integration"
+echo "3) Scan and generate SVG diagram"
+echo "4) Scan specific pfSense device"
+echo "5) Show help"
+echo "6) Exit"
+echo ""
+read -p "Choose an option (1-6): " choice
+
+case $choice in
+    1)
+        echo ""
+        echo "🔍 Running quick network scan..."
+        ./network_scanner.py -o quick_scan.json -v
+        echo ""
+        echo "✓ Done! Results saved to: quick_scan.json"
+        echo "  Generate diagram with: ./svg_generator.py quick_scan.json"
+        ;;
+    2)
+        echo ""
+        echo "🔍 Running full integrated scan..."
+        ./integrated_scanner.py -o full_scan.json -v
+        echo ""
+        echo "✓ Done! Results saved to: full_scan.json"
+        ;;
+    3)
+        echo ""
+        echo "🔍 Running scan and generating diagram..."
+        ./integrated_scanner.py -o scan_with_diagram.json -v --generate-svg
+        echo ""
+        echo "✓ Done! Open scan_with_diagram.svg to view the network diagram"
+        ;;
+    4)
+        echo ""
+        read -p "Enter pfSense IP address: " pfsense_ip
+        echo "🔍 Scanning pfSense at $pfsense_ip..."
+        ./pfsense_scanner.py "$pfsense_ip" -o "pfsense_${pfsense_ip}.json"
+        echo ""
+        echo "✓ Done! Results saved to: pfsense_${pfsense_ip}.json"
+        ;;
+    5)
+        echo ""
+        cat << 'HELP'
+Network Scanner - Help
+======================
+
+Available Scripts:
+-----------------
+
+1. network_scanner.py
+   Basic network scanner that discovers devices and gathers info
+   Usage: ./network_scanner.py [-c config.json] [-o output.json] [-v]
+
+2. pfsense_scanner.py
+   Specialized scanner for pfSense firewalls
+   Usage: ./pfsense_scanner.py <ip> [-u user] [-k keyfile] [-o output.json]
+
+3. integrated_scanner.py
+   Complete scanner with pfSense integration
+   Usage: ./integrated_scanner.py [-c config.json] [-o output.json] [-v] [--generate-svg]
+
+4. svg_generator.py
+   Generate SVG diagram from scan results
+   Usage: ./svg_generator.py <input.json> [-o output.svg]
+
+Configuration:
+-------------
+Edit config.json to customize:
+- SSH credentials
+- Network ranges to scan
+- Special device definitions
+- Scan timeouts
+
+Examples:
+--------
+# Quick scan of current network
+./network_scanner.py -v
+
+# Full scan with diagram
+./integrated_scanner.py --generate-svg
+
+# Scan pfSense
+./pfsense_scanner.py 192.168.1.1 -u root -k ~/.ssh/id_rsa
+
+# Generate diagram from existing scan
+./svg_generator.py network_scan.json -o my_network.svg
+
+For more information, see README.md
+HELP
+        ;;
+    6)
+        echo "Goodbye!"
+        exit 0
+        ;;
+    *)
+        echo "Invalid option"
+        exit 1
+        ;;
+esac
+
+echo ""
+echo "================================"
+echo "Thanks for using Network Scanner!"
+echo "================================"

scripts/run_network_mapping.sh

@@ -0,0 +1,214 @@
+#!/bin/bash
+# Complete Network Mapping Workflow
+# This script runs the full network discovery and diagram generation process
+
+set -e  # Exit on any error
+
+echo "=========================================="
+echo "COMPREHENSIVE NETWORK MAPPING WORKFLOW"
+echo "=========================================="
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# Function to print colored output
+print_status() {
+    echo -e "${GREEN}[INFO]${NC} $1"
+}
+
+print_warning() {
+    echo -e "${YELLOW}[WARN]${NC} $1"
+}
+
+print_error() {
+    echo -e "${RED}[ERROR]${NC} $1"
+}
+
+print_step() {
+    echo -e "${BLUE}[STEP]${NC} $1"
+}
+
+# Check if required files exist
+check_requirements() {
+    print_step "Checking requirements..."
+
+    if [ ! -f "network_scanner.py" ]; then
+        print_error "network_scanner.py not found!"
+        exit 1
+    fi
+
+    if [ ! -f "pfsense_xml_parser.py" ]; then
+        print_error "pfsense_xml_parser.py not found!"
+        exit 1
+    fi
+
+    if [ ! -f "comprehensive_mapper.py" ]; then
+        print_error "comprehensive_mapper.py not found!"
+        exit 1
+    fi
+
+    if [ ! -f "svg_generator.py" ]; then
+        print_error "svg_generator.py not found!"
+        exit 1
+    fi
+
+    print_status "All required scripts found"
+}
+
+# Find pfSense XML files
+find_pfsense_files() {
+    print_step "Looking for pfSense XML configuration files..."
+
+    PFSENSE_FILES=$(ls config-*.xml 2>/dev/null || true)
+
+    if [ -z "$PFSENSE_FILES" ]; then
+        print_warning "No pfSense XML files found in current directory"
+        print_warning "Please place your pfSense backup XML files here"
+        echo "Expected format: config-hostname-timestamp.xml"
+        return 1
+    fi
+
+    print_status "Found pfSense XML files:"
+    echo "$PFSENSE_FILES" | while read -r file; do
+        echo "  - $file"
+    done
+
+    # Export for use in other functions
+    export PFSENSE_FILES
+    return 0
+}
+
+# Run network scan (optional)
+run_network_scan() {
+    print_step "Running network scan..."
+
+    if [ -f "config.json" ]; then
+        print_status "Using existing config.json for network scan"
+        python3 network_scanner.py -c config.json -o network_scan.json
+    else
+        print_warning "No config.json found - skipping network scan"
+        print_warning "Create config.json to enable live network scanning"
+        return 1
+    fi
+}
+
+# Run comprehensive mapping
+run_comprehensive_mapping() {
+    print_step "Running comprehensive network mapping..."
+
+    # Build command with pfSense files
+    CMD="./comprehensive_mapper.py -o comprehensive_network.json --svg comprehensive_network.svg -v"
+
+    if [ -n "$PFSENSE_FILES" ]; then
+        CMD="$CMD -p $PFSENSE_FILES"
+    fi
+
+    if [ -f "network_scan.json" ]; then
+        CMD="$CMD -s network_scan.json"
+    fi
+
+    print_status "Executing: $CMD"
+    eval $CMD
+}
+
+# Generate summary report
+generate_report() {
+    print_step "Generating summary report..."
+
+    if [ -f "comprehensive_network.json" ]; then
+        echo "# Network Mapping Report" > network_report.md
+        echo "Generated on: $(date)" >> network_report.md
+        echo "" >> network_report.md
+
+        # Extract key statistics
+        SEGMENTS=$(jq '.segments | length' comprehensive_network.json)
+        PFSENSE_COUNT=$(jq '.pfsense_firewalls | length' comprehensive_network.json)
+        WG_NETWORKS=$(jq '.wireguard_networks | length' comprehensive_network.json)
+        STATIC_ROUTES=$(jq '.routing_table | length' comprehensive_network.json)
+        DHCP_MAPPINGS=$(jq '.static_mappings | length' comprehensive_network.json)
+
+        echo "## Network Statistics" >> network_report.md
+        echo "- Network Segments: $SEGMENTS" >> network_report.md
+        echo "- pfSense Firewalls: $PFSENSE_COUNT" >> network_report.md
+        echo "- WireGuard Networks: $WG_NETWORKS" >> network_report.md
+        echo "- Static Routes: $STATIC_ROUTES" >> network_report.md
+        echo "- DHCP Static Mappings: $DHCP_MAPPINGS" >> network_report.md
+        echo "" >> network_report.md
+
+        echo "## Generated Files" >> network_report.md
+        echo "- comprehensive_network.json - Complete network data" >> network_report.md
+        echo "- comprehensive_network.svg - Network topology diagram" >> network_report.md
+        echo "- network_report.md - This summary report" >> network_report.md
+
+        print_status "Report generated: network_report.md"
+    else
+        print_error "No comprehensive network data found"
+    fi
+}
+
+# Main workflow
+main() {
+    echo "Starting comprehensive network mapping workflow..."
+    echo ""
+
+    check_requirements
+
+    if ! find_pfsense_files; then
+        print_error "Cannot proceed without pfSense XML files"
+        exit 1
+    fi
+
+    # Optional network scan
+    if [ -f "config.json" ]; then
+        run_network_scan
+    fi
+
+    # Comprehensive mapping (required)
+    run_comprehensive_mapping
+
+    # Generate report
+    generate_report
+
+    echo ""
+    print_status "Workflow completed successfully!"
+    echo ""
+    echo "Generated files:"
+    echo "  📊 comprehensive_network.json - Complete network data"
+    echo "  🖼️  comprehensive_network.svg - Network topology diagram"
+    echo "  📋 network_report.md - Summary report"
+    echo ""
+    echo "Open comprehensive_network.svg in your browser to view the network diagram"
+}
+
+# Handle command line arguments
+case "${1:-}" in
+    "scan-only")
+        check_requirements
+        run_network_scan
+        ;;
+    "map-only")
+        check_requirements
+        find_pfsense_files
+        run_comprehensive_mapping
+        ;;
+    "report-only")
+        generate_report
+        ;;
+    "help"|"-h"|"--help")
+        echo "Usage: $0 [command]"
+        echo ""
+        echo "Commands:"
+        echo "  (no command)  - Run full workflow"
+        echo "  scan-only     - Run only network scan"
+        echo "  map-only      - Run only comprehensive mapping"
+        echo "  report-only   - Generate only summary report"
+        echo "  help          - Show this help"
+        ;;
+    *)
+        main
+        ;;
+esac