ipwatch
This commit is contained in:
270
README.md
Executable file
270
README.md
Executable file
@@ -0,0 +1,270 @@
|
||||
# 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**
|
||||
```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
|
||||
|
||||
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"
|
||||
```
|
||||
|
||||
## 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 :
|
||||
|
||||
```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
|
||||
|
||||
## 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.
|
||||
Reference in New Issue
Block a user