veza/veza-backend-api/P1_004_VULNERABILITY_SCANNING_REPORT.md

# ✅ P1-004 — VULNERABILITY SCANNING CI

**Date**: 2025-12-12  
**Objectif**: Ajouter un job CI qui scanne les vulnérabilités (dépendances Go, images Docker)

---

## 📋 RÉSUMÉ

✅ **Workflow GitHub Actions créé** : Scan automatique des vulnérabilités Go et Docker  
✅ **Scan Go (govulncheck)** : Bloque les PRs si HIGH/CRITICAL trouvées  
✅ **Scan Docker (Trivy)** : Scan des images Docker avec upload dans GitHub Security  
✅ **Documentation complète** : Guide d'utilisation locale et CI  
✅ **Makefile enrichi** : Nouvelles cibles pour scans locaux

---

## 📁 FICHIERS CRÉÉS/MODIFIÉS

### 1. `.github/workflows/vulnerability-scan.yml` (nouveau)
- ✅ Workflow GitHub Actions pour scan automatique
- ✅ Job `scan-go-dependencies` : Utilise `govulncheck`
- ✅ Job `scan-docker-image` : Utilise Trivy (mode gate)
- ✅ Job `scan-docker-image-report-only` : Utilise Trivy (mode report, schedule)
- ✅ Bloque les PRs si HIGH/CRITICAL trouvées
- ✅ Upload des rapports en artifacts
- ✅ Commentaire automatique sur les PRs

### 2. `docs/VULNERABILITY_SCANNING.md` (nouveau)
- ✅ Guide complet pour scans locaux
- ✅ Instructions d'installation (govulncheck, Trivy)
- ✅ Exemples de commandes
- ✅ Interprétation des résultats
- ✅ Bonnes pratiques

### 3. `Makefile` (modifié)
- ✅ Nouvelle cible `vulncheck` : Scan Go uniquement
- ✅ Nouvelle cible `docker-scan` : Scan Docker (CRITICAL/HIGH)
- ✅ Nouvelle cible `docker-scan-full` : Scan Docker (toutes sévérités)
- ✅ Cible `security` existante conservée

---

## 🎯 FONCTIONNALITÉS

### Scan Go (govulncheck)

**Déclenchement** :
- Sur chaque push/PR vers `main` ou `develop`
- Tous les lundis à 2h UTC (schedule)
- Manuellement via `workflow_dispatch`

**Comportement** :
- ✅ Bloque le merge si HIGH/CRITICAL trouvées
- ✅ Upload du rapport en artifact
- ✅ Commentaire automatique sur les PRs

**Exécution locale** :
```bash
# Via Makefile
make vulncheck

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

### Scan Docker (Trivy)

**Déclenchement** :
- Sur chaque push/PR (mode gate, bloque si HIGH/CRITICAL)
- Sur schedule (mode report only, ne bloque pas)

**Comportement** :
- ✅ Scan de l'image Docker construite
- ✅ Upload des résultats dans GitHub Security (SARIF)
- ✅ Upload du rapport en artifact
- ✅ Bloque le merge si HIGH/CRITICAL trouvées (mode gate)

**Exécution locale** :
```bash
# Via Makefile
make docker-scan          # CRITICAL/HIGH uniquement
make docker-scan-full     # Toutes sévérités

# Directement
trivy image veza-backend-api:latest
```

---

## 🔄 WORKFLOW CI

### Structure

```yaml
jobs:
  scan-go-dependencies:
    - Checkout
    - Setup Go
    - Install govulncheck
    - Run govulncheck
    - Check for HIGH/CRITICAL
    - Upload report
    - Comment PR

  scan-docker-image:
    - Checkout
    - Setup Docker Buildx
    - Build image
    - Run Trivy
    - Upload to GitHub Security
    - Upload report

  scan-docker-image-report-only:
    - (même structure, mais exit-code: 0)
```

### Permissions

Le workflow nécessite :
- `contents: read` : Lire le code
- `security-events: write` : Uploader dans GitHub Security

### Artifacts

Les rapports sont sauvegardés en artifacts :
- `govulncheck-report` : Rapport Go (30 jours)
- `trivy-report` : Rapport Docker (30 jours)
- `trivy-report-scheduled` : Rapport schedule (30 jours)

---

## 📊 EXEMPLES DE SORTIE

### govulncheck

```
Scanning Go dependencies for vulnerabilities...

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()

❌ HIGH or CRITICAL vulnerabilities found!
```

### 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            │
└─────────────────────┴────────────────┴──────────┴─────────────────────┘
```

---

## 🧪 VALIDATION

### Tests locaux

#### Scan Go

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

# Exécution
govulncheck ./...

# Via Makefile
make vulncheck
```

**Résultat attendu** : Scan complet, rapport des vulnérabilités trouvées

#### Scan Docker

```bash
# Construire l'image
make docker-build

# Scanner
make docker-scan

# Ou directement
trivy image veza-backend-api:latest
```

**Résultat attendu** : Scan de l'image, rapport des vulnérabilités

### Tests CI

Le workflow sera testé lors du prochain push/PR vers `main` ou `develop`.

Pour tester manuellement :

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

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

---

## 📝 COMMANDES LOCALES

### Scan Go

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

# Scan complet
govulncheck ./...

# Scan avec rapport JSON
govulncheck -json ./... > vulncheck-report.json

# Via Makefile
make vulncheck
make security  # Inclut aussi gosec
```

### Scan Docker

```bash
# Installation Trivy
# macOS
brew install trivy

# 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

# Construire l'image
make docker-build

# Scanner
make docker-scan          # CRITICAL/HIGH uniquement
make docker-scan-full     # Toutes sévérités

# Ou directement
trivy image veza-backend-api:latest
trivy image --severity CRITICAL,HIGH veza-backend-api:latest
```

### Scan Dockerfile

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

---

## 🔍 DÉTAILS TECHNIQUES

### govulncheck

- **Source** : Base de données Go Vulnerability
- **Méthode** : Analyse des dépendances dans `go.mod` et `go.sum`
- **Sévérités** : CRITICAL, HIGH, MEDIUM, LOW
- **Blocage** : HIGH/CRITICAL bloquent le merge

### Trivy

- **Source** : Base de données CVE (Common Vulnerabilities and Exposures)
- **Méthode** : Scan de l'image Docker construite
- **Sévérités** : CRITICAL, HIGH, MEDIUM, LOW, UNKNOWN
- **Blocage** : HIGH/CRITICAL bloquent le merge (mode gate)
- **Upload** : Résultats uploadés dans GitHub Security (SARIF)

---

## ⚙️ CONFIGURATION

### Mode "Report Only"

Par défaut, le workflow bloque les PRs si 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    
```

### Ignorer des vulnérabilités

#### govulncheck

Créer un fichier `.govulncheck-ignore` :

```
# Ignorer une vulnérabilité spécifique
GO-2024-XXXX
```

#### Trivy

Créer un fichier `.trivyignore` :

```
# Ignorer une CVE spécifique
CVE-2024-XXXX
```

---

## ✅ VALIDATION

### Compilation

```bash
go build ./...
```

**Résultat** : ✅ **Compilation réussie**

### Tests locaux

```bash
# Scan Go
make vulncheck

# Scan Docker (si image construite)
make docker-build
make docker-scan
```

**Résultat** : ✅ **Commandes exécutables localement**

### CI

Le workflow sera validé lors du prochain push/PR.

---

## 🎯 OBJECTIFS ATTEINTS

- ✅ **Scan Go (govulncheck)** : Workflow CI créé, bloque si HIGH/CRITICAL
- ✅ **Scan Docker (Trivy)** : Workflow CI créé, upload dans GitHub Security
- ✅ **Documentation** : Guide complet dans `docs/VULNERABILITY_SCANNING.md`
- ✅ **Commandes locales** : Makefile enrichi, commandes documentées
- ✅ **Mode report only** : Disponible pour schedule (ne bloque pas)
- ✅ **Mode gate** : Bloque les PRs si HIGH/CRITICAL trouvées

---

## 📋 COMMANDES DE VALIDATION

### Installation des outils

```bash
make install-tools
```

### Scan Go

```bash
make vulncheck
```

### Scan Docker

```bash
make docker-build
make docker-scan
```

### Scan complet (sécurité)

```bash
make security
```

---

## 🔗 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)

---

**Statut final** : ✅ **P1-004 IMPLÉMENTÉ ET DOCUMENTÉ**