zakirkun/guardian-cli

Guardian CLI – Référence de la compétence

1. Présentation du projet

Guardian (v2.0) est une application CLI Python 3.11+ qui automatise les workflows de tests d'intrusion à l'aide d'un système d'IA multi-agents. Elle est conçue uniquement pour des évaluations de sécurité autorisées.

guardian-cli/
├── ai/               # Intégrations des fournisseurs IA & modèles de prompts
│   ├── providers/    # base_provider, openai, claude, gemini, openrouter
│   └── prompt_templates/
├── cli/              # Point d'entrée CLI (Typer) & commandes
│   └── commands/     # init, scan, recon, analyze, report, workflow, ai, models
├── core/             # Moteur d'orchestration multi-agents
│   ├── agent.py          # BaseAgent
│   ├── planner.py        # PlannerAgent  – décide de la prochaine étape de test
│   ├── tool_agent.py     # ToolAgent     – sélectionne et exécute les outils
│   ├── analyst_agent.py  # AnalystAgent  – interprète les résultats des outils
│   ├── reporter_agent.py # ReporterAgent – génère les rapports finaux
│   ├── memory.py         # PentestMemory, ToolExecution, dataclasses Finding
│   └── workflow.py       # WorkflowEngine – orchestrateur principal
├── tools/            # 19 wrappers d'outils de sécurité (un fichier Python chacun)
├── workflows/        # Définitions de workflows YAML (8 intégrés)
├── utils/            # logger, scope_validator, helpers
├── config/           # Fichier de configuration guardian.yaml
├── reports/          # Répertoire de sortie pour les rapports générés et l'état des sessions
└── docs/             # Guides (WORKFLOW_GUIDE, TOOLS_DEVELOPMENT_GUIDE, …)

---

2. Architecture

2.1 Pipeline d'agents

Entrée cible
    │
    ▼
WorkflowEngine.run_workflow()  ──ou──  WorkflowEngine.run_autonomous()
    │
    ├──► PlannerAgent.decide_next_action()   — Raisonnement IA stratégique
    │
    ├──► ToolAgent.execute_tool()            — Exécute l'outil de sécurité choisi
    │
    ├──► AnalystAgent.interpret_output()     — Analyse et lie les résultats aux exécutions
    │
    └──► ReporterAgent.execute()             — Génère un rapport markdown / HTML / JSON

Chaque agent hérite de BaseAgent et utilise un objet PentestMemory partagé qui stocke :

Store	Classe	Objectif
findings	Finding	Vulnérabilités découvertes
tool_executions	ToolExecution	Commande complète + sortie brute
completed_actions	list[str]	Suivi de progression des phases
current_phase	str	reconnaissance → scanning → analyse → reporting

2.2 Abstraction des fournisseurs IA

Tous les fournisseurs implémentent la même interface BaseProvider, ce qui les rend interchangeables au moment de l'exécution :

Fournisseur	Variable d'environnement	Modèle par défaut
openai	OPENAI_API_KEY	gpt-4o
claude	ANTHROPIC_API_KEY	claude-3-5-sonnet-20241022
gemini	GOOGLE_API_KEY	gemini-2.5-pro
openrouter	OPENROUTER_API_KEY	anthropic/claude-3.5-sonnet

Changez de fournisseur via config/guardian.yaml ou le flag CLI --provider.

---

3. Commandes CLI

Exécutez avec python -m cli.main <commande> (ou guardian <commande> après installation).

Commande	Objectif
init	Créer/valider config/guardian.yaml
scan	Scan de vulnérabilité unique sur une cible
recon	Reconnaissance passive / active
analyze	Ré-analyser une session existante
report	Générer / régénérer un rapport pour une session
workflow list	Lister les workflows disponibles
workflow run	Exécuter un workflow nommé sur une cible
ai	Interroger l'IA sur un résultat ou un prompt personnalisé
models	Lister les fournisseurs IA et modèles configurés
version	Afficher la version

Flags communs

--target <IP/domaine/CIDR>   # Requis pour scan/recon/workflow run
--provider <openai|claude|gemini|openrouter>
--name <nom-workflow>        # Pour workflow run
--format <markdown|html|json>
--session <SESSION_ID>       # Pour régénération de rapport

---

4. Système de workflows

4.1 Exécution d'un workflow

# Lister les workflows disponibles
python -m cli.main workflow list

# Test d'intrusion web
python -m cli.main workflow run --name web_pentest --target https://cible.example.com

# Évaluation réseau complète
python -m cli.main workflow run --name network --target 192.168.1.0/24

# Test d'intrusion autonome piloté par l'IA
python -m cli.main workflow run --name autonomous --target example.com

4.2 Workflows intégrés

Fichier	Nom	Description
recon.yaml	recon	Reconnaissance passive + active
web_pentest.yaml	web_pentest	Découverte HTTP, scan de vulnérabilités, rapport
network_pentest.yaml	network	Scan de ports, détection de services, analyse
advanced_recon.yaml	advanced_recon	Énumération profonde des sous-domaines + DNS
full_vuln_scan.yaml	full_vuln_scan	Balayage complet des vulnérabilités
wordpress_audit.yaml	wordpress_audit	Audit spécifique WordPress
autonomous.yaml	autonomous	Mode où l'IA décide de tout

4.3 Schéma YAML d'un workflow

name: mon_workflow
description: "Brève description"

steps:
  - name: http_discovery
    type: tool              # tool | analysis | report
    tool: httpx             # nom de l'outil (doit correspondre au wrapper dans tools/)
    objective: "Décrire ce qu'il faut trouver"
    parameters:             # Remplace les valeurs par défaut de config/guardian.yaml
      tech_detect: true
      threads: 100

  - name: analyze
    type: analysis
    agent: analyst
    objective: "Corréler les résultats"

  - name: generate_report
    type: report
    # format par défaut selon config output.format

settings:
  max_parallel_tools: 3
  require_confirmation: true
  save_intermediate: true

Priorité des paramètres : Workflow YAML > config/guardian.yaml > Valeurs par défaut des outils

4.4 Correspondance floue de workflows

Le moteur résout automatiquement --name web → web_pentest.yaml en utilisant une correspondance par sous-chaîne sur le nom de fichier.

---

5. Outils de sécurité intégrés (19)

Catégorie	Outils
Réseau	nmap, masscan
Reconnaissance web	httpx, whatweb, wafw00f
Sous-domaine / DNS	subfinder, amass, dnsrecon
Vulnérabilité	nuclei, nikto, sqlmap, wpscan
SSL/TLS	testssl, sslyze
Découverte de contenu	gobuster, ffuf, arjun
Analyse de sécurité	xsstrike, gitleaks, cmseek

Chaque outil possède un wrapper Python autonome dans tools/<outil>.py qui :

1. Construit la commande shell à partir des paramètres
2. L'exécute de manière asynchrone (sous-processus asyncio)
3. Retourne {"success": bool, "command": str, "raw_output": str, "exit_code": int, "duration": float}

Guardian fonctionne avec un sous-ensemble des outils disponibles ; l'IA s'adapte en fonction de ce qui est installé.

---

6. Configuration (config/guardian.yaml)

Sections clés :

ai:
  provider: openai          # Fournisseur actif
  openai:
    model: gpt-4o
    api_key: null            # Ou définir la variable d'environnement OPENAI_API_KEY
  temperature: 0.2
  max_tokens: 8000

pentest:
  safe_mode: true            # Désactiver les actions destructrices
  require_confirmation: true
  max_parallel_tools: 3
  tool_timeout: 300          # secondes

output:
  format: markdown           # markdown | html | json
  save_path: ./reports
  verbosity: normal          # quiet | normal | verbose | debug

scope:
  blacklist:                 # Ne jamais scanner ceux-ci
    - 127.0.0.0/8
    - 10.0.0.0/8
    - 172.16.0.0/12
    - 192.168.0.0/16

---

7. Sortie et preuves

Chaque session de scan produit :

Fichier	Contenu
reports/report_<SESSION_ID>.md	Rapport complet de test d'intrusion
reports/session_<SESSION_ID>.json	État brut de la session (résultats, exécutions, phase)

La conservation des preuves inclut :

• ID d'exécution lié à chaque résultat (champ execution_id sur Finding)
• Sortie brute complète (extraits jusqu'à 2000 caractères) de chaque exécution d'outil
• Trace du raisonnement IA intégrée dans les rapports (lorsque include_reasoning: true)

Les formats de rapport sont sélectionnés via la clé de configuration output.format ou le flag CLI --format et correspondent aux extensions de fichier .md, .html, .json.

---

8. Ajout d'un nouvel outil

1. Créez tools/monoutil.py héritant de BaseTool (voir tools/base_tool.py)
2. Implémentez async def run(self, target: str, **kwargs) -> dict ; retournez le dictionnaire standard de résultat
3. Enregistrez l'outil dans tools/__init__.py
4. Référencez-le par son nom dans toute étape de workflow YAML (tool: monoutil)

Consultez docs/TOOLS_DEVELOPMENT_GUIDE.md pour la documentation complète.

---

9. Ajout d'un nouveau fournisseur IA

1. Créez ai/providers/monfournisseur_provider.py héritant de BaseProvider (ai/providers/base_provider.py)
2. Implémentez async def complete(self, messages, system_prompt) -> dict
3. Enregistrez dans la fabrique de fournisseurs ai/ai_client.py
4. Ajoutez le bloc de configuration à config/guardian.yaml sous ai:

---

10. Développement

# Configuration
python -m venv venv
.\venv\Scripts\activate        # Windows
pip install -e ".[dev]"

# Exécution
python -m cli.main --help

# Tests
pytest tests/

# Lint / Format
black .
ruff check .

Dépendances principales : typer[all], rich, langchain, langchain-google-genai, langchain-openai, langchain-anthropic, pyyaml, python-dotenv, pydantic, asyncio, aiofiles, jinja2

---

11. Légal et éthique

⚠️ Guardian est conçu exclusivement pour des tests de sécurité autorisés et à des fins éducatives.
Vous êtes seul responsable de l'obtention d'une autorisation écrite explicite avant de tester tout système.
Tout accès non autorisé est illégal (CFAA, RGPD et lois équivalentes dans le monde entier).