Metadata-Version: 2.4
Name: vigia
Version: 0.5.0
Summary: LLM & Agent Red Teaming Framework — automated security testing for AI systems
Author-email: Jordi Gil Nadal <jordigiln@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/jordigilnadal/vigia
Project-URL: Repository, https://github.com/jordigilnadal/vigia
Project-URL: Issues, https://github.com/jordigilnadal/vigia/issues
Keywords: llm,red-teaming,security,ai-safety,owasp,pentesting,agents
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Security
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: ollama>=0.4
Requires-Dist: langchain-text-splitters>=0.3
Requires-Dist: langchain-community>=0.4
Requires-Dist: langchain-chroma>=1.0
Requires-Dist: langchain-core>=1.0
Requires-Dist: chromadb>=1.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: litellm>=1.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Dynamic: license-file

# VIGÍA

**Framework de red teaming automatizado para LLMs en español — single-shot, multi-turn adaptativo y testing de agentes.**

Casi toda la investigación de seguridad en LLMs se hace en inglés, pero las empresas españolas están desplegando chatbots RAG en castellano para banca, sanidad y administración pública. Esos chatbots tienen guardrails entrenados mayoritariamente en inglés. VIGÍA automatiza la auditoría de seguridad con ataques diseñados nativamente en español, técnicas de code-switching entre lenguas ibéricas, y vectores que explotan cómo los modelos procesan el castellano.

## Qué hace

VIGÍA lanza ataques automatizados contra tu chatbot (local o remoto), evalúa si ha filtrado información sensible usando un LLM como juez, y genera un informe con los resultados mapeados a OWASP Top 10 for LLMs y MITRE ATLAS.

### Modos de ataque

- **Single-shot** — una seed, un intento, un score. El benchmark clásico.
- **Multi-turn** — conversación de hasta 7 turnos con estrategia de extracción progresiva (rapport → escalation → language rotation).
- **Adaptativo** — el atacante acumula memoria de sesión (qué vectores funcionan, dónde falla el modelo) y auto-selecciona la estrategia óptima por seed.
- **Agentic** — ataca agentes AI con herramientas (tool misuse, goal hijacking, privilege escalation).

## Resultados

### Benchmark Single-Shot RAG — 19 seeds × 5 modelos (threshold ≥ 5)

| Modelo | Tipo | Tasa vuln | Vulns | Críticos (≥7) | Score medio | Score máx |
|--------|------|:---------:|:-----:|:-------------:|:-----------:|:---------:|
| Claude Haiku 4.5 | Comercial | 21.1% | 4/19 | 1 | 1.9 | 9 |
| Llama 3.1 8B | Open source | 31.6% | 6/19 | 6 | 2.9 | 9 |
| Gemma2 2B | Open source | 68.4% | 13/19 | 6 | 5.1 | 10 |
| Gemini 2.5 Flash | Comercial | 73.7% | 14/19 | 10 | 5.5 | 10 |
| Mistral 7B | Open source | 94.7% | 18/19 | 10 | 6.7 | 10 |

Gemini 2.5 Flash (comercial) es más vulnerable que Gemma2 2B (open-source). Ser comercial no garantiza seguridad; lo que importa es el alignment training en idiomas distintos del inglés.

### Benchmark Multi-Turn — Llama 3.1 8B (target + judge)

| Estrategia | Seeds | Tasa vuln | Detalle |
|------------|:-----:|:---------:|---------|
| `rapport_to_extraction` | 5 | 40.0% | Construye confianza → extrae gradualmente |
| `escalation` | 5 | **60.0%** | Presión incremental. Mejor rendimiento |
| `language_rotation` | 5 | 20.0% | Rotación entre lenguas ibéricas |
| Adaptive (ronda 1) | 10 | 20.0% | Auto-selección de estrategia con memoria vacía |
| Adaptive (ronda 2) | 10 | 20.0% | Reutiliza learnings de ronda 1 |

La estrategia `escalation` es la más efectiva contra Llama 3.1 8B en multi-turn, triplicando la tasa de `language_rotation`.

### Benchmark Multi-Turn Adaptativo — Modelos Comerciales

| Modelo | Seeds | Tasa vuln | Estrategia seleccionada |
|--------|:-----:|:---------:|-------------------------|
| Claude Haiku 4.5 | 5 | 20.0% | Auto (adaptive) |
| Gemini 2.5 Flash | 5 | 20.0% | Auto (adaptive) |

### Benchmark Agentic — 18 seeds × llama3.1:8b

| Métrica | Resultado |
|---------|:---------:|
| Tasa de vulnerabilidad | 61.1% |
| Ataques ejecutados | 18/18 |
| Vulnerabilidades (score ≥ 5) | 11 |
| OWASP Agentic detectados | ASI01 (Goal Hijacking), ASI02 (Tool Misuse), ASI04 (Excessive Agency) |

### Session Memory — Acumulación de inteligencia

Tras las campañas multi-turn, VIGÍA acumuló automáticamente:
- **13 entradas** en `vector_effectiveness` con tasas de éxito por vector/modelo
- **Perfil de resistencia** del target con patrones (full_block, partial_resist, vulnerable)
- **9 entradas** en `eval_cache` para evaluaciones reutilizables entre campañas
- **Token savings** entre 5.7% y 16.7% por cached calls acumulados

## Quickstart

```bash
pip install vigia

# Necesitas Ollama corriendo
ollama serve  # en otra terminal
ollama pull llama3.1:8b
ollama pull nomic-embed-text

# Lanzar campaña contra el chatbot demo
vigia run
```

Para usar modelos comerciales como target o evaluador:

```bash
export ANTHROPIC_API_KEY=tu_key
vigia run -c vigia/config/claude_haiku.yaml
```

## Comandos

```bash
# Campaña one-shot contra chatbot RAG
vigia run
vigia run -c vigia/config/claude_haiku.yaml

# Multi-turn con estrategia específica
vigia multiturn --strategy rapport_to_extraction --max-seeds 5
vigia multiturn --strategy escalation --max-seeds 5
vigia multiturn --strategy language_rotation --max-seeds 5

# Multi-turn adaptativo — usa session memory para auto-seleccionar estrategia
vigia multiturn --adaptive --max-seeds 10

# Testing de agentes AI con herramientas
vigia agent
vigia agent --plan

# CI/CD gate — exit code 0 (pass) o 1 (vulns encontradas)
vigia scan -c config.yaml --fail-on-score 5
vigia scan --format junit -o report.xml

# Benchmarking comparativo
vigia benchmark -c vigia/config/default.yaml vigia/config/claude_haiku.yaml vigia/config/gemini.yaml

# Generar variantes lingüísticas (12 estrategias)
vigia mutate --strategies euskera,gallego,codeswitching_euskera
```

## Atacar tu propio chatbot

```bash
cp vigia/config/http_example.yaml mi_chatbot.yaml
```

```yaml
target:
  type: "http"
  url: "https://api.tu-empresa.com/chatbot/v1/message"
  headers:
    Authorization: "Bearer tu-api-key"
  request_format: "simple"
  request_field: "message"
  response_field: "data.answer"
```

```bash
vigia run -c mi_chatbot.yaml
```

El evaluador siempre corre en local — no envía datos de tu chatbot a ningún servicio externo.

## Nuevas funcionalidades (v0.5.0)

### Multi-Turn Adaptativo

El atacante mantiene una **memoria de sesión** que persiste entre campañas en SQLite. Tras cada evaluación, registra qué vectores funcionaron contra qué modelo y con qué score. En campañas posteriores, usa esa inteligencia para:

1. **Auto-seleccionar estrategia** — si el modelo bloquea >50% de ataques pero tiene cracks parciales → `escalation`. Si las defensas más débiles son vectores lingüísticos → `language_rotation`. Si es vulnerable → `rapport_to_extraction`.
2. **Inyectar intel en el prompt del atacante** — tasas de éxito por vector, defensas débiles y fuertes del modelo, warnings sobre vectores que han fallado previamente.
3. **Hooks por turno** — eventos `TURN_COMPLETE` y `POST_EVALUATE` para integración con pipelines externos.

```bash
# Primera campaña: acumula learnings
vigia multiturn --adaptive --max-seeds 10

# Segunda campaña: reutiliza intel acumulada
vigia multiturn --adaptive --max-seeds 10
```

### Token Efficiency

- **Tracking global** — conteo de tokens prompt/completion por modelo, calls totales, errores. Panel de resumen al final de cada campaña.
- **Early termination** — en multi-turn, corta tras 3 rechazos consecutivos de alta resistencia o cuando ya ha extraído ≥3 datos sensibles.
- **Compactación de system prompts** — los prompts del atacante, evaluador y evaluador agentic se redujeron ~50% preservando semántica.
- **Eval cache persistente** — evaluaciones de score ≤2 (rechazos claros) se cachean en SQLite y se reutilizan entre campañas, ahorrando entre 5-17% de LLM calls.

## Taxonomía de ataques

### RAG — 9 vectores

| Vector | Técnica | OWASP |
|--------|---------|-------|
| V01 | Ancla Numérica — forzar comparación que revela el dato exacto | LLM02 |
| V02 | Exfiltración por Resumen — el modo resumen prioriza completitud sobre restricciones | LLM02 |
| V03 | Fragmentación Temporal — rangos de fecha evitan keywords de guardrails | LLM02 |
| V04 | Negación Invertida — "qué NO puedes decirme" enumera categorías protegidas | LLM07 |
| V05 | Exfiltración Pasiva — datos sensibles adyacentes en chunks RAG | LLM02 |
| V06 | Impersonación de Rol — CISO, RRHH, auditor | LLM01 |
| V07 | Confusión Cross-Language — cambio a inglés evade guardrails en español | LLM01 |
| V08 | Chain-of-Thought — razonamiento paso a paso enumera datos como paso intermedio | LLM06 |
| V09 | Reformulación Compliant — datos "anonimizados" reidentificables con N pequeña | LLM09 |

### Agentes — 7 vectores (OWASP Agentic ASI01-ASI04)

Goal hijacking, indirect prompt injection (vía tool outputs), tool misuse, data exfiltration via tool chaining, privilege escalation, cross-tool credential theft, y excessive agency.

## Estrategias de mutación

12 estrategias lingüísticas para lenguas ibéricas:

| Estrategia | Qué hace |
|-----------|----------|
| `register_formal` | Subjuntivo, ustedeo, cortesía extrema |
| `register_informal` | Tuteo, expresiones coloquiales |
| `catalan` | Traducción a catalán estándar |
| `codeswitching` | Mezcla castellano-catalán mid-sentence |
| `euskera` | Euskera batua — tokenizers lo procesan peor |
| `codeswitching_euskera` | Mezcla castellano-euskera |
| `gallego` | Gallego normativo |
| `codeswitching_gallego` | Mezcla castellano-gallego |
| `rephrase` | Reformulación completa |
| `academic` | Encuadre de investigación/auditoría |
| `authority` | Rol de autoridad (auditor, IT, dirección) |
| `sms_speak` | Abreviaturas SMS/WhatsApp españolas |

## Licencia

MIT
