# Web Sentinel - Instructions pour les Agents IA

## Vue d'ensemble de l'architecture

Web Sentinel est un outil de diagnostic de sécurité web **passif-first** organisé autour d'un orchestrateur modulaire :

- **CLI** (`web_sentinel/cli.py`) : Point d'entrée avec gestion des rapports et historique
- **Orchestrateur** (`web_sentinel/scanner.py`) : Exécute les modules en parallèle via `ThreadPoolExecutor`
- **Modules** (`web_sentinel/checks/`) : Chaque module expose une fonction `evaluate_*` qui retourne des `Finding`
- **Moteur de rapport** (`web_sentinel/reporting.py`) : Historisation, comparaison de régressions, export HTML/JSON

## Patterns de développement critiques

### Structure des modules de vérification

Tous les modules suivent le pattern :
```python
def evaluate_module_name(request: ScanRequest) -> Iterable[Finding]:
    findings: List[Finding] = []
    # Logique de test
    return findings
```

Exemple d'enregistrement dans `orchestrator.py` :
```python
CheckModule(
    name="module-name",
    description="Brief description for CLI help",
    runner=evaluate_module_name,
    tags=("passive", "category"),  # passive/active + domain tags
)
```

### Gestion passive vs invasive

- **Par défaut** : Mode passif uniquement (inspection TLS, headers HTTP, DOM statique)
- **Mode invasif** : Activé avec `request.allow_invasive=True`, permet les payloads bénins
- Chaque module doit vérifier `request.allow_invasive` avant les tests actifs

### Modèle de données strict

```python
@dataclass(frozen=True)
class Finding:
    check: str          # Nom du module (correspond au CheckModule.name)
    title: str         # Titre court pour UI
    severity: str      # critical|high|medium|low|info
    description: str   # Explication détaillée
    remediation: str   # Instructions de correction
    impact: Optional[str] = None
    evidence: Optional[str] = None
```

### Gestion des erreurs réseau

Pattern standard pour tous les modules réseau :
```python
try:
    # Opération réseau avec request.timeout
except (requests.RequestException, socket.error, ssl.SSLError) as exc:
    findings.append(Finding(
        check="module-name",
        title="Connection failed",
        severity="medium",  # Pas critical pour erreurs réseau
        description=f"Network error: {exc}",
        remediation="Verify connectivity and firewall rules.",
    ))
```

## Flux de développement

### Ajouter un nouveau module

1. Créer `web_sentinel/checks/nouveau_module.py`
2. Implémenter `evaluate_nouveau_module(request: ScanRequest) -> Iterable[Finding]`
3. Ajouter dans `build_default_modules()` dans `orchestrator.py`
4. Tester avec : `python -m web_sentinel.cli example.com --modules nouveau-module`

### Intégrations tierces

Les modules tiers (ZAP, Burp, Nikto) ne lancent **jamais** de scans automatiques :
- Vérification de connectivité API uniquement
- Retour d'instructions pour déclencher manuellement les profils passifs
- Variables d'environnement : `ZAP_API_URL`, `BURP_API_URL`, `NIKTO_PATH`

### Historisation et régressions

`HistoryStore` compare automatiquement avec le scan précédent :
- Stockage par domaine dans `~/.web-sentinel/history.json`
- Détection automatique des nouvelles vulnérabilités vs corrections
- Export dans les rapports JSON avec section `regressions`

## Commandes de développement

```bash
# Test module spécifique
python -m web_sentinel.cli example.com --modules tls headers

# Mode invasif (payloads bénins)
python -m web_sentinel.cli example.com --allow-invasive

# Export avec historique
python -m web_sentinel.cli example.com --json-report report.json --html-report report.html

# Désactivation historique
python -m web_sentinel.cli example.com --no-history
```

## Contraintes de sécurité

- **Responsabilité** : Utilisation limitée aux domaines autorisés uniquement
- **Journalisation défensive** : Tous les accès réseau sont loggés via `--log-file`
- **Payloads bénins** : Les charges d'injection ne contiennent jamais d'exploits réels
- **Mode passif par défaut** : Les tests invasifs nécessitent confirmation explicite

## Références OWASP

Le projet suit les recommandations OWASP Top 10 et CWE :
- Modules alignés sur les catégories OWASP (XSS=CWE-79, CSRF=CWE-352)
- Signatures d'erreur maintenues à jour dans `checks/injection.py`
- Headers de sécurité selon les standards OWASP dans `checks/headers.py`