### Étape 2: Configurer l'environnement Python

**Linux/macOS:**```bash
python3 -m venv venv
source venv/bin/activate
pip install -e .

### Étape 3 : Configurer le fournisseur d'IA

Guardian prend en charge plusieurs fournisseurs d'IA. Configurez votre fournisseur préféré dans `config/guardian.yaml` :```yaml
# config/guardian.yaml
ai:
  # Choose your provider: openai, claude, gemini, openrouter, or requesty
  provider: openai
  
  # OpenAI Configuration (recommended)
  openai:
    model: gpt-4o
    api_key: sk-your-api-key-here  # Or set OPENAI_API_KEY env var
  
  # Claude Configuration
  claude:
    model: claude-3-5-sonnet-20241022
    api_key: null  # Or set ANTHROPIC_API_KEY env var
  
  # Gemini Configuration
  gemini:
    model: gemini-2.5-pro
    api_key: null  # Or set GOOGLE_API_KEY env var
  
  # OpenRouter Configuration
  openrouter:
    model: anthropic/claude-3.5-sonnet
    api_key: null  # Or set OPENROUTER_API_KEY env var

  # Requesty Configuration (OpenAI-compatible gateway)
  requesty:
    model: openai/gpt-4o-mini
    api_key: null  # Or set REQUESTY_API_KEY env var

### Étape 4 : Initialiser la configuration```bash
# Verify installation
python -m cli.main --help

# Check AI provider status
python -m cli.main models

### Exemples de scénarios d'utilisation

#### 1. Test d'intrusion rapide d'application web```bash
# Fast security check with evidence capture
python -m cli.main workflow run --name web_pentest --target https://dvwa.csalab.app

#### 3. Workflow personnalisé avec paramètres```bash
# Run with workflow-specific parameters
# Parameters in workflow YAML override config defaults
python -m cli.main workflow run --name web_pentest --target example.com

#### 5. Changer de fournisseurs d'IA```bash
# Use OpenAI GPT-4
python -m cli.main workflow run --name web_pentest --target example.com --provider openai

# Use Claude
python -m cli.main workflow run --name web_pentest --target example.com --provider claude

# Use Gemini
python -m cli.main workflow run --name web_pentest --target example.com --provider gemini

# Local Ollama (no cloud)
OLLAMA_HOST=http://localhost:11434 python -m cli.main workflow run --name recon --target scanme.nmap.org --provider ollama

# Any OpenAI-compatible endpoint (vLLM, LM Studio, Together, Groq)
python -m cli.main workflow run --name web_pentest --target example.com --provider openai_compatible

Activer l'ancrage de l'analyste dans `config/guardian.yaml` :```yaml
rag:
  enabled: true
  top_k: 5

Trois rôles (avocat rouge, avocat bleu, juge) débattent uniquement des résultats ambigus — les verdicts confiants évitent le débat pour limiter le coût en tokens.

#### 8. Triage visuel (vision-LLM)```bash
# Captures full-page screenshots and feeds them to a vision-capable provider
python -m cli.main workflow run --name web_visual_pentest --target https://example.com --provider openai

#### 10. Telemetry + Learned Ranker (offline)```bash
# Anonymise sessions into JSONL (no raw targets, no commands, no secrets)
python -m cli.main telemetry export ./reports --out telemetry.jsonl

# Train the offline tool ranker
python -m cli.main telemetry train telemetry.jsonl

# Inspect what the ranker learned
python -m cli.main telemetry status

> **Utilisateurs Windows** : Utilisez `python -m cli.main` au lieu de `guardian`

---

## 🔧 Configuration

### Référence complète de configuration

Modifiez `config/guardian.yaml` pour personnaliser le comportement de Guardian :```yaml
# AI Configuration
ai:
  provider: openai  # openai, claude, gemini, openrouter, requesty
  
  openai:
    model: gpt-4o
    api_key: sk-your-key  # Or use OPENAI_API_KEY env var
  
  claude:
    model: claude-3-5-sonnet-20241022
    api_key: null
  
  gemini:
    model: gemini-2.5-pro
    api_key: null
  
  temperature: 0.2
  max_tokens: 8000

# Penetration Testing Settings
pentest:
  safe_mode: true              # Prevent destructive actions
  require_confirmation: true   # Confirm before each step
  max_parallel_tools: 3        # Concurrent tool execution
  max_depth: 3                 # Maximum scan depth
  tool_timeout: 300            # Tool timeout in seconds

# Output Configuration
output:
  format: markdown             # markdown, html, json
  save_path: ./reports
  include_reasoning: true
  verbosity: normal            # quiet, normal, verbose, debug

# Scope Validation
scope:
  blacklist:                   # Never scan these
    - 127.0.0.0/8
    - 10.0.0.0/8
    - 172.16.0.0/12
    - 192.168.0.0/16
  require_scope_file: false
  max_targets: 100

# Tool Configuration (defaults)
tools:
  httpx:
    threads: 50
    timeout: 10
    tech_detect: true
  
  nuclei:
    severity: ["critical", "high", "medium"]
    templates_path: ~/nuclei-templates
  
  nmap:
    default_args: "-sV -sC"
    timing: T4

**Priorité des paramètres :**
- Les paramètres de workflow **remplacent** les paramètres de configuration
- Les paramètres de configuration **remplacent** les valeurs par défaut de l'outil
- Workflows autonomes et réutilisables

---

## 📖 Documentation

### Guides utilisateur
- **[Guide de démarrage rapide](https://github.com/zakirkun/guardian-cli/blob/HEAD/QUICKSTART.md)** - Mettez-vous en route en 5 minutes
- **[Référence des commandes](https://github.com/zakirkun/guardian-cli/blob/HEAD/docs/)** - Documentation détaillée pour toutes les commandes
- **[Guide de configuration](https://github.com/zakirkun/guardian-cli/blob/HEAD/config/guardian.yaml)** - Référence complète de la configuration
- **[Guide des workflows](https://github.com/zakirkun/guardian-cli/blob/HEAD/docs/WORKFLOW_GUIDE.md)** - Créer des workflows personnalisés
- **[Guide d'évaluation](https://github.com/zakirkun/guardian-cli/blob/HEAD/docs/EVAL_GUIDE.md)** - Exécuter et étendre le harnais d'évaluation
- **[Guide des plugins](https://github.com/zakirkun/guardian-cli/blob/HEAD/docs/PLUGIN_GUIDE.md)** - Distribution de fournisseurs et outils tiers
- **[Journal des modifications](https://github.com/zakirkun/guardian-cli/blob/HEAD/CHANGELOG.md)** - Historique des versions et notes de migration

### Guides développeur
- **[Création d'outils personnalisés](https://github.com/zakirkun/guardian-cli/blob/HEAD/docs/TOOLS_DEVELOPMENT_GUIDE.md)** - Créez vos propres intégrations d'outils
- **[Développement de workflows](https://github.com/zakirkun/guardian-cli/blob/HEAD/docs/WORKFLOW_GUIDE.md)** - Créez des workflows de test personnalisés
- **[Outils disponibles](https://github.com/zakirkun/guardian-cli/blob/HEAD/tools/README.md)** - Aperçu des outils intégrés

### Vue d'ensemble de l'architecture```
Guardian Architecture:
┌─────────────────────────────────────────┐
│         AI Provider Layer               │
│  (OpenAI, Claude, Gemini, OpenRouter,   │
│   Requesty)                             │
└─────────────────────────────────────────┘
                 │
┌─────────────────────────────────────────┐
│       Multi-Agent System                │
│  Planner → Tool Agent → Analyst →      │
│            Reporter                      │
└─────────────────────────────────────────┘
                 │
┌─────────────────────────────────────────┐
│      Workflow Engine                    │
│  - Parameter Priority                   │
│  - Evidence Capture                     │
│  - Session Management                   │
└─────────────────────────────────────────┘
                 │
┌─────────────────────────────────────────┐
│      Tool Integration Layer             │
│  (19 Security Tools)                    │
└─────────────────────────────────────────┘

## 🆕 Dernières mises à jour

### Version 4.0.0 — Nouvelle R&D + Expansion de couverture

**Piste A — R&D IA/Agent (7 éléments)**

| ID | Élément | Points forts |
|---|---|---|
| A1 | Base de connaissances RAG | `core/knowledge_base.py` SQLite + FTS5 + embeddings optionnels ; ancrage analyste via slot `kb_references` ; `guardian kb {seed,update,query,status}` |
| A2 | Tri par débat multi-agent | Rouge/Bleu/Juge sur les résultats MEDIUM-fp uniquement ; nouveau type d'étape d'analyse `agent: debate` |
| A3 | Analyse de captures d'écran Vision-LLM | `tools/playwright_screenshot.py` + `core/agents/visual_triage.py` ; OpenAI + Claude `generate_with_images` |
| A4 | Contrat de plugin + fournisseurs locaux | Découverte de points d'entrée pour les fournisseurs ET les outils ; fournisseurs **Ollama** + **compatibles OpenAI** fournis |
| A5 | Sélection d'outils apprise (hors ligne) | `core/learners/tool_ranker.py` + `core/telemetry.py` ; activation via `ai.use_learned_ranker: true` |
| A6 | Harness d'évaluation | `evals/{__init__,scoring,fixtures_loader,test_*}.py` + fixtures dorées ; 3 niveaux (parser, workflow, ancrage agent) |
| A7 | Mise à niveau du modèle juge | `BaseAgent.think_deeply(judge_model=...)` échange et restauration ; jugement par transcription pour une réduction de coût d'environ 10x |

**Piste B — Expansion de couverture d'outils (7 éléments)**

| ID | Catégorie | Outils ajoutés |
|---|---|---|
| B8 | Active Directory | crackmapexec, bloodhound, kerbrute, impacket-secretsdump |
| B9 | Mobile Android | mobsf, apkleaks, objection |
| B10 | Fuzzers API | schemathesis, restler, cariddi |
| B11 | SAST + secrets | semgrep, trufflehog, dependency-check |
| B12 | Red-team LLM | garak, pyrit, prompt_fuzz |
| B13 | Pont Burp/ZAP | zap, burp |
| B14 | Exportateurs de sortie | SARIF v2.1.0, DefectDojo, Slack |

**Barre de qualité :**
- 296 tests réussis (+93 % par rapport à la base v3 de 153)
- Tout le durcissement v3 préservé : délimiteurs d'injection de prompt, nettoyage de clés, portée de résolution DNS, points de contrôle atomiques, rotation des logs, chargement paresseux des outils
- Le temps de démarrage `guardian --help` reste inférieur à 500 ms malgré 50 outils
- Nouvelles surfaces CLI : `guardian kb`, `guardian telemetry`
- 8 nouveaux workflows livrés : `web_pentest_with_debate`, `web_visual_pentest`, `ad_assessment`, `mobile_android`, `llm_redteam`, `sast_review`, `api_pentest_v2`, plus les workflows v3 existants

### Version 3.0.0 — Durcissement + Moteur v2

- Délimiteurs d'injection de prompt (`<UNTRUSTED_TOOL_OUTPUT>`) sur toutes les sorties d'outils
- Planificateur DAG, schémas Pydantic, points de contrôle atomiques, `--resume`
- 11 nouveaux wrappers (cloud/container/SBOM/GraphQL/JWT/OSINT)
- Recomputaison CVSS v3.1 + détection de dérive
- Rotation des logs, nettoyage de clés à l'écriture
- Porte de confirmation câblée pour les outils actifs+

### Version 2.0.0

- IA multi-fournisseurs (OpenAI, Claude, Gemini, OpenRouter, Requesty)
- Liaison de preuves via `execution_id`
- Système de priorité des paramètres de workflow

---

## 🤝 Contribuer

Nous accueillons volontiers les contributions ! Voici comment :

### Configuration de l'environnement de développement```bash
# Fork and clone
git clone https://github.com/zakirkun/guardian-cli.git
cd guardian-cli

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/

# Format code
black .

**Erreurs du fournisseur d'IA**```bash
# Verify API key is set
python -m cli.main models

# Check provider configuration
cat config/guardian.yaml | grep -A 5 "ai:"

**Workflow ne se charge pas**```bash
# Check workflow file exists
ls workflows/web_pentest.yaml

# Verify YAML syntax
python -c "import yaml; yaml.safe_load(open('workflows/web_pentest.yaml'))"

Pour plus d'aide, [ouvrez un ticket](https://github.com/zakirkun/guardian-cli/issues).

---

## 📄 Licence

Ce projet est sous licence MIT - voir le fichier [LICENSE](https://github.com/zakirkun/guardian-cli/blob/HEAD/LICENSE) pour plus de détails.

---

## 🙏 Remerciements

- **OpenAI** - Capacités GPT-4
- **Anthropic** - IA Claude
- **Google** - IA Gemini
- **LangChain** - Cadre d'orchestration IA
- **ProjectDiscovery** - Outils de sécurité open-source (httpx, subfinder, nuclei)
- **Nmap** - Exploration réseau et audit de sécurité
- **La communauté de la sécurité** - Développeurs d'outils et chercheurs

---

## 📞 Support et Contact

- **GitHub Issues** : [Signalez des bugs ou demandez des fonctionnalités](https://github.com/zakirkun/guardian-cli/issues)
- **Discussions** : [Participez aux discussions communautaires](https://github.com/zakirkun/guardian-cli/discussions)
- **Documentation** : [Lisez la documentation](https://github.com/zakirkun/guardian-cli/blob/HEAD/docs/)
- **Sécurité** : Signalez les vulnérabilités en privé à [email protected]

---

## 🌟 Historique des étoiles

<a href="https://github.com/zakirkun/guardian-cli/stargazers">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=zakirkun/guardian-cli&type=Date&theme=dark" />
    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=zakirkun/guardian-cli&type=Date" />
    Graphique de l
  </picture>
</a>

---
---

<div align="center">

**Guardian** - Test de pénétration intelligent, éthique et automatisé

Réalisé avec ❤️ par la communauté de la sécurité

[⬆ Retour en haut](#-guardian)

</div>