### Paso 2: Configurar el Entorno de Python

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

### Paso 3: Configurar el Proveedor de IA

Guardian admite múltiples proveedores de IA. Configure su proveedor preferido en `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

### Paso 4: Inicializar Configuración```bash
# Verify installation
python -m cli.main --help

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

### Escenarios de uso de ejemplo

#### 1. Prueba de penetración rápida de aplicaciones web```bash
# Fast security check with evidence capture
python -m cli.main workflow run --name web_pentest --target https://dvwa.csalab.app

#### 3. Flujo de trabajo personalizado con parámetros```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. Cambiar proveedores de 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

Habilite la fundamentación del analista en `config/guardian.yaml`:```yaml
rag:
  enabled: true
  top_k: 5

#### 8. Triaje visual (vision-LLM)

Tres roles (defensor rojo, defensor azul, juez) debaten solo hallazgos ambiguos — los veredictos seguros se saltan el debate para limitar el costo de tokens.```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. Telemetría + Ranker Aprendido (fuera de línea)```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

> **Usuarios de Windows**: Usa `python -m cli.main` en lugar de `guardian`

---

## 🔧 Configuración

### Referencia completa de configuración

Edita `config/guardian.yaml` para personalizar el comportamiento 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

**Prioridad de parámetros:**
- Los parámetros del flujo de trabajo **anulan** los parámetros de configuración
- Los parámetros de configuración **anulan** los valores predeterminados de la herramienta
- Flujos de trabajo autocontenidos y reutilizables

---

## 📖 Documentación

### Guías de usuario
- **[Guía de inicio rápido](https://github.com/zakirkun/guardian-cli/blob/main/QUICKSTART.md)** - Ponte en marcha en 5 minutos
- **[Referencia de comandos](https://github.com/zakirkun/guardian-cli/blob/main/docs)** - Documentación detallada de todos los comandos
- **[Guía de configuración](https://github.com/zakirkun/guardian-cli/blob/main/config/guardian.yaml)** - Referencia completa de configuración
- **[Guía de flujos de trabajo](https://github.com/zakirkun/guardian-cli/blob/main/docs/WORKFLOW_GUIDE.md)** - Creación de flujos de trabajo personalizados
- **[Guía de evaluación](https://github.com/zakirkun/guardian-cli/blob/main/docs/EVAL_GUIDE.md)** - Ejecución y extensión del entorno de evaluación
- **[Guía de plugins](https://github.com/zakirkun/guardian-cli/blob/main/docs/PLUGIN_GUIDE.md)** - Distribución de proveedores y herramientas de terceros
- **[Historial de cambios](https://github.com/zakirkun/guardian-cli/blob/main/CHANGELOG.md)** - Historial de versiones y notas de migración

### Guías de desarrollador
- **[Creación de herramientas personalizadas](https://github.com/zakirkun/guardian-cli/blob/main/docs/TOOLS_DEVELOPMENT_GUIDE.md)** - Construye tus propias integraciones de herramientas
- **[Desarrollo de flujos de trabajo](https://github.com/zakirkun/guardian-cli/blob/main/docs/WORKFLOW_GUIDE.md)** - Crea flujos de trabajo de prueba personalizados
- **[Herramientas disponibles](https://github.com/zakirkun/guardian-cli/blob/main/tools/README.md)** - Descripción general de las herramientas integradas

### Descripción general de la arquitectura```
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)                    │
└─────────────────────────────────────────┘

---

## 🆕 Últimas actualizaciones

### Versión 4.0.0 — I+D novedosa + Expansión de cobertura

**Pista A — I+D de IA/Agente (7 elementos)**

| ID | Elemento | Aspectos destacados |
|---|---|---|
| A1 | Base de conocimiento RAG | `core/knowledge_base.py` SQLite + FTS5 + embeddings opcionales; fundamentación del analista mediante ranura `kb_references`; `guardian kb {seed,update,query,status}` |
| A2 | Triaje por debate multiagente | Rojo/Azul/Juez solo sobre hallazgos MEDIUM-fp; nuevo tipo de paso de análisis `agent: debate` |
| A3 | Análisis de capturas con Vision-LLM | `tools/playwright_screenshot.py` + `core/agents/visual_triage.py`; OpenAI + Claude `generate_with_images` |
| A4 | Contrato de plugins + proveedores locales | Descubrimiento por punto de entrada para proveedores Y herramientas; proveedores **Ollama** + **compatibles con OpenAI** incluidos |
| A5 | Selección aprendida de herramientas (offline) | `core/learners/tool_ranker.py` + `core/telemetry.py`; opt-in mediante `ai.use_learned_ranker: true` |
| A6 | Herramienta de evaluación | `evals/{__init__,scoring,fixtures_loader,test_*}.py` + fixtures dorados; 3 niveles (parser, flujo de trabajo, fundamentación del agente) |
| A7 | Actualización del modelo juez | `BaseAgent.think_deeply(judge_model=...)` intercambio y restauración; juzgar transcripciones para una reducción de coste de ~10x |

**Pista B — Expansión de cobertura de herramientas (7 elementos)**

| ID | Categoría | Herramientas añadidas |
|---|---|---|
| B8 | Active Directory | crackmapexec, bloodhound, kerbrute, impacket-secretsdump |
| B9 | Móvil Android | mobsf, apkleaks, objection |
| B10 | Fuzzers de API | schemathesis, restler, cariddi |
| B11 | SAST + secretos | semgrep, trufflehog, dependency-check |
| B12 | Equipo rojo LLM | garak, pyrit, prompt_fuzz |
| B13 | Puente Burp/ZAP | zap, burp |
| B14 | Exportadores de salida | SARIF v2.1.0, DefectDojo, Slack |

**Barrera de calidad:**
- 296 pruebas pasan (+93% respecto a la línea base de 153 de v3)
- Todas las medidas de endurecimiento de v3 preservadas: delimitadores de inyección de indicaciones, limpieza de claves, alcance de resolución DNS, puntos de control atómicos, rotación de logs, carga diferida de herramientas
- El tiempo de inicio de `guardian --help` se mantiene por debajo de 500ms a pesar de 50 herramientas
- Nuevas superficies de CLI: `guardian kb`, `guardian telemetry`
- 8 nuevos flujos de trabajo incluidos: `web_pentest_with_debate`, `web_visual_pentest`, `ad_assessment`, `mobile_android`, `llm_redteam`, `sast_review`, `api_pentest_v2`, más los flujos de trabajo existentes de v3

### Versión 3.0.0 — Endurecimiento + Motor v2

- Delimitadores de inyección de indicaciones (`<UNTRUSTED_TOOL_OUTPUT>`) en toda la salida de herramientas
- Planificador DAG, esquemas Pydantic, puntos de control atómicos, `--resume`
- 11 nuevos envoltorios (nube/contenedor/SBOM/GraphQL/JWT/OSINT)
- Recomputación de CVSS v3.1 + detección de desviación
- Rotación de logs, limpieza de claves al escribir
- Compuerta de confirmación cableada para herramientas activas+

### Versión 2.0.0

- IA multiproveedor (OpenAI, Claude, Gemini, OpenRouter, Requesty)
- Vinculación de evidencia mediante `execution_id`
- Sistema de prioridad de parámetros de flujo de trabajo

---

## 🤝 Cómo contribuir

¡Aceptamos contribuciones! Así es como puedes hacerlo:

### Configuración del entorno de desarrollo```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 .

**Errores del Proveedor de IA**```bash
# Verify API key is set
python -m cli.main models

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

**Flujo de trabajo no se carga**```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'))"

Para más ayuda, [abre un issue](https://github.com/zakirkun/guardian-cli/issues).

---

## 📄 Licencia

Este proyecto está bajo la licencia MIT - consulta el archivo [LICENSE](https://github.com/zakirkun/guardian-cli/blob/main/LICENSE) para más detalles.

---

## 🙏 Agradecimientos

- **OpenAI** - Capacidades de GPT-4
- **Anthropic** - Claude AI
- **Google** - Gemini AI
- **LangChain** - Marco de orquestación de IA
- **ProjectDiscovery** - Herramientas de seguridad de código abierto (httpx, subfinder, nuclei)
- **Nmap** - Exploración de redes y auditoría de seguridad
- **Comunidad de Seguridad** - Desarrolladores e investigadores de herramientas

---

## 📞 Soporte y Contacto

- **Issues de GitHub**: [Reporta errores o solicita funciones](https://github.com/zakirkun/guardian-cli/issues)
- **Discusiones**: [Únete a las discusiones de la comunidad](https://github.com/zakirkun/guardian-cli/discussions)
- **Documentación**: [Lee la documentación](https://github.com/zakirkun/guardian-cli/blob/main/docs)
- **Seguridad**: Reporta vulnerabilidades de forma privada a [email protected]

---

## 🌟 Historial de Estrellas

<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" />
    Star History Chart
  </picture>
</a>

---
---

<div align="center">

**Guardian** - Pruebas de Penetración Inteligentes, Éticas y Automatizadas

Hecho con ❤️ por la Comunidad de Seguridad

[⬆ Volver al Inicio](#-guardian)

</div>