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
• 🐳 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

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

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"

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)

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

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

Architecture

ipwatch/
├── backend/
│   ├── app/
│   │   ├── core/          # Configuration, database
│   │   ├── models/        # Modèles SQLAlchemy
│   │   ├── routers/       # Endpoints API
│   │   ├── services/      # Services réseau, scheduler, WebSocket
│   │   └── main.py        # Application FastAPI
│   └── requirements.txt
├── frontend/
│   ├── src/
│   │   ├── assets/        # CSS Monokai
│   │   ├── components/    # Composants Vue
│   │   ├── stores/        # Pinia stores
│   │   └── 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.