netzwerk_diagramm_scanner/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

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):

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

• Copy SSH key to your devices:

# 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:

ssh -i ~/.ssh/network_scanner root@<device-ip> "echo Connection OK"

3. Create Configuration

• Copy example config:

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:

{
  "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:

./quickstart.sh

Choose option 1 for a quick test scan.

Option B: Direct Scan

• Run integrated scanner:

./integrated_scanner.py -v -o first_scan.json

• Check output:

cat first_scan.json | jq '.segments | length'

Option C: With SVG Diagram

• Run with diagram generation:

./integrated_scanner.py -v -o scan.json --generate-svg

• Open diagram:

firefox scan.svg
# or
xdg-open scan.svg

✅ Verification Steps

After your first scan:

• Check segment count:

cat first_scan.json | jq '.segments | length'

Expected: At least 1 network segment

• Check device count:

cat first_scan.json | jq '[.segments[].devices[]] | length'

Expected: Number of devices in your network

• List found devices:

cat first_scan.json | jq -r '.segments[].devices[].ip'

• Check pfSense detection (if applicable):

cat first_scan.json | jq '.segments[].devices[] | select(.device_type=="firewall")'

✅ Advanced Configuration

For pfSense Users:

• Test pfSense scanner directly:

./pfsense_scanner.py <pfsense-ip> -u root -k ~/.ssh/network_scanner -o pfsense_test.json

• Verify pfSense data:

# 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:

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:

# On pfSense or WireGuard server
wg show

• Add VPN networks to config.json additional_networks

• Verify VPN is marked in scan results:

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

# 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

# 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