123 lines
5.3 KiB
Markdown
Executable File
123 lines
5.3 KiB
Markdown
Executable File
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
IPWatch is a network scanner web application that visualizes IP addresses, their states (online/offline), open ports, and historical data. The project consists of:
|
|
|
|
- **Backend**: FastAPI + SQLAlchemy + APScheduler for network scanning
|
|
- **Frontend**: Vue 3 + Vite + Tailwind with Monokai dark theme
|
|
- **Deployment**: Docker containerization with volumes for config and database
|
|
|
|
## Key Specification Files
|
|
Speek in french and comment in french
|
|
The project has detailed specifications that MUST be followed when implementing features:
|
|
|
|
- [prompt-claude-code.md](prompt-claude-code.md) - Overall project objectives and deliverables
|
|
- [architecture-technique.md](architecture-technique.md) - Technical architecture (backend modules, frontend structure, Docker setup)
|
|
- [modele-donnees.md](modele-donnees.md) - SQLite database schema (ip and ip_history tables with required indexes)
|
|
- [workflow-scan.md](workflow-scan.md) - 10-step scan pipeline from YAML config to WebSocket push
|
|
- [consigne-parametrage.md](consigne-parametrage.md) - Complete YAML configuration structure with all sections (app, network, ip_classes, scan, ports, locations, hosts, history, ui, colors, network_advanced, filters, database)
|
|
- [consigne-design_webui.md](consigne-design_webui.md) - UI layout (3-column design), interaction patterns, visual states
|
|
- [guidelines-css.md](guidelines-css.md) - Monokai color palette, IP cell styling rules (solid border for online, dashed for offline, animated halo for ping)
|
|
- [tests-backend.md](tests-backend.md) - Required unit and integration tests
|
|
|
|
## Architecture Principles
|
|
|
|
### Backend Structure
|
|
- FastAPI application with separate modules for network operations (ping, ARP, port scanning)
|
|
- SQLAlchemy models matching the schema in [modele-donnees.md](modele-donnees.md)
|
|
- APScheduler for periodic network scans
|
|
- WebSocket endpoint for real-time push notifications
|
|
- REST APIs for: IP management, scan operations, configuration, historical data
|
|
|
|
### Frontend Structure
|
|
- Vue 3 with Composition API
|
|
- Pinia for global state management
|
|
- WebSocket client for real-time updates
|
|
- 3-column layout: left (IP details), center (IP grid + legend), right (new detections)
|
|
- Monokai dark theme with specific color codes from [guidelines-css.md](guidelines-css.md)
|
|
|
|
### Data Flow
|
|
1. YAML configuration loads network CIDR and scan parameters
|
|
2. Scheduled scan generates IP list, performs ping (parallel), ARP lookup, port scanning
|
|
3. Results classified and stored in SQLite
|
|
4. New/changed IPs trigger WebSocket push to frontend
|
|
5. UI updates grid with appropriate visual states
|
|
|
|
## Database Schema
|
|
|
|
### ip table (PRIMARY)
|
|
- `ip` (PK): IP address
|
|
- `name`, `known` (bool), `location`, `host`: metadata
|
|
- `first_seen`, `last_seen`: timestamps
|
|
- `last_status`: current online/offline state
|
|
- `mac`, `vendor`, `hostname`: network info
|
|
- `open_ports`: JSON array
|
|
|
|
### ip_history table
|
|
- `id` (PK)
|
|
- `ip` (FK to ip.ip)
|
|
- `timestamp`, `status`, `open_ports` (JSON)
|
|
- **Required index**: timestamp for efficient historical queries
|
|
|
|
### Important Indexes
|
|
- Index on `ip.last_status` for filtering
|
|
- Index on `ip_history.timestamp` for 24h history retrieval
|
|
|
|
## Visual Design Rules
|
|
|
|
### IP Cell States
|
|
- **Online + Known**: Green (#A6E22E) with solid border
|
|
- **Online + Unknown**: Cyan (#66D9EF) with solid border
|
|
- **Offline**: Dashed border + configurable transparency
|
|
- **Ping in progress**: Animated halo using CSS keyframes
|
|
- **Free IP**: Distinct color from occupied states
|
|
|
|
### Theme Colors (Monokai)
|
|
- Background: `#272822`
|
|
- Text: `#F8F8F2`
|
|
- Accents: `#A6E22E` (green), `#F92672` (pink), `#66D9EF` (cyan)
|
|
|
|
## Configuration System
|
|
|
|
The application is driven by a YAML configuration file ([consigne-parametrage.md](consigne-parametrage.md)) with these sections:
|
|
- `network`: CIDR, gateway, DNS
|
|
- `ip_classes`: Define known IPs with metadata
|
|
- `scan`: Intervals, parallelization settings
|
|
- `ports`: Port scan ranges
|
|
- `locations`, `hosts`: Categorical data
|
|
- `history`: Retention period
|
|
- `ui`: Display preferences, transparency
|
|
- `colors`: Custom color mapping
|
|
- `network_advanced`: ARP, timeout settings
|
|
- `filters`: Default filter states
|
|
- `database`: SQLite path
|
|
|
|
## Testing Requirements
|
|
|
|
When implementing backend features, ensure tests cover ([tests-backend.md](tests-backend.md)):
|
|
- Network module unit tests: `test_ping()`, `test_port_scan()`, `test_classification()`
|
|
- SQLAlchemy models: `test_sqlalchemy_models()`
|
|
- API endpoints: `test_api_get_ip()`, `test_api_update_ip()`
|
|
- Scheduler: `test_scheduler()`
|
|
- Integration: Full network scan simulation, WebSocket notification flow
|
|
|
|
## Docker Setup
|
|
|
|
The application should run as a single Docker service:
|
|
- Combined backend + frontend container
|
|
- Volume mount for `config.yaml`
|
|
- Volume mount for `db.sqlite`
|
|
- Exposed ports for web access and WebSocket
|
|
|
|
## Implementation Notes
|
|
|
|
- **Parallelization**: Ping operations must be parallelized for performance
|
|
- **Real-time updates**: WebSocket is critical for live UI updates during scans
|
|
- **MAC vendor lookup**: Use ARP data to populate vendor information
|
|
- **Port scanning**: Respect intervals defined in YAML to avoid network overload
|
|
- **Classification logic**: Follow the 10-step workflow in [workflow-scan.md](workflow-scan.md)
|
|
- **Responsive design**: Grid layout must be fluid with collapsible columns
|