Khipu

Khipu is a cybersecurity threat-detection platform that lets anyone analyze emails, URLs, and network logs in plain language, without needing to read raw ML output — a GPT-powered agent picks the right specialized model and explains the verdict, built by students at Universidad Nacional de Colombia Sede Manizales for a hackathon. The name honors the knotted-cord record-keeping systems of pre-Columbian Andean cultures.

Architecture and Tech Stack

Core Architecture

• Frontend: Next.js 15 (App Router) + TypeScript, Tailwind CSS, Vercel AI SDK, Auth.js for authentication
• Backend: FastAPI exposing REST endpoints, one per detection capability
• Agent: LangChain AgentExecutor over OpenAI GPT — picks which ML tool(s) a query needs instead of calling a fixed endpoint
• ML models: 4 specialized scikit-learn models, pre-trained and loaded from .pkl files
• Database: PostgreSQL (Neon) via Drizzle ORM for chat history and user data
• Validation: Pydantic schemas for every request/response

Layered Architecture

Two front doors into the same detection logic: the dashboard calls the REST endpoints directly for structured results, while the chat goes through the LangChain agent, which decides which endpoint(s) to call from a natural-language question — both paths terminate in the same FastAPI services and ML models.

Request Flow

A conversational query ("is this URL safe? http://...") is what a raw REST call in the dashboard skips straight to — the agent path exists specifically to bridge natural language to the right specialized tool.

Key Features

Detection Models at a Glance

Real-Time Threat Detection

Each detection capability is a standalone FastAPI service with its own trained model and endpoint, so the dashboard, the agent, and any external caller can all reach the exact same classification logic:

• Spam Classifier — TF-IDF vectorization + Logistic Regression over email content
• Phishing URL Detector — Logistic Regression over tokenized URL features, with a risk-level rating
• Suspicious Access Detector — Gradient Boosting over network access patterns
• Network Logs Analyzer — Decision Tree over traffic anomaly features

Conversational Security Analysis

The chat interface lets a non-technical user ask about an email, URL, or log entry in plain language. The LangChain agent selects the matching tool(s), calls the underlying FastAPI service, and turns the raw prediction + confidence score into a structured, explained assessment — instead of the user having to know which of four endpoints applies.

Comprehensive Testing Infrastructure

The backend ships with a dedicated test suite (test_api.py, test_attack.py, test_phishing.py, test_suspicious.py, test_suspicious_logs.py) covering 13 predefined scenarios — normal corporate access, brute-force attempts, data exfiltration, SYN floods, port scans, and UDP floods — so each model's behavior is checked against realistic attack patterns, not just clean inputs.

Technical Highlights

One agent, four tools, one decision layer

Instead of one monolithic classifier or a menu the user has to navigate, CybersecurityAgent wraps each ML service as a LangChain Tool with its own description — the LLM reads the query and the tool descriptions and picks which one(s) apply, the same pattern that lets it be extended with a fifth detector without touching the other four.

Two front doors, one detection layer

The dashboard's structured REST calls and the chat's natural-language queries both terminate in the same spam_service / phishing_service / suspicious_service instances — there's exactly one place classification logic lives, regardless of which UI triggered it.

Attack-scenario testing over unit testing alone

Rather than only asserting on function outputs, the test suite drives the API through named attack scenarios (brute force, SYN flood, port scan, exfiltration) — closer to how the models will actually be judged in a live security context.

Project Structure

backend/
├── app/
│   ├── main.py                    # FastAPI app entrypoint
│   ├── api/
│   │   ├── router.py              # Aggregates all endpoint routers
│   │   └── 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 # LangChain AgentExecutor + system prompt
│   │   └── tools.py               # Wraps each ML service as a LangChain Tool
│   ├── services/                  # spam / phishing / suspicious business logic
│   ├── schemas/                   # Pydantic request/response models
│   └── core/                      # Config + shared dependencies
├── trained_models/                # Pre-trained .pkl models + vectorizers
└── test_*.py                      # Attack-scenario test suite

frontend/
├── app/
│   ├── (auth)/                    # Auth.js login/register
│   └── (chat)/                    # Chat UI, streaming API route, history, votes
└── ...                            # Next.js 15 App Router, Drizzle schema, Vercel AI SDK

Impact and Scalability

• Democratizes threat analysis: a plain-language chat interface removes the need to know which of four specialized models applies to a given input
• Extensible by design: adding a fifth detector means one new service + one new LangChain tool — the agent picks it up without changes elsewhere
• Realistic testing: 13 named attack scenarios stand in for the security-review process a production system would face
• Two consumption modes: the same detection layer serves both a structured dashboard and a conversational agent

Notes

Built with Next.js 15, FastAPI, LangChain, and scikit-learn. Code is public on GitHub. For a deeper technical deep-dive, see the documentation wiki.

🖼️ IMAGE PLACEHOLDER — dashboard view showing recent security events and alerts

🖼️ IMAGE PLACEHOLDER — chat interface analyzing a suspicious URL or email in natural language