netzwerk_diagramm_scanner/docs/GETTING_STARTED.md

# Network Scanner - Getting Started Checklist

## ✅ Pre-Installation Checklist

- [ ] Linux system available
- [ ] Python 3.8 or higher installed
- [ ] Network access to devices you want to scan
- [ ] Authorization to scan your network
- [ ] SSH access to network devices (optional but recommended)

## ✅ Initial Setup

### 1. Verify System
```bash
cd /home/rwiegand/Nextcloud/entwicklung/Werkzeuge/netzwerk_diagramm_scanner
./test_system.py
```

**Expected outcome:** All tests should pass ✓

### 2. Configure SSH Access (Recommended)

- [ ] **Generate SSH key** (if you don't have one):
```bash
ssh-keygen -t ed25519 -f ~/.ssh/network_scanner -N ""
```

- [ ] **Copy SSH key to your devices**:
```bash
# For each device you want to scan
ssh-copy-id -i ~/.ssh/network_scanner.pub root@<device-ip>

# Example for pfSense
ssh-copy-id -i ~/.ssh/network_scanner.pub root@192.168.1.1
```

- [ ] **Test SSH connection**:
```bash
ssh -i ~/.ssh/network_scanner root@<device-ip> "echo Connection OK"
```

### 3. Create Configuration

- [ ] **Copy example config**:
```bash
cp config.json.example config.json
```

- [ ] **Edit config.json** with your details:
  - [ ] Update `ssh_user` (usually "root" or your admin user)
  - [ ] Update `ssh_key_path` (e.g., `/home/username/.ssh/network_scanner`)
  - [ ] Add your network ranges to `additional_networks`
  - [ ] Add your pfSense/router IPs to `special_devices`

**Example config.json:**
```json
{
  "ssh_user": "root",
  "ssh_key_path": "/home/rwiegand/.ssh/network_scanner",
  "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",
      "type": "firewall",
      "os": "pfSense"
    }
  }
}
```

## ✅ First Scan

### Option A: Interactive Mode
- [ ] **Run quickstart**:
```bash
./quickstart.sh
```
Choose option 1 for a quick test scan.

### Option B: Direct Scan
- [ ] **Run integrated scanner**:
```bash
./integrated_scanner.py -v -o first_scan.json
```

- [ ] **Check output**:
```bash
cat first_scan.json | jq '.segments | length'
```

### Option C: With SVG Diagram
- [ ] **Run with diagram generation**:
```bash
./integrated_scanner.py -v -o scan.json --generate-svg
```

- [ ] **Open diagram**:
```bash
firefox scan.svg
# or
xdg-open scan.svg
```

## ✅ Verification Steps

After your first scan:

- [ ] **Check segment count**:
```bash
cat first_scan.json | jq '.segments | length'
```
Expected: At least 1 network segment

- [ ] **Check device count**:
```bash
cat first_scan.json | jq '[.segments[].devices[]] | length'
```
Expected: Number of devices in your network

- [ ] **List found devices**:
```bash
cat first_scan.json | jq -r '.segments[].devices[].ip'
```

- [ ] **Check pfSense detection** (if applicable):
```bash
cat first_scan.json | jq '.segments[].devices[] | select(.device_type=="firewall")'
```

## ✅ Advanced Configuration

### For pfSense Users:

- [ ] **Test pfSense scanner directly**:
```bash
./pfsense_scanner.py <pfsense-ip> -u root -k ~/.ssh/network_scanner -o pfsense_test.json
```

- [ ] **Verify pfSense data**:
```bash
# Check interfaces
cat pfsense_test.json | jq '.interfaces'

# Check VPN
cat pfsense_test.json | jq '.vpn'

# Check routes
cat pfsense_test.json | jq '.routes | length'
```

### For Multiple Networks:

- [ ] **List all networks**:
```bash
ip route show
```

- [ ] **Add each network to config.json**:
  - Local network (e.g., 192.168.1.0/24)
  - Guest network (e.g., 192.168.2.0/24)
  - VPN networks (e.g., 10.8.0.0/24)
  - WireGuard networks (e.g., 10.0.0.0/24)

### For VPN Networks:

- [ ] **Check WireGuard**:
```bash
# On pfSense or WireGuard server
wg show
```

- [ ] **Add VPN networks** to config.json additional_networks

- [ ] **Verify VPN is marked** in scan results:
```bash
cat scan.json | jq '.segments[] | select(.is_vpn==true)'
```

## ✅ Common Issues & Solutions

### Issue: No devices found
- [ ] Check network connectivity: `ping <gateway>`
- [ ] Verify ICMP is not blocked
- [ ] Try with verbose mode: `-v`
- [ ] Check if you're on the correct network

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

### Issue: pfSense not detected
- [ ] Verify pfSense SSH is enabled
- [ ] Check pfSense is in special_devices config
- [ ] Test direct pfSense scan: `./pfsense_scanner.py <ip>`
- [ ] Check pfSense firewall rules allow SSH from your IP

### Issue: Scan too slow
- [ ] Reduce timeout in config.json
- [ ] Limit network ranges in additional_networks
- [ ] Increase max_workers (if you have powerful system)

## ✅ Next Steps

Once basic scanning works:

### Documentation
- [ ] Run full scan: `./integrated_scanner.py -o full_network.json --generate-svg`
- [ ] Review SVG diagram
- [ ] Generate markdown docs (see EXAMPLES.sh)
- [ ] Save baseline scan for future comparison

### Automation
- [ ] Set up scheduled scans (cron)
- [ ] Create backup script for scan results
- [ ] Set up alerts for network changes

### Customization
- [ ] Customize device type detection
- [ ] Adjust SVG styling and colors
- [ ] Add custom port scanning
- [ ] Create custom reports

### Integration
- [ ] Export data to CSV
- [ ] Integrate with monitoring system
- [ ] Create dashboards
- [ ] Set up change detection

## ✅ Quick Reference

### Most Common Commands

```bash
# Quick scan
./network_scanner.py -v

# Full scan with diagram
./integrated_scanner.py --generate-svg

# Scan specific pfSense
./pfsense_scanner.py 192.168.1.1 -u root -k ~/.ssh/id_rsa

# Generate diagram from existing scan
./svg_generator.py scan.json -o diagram.svg

# Interactive mode
./quickstart.sh

# System test
./test_system.py
```

### Useful jq Queries

```bash
# List all IPs
cat scan.json | jq -r '.segments[].devices[].ip'

# List SSH-accessible devices
cat scan.json | jq -r '.segments[].devices[] | select(.ssh_accessible==true) | .ip'

# Count devices per segment
cat scan.json | jq '.segments[] | "\(.name): \(.devices | length) devices"'

# List routers and firewalls
cat scan.json | jq -r '.segments[].devices[] | select(.device_type=="router" or .device_type=="firewall") | "\(.ip) - \(.hostname)"'
```

## ✅ Getting Help

- [ ] Read README.md for detailed documentation
- [ ] Check EXAMPLES.sh for usage scenarios
- [ ] Review PROJECT_SUMMARY.md for overview
- [ ] Run `./quickstart.sh` for interactive help

## 🎉 Success Criteria

You're ready to use the scanner when:

- ✅ All system tests pass
- ✅ SSH keys are set up and working
- ✅ config.json is properly configured
- ✅ First scan completes successfully
- ✅ Devices are detected in your network
- ✅ SVG diagram is generated
- ✅ pfSense devices are properly detected (if applicable)

---

**Need help?** Check the troubleshooting section above or review the documentation files.

**Ready to go?** Run `./quickstart.sh` or `./integrated_scanner.py --generate-svg -v`