TP – API VirusTotal : Vérifier la réputation d’URLs et classifier
=================================================================

Durée : 5 heures
Niveau : BTS SIO 1re année (initiation API sécurité + JSON)

------------------------------------------------------------------------------
1) Objectif pédagogique
------------------------------------------------------------------------------
Écrire un script Python qui :
1) lit une liste d’URLs depuis un fichier texte ;
2) interroge l’API VirusTotal (Public API) pour obtenir une analyse/réputation ;
3) classe chaque URL en “clean”, “suspicious” ou “malicious” ;
4) exporte un CSV et affiche un résumé (compte de sites malveillants).

------------------------------------------------------------------------------
2) Exigences techniques (OBLIGATOIRE)
------------------------------------------------------------------------------
- Utiliser un **environnement virtuel** : `python-venv`
- Bibliothèques Python : 
  • `requests` (requêtes HTTP)
  • `python-dotenv` (clé API dans `.env`, jamais en clair)
- Fichier d’entrée : `urls.txt` (une URL par ligne)
- Sorties : `vt_report.csv` + résumé clair en console
- Respecter la **limite de la Public API** (voir § limites & rythme)

------------------------------------------------------------------------------
3) Pré-requis côté plateforme
------------------------------------------------------------------------------
- Debian 13 avec `python3`, `venv`, `pip`
- Connexion Internet
- Compte **gratuit** VirusTotal (Public API) pour obtenir une **API key**

Limites de la Public API (rappel à afficher aux étudiants) :
- **4 requêtes par minute** et **~500 requêtes par jour** (sujet à changement).
  → Imposer un **délai** entre deux analyses pour rester sous le quota.
  (Source : documentation officielle). 

------------------------------------------------------------------------------
4) Mise en place de l’environnement (commandes à exécuter)
------------------------------------------------------------------------------
1) Créer le projet et activer le venv :
   $ mkdir tp-virustotal && cd tp-virustotal
   $ python3 -m venv .venv
   $ source .venv/bin/activate

2) Installer les bibliothèques :
   (.venv) $ python -m pip install --upgrade pip
   (.venv) $ pip install requests python-dotenv

3) Fichiers à créer :
   - `.env` :
       VT_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxx
   - `urls.txt` : 
       https://example.com
       https://test-malware.org/...
       (10–20 URLs maximum pour rester sous les quotas)

------------------------------------------------------------------------------
5) Spécification fonctionnelle du programme (sans code)
------------------------------------------------------------------------------
Nom suggéré : `vt_url_checker.py`

Entrées :
- `urls.txt` (une URL par ligne)
- `.env` avec `VT_API_KEY`

API VirusTotal (v3) – endpoints à utiliser (lecture seule) :
- **Soumettre une URL à analyser** : `POST /api/v3/urls`
  - En-tête : `x-apikey: <VT_API_KEY>`
  - Corps : champ `url` avec l’URL à analyser
  - Retourne un **identifiant d’analyse** (`analysis id`)
- **Récupérer le résultat d’une analyse** : `GET /api/v3/analyses/{analysis_id}`
  - En-tête : `x-apikey: <VT_API_KEY>`
  - Le JSON renvoie notamment des **verdicts** (malicious / suspicious / harmless, etc.)

Alternative (après analyse) :
- **Obtenir l’objet URL** : `GET /api/v3/urls/{url_id}`  
  (nécessite l’**identifiant d’URL** spécifique, différent de l’`analysis id`)

Classification demandée (à implémenter côté script) :
- **malicious** : ≥ 1 moteur classe l’URL comme malveillante
- **suspicious** : aucun “malicious” mais présence de “suspicious”/“phishing” selon les champs renvoyés
- **clean** : tout le reste (harmless / undetected uniquement)

Rythme & réessai :
- Après le `POST /urls`, **attendre** avant le `GET /analyses/{id}` si l’analyse n’est pas terminée. 
- **Respecter le quota** (voir § limites). Introduire un **sleep** global (ex. ~15–20 s) entre soumissions pour éviter 4 req/min.

Sorties attendues :
- **CSV `vt_report.csv`** (une ligne par URL) avec colonnes minimales :
  • `url`
  • `status` (clean / suspicious / malicious)
  • `malicious_count` (nombre de moteurs “malicious”)
  • `suspicious_count`
  • `harmless_count`
  • `undetected_count`
  • `analysis_date` (ou timestamp fourni par l’API)
- **Résumé console** :
  • total d’URLs traitées
  • répartition : #clean / #suspicious / #malicious
  • pourcentage de malveillants

Gestion d’erreurs (à afficher proprement) :
- URL vide/invalide dans le fichier
- 401/403 (clé API manquante/incorrecte)
- 429 (rate limit atteint) → attendre puis reprendre
- Temps d’analyse trop long → indiquer “pending/unknown” et passer à l’URL suivante

------------------------------------------------------------------------------
6) Scénarios de test
------------------------------------------------------------------------------
- Test 1 : 5–8 URLs “classiques” (sites connus) → majorité “clean”
- Test 2 : 2–3 URLs douteuses (listes publiques de phishing/malware de démo) → au moins “suspicious/malicious”
- Test 3 : Gérer un format invalide (ligne vide, URL mal formée)
- Test 4 : Confirmer que le **CSV** est lisible (UTF-8, séparateur clair)
- Test 5 : Vérifier que le **quota/minute** est respecté (pas d’erreurs 429)

------------------------------------------------------------------------------
7) Livrables
------------------------------------------------------------------------------
1) Script Python (`vt_url_checker.py`) – sans la clé dans le code
2) Fichier `vt_report.csv`
3) Capture d’écran du résumé console
4) README (≤ 1 page) :
   - comment créer l’environnement venv et installer les libs
   - comment mettre la clé dans `.env`
   - comment lancer le script
   - description des colonnes CSV

------------------------------------------------------------------------------
8) Barème (20 points)
------------------------------------------------------------------------------
- Appels API (POST analyse + GET résultat) ....................... 6 pts
- Parsing JSON & classification clean/suspicious/malicious ........ 6 pts
- Export CSV + résumé console .................................... 4 pts
- Qualité (CLI propre, gestion quotas/erreurs, README) ........... 4 pts

------------------------------------------------------------------------------
9) Bonus (facultatif)
------------------------------------------------------------------------------
- **Graphe simple** (bar chart) du % clean / suspicious / malicious
- Colonne “**top verdict**” (catégorie la plus sévère)
- Option `--limit` pour plafonner le nombre d’URLs analysées
- Log fichier avec timestamp et erreurs 429/401