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.
This commit is contained in:
mindesbunister
299
docs/GETTING_STARTED.md
Normal file
299
docs/GETTING_STARTED.md
Normal file
@@ -0,0 +1,299 @@
|
||||
# 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`
|
||||
Reference in New Issue
Block a user