geo/api/docs/API-SECURITY.md

# API Security & Performance Monitoring

## 📋 Vue d'ensemble

Système complet de sécurité et monitoring pour l'API GeoSector implémenté et opérationnel.

### ✅ Fonctionnalités implémentées

- **Détection d'intrusions** : Brute force, SQL injection, patterns de scan
- **Monitoring des performances** : Temps de réponse, utilisation mémoire, requêtes DB
- **Alertes email intelligentes** : Throttling, niveaux de priorité
- **Blocage d'IP automatique** : Temporaire ou permanent
- **Traçabilité complète** : Historique pour audit et analyse

## 🏗️ Architecture

### Tables de base de données (préfixe `sec_`)

```sql
-- 4 tables créées dans scripts/sql/create_security_tables.sql
sec_alerts                 -- Alertes de sécurité
sec_performance_metrics    -- Métriques de performance
sec_failed_login_attempts  -- Tentatives de connexion échouées
sec_blocked_ips           -- IPs bloquées
```

### Services PHP implémentés

```
src/Services/Security/
├── AlertService.php        # Gestion centralisée des alertes
├── EmailThrottler.php      # Anti-spam pour emails
├── SecurityMonitor.php     # Détection des menaces
├── PerformanceMonitor.php  # Monitoring des temps
└── IPBlocker.php          # Gestion des blocages IP
```

### Contrôleur d'administration

```
src/Controllers/SecurityController.php  # Interface d'administration
```

## 🚀 Installation

### 1. Créer les tables

```bash
# Exécuter le script SQL sur chaque environnement
mysql -u root -p geo_app < scripts/sql/create_security_tables.sql
```

### 2. Configurer le cron de purge

```bash
# Ajouter dans crontab (crontab -e)
0 2 * * * /usr/bin/php /var/www/geosector/api/scripts/cron/cleanup_security_data.php >> /var/log/security_cleanup.log 2>&1
```

### 3. Tester l'installation

```bash
php test_security.php
```

## 🔒 Fonctionnement

### Détection automatique

Le système détecte et bloque automatiquement :

- **Brute force** : 5 tentatives échouées en 5 minutes → IP bloquée 1h
- **SQL injection** : Patterns suspects → IP bloquée définitivement
- **Scan de vulnérabilités** : Accès aux fichiers sensibles → IP bloquée 1h
- **Rate limiting** : Plus de 60 requêtes/minute → Rejet temporaire

### Monitoring de performance

Chaque requête est automatiquement monitorée :

```php
// Dans index.php
PerformanceMonitor::startRequest();
// ... traitement ...
PerformanceMonitor::endRequest($endpoint, $method, $statusCode);
```

### Alertes email

Configuration des niveaux :

- **INFO** : Log uniquement
- **WARNING** : Email avec throttling 1h
- **ERROR** : Email avec throttling 15min
- **CRITICAL** : Email avec throttling 5min
- **SECURITY** : Email immédiat, priorité haute

## 📊 Endpoints d'administration

Tous les endpoints nécessitent une authentification admin (role >= 2) :

```
GET  /api/admin/metrics           # Métriques de performance
GET  /api/admin/alerts            # Alertes actives
POST /api/admin/alerts/:id/resolve # Résoudre une alerte
GET  /api/admin/blocked-ips       # IPs bloquées
POST /api/admin/unblock-ip        # Débloquer une IP
POST /api/admin/block-ip          # Bloquer une IP manuellement
GET  /api/admin/security-report   # Rapport complet
POST /api/admin/cleanup           # Nettoyer les anciennes données
POST /api/admin/test-alert        # Tester les alertes
```

## 🔧 Configuration

### Seuils par défaut (modifiables dans les services)

```php
// PerformanceMonitor.php
const DEFAULT_THRESHOLDS = [
    'response_time_warning' => 1000,    // 1 seconde
    'response_time_critical' => 3000,   // 3 secondes
    'db_time_warning' => 500,           // 500ms
    'db_time_critical' => 1000,         // 1 seconde
    'memory_warning' => 64,             // 64 MB
    'memory_critical' => 128            // 128 MB
];

// SecurityMonitor.php
- Brute force : 5 tentatives en 5 minutes
- Rate limit : 60 requêtes par minute
- 404 pattern : 10 erreurs 404 en 10 minutes

// EmailThrottler.php
const DEFAULT_CONFIG = [
    'max_per_hour' => 10,
    'max_per_day' => 50,
    'digest_after' => 5,
    'cooldown_minutes' => 60
];
```

### Rétention des données

Configurée dans `scripts/cron/cleanup_security_data.php` :

```php
$RETENTION_DAYS = [
    'performance_metrics' => 30,      // 30 jours
    'failed_login_attempts' => 7,     // 7 jours
    'resolved_alerts' => 90,          // 90 jours
    'expired_blocks' => 0              // Déblocage immédiat
];
```

## 📈 Métriques surveillées

### Performance
- Temps de réponse total
- Temps cumulé des requêtes DB
- Nombre de requêtes DB
- Utilisation mémoire (pic et moyenne)
- Codes HTTP de réponse

### Sécurité
- Tentatives de connexion échouées
- IPs bloquées (temporaires/permanentes)
- Patterns d'attaque détectés
- Alertes par type et niveau

## 🛡️ Patterns de détection

### SQL Injection
```php
// Patterns détectés dans SecurityMonitor.php
- UNION SELECT
- DROP TABLE
- INSERT INTO
- UPDATE SET
- DELETE FROM
- Script tags
- OR 1=1
- Commentaires SQL (--)
```

### Fichiers sensibles
```php
// Patterns de scan détectés
- admin, administrator
- wp-admin, phpmyadmin
- .git, .env
- config.php
- backup, .sql, .zip
- shell.php, eval.php
```

## 📝 Exemples d'utilisation

### Déclencher une alerte manuelle

```php
use App\Services\Security\AlertService;

AlertService::trigger('CUSTOM_ALERT', [
    'message' => 'Événement important détecté',
    'details' => ['user' => $userId, 'action' => $action]
], 'WARNING');
```

### Bloquer une IP manuellement

```php
use App\Services\Security\IPBlocker;

// Blocage temporaire (1 heure)
IPBlocker::block('192.168.1.100', 3600, 'Comportement suspect');

// Blocage permanent
IPBlocker::blockPermanent('192.168.1.100', 'Attaque confirmée');
```

### Obtenir les statistiques

```php
use App\Services\Security\SecurityMonitor;
use App\Services\Security\PerformanceMonitor;

$securityStats = SecurityMonitor::getSecurityStats();
$perfStats = PerformanceMonitor::getStats(null, 24); // 24h
```

## ⚠️ Points d'attention

### RGPD
- Les IPs sont des données personnelles
- Durée de conservation limitée (voir rétention)
- Anonymisation après traitement

### Performance
- Overhead < 5ms par requête
- Optimisation des tables avec index
- Purge automatique des anciennes données

### Sécurité
- Pas d'exposition de données sensibles dans les alertes
- Chiffrement des données utilisateur
- Whitelist pour IPs de confiance (localhost)

## 🔄 Maintenance

### Quotidienne (cron)
```bash
# Purge automatique à 2h du matin
0 2 * * * php /var/www/geosector/api/scripts/cron/cleanup_security_data.php
```

### Hebdomadaire
- Vérifier les alertes actives
- Analyser les tendances de performance
- Ajuster les seuils si nécessaire

### Mensuelle
- Analyser le rapport de sécurité
- Mettre à jour les IPs whitelist/blacklist
- Optimiser les tables si nécessaire

## 🐛 Dépannage

### Les tables n'existent pas
```bash
# Créer les tables
mysql -u root -p geo_app < scripts/sql/create_security_tables.sql
```

### Pas d'alertes email
- Vérifier la configuration email dans `AppConfig`
- Vérifier les logs : `tail -f logs/geosector-*.log`
- Tester avec : `POST /api/admin/test-alert`

### IP bloquée par erreur
```bash
# Via API
curl -X POST https://dapp.geosector.fr/api/admin/unblock-ip \
  -H "Authorization: Bearer TOKEN" \
  -d '{"ip": "192.168.1.100"}'

# Via MySQL
UPDATE sec_blocked_ips SET unblocked_at = NOW() WHERE ip_address = '192.168.1.100';
```

## 📚 Ressources

- [OWASP Top 10](https://owasp.org/www-project-top-ten/)
- [PHP Security Best Practices](https://www.php.net/manual/en/security.php)
- Code source : `/src/Services/Security/`
- Tests : `test_security.php`
- Logs : `/logs/geosector-*.log`

## 🎯 Statut d'implémentation

✅ **Phase 1** : Infrastructure de base - COMPLÉTÉ
- Tables créées avec préfixe `sec_`
- Services PHP implémentés
- Intégration dans index.php et Database.php

✅ **Phase 2** : Monitoring de Performance - COMPLÉTÉ
- Chronométrage automatique des requêtes
- Monitoring des requêtes DB
- Alertes sur dégradation

✅ **Phase 3** : Détection d'intrusions - COMPLÉTÉ
- Détection brute force
- Détection SQL injection
- Blocage IP automatique

✅ **Phase 4** : Alertes Email - COMPLÉTÉ
- Service d'alertes avec throttling
- Templates d'emails
- Niveaux de priorité

✅ **Phase 5** : Administration - COMPLÉTÉ
- Endpoints d'administration
- Interface de gestion
- Rapports de sécurité

✅ **Phase 6** : Maintenance - COMPLÉTÉ
- Script de purge automatique
- Optimisation des tables
- Documentation complète

---

*Dernière mise à jour : 2025-01-17*
*Version : 1.0.0*