- **14 Codes de recherche** : Spécifiques au SGBD (MySQL, PostgreSQL, MSSQL, Oracle, SQLite) + spécifiques à la technique
- **Empreinte SGBD** : Détection automatique du type et de la version de la base de données
- **Contournement WAF** : Plus de 170 payloads de contournement en mode agressif (hex, encodage URL, commentaires en ligne, variantes de casse)
- **Détection des variables de session** : Chaîne POST→GET pour les schémas d’authentification de type DVWA-high
- **Analyseur intelligent** : BFS avec extraction de popups/onclick (`--js`), sitemap, robots.txt
- **Renforcement anti-faux positifs** : Scoring de similarité SequenceMatcher + confirmation multi-payloads

### Intégration CI/CD```bash
# Pipeline-friendly: exit 10 if high+ findings found
python -m pyth --target https://staging.app.com --aggressive --fail-on high
echo $?  # 0=clean, 10=findings found, 1=error

# SARIF for GitHub Security / GitLab SAST
python -m pyth --target https://app.com --aggressive --sarif > results.sarif

# Compare vs last scan — show what's new, what's fixed
python -m pyth --target https://app.com --aggressive --diff last --html

Passez `--auth-header` plusieurs fois pour plusieurs en-têtes.

### Analyse par IA

Choisissez votre fournisseur d'IA depuis la ligne de commande :

| Fournisseur                    | Idéal pour                                | Vitesse     | Coût           | Confidentialité |
| ------------------------------ | ----------------------------------------- | ----------- | -------------- | --------------- |
| **OpenAI gpt-4o-mini** (défaut)| Qualité professionnelle, faible coût       | Rapide      | ~$0.02/scan    | Standard        |
| **Anthropic Claude**           | Confidentialité, correction de code        | Rapide      | ~$0.06/scan    | Améliorée       |
| **Ollama (Local)**             | Confidentialité totale                     | Lent (CPU)  | Gratuit        | 100 % hors ligne|```bash
# Standard analysis
python -m pyth --target http://example.com --use-ai --ai-tone technical --html

# Agent mode: AI queries NVD for real CVEs (no API key for NVD)
python -m pyth --target http://example.com --use-ai --ai-agent --html

# Multi-provider comparison
python -m pyth --target http://example.com --use-ai \
  --ai-compare "openai:gpt-4o-mini,anthropic:claude-3-5-haiku-20241022" --html

# With budget cap
python -m pyth --target http://example.com --use-ai --ai-budget 0.05 --html

**Rapports HTML** (Conviviaux)

- Barre de filtrage : sévérité, catégorie OWASP, méthode de détection, SGBD
- Badges OWASP/CWE/CVE par résultat (cliquables vers des références externes)
- Score CVSS de base + contextuel avec code couleur
- Sections de preuves extensibles avec visualisation des payloads
- Onglets d'analyse IA (standard / agent / comparer)
- Section Diff (résultats nouveaux/corrigés/persistants)
- Thème Oracle (violet `#6a11cb`) — livrable aux clients sans édition

### Codes des résultats

Tous les codes → **OWASP A03 Injection** / **CWE-89 SQL Injection**

| Code             | Type               | SGBD / Vecteur            | Mode       |
| ---------------- | ------------------ | ------------------------ | ---------- |
| `PYTHIA-SQL-001` | Error-Based        | MySQL / MariaDB          | Sûr       |
| `PYTHIA-SQL-002` | Error-Based        | PostgreSQL               | Sûr       |
| `PYTHIA-SQL-003` | Error-Based        | MSSQL                    | Sûr       |
| `PYTHIA-SQL-004` | Error-Based        | Oracle                   | Sûr       |
| `PYTHIA-SQL-005` | Error-Based        | SQLite                   | Sûr       |
| `PYTHIA-SQL-010` | Boolean Blind      | Tout SGBD                 | Sûr       |
| `PYTHIA-SQL-011` | Boolean Blind      | Via l'injection d'en-tête     | Sûr       |
| `PYTHIA-SQL-020` | Time-Based         | MySQL SLEEP()            | Agressif |
| `PYTHIA-SQL-021` | Time-Based         | MSSQL WAITFOR            | Agressif |
| `PYTHIA-SQL-022` | Time-Based         | PostgreSQL pg_sleep()    | Agressif |
| `PYTHIA-SQL-030` | UNION-Based        | Paramètre GET/POST       | Agressif |
| `PYTHIA-SQL-031` | UNION-Based        | Via cookie               | Agressif |
| `PYTHIA-SQL-040` | Second-Order       | Motif stockage → récupération | Agressif |
| `PYTHIA-SQL-050` | ORDER BY Injection | Paramètre de tri numérique   | Agressif |

---

## Validation & Tests

Pythia v0.2.0 a été **validé empiriquement** à l'aide d'applications vulnérables contrôlées basées sur Docker.

### Résultats QA (mai 2026)

| Cible                  | Mode                              | Résultats        | Notes                                      |
| ----------------------- | --------------------------------- | --------------- | ------------------------------------------ |
| **Lab PHP** (8081)      | `--aggressive`                    | **26 résultats** | Toutes les 4 techniques + second-order + ORDER BY |
| **Lab Flask** (8082)    | `--js --aggressive`               | **18 résultats** | Session-var + second-order + ORDER BY      |
| **DVWA Low**            | `--no-crawl --aggressive`         | 4/4 techniques  | PYTHIA-SQL-001/010/020/030                 |
| **DVWA Medium**         | `--no-crawl --aggressive`         | 4/4 techniques  | Formulaire POST, toutes les techniques                  |
| **DVWA High**           | `--js --max-pages 2 --aggressive` | 4/4 techniques  | Chaîne POST→GET de variable de session            |
| **Test de faux positifs** | `--aggressive`                    | **0 résultats**  | URL statique — aucun faux positif confirmé  |

**Validations clés :**

- ✅ Les 14 codes de résultat fonctionnels
- ✅ DVWA haut (motif de variable de session) — parité 4/4 complète
- ✅ Détection de second-order (PYTHIA-SQL-040)
- ✅ Détection d'injection ORDER BY (PYTHIA-SQL-050)
- ✅ Zéro faux positif sur les URL statiques
- ✅ Codes de sortie `--fail-on` (0/10/1) corrects
- ✅ La sortie SARIF 2.1.0 valide
- ✅ Comparaison `--diff last` fonctionnelle
- ✅ `--auth-header` transmet les en-têtes via toutes les requêtes

---

## Démarrage rapide

### Prérequis

- **Python 3.11+** (3.12 recommandé)
- **pip** (gestionnaire de paquets Python)
- **Docker** (optionnel, pour les labs vulnérables)

### Installation

**1. Clonez le dépôt**```bash
git clone https://github.com/rodhnin/pythia-sql-clairvoyance.git
cd pythia-sql-clairvoyance

**3. Installer les dépendances**```bash
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

**5. Vérifier l'installation**```bash
python -m pyth --version
# Output: Pythia v0.2.0

Rapports sauvegardés dans `~/.pythia/reports/`.

---

## Guide d'utilisation

### Référence des options CLI```
Scan Options:
  --target URL          Target URL to scan
  --safe                Safe mode (default): error-based + boolean-blind
  --aggressive          Aggressive mode: all 6 techniques + WAF bypass payloads

Auth:
  --cookie COOKIE       Session cookie string
  --auth-header HEADER  Custom HTTP header (pass multiple times for multiple headers)
  --auto-csrf           Automatically detect and include CSRF tokens

Crawler:
  --max-depth N         Max crawl depth (default: 2)
  --max-pages N         Max pages to crawl (default: 100)
  --no-robots           Ignore robots.txt
  --no-crawl            Skip BFS crawl, test target URL only
  --js                  JS-aware popup/onclick URL extraction

Output:
  --report-dir DIR      Output directory for reports (default: ~/.pythia/reports/)
  --html                Generate HTML report
  --db                  Save findings to database
  --diff SCAN_ID        Compare vs previous scan (use "last" for most recent)
  --sarif               Output SARIF 2.1.0 to stdout (logs redirect to stderr)
  --fail-on SEVERITY    Exit 10 if findings found at this severity or higher

CI/CD:
  --fail-on SEVERITY    Exit codes: 0=clean, 10=findings found, 1=error

Logging:
  -v / -vv / -vvv       Verbosity levels
  -q                    Quiet mode (errors only)
  --log-file FILE       Log to file
  --log-json            Structured JSON logging
  --no-color            Disable colored output

AI:
  --use-ai              Enable AI analysis
  --ai-tone TONE        Analysis tone: technical, non_technical, both
  --api-key-env VAR     Environment variable name for API key
  --ai-provider NAME    AI provider: openai, anthropic, ollama
  --ai-model MODEL      Model name (e.g. gpt-4o-mini, claude-3-5-haiku-20241022)
  --ai-stream           Stream AI output token by token
  --ai-compare LIST     Compare providers (e.g. "openai,anthropic" or "openai:gpt-4o-mini,anthropic:claude-3-5-haiku-20241022")
  --ai-agent            Agent mode: NVD CVE lookup + iterative analysis
  --ai-budget AMOUNT    Cost cap per scan in USD

Consent:
  --gen-consent DOMAIN  Generate consent token for domain
  --verify-consent METHOD  Verify consent: http or dns
  --domain DOMAIN       Domain for consent verification
  --token TOKEN         Consent token value

Advanced:
  --rate N              Request rate limit (default: 2.0 safe, 5.0 aggressive)
  --timeout N           HTTP timeout in seconds (default: 10)
  --user-agent STRING   Custom User-Agent
  --no-verify-ssl       Disable SSL verification
  --threads N           Worker threads (default: 5)
  --version             Show version and exit

### CI/CD Intégration```bash
# Exit 10 if high or critical findings exist (blocks pipeline)
python -m pyth \
  --target https://staging.myapp.com \
  --aggressive \
  --fail-on high

# SARIF output for GitHub Security tab
python -m pyth \
  --target https://staging.myapp.com \
  --aggressive \
  --sarif > results.sarif

# Compare vs last scan to see what changed
python -m pyth \
  --target https://staging.myapp.com \
  --aggressive \
  --diff last \
  --html

### Crawling avec prise en compte du JavaScript```bash
# Extract popup/onclick URLs for complex navigation patterns
python -m pyth \
  --target http://localhost:8082 \
  --js \
  --aggressive \
  --html

# DVWA high: session-variable form (needs popup URL extraction)
python -m pyth \
  --target "http://localhost:8080/vulnerabilities/sqli/" \
  --js \
  --max-pages 2 \
  --aggressive \
  --cookie "PHPSESSID=abc123; security=high"

---

## Déploiement Docker

Pythia propose deux options de déploiement Docker :

1. **Image de scanner**: Construire Pythia en tant qu'image Docker pour des analyses ponctuelles
2. **Lab de test**: Applications vulnérables (DVWA, PHP, Flask) pour des tests sécurisés

### Démarrage rapide```bash
cd docker
./deploy.sh

---

## Analyse basée sur l'IA

Pythia utilise **LangChain v1.0.0** avec la prise en charge de plusieurs fournisseurs d'IA.

### Deux modes d'analyse

- **Technique** : Requêtes préparées, requêtes paramétrées, code de validation d'entrée (PHP/PDO, Python/SQLAlchemy, Node.js/pg, Java/PreparedStatement)
- **Exécutif** : Évaluation des risques en langage simple destinée aux parties prenantes et à la direction

### Changement de fournisseurs```bash
# CLI flags (v0.2.0) — no YAML editing required
python -m pyth --target http://example.com --use-ai --ai-provider anthropic --ai-model claude-3-5-haiku-20241022 --html
python -m pyth --target http://example.com --use-ai --ai-provider ollama --ai-model llama3.2 --html

### Cartographie de la sévérité

- **CRITIQUE (9.0-10.0)** : Basé sur les erreurs, basé sur le temps, basé sur UNION, injection de second ordre avec exploitation confirmée
- **HAUT (7.0-8.9)** : Aveugle booléen (haute confiance), injection ORDER BY
- **MOYEN (4.0-6.9)** : Aveugle booléen (confiance moyenne)
- **FAIBLE (0.1-3.9)** : SQLi potentiel avec preuves non concluantes

### Codes de sortie

| Code  | Meaning                                                                       |
| ----- | ----------------------------------------------------------------------------- |
| `0`   | Analyse terminée, aucun résultat au seuil `--fail-on` (ou `--fail-on` non utilisé) |
| `1`   | Erreur technique (connexion, délai d'attente, base de données)               |
| `10`  | Résultats trouvés au niveau ou au-dessus du seuil de sévérité `--fail-on`    |
| `130` | Utilisateur annulé (Ctrl+C)                                                  |

---

## Persistance de la base de données

Base de données SQLite **partagée avec l'écosystème Argos** (`~/.argos/argos.db`) :

- **Historique des analyses** : Date, durée, nombre de résultats, méthodes de détection
- **Répertoire des résultats** : Base de données consultable de vulnérabilités d'injection SQL
- **Domaines vérifiés** : Suivi des jetons de consentement avec expiration
- **Coûts IA** : Suivi des coûts par analyse (nouveau dans v0.2.0)```bash
# Query recent Pythia scans
sqlite3 ~/.argos/argos.db "SELECT * FROM scans WHERE tool='pythia' ORDER BY scan_id DESC LIMIT 10"

# Find critical SQL injections
sqlite3 ~/.argos/argos.db "SELECT * FROM findings WHERE severity='critical' AND scan_id IN (SELECT scan_id FROM scans WHERE tool='pythia')"

# View AI cost summary
sqlite3 ~/.argos/argos.db "SELECT provider, model, ROUND(SUM(cost_usd),4) FROM ai_costs WHERE tool='pythia' GROUP BY provider, model"

---

## Feuille de route

### v0.1.0 — Version initiale (novembre 2025)

**Statut :** Publiée

- 4 méthodes de détection, correction IA, système de consentement, rapports HTML+JSON, persistance SQLite

### v0.2.0 — Parité complète et fonctionnalités Entreprise (mai 2026)

**Statut :** Publiée

- 6 méthodes de détection (ajouté second-order + ORDER BY)
- 14 codes de constatation spécifiques aux SGBD
- Intégration CI/CD (`--fail-on`, `--sarif`, `--diff`)
- En-têtes d'authentification, exploration JS-aware, charges utiles de contournement WAF
- IA : streaming, comparaison, agent (recherche NVD CVE), suivi des coûts, drapeaux `--ai-provider`/`--ai-model`
- Score de risque OWASP/CWE/CVSS/contextuel dans chaque constatation
- Durcissement contre les faux positifs (score de similarité, confirmation multi-charge utile)
- Parité de sécurité élevée DVWA (chaîne de variables de session)

### v0.3.0 — Suite Pytest et Outils Développeur (T3 2026)

**Prévu :**

- 40+ tests pytest couvrant les 14 codes de constatation
- Gestion interactive de la configuration (`python -m pyth config set`)
- CLI de base de données (`python -m pyth db scans list`)
- Détection d'expiration de session lors des scans authentifiés
- Scan par lots multi-sites (`--targets targets.txt`)

### v0.4.0 — Intelligence et Automatisation (T1 2027)

**Prévu :**

- Détection d'anomalies basée sur le ML
- Exploitation automatisée en lecture seule (preuve d'impact)
- Interface de chat IA pour l'analyse des résultats de scan

Pour des descriptions détaillées des fonctionnalités, voir [docs/ROADMAP.md](https://github.com/rodhnin/pythia-sql-clairvoyance/blob/main/docs/ROADMAP.md)

---

## Éthique et Légal

### La Règle d'Or

**Scannez uniquement les systèmes que vous possédez ou pour lesquels vous avez une autorisation écrite explicite de test.**

### Application du Consentement

| Mode            | Tests                      | Consentement Requis | Limite de Débit |
| --------------- | -------------------------- | ------------------- | --------------- |
| **Sûr**         | Basé sur les erreurs, Aveugle booléenne | Non                 | 2.0 req/s       |
| **Agressif**    | Toutes les 6 techniques    | Oui                 | 5.0 req/s       |
| **Analyse IA**  | Guide de correction        | Oui                 | N/A             |

### Cadre Légal

- États-Unis : Computer Fraud and Abuse Act (CFAA)
- Royaume-Uni : Computer Misuse Act 1990
- UE : Directive 2013/40/UE
- International : Diverses lois sur la cybercriminalité

Pour des directives éthiques complètes, voir [docs/ETHICS.md](https://github.com/rodhnin/pythia-sql-clairvoyance/blob/main/docs/ETHICS.md)

---

## Contribuer

Nous accueillons les contributions — rapports de bogues, demandes de fonctionnalités, améliorations de la documentation et contributions de code.

### Comment Contribuer

1. Forker le dépôt
2. Créer une branche de fonctionnalité (`git checkout -b feature/amazing-feature`)
3. Effectuer vos modifications et écrire des tests
4. Valider vos modifications
5. Pousser la branche et ouvrir une Pull Request

### Configuration de Développement```bash
git clone https://github.com/YOUR-USERNAME/pythia-sql-clairvoyance.git
cd pythia-sql-clairvoyance
python -m pip install -r requirements.txt
python -m pip install pytest black flake8 mypy
black pyth/
flake8 pyth/
pytest tests/