veza/veza-backend-api/docs/VULNERABILITY_SCANNING.md

# Vulnerability Scanning

Ce document décrit comment scanner les vulnérabilités dans le projet Veza Backend API.

## 🔒 Scan des Dépendances Go

### Installation de govulncheck

```bash
go install golang.org/x/vuln/cmd/govulncheck@latest
```

Ou via le Makefile :

```bash
make install-tools
```

### Exécution locale

#### Scan complet

```bash
govulncheck ./...
```

#### Scan avec rapport détaillé

```bash
govulncheck -json ./... > vulncheck-report.json
govulncheck ./... > vulncheck-report.txt
```

#### Via Makefile

```bash
make security
```

Cette commande exécute :
- `gosec` pour l'analyse statique de sécurité
- `govulncheck` pour les vulnérabilités des dépendances

### Interprétation des résultats

- **CRITICAL** : Vulnérabilité critique nécessitant une action immédiate
- **HIGH** : Vulnérabilité élevée nécessitant une attention prioritaire
- **MEDIUM** : Vulnérabilité moyenne à traiter
- **LOW** : Vulnérabilité faible, peut être traitée plus tard

### Correction des vulnérabilités

1. Identifier la dépendance vulnérable dans le rapport
2. Vérifier si une version corrigée existe :
   ```bash
   go list -m -u <package>
   ```
3. Mettre à jour la dépendance :
   ```bash
   go get -u <package>@latest
   go mod tidy
   ```
4. Re-scanner pour vérifier :
   ```bash
   govulncheck ./...
   ```

---

## 🐳 Scan des Images Docker

### Installation de Trivy

#### Via Homebrew (macOS)

```bash
brew install trivy
```

#### Via Docker

```bash
docker pull aquasec/trivy:latest
```

#### Via script d'installation

```bash
# Linux
wget -qO - https://aquasecurity.github.io/trivy-repo/deb/public.key | sudo apt-key add -
echo "deb https://aquasecurity.github.io/trivy-repo/deb $(lsb_release -sc) main" | sudo tee -a /etc/apt/sources.list.d/trivy.list
sudo apt-get update
sudo apt-get install trivy
```

### Exécution locale

#### Construire l'image Docker

```bash
make docker-build
# ou
docker build -t veza-backend-api:scan .
```

#### Scanner l'image

```bash
# Scan avec sortie table
trivy image veza-backend-api:scan

# Scan avec sortie JSON
trivy image -f json -o trivy-report.json veza-backend-api:scan

# Scan uniquement CRITICAL et HIGH
trivy image --severity CRITICAL,HIGH veza-backend-api:scan

# Scan avec ignore des vulnérabilités non corrigées
trivy image --ignore-unfixed veza-backend-api:scan
```

#### Via Docker (si Trivy n'est pas installé localement)

```bash
docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  aquasec/trivy:latest image veza-backend-api:scan
```

### Scan d'un fichier Dockerfile

```bash
trivy fs --security-checks vuln .
```

---

## 🔄 CI/CD

### GitHub Actions

Le workflow `.github/workflows/vulnerability-scan.yml` exécute automatiquement :

1. **Scan Go (govulncheck)** :
   - Sur chaque push/PR vers `main` ou `develop`
   - Tous les lundis à 2h UTC (schedule)
   - Bloque le merge si HIGH/CRITICAL trouvées

2. **Scan Docker (Trivy)** :
   - Sur chaque push/PR (mode gate)
   - Sur schedule (mode report only)
   - Upload des résultats dans GitHub Security

### Déclenchement manuel

```bash
# Via GitHub CLI
gh workflow run vulnerability-scan.yml

# Via l'interface GitHub
# Actions > Vulnerability Scan > Run workflow
```

---

## 📊 Exemples de Rapports

### Rapport govulncheck

```
Vulnerability #1: GO-2024-XXXX
  Package: github.com/example/package
  Version: v1.2.3
  Fixed in: v1.2.5
  Severity: HIGH
  Description: Description of the vulnerability
  Call stacks:
    - main.go:42: functionCall()
```

### Rapport Trivy

```
veza-backend-api:scan (alpine 3.18.0)
Total: 15 (CRITICAL: 2, HIGH: 5, MEDIUM: 6, LOW: 2)

┌─────────────────────┬────────────────┬──────────┬─────────────────────┐
│      Library         │ Vulnerability  │ Severity │   Installed Version │
├─────────────────────┼────────────────┼──────────┼─────────────────────┤
│ openssl              │ CVE-2024-XXXX  │ CRITICAL │ 3.1.0-r0            │
│ libcrypto            │ CVE-2024-YYYY  │ HIGH     │ 3.1.0-r0            │
└─────────────────────┴────────────────┴──────────┴─────────────────────┘
```

---

## 🛠️ Intégration dans le Makefile

Le Makefile inclut déjà une cible `security` :

```bash
make security
```

Cette commande exécute :
- `gosec` : Analyse statique de sécurité
- `govulncheck` : Scan des vulnérabilités Go

Pour ajouter le scan Docker :

```bash
# Ajouter dans le Makefile
docker-scan: docker-build
	@echo "$(GREEN)🔒 Scan de l'image Docker...$(NC)"
	@trivy image $(DOCKER_IMAGE):$(DOCKER_TAG)
```

---

## ⚠️ Mode "Report Only"

Par défaut, le workflow CI bloque les PRs si des vulnérabilités HIGH/CRITICAL sont trouvées.

Pour activer le mode "report only" (ne bloque pas), modifier le workflow :

```yaml
- name: Check for HIGH/CRITICAL vulnerabilities
  run: |
    # ... scan ...
    exit 0  # Ne pas bloquer, juste reporter    
```

---

## 📝 Bonnes Pratiques

1. **Scanner régulièrement** : Exécuter les scans au moins une fois par semaine
2. **Mettre à jour les dépendances** : Maintenir les dépendances à jour
3. **Réviser les rapports** : Analyser les vulnérabilités et prioriser les corrections
4. **Documenter les exceptions** : Si une vulnérabilité ne peut pas être corrigée immédiatement, documenter pourquoi
5. **Automatiser** : Utiliser les workflows CI pour automatiser les scans

---

## 🔗 Ressources

- [govulncheck Documentation](https://pkg.go.dev/golang.org/x/vuln/cmd/govulncheck)
- [Trivy Documentation](https://aquasecurity.github.io/trivy/)
- [Go Vulnerability Database](https://pkg.go.dev/vuln/)
- [GitHub Security Advisories](https://github.com/advisories)