root/netzwerk_diagramm_scanner
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
7621e1829d5e5e7536ea5fac51361185c45ce5de
netzwerk_diagramm_scanner/PROJECT_SUMMARY.md

9.2 KiB
Raw Blame History

Network Scanner Project - Complete Summary

📁 Project Structure

netzwerk_diagramm_scanner/
├── network_scanner.py          # Main network scanning engine
├── pfsense_scanner.py          # pfSense-specific scanner
├── svg_generator.py            # SVG diagram generator
├── integrated_scanner.py       # Combined scanner with pfSense integration
├── test_system.py              # System verification and testing
├── quickstart.sh               # Interactive quick start guide
├── EXAMPLES.sh                 # Usage examples and scenarios
├── config.json.example         # Configuration template
├── requirements.txt            # Python dependencies
├── README.md                   # Complete documentation
└── .gitignore                  # Git ignore file

🚀 Quick Start

# 1. Run system tests
./test_system.py

# 2. Use the interactive quickstart
./quickstart.sh

# 3. Or run directly
./integrated_scanner.py --generate-svg -v

📋 What Each Script Does

network_scanner.py

Main network scanner - Discovers and scans network devices

  • Auto-discovers network segments from routing table
  • Ping sweep to find live hosts
  • Port scanning (common services)
  • SSH-based information gathering
  • Device type identification
  • Routing table extraction
  • Network interface enumeration

Usage:

./network_scanner.py -c config.json -o scan_results.json -v

pfsense_scanner.py

pfSense-specific scanner - Deep dive into pfSense firewalls

  • Network interfaces and IP configuration
  • Complete routing table
  • VPN information:
    • WireGuard tunnels and peers
    • OpenVPN connections
    • IPsec tunnels
  • Active firewall rules
  • DHCP leases
  • ARP table
  • Gateway status

Usage:

./pfsense_scanner.py 192.168.1.1 -u root -k ~/.ssh/id_rsa -o pfsense.json

svg_generator.py

SVG diagram generator - Creates visual network topology

  • Color-coded network segments
  • Device type icons (routers, servers, clients)
  • Device information (IP, hostname, type)
  • Network connections
  • Legend explaining device types

Usage:

./svg_generator.py scan_results.json -o network_diagram.svg

integrated_scanner.py

All-in-one scanner - Combines everything

  • Full network scan
  • Automatic pfSense detection and deep scanning
  • Enhanced routing analysis
  • Optional SVG generation
  • Comprehensive reporting

Usage:

./integrated_scanner.py -c config.json -o full_scan.json --generate-svg -v

test_system.py

System verification - Checks if everything is ready

  • Python version check
  • Network connectivity test
  • Required commands verification
  • Script syntax validation
  • SSH key detection
  • Network detection test

Usage:

./test_system.py

🔧 Configuration

Create config.json from the example:

{
  "ssh_user": "root",
  "ssh_key_path": "/home/user/.ssh/id_rsa",
  "timeout": 2,
  "additional_networks": [
    "192.168.1.0/24",
    "10.0.0.0/24",
    "10.8.0.0/24"
  ],
  "special_devices": {
    "192.168.1.1": {
      "name": "pfSense Main Firewall",
      "type": "firewall",
      "os": "pfSense"
    }
  },
  "scan_options": {
    "max_workers": 10,
    "ping_timeout": 2,
    "port_scan_timeout": 1
  }
}

📊 Output Format

JSON Structure

{
  "scan_timestamp": "2025-10-10T12:00:00",
  "segments": [
    {
      "name": "192.168.1.0/24",
      "cidr": "192.168.1.0/24",
      "gateway": "192.168.1.1",
      "is_vpn": false,
      "devices": [
        {
          "ip": "192.168.1.1",
          "hostname": "pfsense.local",
          "mac": "00:11:22:33:44:55",
          "device_type": "firewall",
          "os_type": "pfSense (FreeBSD)",
          "open_ports": [22, 80, 443],
          "ssh_accessible": true,
          "routes": [...],
          "interfaces": [...],
          "pfsense_info": {
            "vpn": {...},
            "firewall_rules": [...],
            "dhcp_leases": [...]
          }
        }
      ]
    }
  ]
}

🎯 Common Use Cases

1. Network Documentation

# Generate complete network documentation
./integrated_scanner.py -o network_doc.json --generate-svg

2. Security Audit

# Scan and analyze open ports
./network_scanner.py -v -o security_scan.json
cat security_scan.json | jq '.segments[].devices[] | select(.open_ports[]? == 23)'

3. VPN Topology Mapping

# Extract VPN information
./pfsense_scanner.py <pfsense-ip> -o vpn_info.json
cat vpn_info.json | jq '.vpn'

4. Change Detection

# Baseline scan
./integrated_scanner.py -o baseline.json

# After changes
./integrated_scanner.py -o current.json

# Compare
diff <(jq -S . baseline.json) <(jq -S . current.json)

5. Scheduled Monitoring

# Add to crontab for daily scans
0 2 * * * /path/to/integrated_scanner.py -o /var/log/network-scan-$(date +\%Y\%m\%d).json

🔐 Security Setup

SSH Key Generation

ssh-keygen -t ed25519 -f ~/.ssh/network_scanner -N ""

Distribute to All Devices

for ip in 192.168.1.{1..254}; do
    ssh-copy-id -i ~/.ssh/network_scanner.pub root@$ip 2>/dev/null
done

Update Configuration

{
  "ssh_user": "root",
  "ssh_key_path": "/home/user/.ssh/network_scanner"
}

🔍 Features

Network Discovery

  • ✅ Auto-detect network segments from routing table
  • ✅ Configurable additional networks
  • ✅ VPN network detection
  • ✅ Multi-threaded scanning

Device Information

  • ✅ IP address and hostname
  • ✅ MAC address lookup
  • ✅ OS detection (via SSH)
  • ✅ Device type classification
  • ✅ Open port scanning
  • ✅ Service enumeration

pfSense Integration

  • ✅ Full routing table extraction
  • ✅ WireGuard tunnel mapping
  • ✅ OpenVPN status
  • ✅ IPsec tunnels
  • ✅ Firewall rules
  • ✅ DHCP lease tracking
  • ✅ ARP table

Visualization

  • ✅ SVG diagram generation
  • ✅ Color-coded networks
  • ✅ Device type icons
  • ✅ Connection mapping
  • ✅ Legend and labels

Output & Integration

  • ✅ JSON export
  • ✅ Structured data format
  • ✅ Easy integration with other tools
  • ✅ jq-friendly output

🛠️ Requirements

  • Python 3.8+
  • Linux operating system
  • Standard utilities: ping, ip, ssh
  • SSH access to network devices (recommended)
  • SSH key-based authentication (recommended)

📈 Performance

  • Small networks (<50 devices): ~1-2 minutes
  • Medium networks (50-200 devices): ~5-10 minutes
  • Large networks (200+ devices): ~15-30 minutes

Times vary based on:

  • Network latency
  • SSH accessibility
  • Number of ports scanned
  • Concurrent worker threads

🐛 Troubleshooting

No devices found

# Check network connectivity
ping <gateway-ip>

# Check routing table
ip route show

# Run with verbose mode
./network_scanner.py -v

SSH failures

# Test SSH manually
ssh -i ~/.ssh/network_scanner root@<device-ip>

# Check key permissions
chmod 600 ~/.ssh/network_scanner

# Verify key is loaded
ssh-add -l

Slow scanning

# Reduce timeout in config.json
{
  "timeout": 1,
  "scan_options": {
    "ping_timeout": 1,
    "port_scan_timeout": 1
  }
}

# Scan specific networks only
{
  "additional_networks": ["192.168.1.0/24"]
}

🎓 Advanced Usage

Custom Device Types

Edit network_scanner.py to add custom device identification logic.

Extended Port Scanning

Modify _scan_common_ports() to scan additional ports.

Custom Visualization

Edit svg_generator.py to customize colors, icons, and layout.

Integration with Other Tools

Use JSON output with tools like:

  • jq - JSON processing
  • python - Custom analysis
  • ansible - Automation
  • grafana - Monitoring
  • prometheus - Metrics

📝 Next Steps

  1. Initial Setup

    ./test_system.py
cp config.json.example config.json
# Edit config.json with your details

  2. First Scan

    ./quickstart.sh
# Or: ./integrated_scanner.py --generate-svg -v

  3. Review Results

    # View JSON
cat network_scan.json | jq .

# View diagram
firefox network_diagram.svg

  4. Customize

    • Add your networks to config.json
    • Mark special devices (pfSense, routers)
    • Adjust timeouts and workers
    • Set up SSH keys for all devices

  5. Automate

    • Schedule regular scans
    • Compare with baselines
    • Generate documentation
    • Monitor for changes

💡 Tips

  • Always get authorization before scanning networks
  • Use SSH keys instead of passwords for automation
  • Start small - test on a single network first
  • Increase verbosity (-v) for troubleshooting
  • Use jq for powerful JSON querying
  • Keep baselines for change detection
  • Document special devices in config.json

📞 Support

  • See README.md for detailed documentation
  • Check EXAMPLES.sh for usage scenarios
  • Run ./quickstart.sh for interactive help
  • Run ./test_system.py to verify setup

✅ Project Status

All components are complete and tested:

  • ✅ Core network scanner
  • ✅ pfSense integration
  • ✅ SVG diagram generation
  • ✅ Integrated scanner
  • ✅ Configuration system
  • ✅ Documentation
  • ✅ Examples and quick start
  • ✅ System tests

Ready to use! 🎉

Generated for comprehensive network topology discovery and visualization.

Reference in New Issue View Git Blame Copy Permalink