ipwatch/README.md

# 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**
```bash
git clone <repo-url>
cd ipwatch
```

2. **Configurer le réseau**

Éditer `config.yaml` et ajuster le CIDR de votre réseau :
```yaml
network:
  cidr: "192.168.1.0/24"  # Adapter à votre réseau
```

3. **Lancer avec docker-compose**
```bash
docker-compose up -d
```

4. **Accéder à l'interface**

Ouvrir votre navigateur : `http://localhost:8080`

### Installation manuelle (développement)

#### Backend

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

#### Frontend

```bash
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 :
```yaml
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 :

```bash
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` :

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

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