netzwerk_diagramm_scanner/docs/README.md

# Network Diagram Scanner

A comprehensive network topology discovery tool that scans local and VPN-connected networks, gathers detailed device information, extracts routing tables from pfSense and other routers, and generates SVG diagrams for network visualization.

## Features

- 🔍 **Network Discovery**: Automatically discovers all network segments from routing tables
- 🖥️ **Device Detection**: Identifies devices via ping sweep and port scanning
- 🔐 **SSH Access**: Gathers detailed information from SSH-accessible devices
- 🛡️ **pfSense Integration**: Specialized scanner for pfSense firewalls (routing, VPN, firewall rules, DHCP)
- 🌐 **VPN Support**: Scans networks connected via WireGuard, OpenVPN, and IPsec
- 📊 **SVG Diagram Generation**: Creates visual network topology diagrams
- 🔄 **Routing Analysis**: Extracts and analyzes routing tables from routers
- 📝 **JSON Export**: Structured data output for further processing
- 📄 **pfSense XML Parsing**: Automatically parses pfSense backup XML files for complete configuration analysis
- 🔗 **Automatic Integration**: Seamlessly integrates pfSense XML data into network scans

## Requirements

- Python 3.8 or higher
- Linux-based network (all scripts designed for Linux systems)
- SSH access to network devices (recommended)
- SSH key-based authentication (recommended for automation)

## Installation

1. Clone or download this repository:
```bash
cd /home/rwiegand/Nextcloud/entwicklung/Werkzeuge/netzwerk_diagramm_scanner
```

2. Make scripts executable:
```bash
chmod +x network_scanner.py pfsense_scanner.py svg_generator.py
```

3. (Optional) Install additional dependencies for enhanced features:
```bash
pip3 install -r requirements.txt
```

## Configuration

1. Copy the example configuration:
```bash
cp config.json.example config.json
```

2. Edit `config.json` with your network details:
```json
{
  "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"
    }
  }
}
```

### Configuration Options

- **ssh_user**: SSH username for accessing devices (default: `root`)
- **ssh_key_path**: Path to SSH private key for authentication
- **timeout**: Connection timeout in seconds (default: 2)
- **additional_networks**: List of network CIDRs to scan (in addition to auto-discovered ones)
- **special_devices**: Dictionary of known devices with custom attributes

## Usage

### Basic Network Scan

Run a complete network scan:
```bash
./network_scanner.py
```

This will:
1. Auto-discover network segments from your routing table
2. Perform ping sweeps to find live hosts
3. Scan common ports on each device
4. Attempt SSH connections to gather detailed information
5. Save results to `network_scan.json`

### Custom Configuration

Use a custom config file and output location:
```bash
./network_scanner.py -c my_config.json -o my_scan_results.json
```

### Verbose Output

Enable detailed logging:
```bash
./network_scanner.py -v
```

### pfSense-Specific Scanning

Scan a pfSense firewall directly:
```bash
./pfsense_scanner.py 192.168.1.1 -u root -k ~/.ssh/id_rsa -o pfsense_info.json
```

This extracts:
- Network interfaces and IP addresses
- Complete routing table
- VPN configurations (WireGuard, OpenVPN, IPsec)
- Active firewall rules
- DHCP leases
- ARP table
- Gateway status

### Generate SVG Diagram

After scanning, generate a visual network diagram:
```bash
./svg_generator.py network_scan.json -o network_diagram.svg
```

Open the SVG in a web browser or image viewer:
```bash
firefox network_diagram.svg
# or
xdg-open network_diagram.svg
```

## Output Format

### JSON Structure

The scanner produces JSON with the following structure:

```json
{
  "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": "FreeBSD",
          "open_ports": [22, 80, 443],
          "ssh_accessible": true,
          "routes": [...],
          "interfaces": [...]
        }
      ]
    }
  ]
}
```

## Workflow

### Complete Network Discovery Workflow

1. **Configure SSH Access**:
   ```bash
   # Generate SSH key if needed
   ssh-keygen -t ed25519 -f ~/.ssh/network_scanner
   
   # Copy to devices
   ssh-copy-id -i ~/.ssh/network_scanner root@192.168.1.1
   ```

2. **Create Configuration**:
   ```bash
   cp config.json.example config.json
   nano config.json  # Edit with your settings
   ```

3. **Run Network Scan**:
   ```bash
   ./network_scanner.py -c config.json -o scan_results.json -v
   ```

4. **Scan pfSense Devices** (if not already captured):
   ```bash
   ./pfsense_scanner.py 192.168.1.1 -u root -k ~/.ssh/network_scanner -o pfsense.json
   ```

5. **Generate Diagram**:
   ```bash
   ./svg_generator.py scan_results.json -o network_topology.svg
   ```

6. **View Results**:
   ```bash
   firefox network_topology.svg
   ```

### Complete Automated Workflow

For the ultimate network discovery experience, use the automated workflow script:

```bash
./complete_workflow.sh
```

This script will:
1. ✅ Verify system requirements
2. 🔍 Run integrated network scan (including pfSense XML if present)
3. 🎨 Generate SVG network diagram
4. 📋 Create network summary (if pfSense XML files exist)
5. 📊 Display statistics and next steps

**One-command network discovery!**

## SSH Access Setup

For automated scanning, SSH key-based authentication is recommended:

### Generate SSH Key
```bash
ssh-keygen -t ed25519 -f ~/.ssh/network_scanner -N ""
```

### Copy to All Devices
```bash
# For each device in your network
ssh-copy-id -i ~/.ssh/network_scanner.pub root@<device-ip>
```

### Update config.json
```json
{
  "ssh_user": "root",
  "ssh_key_path": "/home/username/.ssh/network_scanner"
}
```

## Device Types

The scanner identifies the following device types:

- **router**: Devices with extensive routing tables
- **firewall**: pfSense and other firewall devices
- **switch**: Network switches (if detectable)
- **server**: Linux servers with SSH access
- **linux_server**: Specifically identified Linux servers
- **windows_client**: Windows machines (RDP port open)
- **client**: Generic client devices

## Advanced Features

### Custom Device Identification

You can add custom device identification logic by modifying the `_identify_device_type()` method in `network_scanner.py`.

### WireGuard VPN Scanning

The scanner automatically detects WireGuard tunnels on pfSense and Linux systems by:
1. Checking for `wg` interfaces
2. Extracting peer information
3. Mapping allowed IPs to network segments

### Routing Table Analysis

Routing information is extracted from:
- Linux: `ip route show`
- pfSense: `netstat -rn`
- Other systems: Adaptable via SSH commands

## Troubleshooting

### No devices found
- Check network connectivity: `ping <gateway>`
- Verify ICMP is not blocked by firewalls
- Try with verbose mode: `-v`

### SSH connection failures
- Verify SSH key permissions: `chmod 600 ~/.ssh/network_scanner`
- Test manual SSH: `ssh -i ~/.ssh/network_scanner root@<ip>`
- Check SSH service is running on target devices

### Permission denied errors
- Scanner needs root/sudo for some operations (ICMP ping)
- Run with: `sudo ./network_scanner.py`

### Large networks taking too long
- Reduce scan scope by specifying specific networks in config
- Increase timeout values
- Use fewer worker threads

## Examples

### Scan only specific networks
Edit `config.json`:
```json
{
  "additional_networks": [
    "192.168.1.0/24",
    "10.8.0.0/24"
  ]
}
```

### Quick scan without SSH
Set empty SSH key path to skip SSH attempts:
```json
{
  "ssh_key_path": null
}
```

### Scan and immediately visualize
```bash
./network_scanner.py -o scan.json && ./svg_generator.py scan.json -o diagram.svg && xdg-open diagram.svg
```

## Security Considerations

- **SSH Keys**: Keep private keys secure with proper permissions (600)
- **Credentials**: Never commit `config.json` with real credentials to version control
- **Network Access**: This tool performs active scanning - ensure you have authorization
- **Firewall Rules**: May trigger IDS/IPS systems - coordinate with network admins

## Customization

### Adding New Device Types

Edit `network_scanner.py`:
```python
def _identify_device_type(self, device: Device) -> str:
    # Add your custom logic
    if device.hostname and 'myswitch' in device.hostname.lower():
        return 'switch'
    # ... existing logic
```

### Custom SVG Styling

Edit `svg_generator.py`:
```python
DEVICE_STYLES = {
    'my_custom_type': {'color': '#FF00FF', 'icon': '🎯', 'shape': 'rect'},
    # ... existing styles
}
```

## Future Enhancements

- [ ] SNMP support for switches and routers
- [ ] Automatic link detection via LLDP/CDP
- [ ] Interactive HTML diagram with zoom/pan
- [ ] Historical comparison (detect network changes)
- [ ] Integration with monitoring systems (Prometheus, Grafana)
- [ ] Multi-threaded pfSense scanning for large deployments
- [ ] Automatic VPN tunnel mapping

## Contributing

Feel free to submit issues, feature requests, or pull requests.

## License

This project is provided as-is for network documentation and analysis purposes.

## Author

Created for comprehensive network topology discovery and visualization.

---

**Note**: Always ensure you have proper authorization before scanning networks. This tool performs active network reconnaissance.

### pfSense XML Integration

The scanner can automatically parse pfSense backup XML files to extract comprehensive configuration data:

- **Network Interfaces**: All interface configurations, IP addresses, VLANs
- **Routing Tables**: Static routes, dynamic routing, gateway configurations
- **VPN Configurations**: WireGuard tunnels, OpenVPN servers/clients, IPsec
- **Firewall Rules**: NAT rules, port forwarding, access control lists
- **DHCP Services**: Server configurations, static mappings, lease pools
- **DNS Settings**: Resolvers, domain configurations
- **System Information**: Hostname, domain, version, services

**Automatic Integration**: Place pfSense XML backup files in the scanner directory, and they will be automatically parsed and integrated into network scans.

**Manual Parsing**: Use `pfsense_integrator.py` to work with XML files independently:

```bash
# Parse XML files and generate summary
./pfsense_integrator.py *.xml --summary network_summary.md

# Integrate with existing scan
./pfsense_integrator.py *.xml -s scan.json -o enhanced_scan.json
```