Khipu

Khipu es una plataforma de detección de amenazas de ciberseguridad que permite a cualquiera analizar correos, URLs y logs de red en lenguaje natural, sin necesidad de interpretar la salida cruda de un modelo de ML — un agente potenciado por GPT elige el modelo especializado correcto y explica el veredicto, construido por estudiantes de la Universidad Nacional de Colombia Sede Manizales para una hackathon. El nombre honra los sistemas de registro con cuerdas anudadas de las culturas precolombinas andinas.

Arquitectura y Stack Tecnológico

Arquitectura Central

• Frontend: Next.js 15 (App Router) + TypeScript, Tailwind CSS, Vercel AI SDK, Auth.js para autenticación
• Backend: FastAPI exponiendo endpoints REST, uno por capacidad de detección
• Agente: AgentExecutor de LangChain sobre OpenAI GPT — elige qué tool(s) de ML necesita una consulta en vez de llamar a un endpoint fijo
• Modelos de ML: 4 modelos especializados de scikit-learn, preentrenados y cargados desde archivos .pkl
• Base de datos: PostgreSQL (Neon) vía Drizzle ORM para historial de chat y datos de usuario
• Validación: esquemas Pydantic en cada request/response

Arquitectura en Capas

Dos puertas de entrada a la misma lógica de detección: el dashboard llama directamente a los endpoints REST para resultados estructurados, mientras que el chat pasa por el agente de LangChain, que decide qué endpoint(s) llamar a partir de una pregunta en lenguaje natural — ambos caminos terminan en los mismos servicios de FastAPI y modelos de ML.

Flujo de una Petición

Una consulta conversacional ("¿es segura esta URL? http://...") es justo lo que una llamada REST cruda en el dashboard se salta — el camino del agente existe específicamente para conectar el lenguaje natural con la tool especializada correcta.

Características Principales

Los Modelos de Detección de un Vistazo

Detección de Amenazas en Tiempo Real

Cada capacidad de detección es un servicio de FastAPI independiente con su propio modelo entrenado y endpoint, de modo que el dashboard, el agente y cualquier consumidor externo llegan exactamente a la misma lógica de clasificación:

• Clasificador de Spam — vectorización TF-IDF + Regresión Logística sobre el contenido del correo
• Detector de URLs de Phishing — Regresión Logística sobre features tokenizadas de la URL, con una calificación de nivel de riesgo
• Detector de Accesos Sospechosos — Gradient Boosting sobre patrones de acceso de red
• Analizador de Logs de Red — Árbol de Decisión sobre features de anomalías de tráfico

Análisis de Seguridad Conversacional

La interfaz de chat permite a un usuario no técnico preguntar sobre un correo, URL o entrada de log en lenguaje natural. El agente de LangChain selecciona la(s) tool(s) que corresponde(n), llama al servicio de FastAPI subyacente, y convierte la predicción cruda + puntaje de confianza en una evaluación estructurada y explicada — sin que el usuario tenga que saber cuál de los cuatro endpoints aplica.

Infraestructura de Pruebas Integral

El backend incluye una suite de tests dedicada (test_api.py, test_attack.py, test_phishing.py, test_suspicious.py, test_suspicious_logs.py) que cubre 13 escenarios predefinidos — acceso corporativo normal, intentos de fuerza bruta, exfiltración de datos, inundaciones SYN, escaneos de puertos e inundaciones UDP — de modo que el comportamiento de cada modelo se verifica contra patrones de ataque realistas, no solo entradas limpias.

Destacados Técnicos

Un agente, cuatro tools, una capa de decisión

En vez de un clasificador monolítico o un menú que el usuario deba navegar, CybersecurityAgent envuelve cada servicio de ML como una Tool de LangChain con su propia descripción — el LLM lee la consulta y las descripciones de las tools y elige cuál(es) aplica(n), el mismo patrón que permite extenderlo con un quinto detector sin tocar los otros cuatro.

Dos puertas de entrada, una capa de detección

Las llamadas REST estructuradas del dashboard y las consultas en lenguaje natural del chat terminan ambas en las mismas instancias de spam_service / phishing_service / suspicious_service — hay exactamente un lugar donde vive la lógica de clasificación, sin importar qué UI la disparó.

Pruebas por escenario de ataque, no solo pruebas unitarias

En vez de solo verificar salidas de funciones, la suite de tests hace pasar a la API por escenarios de ataque nombrados (fuerza bruta, inundación SYN, escaneo de puertos, exfiltración) — más cercano a cómo se juzgarían los modelos en un contexto de seguridad real.

Estructura del Proyecto

backend/
├── app/
│   ├── main.py                    # Punto de entrada de la app FastAPI
│   ├── api/
│   │   ├── router.py              # Agrega todos los routers de endpoints
│   │   └── endpoints/
│   │       ├── spam.py            # POST /api/v1/spam/classify
│   │       ├── phishing.py        # POST /api/v1/phishing/check-url
│   │       ├── suspicious.py      # POST /api/v1/suspicious/check-access
│   │       ├── suspicious_logs.py # POST /api/v1/suspicious-logs/check-log
│   │       └── agent.py           # POST /api/v1/agent/analyze
│   ├── agents/
│   │   ├── cybersecurity_agent.py # AgentExecutor de LangChain + prompt del sistema
│   │   └── tools.py               # Envuelve cada servicio de ML como una Tool de LangChain
│   ├── services/                  # Lógica de negocio de spam / phishing / suspicious
│   ├── schemas/                   # Modelos Pydantic de request/response
│   └── core/                      # Configuración + dependencias compartidas
├── trained_models/                # Modelos .pkl preentrenados + vectorizadores
└── test_*.py                      # Suite de tests por escenario de ataque

frontend/
├── app/
│   ├── (auth)/                    # Login/registro con Auth.js
│   └── (chat)/                    # UI de chat, ruta API con streaming, historial, votos
└── ...                            # Next.js 15 App Router, esquema Drizzle, Vercel AI SDK

Impacto y Escalabilidad

• Democratiza el análisis de amenazas: una interfaz de chat en lenguaje natural elimina la necesidad de saber cuál de cuatro modelos especializados aplica a una entrada dada
• Extensible por diseño: agregar un quinto detector significa un servicio nuevo + una tool de LangChain nueva — el agente lo adopta sin cambios en el resto
• Pruebas realistas: 13 escenarios de ataque nombrados representan el proceso de revisión de seguridad que enfrentaría un sistema en producción
• Dos modos de consumo: la misma capa de detección sirve tanto a un dashboard estructurado como a un agente conversacional

Notas

Construido con Next.js 15, FastAPI, LangChain y scikit-learn. El código es público en GitHub. Para un análisis técnico más profundo, consulta la wiki de documentación.

🖼️ IMAGE PLACEHOLDER — vista del dashboard mostrando eventos de seguridad recientes y alertas

🖼️ IMAGE PLACEHOLDER — interfaz de chat analizando una URL o correo sospechoso en lenguaje natural