Arquitectura

Vision de alto nivel

┌─────────────────────────────────────────────────────────────┐
│                       Interfaces                            │
│  CLI (osint-agent) │ MCP (44 tools) │ A2A (5 skills)       │
│  Claude Code (15 skills)  │  Python import                  │
├─────────────────────────────────────────────────────────────┤
│              OsintService  (fachada unificada)              │
│             src/services/osint_service.py                   │
├──────────────────────────┬──────────────────────────────────┤
│   Threat Intelligence    │    Investigation Management      │
│                          │                                  │
│  ReAct Agent (LangGraph) │  InvestigationManager           │
│  Risk Dashboard (0-100)  │  EvidencePipeline               │
│  Threat Report (Markdown)│  EntityManager (12 tipos, FTM)  │
│  Auto-Pivot (2 niveles)  │  ClaimTracker (trazabilidad)    │
│                          │  AlertManager                   │
├──────────────────────────┴──────────────────────────────────┤
│  SQLite (cache OSINT)  │  SQLite (investigaciones, 8 tabs) │
│  data/osint_cache.db   │  data/osint_ai.db                 │
│                        │  ChromaDB  data/chroma/           │
├─────────────────────────────────────────────────────────────┤
│          28 Herramientas OSINT + 3 modulos de analisis      │
│  VirusTotal │ AbuseIPDB │ AlienVault │ Shodan │ IPInfo     │
│  URLScan │ WHOIS │ DNS │ crt.sh │ Threat Feeds             │
│  GDELT │ RSS │ Financial │ ACLED │ AIS                     │
│  Pivot │ History │ anomaly_detector │ narrative_detector    │
└─────────────────────────────────────────────────────────────┘

Capas

Interfaces

Cinco puntos de entrada al mismo nucleo de funcionalidad:

• CLI (src/cli/main.py): modo interactivo, query unica, batch, subcomandos de investigacion
• MCP Server (src/mcp_server/): 29 tools, 5 resources, 3 prompts via FastMCP
• A2A Server (src/a2a_server/): 5 skills via protocolo Google A2A, streaming
• Claude Code Skills (.claude/skills/): 15 skills Markdown que Claude Code ejecuta
• Python import: todas las tools son funciones async importables directamente

Fachada unificada (OsintService)

src/services/osint_service.py es el punto central que:

• Expone una API unificada para ambos casos de uso (TI e investigacion)
• Conecta el agente ReAct con el pipeline de investigacion via investigate_and_store()
• Es lo que las interfaces usan — nunca acceden directamente al agente o herramientas

Threat Intelligence

ReAct Agent (src/agent/): implementado con LangGraph. Ciclo razonamiento → accion → observacion hasta llegar a la respuesta final. Selecciona herramientas autonomamente basandose en el tipo de IOC y los resultados previos.

Risk Dashboard (src/scoring/dashboard.py): calcula una puntuacion compuesta 0-100 agregando las senales de todas las herramientas. Niveles: LIMPIO (0-20), BAJO (21-40), MEDIO (41-60), ALTO (61-80), CRITICO (81-100).

Auto-pivot: cuando una herramienta devuelve IOCs relacionados (p.ej. dominios asociados a una IP), el agente los extrae y los investiga automaticamente hasta 2 niveles de profundidad.

Investigation Management

InvestigationManager (src/investigation/manager.py): ciclo de vida de investigaciones — crear, archivar, reactivar. Mantiene el estado en SQLite y ChromaDB.

EvidencePipeline (src/investigation/evidence.py): pipeline completo de ingesta:

Fichero/URL → SHA-256 hash → dedup check → extraccion texto → chunking → embeddings → ChromaDB

Soporta PDF, TXT, HTML, MD. Credibilidad por niveles de fuente.

EntityManager (src/investigation/entities.py): extraccion, normalizacion y deduplicacion de entidades siguiendo la ontologia FollowTheMoney. Reglas especificas para entidades espanolas (DNI, CIF, IBAN, prefijos telefonicos).

ClaimTracker (src/investigation/claims.py): cada claim se registra con evidence_id + chunk_id + snippet. Auditoria para detectar afirmaciones no respaldadas, contradicciones y duplicados.

Persistencia

Store	Proposito	Ruta
SQLite osint_cache.db	Cache de resultados de herramientas OSINT (TTL configurable)	data/osint_cache.db
SQLite osint_ai.db	Investigaciones, evidencias, entidades, claims, alertas (8 tablas)	data/osint_ai.db
ChromaDB	Embeddings para busqueda semantica sobre evidencias	data/chroma/

Flujo de datos

Threat Intelligence

Query usuario
    ↓
ReAct Agent selecciona herramientas
    ↓
Llamadas async a APIs OSINT (httpx)
    ↓
Resultados cacheados en SQLite
    ↓
Agente razona sobre resultados
    ↓ (si encuentra IOCs relacionados)
Auto-pivot → nueva ronda de herramientas
    ↓
Dashboard + Informe Markdown

Investigation Management

Crear investigacion
    ↓
Ingestar evidencias (PDF/URL/texto)
    ↓
SHA-256 → extraccion → chunks → embeddings ChromaDB
    ↓
Extraer entidades (normalizacion FTM)
    ↓
Registrar claims con trazabilidad
    ↓
Busqueda semantica
    ↓
Verificar claims → auditar calidad
    ↓
Generar informe 9 secciones

Bridge: investigar y almacenar

# osint_service.investigate_and_store()
Investiga IOC con agente ReAct
    ↓
Guarda resultado como evidencia en la investigacion activa
    ↓
Extrae entidades automaticamente
    ↓
Registra claims clave con trazabilidad

Esto conecta ambos workflows: el reconocimiento OSINT alimenta la base de evidencias de la investigacion.