Guardian CLI

Guardian CLI – Referencia de la Habilidad

1. Resumen del Proyecto

Guardian (v2.0) es una aplicación CLI de Python 3.11+ que automatiza flujos de trabajo de pruebas de penetración utilizando un sistema de IA multiagente. Está diseñado exclusivamente para evaluaciones de seguridad autorizadas.

guardian-cli/
├── ai/               # Integraciones de proveedores de IA y plantillas de prompts
│   ├── providers/    # base_provider, openai, claude, gemini, openrouter
│   └── prompt_templates/
├── cli/              # Punto de entrada CLI (Typer) y comandos
│   └── commands/     # init, scan, recon, analyze, report, workflow, ai, models
├── core/             # Motor de orquestación multiagente
│   ├── agent.py          # BaseAgent
│   ├── planner.py        # PlannerAgent  – decide el siguiente paso de la prueba
│   ├── tool_agent.py     # ToolAgent     – selecciona y ejecuta herramientas
│   ├── analyst_agent.py  # AnalystAgent  – interpreta la salida de la herramienta
│   ├── reporter_agent.py # ReporterAgent – genera informes finales
│   ├── memory.py         # PentestMemory, ToolExecution, Finding (dataclasses)
│   └── workflow.py       # WorkflowEngine – orquestador principal
├── tools/            # 19 envoltorios de herramientas de seguridad (un archivo Python cada uno)
├── workflows/        # Definiciones de flujo de trabajo YAML (8 incorporados)
├── utils/            # logger, scope_validator, helpers
├── config/           # Archivo de configuración guardian.yaml
├── reports/          # Directorio de salida para informes generados y estado de sesión
└── docs/             # Guías (WORKFLOW_GUIDE, TOOLS_DEVELOPMENT_GUIDE, …)

---

2. Arquitectura

2.1 Pipeline de Agentes

Entrada del Objetivo
    │
    ▼
WorkflowEngine.run_workflow()  ──o──  WorkflowEngine.run_autonomous()
    │
    ├──► PlannerAgent.decide_next_action()   — Razonamiento estratégico de IA
    │
    ├──► ToolAgent.execute_tool()            — Ejecuta la herramienta de seguridad seleccionada
    │
    ├──► AnalystAgent.interpret_output()     — Analiza y vincula hallazgos con ejecuciones
    │
    └──► ReporterAgent.execute()             — Genera informe en markdown / HTML / JSON

Cada agente hereda de BaseAgent y utiliza un objeto PentestMemory compartido que almacena:

Almacén	Clase	Propósito
findings	Finding	Vulnerabilidades descubiertas
tool_executions	ToolExecution	Comando completo + salida sin procesar
completed_actions	list[str]	Rastreador de progreso de fase
current_phase	str	reconocimiento → escaneo → análisis → informes

2.2 Abstracción del Proveedor de IA

Todos los proveedores implementan la misma interfaz BaseProvider, lo que los hace intercambiables en tiempo de ejecución:

Proveedor	Variable de Entorno	Modelo Predeterminado
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

Cambie de proveedor a través de config/guardian.yaml o la bandera CLI --provider.

---

3. Comandos CLI

Ejecute con python -m cli.main <comando> (o guardian <comando> después de la instalación).

Comando	Propósito
init	Crear/validar config/guardian.yaml
scan	Escaneo de vulnerabilidades único en un objetivo
recon	Reconocimiento pasivo / activo
analyze	Re-analizar una sesión existente
report	Generar / re-generar un informe para una sesión
workflow list	Listar flujos de trabajo disponibles
workflow run	Ejecutar un flujo de trabajo nombrado contra un objetivo
ai	Consultar a la IA sobre un hallazgo o prompt personalizado
models	Listar proveedores de IA y modelos configurados
version	Mostrar versión

Banderas Comunes

--target <IP/dominio/CIDR>   # Requerido para scan/recon/workflow run
--provider <openai|claude|gemini|openrouter>
--name <nombre-flujo>        # Para workflow run
--format <markdown|html|json>
--session <ID_SESION>        # Para regeneración de informes

---

4. Sistema de Flujos de Trabajo

4.1 Ejecutar un Flujo de Trabajo

# Listar flujos de trabajo disponibles
python -m cli.main workflow list

# Prueba de penetración web
python -m cli.main workflow run --name web_pentest --target https://target.example.com

# Evaluación completa de red
python -m cli.main workflow run --name network --target 192.168.1.0/24

# Prueba de penetración autónoma impulsada por IA
python -m cli.main workflow run --name autonomous --target example.com

4.2 Flujos de Trabajo Incorporados

Archivo	Nombre	Descripción
recon.yaml	recon	Reconocimiento pasivo + activo
web_pentest.yaml	web_pentest	Descubrimiento HTTP, escaneo de vulnerabilidades, informe
network_pentest.yaml	network	Escaneo de puertos, detección de servicios, análisis
advanced_recon.yaml	advanced_recon	Enumeración profunda de subdominios + DNS
full_vuln_scan.yaml	full_vuln_scan	Barrido completo de vulnerabilidades
wordpress_audit.yaml	wordpress_audit	Auditoría específica de WordPress
autonomous.yaml	autonomous	Modo en que la IA decide todo

4.3 Esquema YAML del Flujo de Trabajo

name: mi_flujo
description: "Breve descripción"

steps:
  - name: http_discovery
    type: tool              # tool | analysis | report
    tool: httpx             # nombre de la herramienta (debe coincidir con el envoltorio en tools/)
    objective: "Describir qué encontrar"
    parameters:             # Sobrescribir valores predeterminados de config/guardian.yaml
      tech_detect: true
      threads: 100

  - name: analyze
    type: analysis
    agent: analyst
    objective: "Correlacionar hallazgos"

  - name: generate_report
    type: report
    # format por defecto es output.format de la configuración

settings:
  max_parallel_tools: 3
  require_confirmation: true
  save_intermediate: true

Prioridad de Parámetros: YAML del flujo de trabajo > config/guardian.yaml > Valores predeterminados de la herramienta

4.4 Coincidencia Difusa de Flujos de Trabajo

El motor resuelve --name web → web_pentest.yaml automáticamente utilizando coincidencia de subcadenas en el nombre del archivo.

---

5. Herramientas de Seguridad Integradas (19)

Categoría	Herramientas
Red	nmap, masscan
Reconocimiento Web	httpx, whatweb, wafw00f
Subdominio / DNS	subfinder, amass, dnsrecon
Vulnerabilidad	nuclei, nikto, sqlmap, wpscan
SSL/TLS	testssl, sslyze
Descubrimiento de Contenido	gobuster, ffuf, arjun
Análisis de Seguridad	xsstrike, gitleaks, cmseek

Cada herramienta tiene un envoltorio Python autocontenido en tools/<nombreherramienta>.py que:

1. Construye el comando de shell a partir de los parámetros
2. Lo ejecuta de forma asíncrona (subproceso asyncio)
3. Devuelve {"success": bool, "command": str, "raw_output": str, "exit_code": int, "duration": float}

Guardian funciona con un subconjunto de herramientas disponibles; la IA se adapta según lo que esté instalado.

---

6. Configuración (config/guardian.yaml)

Secciones clave:

ai:
  provider: openai          # Proveedor activo
  openai:
    model: gpt-4o
    api_key: null            # O establecer la variable de entorno OPENAI_API_KEY
  temperature: 0.2
  max_tokens: 8000

pentest:
  safe_mode: true            # Deshabilitar acciones destructivas
  require_confirmation: true
  max_parallel_tools: 3
  tool_timeout: 300          # segundos

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

scope:
  blacklist:                 # Nunca escanear estos
    - 127.0.0.0/8
    - 10.0.0.0/8
    - 172.16.0.0/12
    - 192.168.0.0/16

---

7. Salida y Evidencia

Cada sesión de escaneo produce:

Archivo	Contenido
reports/report_<ID_SESION>.md	Informe completo de prueba de penetración
reports/session_<ID_SESION>.json	Estado de sesión sin procesar (hallazgos, ejecuciones, fase)

La captura de evidencia incluye:

• ID de ejecución vinculado a cada hallazgo (campo execution_id en Finding)
• Salida sin procesar completa (fragmentos de hasta 2000 caracteres) de cada ejecución de herramienta
• Traza de razonamiento de IA incrustada en los informes (cuando include_reasoning: true)

Los formatos de informe se seleccionan a través de la clave de configuración output.format o la bandera CLI --format y se asignan a las extensiones de archivo .md, .html, .json.

---

8. Agregar una Nueva Herramienta

1. Cree tools/miherramienta.py heredando de BaseTool (consulte tools/base_tool.py)
2. Implemente async def run(self, target: str, **kwargs) -> dict; devuelva el diccionario de resultado estándar
3. Registre la herramienta en tools/__init__.py
4. Refiérase a ella por nombre en cualquier paso YAML del flujo de trabajo (tool: miherramienta)

Consulte docs/TOOLS_DEVELOPMENT_GUIDE.md para la documentación completa.

---

9. Agregar un Nuevo Proveedor de IA

1. Cree ai/providers/miproveedor_provider.py heredando de BaseProvider (ai/providers/base_provider.py)
2. Implemente async def complete(self, messages, system_prompt) -> dict
3. Regístrelo en la fábrica de proveedores de ai/ai_client.py
4. Agregue el bloque de configuración a config/guardian.yaml bajo ai:

---

10. Desarrollo

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

# Ejecución
python -m cli.main --help

# Pruebas
pytest tests/

# Lint / Formato
black .
ruff check .

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

---

11. Legal y Ética

⚠️ Guardian está diseñado exclusivamente para pruebas de seguridad autorizadas y fines educativos.
Usted es completamente responsable de obtener permiso explícito por escrito antes de probar cualquier sistema.
El acceso no autorizado es ilegal (CFAA, GDPR y leyes equivalentes en todo el mundo).