# 🤝 Guide de Contribution - Web Sentinel

Merci de votre intérêt pour contribuer à Web Sentinel ! Ce guide vous aidera à démarrer.

## 🚀 Démarrage Rapide

### 1. Fork et Clone
```bash
# Fork le projet sur GitHub puis :
git clone https://github.com/VOTRE-USERNAME/Web-Sentinel.git
cd Web-Sentinel
```

### 2. Configuration de l'Environnement
```bash
# Installation complète
python install.py

# Ou installation développement
pip install -r requirements.txt
pip install -r requirements-dev.txt
```

### 3. Tests Locaux
```bash
# Tests rapides
python run_tests.py

# Tests complets
pytest tests/ -v

# Test de l'interface
python quick_start.py gui
```

## 📋 Types de Contributions

### 🐛 Corrections de Bugs
1. Créer une issue décrivant le bug
2. Créer une branche : `git checkout -b fix/description-bug`
3. Corriger le bug avec tests
4. Soumettre une Pull Request

### ✨ Nouvelles Fonctionnalités
1. Discuter de l'idée dans une issue
2. Créer une branche : `git checkout -b feature/nouvelle-fonctionnalite`
3. Implémenter avec tests et documentation
4. Soumettre une Pull Request

### 📚 Documentation
- Améliorer le README ou documentation
- Ajouter des exemples d'utilisation
- Corriger les fautes de frappe

### 🔍 Nouveaux Modules de Sécurité
Voir [Architecture des Modules](#architecture-des-modules) pour créer un nouveau module de vérification.

## 🏗️ Architecture des Modules

### Structure d'un Module
```python
# web_sentinel/checks/nouveau_module.py
from typing import Iterable, List
from ..model import Finding, ScanRequest

def evaluate_nouveau_module(request: ScanRequest) -> Iterable[Finding]:
    """
    Évalue un aspect de sécurité spécifique.
    
    Args:
        request: Configuration du scan avec domain, timeout, etc.
        
    Yields:
        Finding: Résultats de sécurité trouvés
    """
    findings: List[Finding] = []
    
    # Logique de test
    try:
        # Votre code de vérification ici
        pass
        
    except Exception as exc:
        findings.append(Finding(
            check="nouveau-module",
            title="Erreur de connexion",
            severity="medium",
            description=f"Erreur réseau : {exc}",
            remediation="Vérifier la connectivité réseau."
        ))
    
    return findings
```

### Enregistrement du Module
```python
# Dans web_sentinel/orchestrator.py
CheckModule(
    name="nouveau-module",
    description="Description courte pour l'aide CLI",
    runner=evaluate_nouveau_module,
    tags=("passive", "security"),  # passive/active + domaine
)
```

## 🧪 Guidelines de Tests

### Tests Unitaires
```python
# tests/test_nouveau_module.py
import pytest
from web_sentinel.checks.nouveau_module import evaluate_nouveau_module
from web_sentinel.model import ScanRequest

def test_nouveau_module_basique():
    request = ScanRequest(domain="example.com")
    findings = list(evaluate_nouveau_module(request))
    
    assert isinstance(findings, list)
    # Ajouter assertions spécifiques
```

### Tests d'Intégration
- Tester le module via CLI : `python -m web_sentinel.cli example.com --modules nouveau-module`
- Tester via GUI si applicable
- Vérifier la génération de rapports

## 🎯 Standards de Qualité

### Code Style
```bash
# Formatage automatique
black web_sentinel/
isort web_sentinel/

# Vérification qualité
flake8 web_sentinel/
pylint web_sentinel/
```

### Documentation
- Docstrings pour toutes les fonctions publiques
- Commentaires pour la logique complexe
- Mise à jour du README si nécessaire
- Exemples d'utilisation

### Traduction Bilingue
Pour l'interface GUI, ajouter les traductions dans `web_sentinel/gui/localization.py` :

```python
"nouveau_module_title": {
    "fr": "Titre en français",
    "en": "English title"
},
```

## 📝 Pull Request Process

### 1. Préparation
- [ ] Code formaté et testé localement
- [ ] Tests passent : `python run_tests.py`
- [ ] Documentation à jour
- [ ] Commit messages descriptifs

### 2. Soumission
- [ ] Titre descriptif : `[TYPE] Description courte`
- [ ] Description détaillée des changements
- [ ] Liens vers les issues reliées
- [ ] Screenshots si changements UI

### 3. Review
- Répondre aux commentaires constructivement
- Effectuer les changements demandés
- Maintenir l'historique git propre

## 🔒 Considérations de Sécurité

### Modules Passifs vs Actifs
- **Passif par défaut** : Inspection sans modification
- **Mode invasif** : Vérifier `request.allow_invasive` avant les tests actifs
- **Payloads bénins** : Jamais d'exploits réels

### Gestion des Erreurs
```python
try:
    # Opération réseau
    response = requests.get(url, timeout=request.timeout)
except (requests.RequestException, socket.error) as exc:
    # Toujours capturer les erreurs réseau
    findings.append(create_network_error_finding(exc))
```

### Logs Défensifs
- Logger tous les accès réseau
- Éviter les informations sensibles dans les logs
- Utiliser les niveaux de log appropriés

## 🆘 Obtenir de l'Aide

- **Issues GitHub** : Pour bugs et questions techniques
- **Discussions** : Pour idées et questions générales
- **Documentation** : [STRUCTURE.md](STRUCTURE.md) pour l'architecture

## 🎉 Reconnaissance

Tous les contributeurs seront mentionnés dans le fichier CONTRIBUTORS.md.

---

**Merci de contribuer à rendre Web Sentinel plus robuste et utile pour la communauté ! 🛡️**