IPWatch - Scanner Réseau Temps Réel

IPWatch est une application web de scan réseau qui visualise en temps réel l'état des adresses IP, leurs ports ouverts, et l'historique des détections sur votre réseau local.

Fonctionnalités

• 🔍 Scan réseau automatique : Ping, ARP lookup, et scan de ports périodiques
• 📊 Visualisation temps réel : Interface web avec mise à jour WebSocket
• 🎨 Thème Monokai : Interface sombre avec codes couleurs intuitifs
• 📝 Gestion des IP : Nommage, classification (connue/inconnue), métadonnées
• 📈 Historique 24h : Suivi de l'évolution de l'état du réseau
• 🔔 Détection automatique : Notification des nouvelles IP sur le réseau
• 🔗 Intégration OPNsense : Gestion des réservations DHCP Kea directement depuis l'interface
• 🌐 Ports & Services : Scan de services réseau (HTTP, SSH, Proxmox, etc.) avec résultats en temps réel et liens cliquables
• 🐳 Déploiement Docker : Configuration simple avec docker-compose

Technologies

Backend

• FastAPI - API REST et WebSocket
• SQLAlchemy - ORM pour SQLite
• APScheduler - Tâches planifiées
• Scapy - Scan ARP et réseau
• httpx - Client HTTP async (intégration OPNsense)

Frontend

• Vue 3 - Framework UI avec Composition API
• Pinia - State management
• Tailwind CSS - Styles avec palette Monokai
• Vite - Build tool

Infrastructure

• Docker - Conteneurisation
• SQLite - Base de données
• WebSocket - Communication temps réel

Installation

Avec Docker (recommandé)

1. Cloner le repository

git clone <repo-url>
cd ipwatch

2. Configurer le réseau

Éditer config.yaml et ajuster le CIDR de votre réseau :

network:
  cidr: "192.168.1.0/24"  # Adapter à votre réseau

3. Lancer avec docker-compose

docker-compose up -d

4. Accéder à l'interface

Ouvrir votre navigateur : http://localhost:8080

Installation manuelle (développement)

Backend

cd backend
pip install -r requirements.txt
python -m backend.app.main

Frontend

cd frontend
npm install
npm run dev

L'API sera accessible sur http://localhost:8080 Le frontend sur http://localhost:3000

Configuration

Le fichier config.yaml permet de configurer :

• Réseau : CIDR, gateway, DNS
• IPs connues : Liste des appareils avec noms et emplacements
• Scan : Intervalles ping/ports, parallélisation
• Ports : Ports à scanner
• Historique : Durée de rétention
• Interface : Transparence, couleurs
• Base de données : Chemin SQLite
• OPNsense : Connexion API pour réservations DHCP Kea
• Services : Liste des services réseau à scanner (nom, port, protocole)

Exemple :

network:
  cidr: "192.168.1.0/24"

scan:
  ping_interval: 60        # Scan ping toutes les 60s
  port_scan_interval: 300  # Scan ports toutes les 5min
  parallel_pings: 50       # 50 pings simultanés max

ports:
  ranges:
    - "22"      # SSH
    - "80"      # HTTP
    - "443"     # HTTPS
    - "3389"    # RDP

ip_classes:
  "192.168.1.1":
    name: "Box Internet"
    location: "Entrée"
    host: "Routeur"

opnsense:
  enabled: true
  host: "10.0.0.1"
  protocol: "http"        # "http" ou "https"
  api_key: "votre_api_key"
  api_secret: "votre_api_secret"
  verify_ssl: false

services:
  - name: "HTTP"
    port: 80
    protocol: "http"
  - name: "HTTPS"
    port: 443
    protocol: "https"
  - name: "SSH"
    port: 22
    protocol: "ssh"
  - name: "Proxmox VE"
    port: 8006
    protocol: "https"

Interface utilisateur

L'interface est organisée en 3 colonnes :

Colonne gauche - Détails IP

• Informations détaillées de l'IP sélectionnée
• Formulaire d'édition (nom, localisation, type d'hôte)
• Informations réseau (MAC, vendor, hostname, ports ouverts)
• Bouton de réservation DHCP OPNsense (si MAC disponible)
• Indicateur "DHCP réservé" (checkbox en lecture seule)

Colonne centrale - Grille d'IP

• Vue d'ensemble de toutes les IP du réseau
• Codes couleurs selon l'état :
  • 🟢 Vert : En ligne + connue
  • 🔵 Cyan : En ligne + inconnue
  • 🔴 Rose : Hors ligne + connue (bordure pointillée)
  • 🟣 Violet : Hors ligne + inconnue (bordure pointillée)
  • ⚪ Gris : IP libre
• Filtres : En ligne, Hors ligne, Connues, Inconnues, Libres
• Légende interactive

Colonne droite - Nouvelles détections

• Liste des IP récemment découvertes
• Tri par ordre chronologique
• Indicateur temps relatif

API REST

Endpoints IPs

• GET /api/ips/ - Liste toutes les IPs (avec filtres optionnels)
• GET /api/ips/{ip} - Détails d'une IP
• PUT /api/ips/{ip} - Mettre à jour une IP
• DELETE /api/ips/{ip} - Supprimer une IP
• GET /api/ips/{ip}/history - Historique d'une IP
• GET /api/ips/stats/summary - Statistiques globales

Endpoints OPNsense (Kea DHCP)

• GET /api/opnsense/status - Test connexion OPNsense
• GET /api/opnsense/dhcp/reservations - Lister les réservations DHCP Kea
• GET /api/opnsense/dhcp/reservation/{ip} - Chercher une réservation par IP
• POST /api/opnsense/dhcp/reservation - Créer ou mettre à jour une réservation DHCP

Endpoints Ports & Services

• GET /api/services/list - Liste des services configurés dans config.yaml
• POST /api/services/scan - Lancer un scan de services (ports sélectionnés sur toutes les IPs connues)

Endpoints Scan

• POST /api/scan/start - Lancer un scan immédiat
• POST /api/scan/cleanup-history - Nettoyer l'historique ancien

WebSocket

• WS /ws - Connexion WebSocket pour notifications temps réel

Messages WebSocket :

• scan_start - Début de scan
• scan_complete - Fin de scan avec statistiques
• ip_update - Changement d'état d'une IP
• new_ip - Nouvelle IP détectée
• service_scan_start - Début de scan de services
• service_scan_progress - Progression du scan (IP en cours)
• service_scan_log - Log individuel par IP scannée
• service_scan_result - Résultat individuel en temps réel (service détecté)
• service_scan_complete - Fin de scan avec résultats agrégés

Tests

Exécuter les tests backend :

cd backend
pytest

Tests disponibles :

• test_network.py - Tests modules réseau (ping, ARP, port scan)
• test_models.py - Tests modèles SQLAlchemy
• test_api.py - Tests endpoints API
• test_scheduler.py - Tests scheduler APScheduler

Intégration OPNsense / Kea DHCP

IPWatch peut se connecter à un pare-feu OPNsense pour gérer les réservations DHCP Kea directement depuis l'interface web.

Configuration

Ajouter la section opnsense dans config.yaml :

opnsense:
  enabled: true
  host: "10.0.0.1"          # IP ou hostname OPNsense
  protocol: "http"           # "http" ou "https"
  api_key: "votre_api_key"
  api_secret: "votre_api_secret"
  verify_ssl: false           # false pour certificats auto-signés

Les clés API se génèrent dans OPNsense : Système > Accès > Utilisateurs > [utilisateur] > Clés API.

Fonctionnement

1. Sélectionner un équipement dans la grille (il doit avoir une adresse MAC)
2. Cliquer sur le bouton DHCP (icone routeur) dans le volet gauche
3. Un popup s'ouvre avec les champs pré-remplis : MAC, IP, hostname, description
4. Cliquer "Mettre à jour OPNsense" pour créer ou mettre à jour la réservation
5. IPWatch résout automatiquement le subnet Kea correspondant à l'IP
6. Après succès, la checkbox "DHCP réservé" passe au vert

Flux technique

IPWatch Frontend → POST /api/opnsense/dhcp/reservation
    → Résolution automatique du subnet UUID Kea
    → Recherche réservation existante par IP
    → Création ou mise à jour de la réservation
    → Reconfiguration du service Kea (application immédiate)
    → Mise à jour dhcp_synced=true en BDD
    → Retour au frontend (checkbox verte)

Ports & Services

L'onglet Ports & Services permet de scanner le réseau à la recherche de services spécifiques et d'afficher les résultats dans un tableau avec des liens cliquables.

Configuration

Les services à scanner sont définis dans la section services de config.yaml :

services:
  - name: "HTTP"
    port: 80
    protocol: "http"
  - name: "Proxmox VE"
    port: 8006
    protocol: "https"
  - name: "SSH"
    port: 22
    protocol: "ssh"

Chaque service a un name, un port, et un protocol optionnel (http, https, ssh, rdp, smb...). Le protocole détermine la construction des URLs cliquables.

Fonctionnement

1. Ouvrir l'onglet Ports & Services depuis la barre de navigation
2. Cocher les services à scanner dans le volet gauche
3. Cliquer "Lancer le scan"
4. Le scan teste chaque IP connue (en base) pour les ports sélectionnés
5. Les résultats apparaissent en temps réel dans le tableau central
6. Les services HTTP/HTTPS sont affichés avec des liens cliquables

Performances

Le scan est parallélisé : 20 IPs sont testées simultanément (configurable via PARALLEL_IPS). Pour un réseau de 1000 IPs avec un timeout de 1s, le scan complet prend environ 50 secondes.

Interface

• Volet gauche : Liste des services avec checkboxes de sélection
• Zone centrale : Barre de progression + tableau de résultats (IP, nom, service, port, lien)
• Volet droit : Logs de scan en temps réel (redimensionnable)

Architecture

ipwatch/
├── backend/
│   ├── app/
│   │   ├── core/          # Configuration, database
│   │   ├── models/        # Modèles SQLAlchemy
│   │   ├── routers/       # Endpoints API
│   │   ├── services/      # Services réseau, scheduler, WebSocket, client OPNsense
│   │   └── main.py        # Application FastAPI
│   └── requirements.txt
├── frontend/
│   ├── src/
│   │   ├── assets/        # CSS Monokai
│   │   ├── components/    # Composants Vue
│   │   ├── stores/        # Pinia stores
│   │   ├── views/         # Vues (Main, Tracking, Services, Architecture, Test)
│   │   └── main.js
│   └── package.json
├── tests/                 # Tests backend
├── config.yaml           # Configuration
├── docker-compose.yml
└── Dockerfile

Workflow de scan

Le scan réseau suit ce workflow (10 étapes) :

1. Charger configuration YAML
2. Générer liste IP du CIDR
3. Ping (parallélisé)
4. ARP + MAC vendor lookup
5. Port scan selon intervalle
6. Classification état (online/offline)
7. Mise à jour SQLite
8. Détection nouvelles IP
9. Push WebSocket vers clients
10. Mise à jour UI temps réel

Sécurité

⚠️ Attention : IPWatch nécessite des privilèges réseau élevés (ping, ARP).

Le conteneur Docker utilise :

• network_mode: host - Accès au réseau local
• privileged: true - Privilèges pour scan réseau
• cap_add: NET_ADMIN, NET_RAW - Capacités réseau

N'exposez pas cette application sur internet - Usage réseau local uniquement.

Volumes Docker

Trois volumes sont montés :

• ./config.yaml - Configuration (lecture seule)
• ./data/ - Base de données SQLite
• ./logs/ - Logs applicatifs

Dépannage

Le scan ne détecte aucune IP

1. Vérifier le CIDR dans config.yaml
2. Vérifier que Docker a accès au réseau (network_mode: host)
3. Vérifier les logs : docker logs ipwatch

WebSocket déconnecté

• Vérifier que le port 8080 est accessible
• Vérifier les logs du navigateur (F12 → Console)
• Le WebSocket se reconnecte automatiquement après 5s

Erreur de permissions réseau

Le conteneur nécessite privileged: true pour :

• Envoi de paquets ICMP (ping)
• Scan ARP
• Capture de paquets réseau

Licence

MIT

Auteur

Développé avec Claude Code selon les spécifications IPWatch.