# Project export: Dyno This document was generated by HackStack to give an AI agent context about a hackathon project. Sections are labeled with their provenance; content marked as truncated was cut to keep this document small. ## Project metadata - Hackathon: Cal Hacks 12.0 - Tagline: Real-time AI-powered API security - Devpost: https://devpost.com/software/dyno - GitHub: https://github.com/kevintsoii/cal-hacks-2025 - Video: https://www.youtube.com/embed/WvsG6LBuIYc?enablejsapi=1&hl=en_US&rel=0&start=&version=3&wmode=transparent - Team: 4 GitHub contributor(s) — Kevin Tsoi (31 commits), kylechu8092 (12 commits), Marvin (9 commits), James Kim (8 commits) ## Devpost submission (written by the team) ### Inspiration APIs are the backbone of every modern app — yet they’re also one of the easiest attack surfaces to exploit. From brute-force login attempts to automated scraping and credential stuffing, most API defenses are still static: rate-limiters and blacklists that can’t adapt. Even larger companies, such as Discord, are not immune to these attacks - recently, over 8 million tickets full of private information were scraped through a compromised admin account. We wanted to build a self-learning layer of defense — something that doesn’t just detect suspicious traffic, but understands why it’s suspicious, adapts in real-time, and learns from every incident. That’s how Dyno was born. ### What it does Dyno is an AI-powered security middleware that sits in front of any FastAPI-based backend and continuously monitors API traffic for threats. It logs all incoming API requests and detects anomalies like brute-force logins, web scraping, and excessive query behavior — and reacts intelligently using a progressive mitigation system: Adds small request delays for mild anomalies Challenges users with CAPTCHAs for moderate suspicion Temporarily blocks Fully bans repeated offenders ### How we built it Dyno is built on a sophisticated multi-layered architecture that combines three specialized databases, an intelligent AI agent pipeline, and a self-learning RAG system. Backend Architecture & Middleware The core of Dyno is a FastAPI middleware that intercepts every API request before it reaches the application layer. The middleware follows a three-step process: Redis Check: First, it performs a lightning-fast lookup in Redis to check if there's an active mitigation for the incoming IP or user. If found, it immediately applies the mitigation (delay, CAPTCHA, or block) without processing the request further. Redis Check: First, it performs a lightning-fast lookup in Redis to check if there's an active mitigation for the incoming IP or user. If found, it immediately applies the mitigation (delay, CAPTCHA, or block) without processing the request further. Request Processing: If no mitigation exists, the request is allowed to proceed normally to the API endpoint. Request Processing: If no mitigation exists, the request is allowed to proceed normally to the API endpoint. Asynchronous Logging: After the request completes, the middleware non-blockingly adds the request details to both an internal queue and Elasticsearch. This ensures zero performance impact on legitimate traffic. Asynchronous Logging: After the request completes, the middleware non-blockingly adds the request details to both an internal queue and Elasticsearch. This ensures zero performance impact on legitimate traffic. The internal queue batches requests and triggers the AI agent pipeline either every 5 seconds or when 100 requests accumulate — whichever comes first. Three-Database Architecture We engineered Dyno to leverage three different databases, each optimized for its specific role: 1. Redis – The first line of defense. Redis stores active mitigations with sub-millisecond lookup times, enabling us to block attacks instantly without consulting slower databases. Every mitigation decision made by the AI agents is written here with TTLs for automatic expiration. 2. Elasticsearch – The comprehensive audit log. Every single API request (with metadata like IP, user, endpoint, headers, response time, status code) is indexed in Elasticsearch. This provides: Full-text search across all historical traffic Complex aggregation queries for pattern detection Time-series analysis of attack trends The data source for our AI agents to investigate suspicious behavior 3. ChromaDB – The memory layer. ChromaDB is a vector database that powers our RAG (Retrieval-Augmented Generation) system. It stores semantic embeddings of past mitigation decisions along with their outcomes and human feedback. When the Calibration Agent needs to make a decision, it queries ChromaDB to find similar historical cases and learns from them. AI Agent System We built a multi-agent system using Fetch.AI's uAgents framework, where specialized agents collaborate to detect threats: Orchestrator Agent – The traffic controller. It receives batches of API requests from the middleware queue and intelligently routes them to the appropriate specialist agent based on endpoint type (e.g., /auth/* → Auth Agent, /search → Search Agent). Specialized Detection Agents – We created three specialist agents, each with domain-specific knowledge: Auth Agent: Detects brute-force login attempts, credential stuffing, account enumeration Search Agent: Identifies scraping behavior, excessive queries, suspicious search patterns General Agent: Catches anomalies in all other endpoints Each specialist agent receives custom rules (loaded from agent_rules/ directory) that define what patterns to look for. The agents use Groq's LLM API (specifically Llama models) to analyze batches of requests and use tool calling to query Elasticsearch for historical context about IPs or users. After analysis, they suggest a mitigation level for suspicious actors. Calibration Agent – The learning layer. This agent takes the raw mitigation suggestions from specialists and refines them using historical knowledge: Queries ChromaDB using RAG to find semantically similar past incidents Amplifies or downgrades the mitigation based on what worked before Saves the final decision back to ChromaDB with reasoning for future reference Incorporates human feedback from the dashboard to continuously improve The calibrated mitigation is then written to Redis, completing the loop. RAG + Feedback System The RAG (Retrieval-Augmented Generation) system is what makes Dyno adaptive: Historical Storage: Every mitigation decision is embedded and stored in ChromaDB along with: The request patterns that triggered it The mitigation level applied Whether it was effective Any human feedback (thumbs up/down from the dashboard) Historical Storage: Every mitigation decision is embedded and stored in ChromaDB along with: The request patterns that triggered it The mitigation level applied Whether it was effective Any human feedback (thumbs up/down from the dashboard) Semantic Retrieval: When the Calibration Agent evaluates a new threat, it performs a semantic search in ChromaDB to find similar past cases — not just exact matches, but situations with similar characteristics. Semantic Retrieval: When the Calibration Agent evaluates a new threat, it performs a semantic search in ChromaDB to find similar past cases — not just exact matches, but situations with similar characteristics. Context-Aware Decisions: The agent uses retrieved examples as context in its LLM prompt, asking: "Given these similar past cases, should I increase or decrease the suggested mitigation?" Context-Aware Decisions: The agent uses retrieved examples as context in its LLM prompt, asking: "Given these similar past cases, should I increase or decrease the suggested mitigation?" Human-in-the-Loop: Security engineers can mark mitigations as correct or incorrect through the dashboard. This feedback is immediately incorporated into ChromaDB, so the system learns from mistakes in real-time. Human-in-the-Loop: Security engineers can mark mitigations as correct or incorrect through the dashboard. This feedback is immediately incorporated into ChromaDB, so the system learns from mistakes in real-time. Rule Customization: The dashboard also allows live editing of agent rules, which are hot-reloaded into the agents without requiring restarts. Rule Customization: The dashboard also allows live editing of agent rules, which are hot-reloaded into the agents without requiring restarts. Frontend & Real-Time Communication The dashboard is built with React + TypeScript using shadcn/ui components and TailwindCSS for styling. It connects to the backend via WebSocket for real-time streaming of: Live API request logs Threat detection alerts Mitigation applications Agent decision explanations We also implemented a security chatbot agent that lets users query the system in natural language (e.g., "Show me all blocked IPs from the last hour") by translating queries to Elasticsearch DSL. Infrastructure Everything is containerized with Docker and orchestrated via docker-compose, making deployment a single command. The entire stack — FastAPI backend, 6 AI agents, Redis, ChromaDB, and the React frontend — spins up together with automatic service discovery. ### Accomplishments we're proud of Fully automating BOTH detection AND acting on malicious API requests Using the Fetch.ai ecosystem for fast, asynchronous communication between agents in real-time Implementing ChromaDB for calibration through human-in-the-loop and agentic memory of previous decisions Using Groq to get < 5 second full end-to-end pipeline speed ### What we learned Multi-agent orchestration introduces both incredible flexibility and complex failure modes — message passing and trust boundaries matter. RAG-based calibration can make AI decisions more explainable and consistent when paired with structured reasoning logs. Human-in-the-loop feedback isn’t just a bonus — it’s essential for avoiding over-blocking legitimate users. Security visibility is just as important as security action: clear dashboards empower developers to intervene intelligently. ### What's next Multi-Framework Support: Extend beyond FastAPI to support Express.js, Django, Rails, and other popular web frameworks Behavioral Fingerprinting: Build user behavior profiles over time to detect subtle account takeovers and anomalous sessions Edge Deployment: Deploy lightweight detection agents at CDN edge locations for sub-10ms global mitigation response times Threat Intelligence Integration: Automatically incorporate external threat feeds (malicious IPs, compromised credentials) into agent decisions Enterprise Multi-Tenancy: Enable multiple organizations to use shared Dyno infrastructure with isolated data and configurations ## README (from the GitHub repository) # AI-Powered API Security Middleware An intelligent API security solution that leverages AI agents and Large Language Models to automatically detect and mitigate malicious API behavior in real-time, including brute-force login attempts, web scraping, and other suspicious activities. ## 🌟 Features - **Real-time Threat Detection**: Monitors all API traffic and identifies suspicious patterns using AI agents - **Intelligent Mitigation**: Progressive mitigation strategy from request delays to full bans - **Multi-Agent Architecture**: Specialized AI agents for different API endpoint types (Auth, Search, General) - **Adaptive Learning**: RAG-based calibration system that learns from past mitigations - **Human-in-the-Loop**: Incorporates human feedback to improve detection accuracy - **Live Dashboard**: Real-time monitoring interface with metrics, threat analysis, and mitigation controls - **Elasticsearch Integration**: Comprehensive logging and querying of API traffic - **WebSocket Updates**: Live streaming of security events to the frontend --- ## 🚀 Getting Started ### Prerequisites - Docker and Docker Compose: https://www.docker.com/ - Elasticsearch instance (cloud): https://cloud.elastic.co/serverless-registration - Groq Dev Tier account: https://console.groq.com/docs/overview - ReCAPTCHA account (optional to make captchas work): https://developers.google.com/recaptcha/intro ### Run 1. Create a `.env` file in the `backend/` directory: ```bash GROQ_API_KEY=your_groq_api_key ELASTICSEARCH_ENDPOINT=your_elasticsearch_url ELASTICSEARCH_API_KEY=your_elasticsearch_api_key RECAPTCHA_SECRET_KEY=your_recaptcha_secret_key_optional ``` 2. **Start all services with Docker Compose** ```bash docker-compose up --build ``` This will start: - Backend API (port 8000) - All AI agents (ports 8001-8007) - Frontend (port 5173) - Redis (port 6379) - ChromaDB (port 9000) 3. **Access the application** - Frontend: http://localhost:5173 --- ## 🏗️ Architecture ### Request Flow ``` API Request → FastAPI Middleware ↓ 1. Redis Check (Active Mitigations) ↓ 2. Process API Request ↓ 3. Log to Agent Pipeline Queue + Elasticsearch ↓ 4. Async Agent Pipeline (every 5s / 100 requests) ↓ Orchestrator Agent → Specialized Agents → Calibration Agent (+ RAG memory) → Redis (Apply Mitigation) ``` ### Mitigation Levels Progressive mitigation strategy based on threat severity: 1. **None**: Normal operation 2. **Small Delay**: 100-500ms request delay 3. **Captcha**: reCAPTCHA challenge 4. **Temporary Block**: Time-limited access restriction 5. **Full Ban**: Permanent IP/user blocking ### AI Agent System **Orchestrator Agent** - Receives batched API requests - Routes requests to specialized agents based on endpoint type - Coordinates the detection pipeline **Specialized Agents** - **Auth Agent**: Analyzes authentication endpoints (login, signup, password reset) - **Search Agent**: Monitors search and query endpoints - **General Agent**: Handles all other API traffic - Uses tool calling to query Elasticsearch logs - Determines appropriate mitigations for suspicious IPs/users **Calibration Agent** - Uses RAG + ChromaDB to access historical mitigation data - Amplifies or downgrades suggested mitigations based on past outcomes - Stores calibrated decisions with semantic reasoning - Learns from human feedback **Support Agents** - **Chatbot Agent**: Interactive security assistant for the dashboard - **ESQL Query Agent**: Natural language to Elasticsearch query translation **Live Feedback** - Configurable Agent Prompts through our dashboard - Calibration feedback by a human in the loop adds to RAG for extra context ## 🛠️ Tech Stack ### Backend - **FastAPI**: High-performance Python web framework - **Fetch.AI (uAgents)**: Multi-agent framework for distributed AI agents - **Groq**: LLM provider for agent intelligence - **Redis**: Fast caching and mitigation state management - **Elasticsearch**: Efficient logging and analytics - **ChromaDB**: Vector database for semantic search and RAG-based learning - **Python 3.11+**: Core language ### Frontend - **React 18**: UI framework - **TypeScript**: Type-safe JavaScript - **Vite**: Fast build tool - **TailwindCSS**: Utility-first CSS framework - **shadcn/ui**: High-quality UI components - **Radix UI**: Accessible component primitives - **WebSocket**: Real-time updates ### Infrastructure - **Docker**: Containerization - **Docker Compose**: Multi-container orchestration ## 📊 Usage ### Dashboard The web dashboard provides: - **Metrics Overview**: Real-time statistics on requests, threats detected, and active mitigations - **Activity Chart**: Visual representation of traffic patterns - **Detection Log**: Live stream of API requests and security events - **Threat Analysis**: Detailed breakdown of detected threats - **Active Mitigations**: Current mitigation rules and controls - **Agent Rules Management**: Configure detection rules for specialized agents - **Security Chat**: Interactive AI assistant for security queries - **Test Suite**: Built-in traffic generation for testing ### API Integration To protect your API with this middleware, wrap your FastAPI application: ```python from fastapi import FastAPI from middleware.middleware import SecurityMiddleware app = FastAPI() app.add_middleware(SecurityMiddleware) @app.get("/api/protected") async def protected_endpoint(): return {"message": "This endpoint is protected"} ``` ## 🤖 Fetch.AI Agent Info - Orchestrator Agent - agent1q0a3vglkxzlaqdgysyl6l7tzfpz5awc2amy2ek50mje0ngqyhrr9k8pjsw5 - https://agentverse.ai/agents/details/agent1q0a3vglkxzlaqdgysyl6l7tzfpz5awc2amy2ek50mje0ngqyhrr9k8pjsw5/profile - Auth API Specialist Agent - agent1q054vfyk2qqnqwsrw804avurynvwkk9vdjcqu9q0at52zlaa5urxv0md3sk - https://agentverse.ai/agents/details/agent1q054vfyk2qqnqwsrw804avurynvwkk9vdjcqu9q0at52zlaa5urxv0md3sk/profile - Search API Specialist Agent - agent1qtpatn2rged8wspghgl8sex9e05s78fvmh84pnyf5ghn6ue0t6vkjvp03mg - https://agentverse.ai/agents/details/agent1qtpatn2rged8wspghgl8sex9e05s78fvmh84pnyf5ghn6ue0t6vkjvp03mg/profile - General API Specialist Agent - agent1q2ackrd978swlwajsswm4kjr9cszhc9rxgnuyy7rv9jzh4v3jta25vzv668 - https://agentverse.ai/agents/details/agent1q2ackrd978swlwajsswm4kjr9cszhc9rxgnuyy7rv9jzh4v3jta25vzv668/profile - Mitigation Calibration Agent - agent1qgnl0fly845g2zlx904lsgwygl4vl7jygcx7xyxf82zu95g26mgmy0dk9rt - https://agentverse.ai/agents/details/agent1qgnl0fly845g2zlx904lsgwygl4vl7jygcx7xyxf82zu95g26mgmy0dk9rt/profile - Chatbot Agent - agent1qw7m6gyh3swk38gw3zkc86sa2wrjqrcykvpzjeeqrxv8k4fgskzpzac6kk5 - https://agentverse.ai/agents/details/agent1qw7m6gyh3swk38gw3zkc86sa2wrjqrcykvpzjeeqrxv8k4fgskzpzac6kk5/profile - ESQL Query Agent - agent1qwxyzc74yr92wstx0g7q4fmvzezev08495m5jq0yl9pwz05ur5gly5t4kuy - https://agentverse.ai/agents/details/agent1qwxyzc74yr92wstx0g7q4fmvzezev08495m5jq0yl9pwz05ur5gly5t4kuy/profile ### Agent Communication Agents communicate via Fetch.AI's uAgents protocol: 1. Orchestrator receives request batches 2. Messages routed to specialized agents 3. Specialized agents analyze and respond with threat assessments 4. Calibration agent refines mitigation levels 5. Mitigations applied to Redis ### Agent Rules Each specialized agent follows rules defined in `backend/agent_rules/`: - `auth_agent_rules.txt`: Authentication endpoint patterns - `search_agent_rules.txt`: Search behavior indicators - `general_agent_rules.txt`: General traffic anomalies Rules can be updated through the dashboard's Agent Rules page. --- ## How we built it Dyno is built on a sophisticated multi-layered architecture that combines three specialized databases, an intelligent AI agent pipeline, and a self-learning RAG system. ### Backend Architecture & Middleware The core of Dyno is a **FastAPI middleware** that intercepts every API request before it reaches the application layer. The middleware fol [README truncated for size] ## Detected evidence (automated analysis) Indexed codebase: 82 recognized source files, 636 KB. - CSS (language) — detected in the code - FastAPI (technology) — detected in the code - HTML (language) — detected in the code - JavaScript (language) — detected in the code - Python (language) — detected in the code - React (technology) — detected in the code - Redis (technology) — detected in the code - Tailwind CSS (technology) — detected in the code - TypeScript (language) — detected in the code - Docker (technology) — claimed on Devpost, not found in the code - AI coding agent: Codex — evidence: config files committed to the repository ## Codebase structure (from repository index) ### Files (104 of 104) ``` .dockerignore .gitignore AGENTS.md backend/.dockerignore backend/.gitignore backend/agent_rules/auth_agent_rules.txt backend/agent_rules/general_agent_rules.txt backend/agent_rules/search_agent_rules.txt backend/agents/auth_agent.py backend/agents/calibration_agent.py backend/agents/chatbot_agent.py backend/agents/esql_query_agent.py backend/agents/general_agent.py backend/agents/models.py backend/agents/orchestrator_agent.py backend/agents/search_agent.py backend/api/rules_routes.py backend/api/websocket_routes.py backend/db/__init__.py backend/db/elasticsearch.py backend/db/redis.py backend/Dockerfile backend/elastictool/elasticsearch_tool.py backend/experiments/__init__.py backend/experiments/agent.py backend/experiments/orchestrator backend/experiments/sample.py backend/experiments/specialist.py backend/experiments/test_agent.py backend/experiments/test_elasticsearch_tool.py backend/experiments/test_traffic_generator.py backend/experiments/testrunners.py backend/fix_cosmpy.sh backend/main.py backend/middleware/__init__.py backend/middleware/middleware.py backend/middleware/mitigation.py backend/middleware/queue.py backend/middleware/recaptcha.py backend/rag/simple_rag.py backend/rag/test_security_rag.py backend/requirements.txt backend/sample.py backend/start.sh backend/test_full_pipeline.py backend/testrunners.py backend/tests/__init__.py backend/tests/auth.py backend/tests/config.py backend/tests/search.py backend/utils/rule_loader.py backend/websocket/__init__.py backend/websocket/connection_manager.py backend/websocket/elasticsearch_poller.py chromadb/CHROMADB_ARCHITECTURE.md chromadb/Dockerfile chromadb/main.py chromadb/README.md chromadb/requirements.txt docker-compose.yml frontend/.dockerignore frontend/.gitignore frontend/components.json frontend/Dockerfile frontend/eslint.config.js frontend/index.html frontend/package.json frontend/README.md frontend/src/App.css frontend/src/App.tsx frontend/src/components/Activity-Chart.tsx frontend/src/components/Detection-Log.tsx frontend/src/components/Endpoint-Status.tsx frontend/src/components/Metrics-Overview.tsx frontend/src/components/Mitigations.tsx frontend/src/components/Navbar.tsx frontend/src/components/RunTests.tsx frontend/src/components/ScrollToTop.tsx frontend/src/components/StartupNavbar.tsx frontend/src/components/Threat-analysis.tsx frontend/src/components/ui/badge.tsx frontend/src/components/ui/button.tsx frontend/src/components/ui/card.tsx frontend/src/components/ui/input.tsx frontend/src/components/ui/table.tsx frontend/src/components/ui/textarea.tsx frontend/src/hooks/useActivityData.tsx frontend/src/hooks/useWebSocket.tsx frontend/src/index.css frontend/src/lib/utils.ts frontend/src/main.tsx frontend/src/pages/AgentRules.tsx frontend/src/pages/Chat.tsx frontend/src/pages/Dashboard.tsx frontend/src/pages/Home.tsx frontend/src/pages/Login.tsx frontend/src/pages/UserSearch.tsx frontend/tsconfig.app.json frontend/tsconfig.json frontend/tsconfig.node.json frontend/vite.config.ts LICENSE package.json README.md ``` ### Dependencies - backend/requirements.txt: aiohappyeyeballs@==2.6.1, aiohttp@==3.13.1, aiosignal@==1.4.0, annotated-types@==0.7.0, anyio@==4.11.0, async-timeout@==5.0.1, attrs@==25.4.0, bech32@==1.2.0, certifi@==2025.10.5, charset-normalizer@==3.4.4, click@==8.3.0, cosmpy@==0.11.1, distlib@==0.4.0, distro@==1.9.0, ecdsa@==0.19.1, elastic-transport@==9.2.0, elasticsearch@==9.1.1, exceptiongroup@==1.3.0, fastapi@==0.119.0, filelock@==3.20.0, frozenlist@==1.8.0, googleapis-common-protos@==1.70.0, groq@==0.33.0, grpcio@==1.75.1, h11@==0.16.0, httpcore@==1.0.9, httptools@==0.7.1, httpx@==0.28.1, idna@==3.10, jsonschema@==4.25.1, jsonschema-specifications@==2025.9.1, multidict@==6.7.0, platformdirs@==4.5.0, propcache@==0.4.1, protobuf@==4.25.3, pycryptodome@==3.23.0, pydantic@==2.12.0, pydantic_core@==2.41.1, python-dateutil@==2.9.0.post0, python-dotenv@==1.1.1, PyYAML@==6.0.3, redis@==6.4.0, referencing@==0.37.0, requests@==2.32.5, rpds-py@==0.27.1, six@==1.17.0, sniffio@==1.3.1, sortedcontainers@==2.4.0, starlette@==0.48.0, typing_extensions@==4.15.0, typing-inspection@==0.4.2, uagents@==0.22.10, uagents-core@==0.3.11, urllib3@==2.5.0, uvicorn@==0.37.0, uvloop@==0.22.1, virtualenv@==20.35.3, watchfiles@==1.1.1, websockets@==15.0.1, yarl@==1.22.0 - chromadb/requirements.txt: chromadb@==1.2.1, fastapi@==0.119.0, pydantic@==2.12.0, uvicorn@==0.37.0 - frontend/package.json: @eslint/js@^9.36.0, @radix-ui/react-dropdown-menu@^2.1.16, @radix-ui/react-icons@^1.3.2, @radix-ui/react-slot@^1.2.3, @tailwindcss/vite@^4.1.16, @types/node@^24.6.0, @types/react@^19.2.2, @types/react-dom@^19.2.2, @vitejs/plugin-react@^5.0.4, class-variance-authority@^0.7.1, clsx@^2.1.1, eslint@^9.36.0, eslint-plugin-react-hooks@^5.2.0, eslint-plugin-react-refresh@^0.4.22, globals@^16.4.0, lucide-react@^0.548.0, react@^19.1.1, react-dom@^19.1.1, react-google-recaptcha@^3.1.0, react-router-dom@^7.9.4, recharts@^3.3.0, tailwind-merge@^3.3.1, tailwindcss@^4.1.16, tw-animate-css@^1.4.0, typescript@~5.9.3, typescript-eslint@^8.45.0, vite@^7.1.7 - package.json: @types/react-google-recaptcha@^2.1.9 ### Recent commits (newest first) - Update README.md - initial readme - ui changes - Feature/metrics (#9) - fix rag for chroma calibration - Merge branch 'custom_chroma_rules' - add custom rules w chromaDB semantic search for calibration agent - add custom rules w chromaDB semantic search for calibration agent - feat(mitigation): add active and historical mitigations endpoints and frontend component (#8) - Merge pull request #7 from kevintsoii/customagentrules - fixagent - custom rules - small chatbot fix - fix dashboard graph - fix package json - fix env - Merge pull request #6 from kevintsoii/newgraph - update - elasticsearch fixes - update ## Key source files (fetched from GitHub, selected and truncated for size) ### AGENTS.md ```markdown # Project Name ## Architecture This project is an AI-powered API security middleware that uses AI agents & LLMs to detect and automatically mitigate malicious API behavior (brute-force logins, scrapiing). - FastAPI middleware covers all API routes - 1st, do a quick check on Redis for any active mitigations and return early with an error if one exists - mitigations: nothing > small 100-500ms request delay > captcha > temporary block > full ban - 2nd, allows the API request to process - 3rd, adds API request details to an internal non-blocking queue + to elasticsearch - The queue asynchronously feeds to the AI agent pipeline every 5s / at 100 requests - Fetch.AI agents handle all detection using Groq as the LLM provider + tool calling + RAG memory - Orchestrator Agent -> splits the batch of requests to the specialized agent for the request type - Specialized Agents (Auth/Search/General) -> Analyze the requests, uses tool calling to access elasticsearch logs, and decide which Users/IPs to apply mitigations to - Calibration Agent -> uses RAG + ChromaDB on past mitigations to amplify or downgrade the mitigation suggested by specialized agent. - saves the newly calibrated mitigation to ChromaDB with semantic reasoning for future reference - Applies the mitigation to Redis - Human Inputs (wheter an auto-mitigation was good or bad) will be provided to the Calibration Agent for future use ## Frontend - Use TypeScript - Use Radix UI for icons - Use TailwindCSS for all CSS changes - Use shadcn for all UI components - Download all components directly using npx shadcn@latest add - Do not npm run dev to test changes ## General - When installing new packages, use npm install or pip install rather than an arbitrary package version directly in the packages file ``` ### chromadb/CHROMADB_ARCHITECTURE.md ```markdown # ChromaDB Microservice Architecture ## Overview ChromaDB runs as a **separate Python microservice** with its own Docker container, dependencies, and virtual environment. This solves the protobuf dependency conflict between ChromaDB and cosmpy. ## Project Structure ``` cal-hacks-2025/ ├── backend/ # Backend service (Python 3.11 + cosmpy + protobuf <6) │ ├── agents/ │ ├── rag/ │ │ └── simple_rag.py # HTTP client to ChromaDB service │ ├── requirements.txt # NO chromadb dependency │ └── Dockerfile │ ├── chromadb/ # NEW: ChromaDB service (Python 3.11 + chromadb + protobuf 6.x) │ ├── main.py # FastAPI server exposing ChromaDB API │ ├── requirements.txt # chromadb==1.2.1 with protobuf 6.x │ ├── Dockerfile │ └── README.md │ ├── frontend/ # React frontend └── docker-compose.yml # Orchestrates all services ``` ## Architecture Diagram ``` ┌─────────────────────────────────────────────────────────────┐ │ Docker Compose │ ├─────────────────────────────────────────────────────────────┤ │ │ │ ┌──────────────────┐ ┌──────────────────┐ │ │ │ Backend │ │ ChromaDB │ │ │ │ Container │ │ Container │ │ │ │ │ │ │ │ │ │ Python 3.11 │──────│ Python 3.11 │ │ │ │ cosmpy │ HTTP │ chromadb 1.2.1 │ │ │ │ protobuf 4.x │ │ protobuf 6.x │ │ │ │ │ │ │ │ │ │ simple_rag.py │ │ FastAPI Server │ │ │ │ (HTTP client) │ │ (Vector Store) │ │ │ └──────────────────┘ └──────────────────┘ │ │ │ │ │ ▼ │ │ ┌──────────────────┐ │ │ │ chromadb-data │ │ │ │ Volume │ │ │ │ (Persistent) │ │ │ └──────────────────┘ │ └─────────────────────────────────────────────────────────────┘ ``` ## Communication Flow 1. **Calibration Agent** (backend) calls `rag.add_item()` or `rag.query_items()` 2. **simple_rag.py** makes HTTP POST/GET request to ChromaDB service 3. **ChromaDB Service** (chromadb/main.py) receives request 4. **ChromaDB** creates vector embeddings and stores/queries data 5. **Response** returned to backend as JSON ## Benefits ### ✅ Dependency Isolation - Backend: cosmpy requires protobuf <6.0 ✅ - ChromaDB: chromadb requires protobuf 6.x ✅ - No conflicts! Each service has its own Python environment ### ✅ Microservices Architecture - Independent deployment and sca [truncated — 1788 more characters] ``` ### package.json ``` { "dependencies": { "@types/react-google-recaptcha": "^2.1.9" } } ``` ### docker-compose.yml ```yaml version: '3.8' services: backend: build: context: ./backend dockerfile: Dockerfile container_name: backend ports: - "8000:8000" - "8001:8001" # Orchestrator Agent - "8002:8002" # Auth Agent - "8003:8003" # Search Agent - "8004:8004" # General Agent - "8006:8006" # ESQL Query Agent - "8007:8007" # Chatbot Agent volumes: - ./backend:/app environment: - PYTHONUNBUFFERED=1 - REDIS_HOST=redis - REDIS_PORT=6379 - CHROMADB_URL=http://chromadb:9000 - CHROMADB_SERVICE_URL=http://chromadb:9000 depends_on: redis: condition: service_started chromadb: condition: service_started networks: - hackathon-network restart: unless-stopped frontend: build: context: ./frontend dockerfile: Dockerfile container_name: frontend volumes: - ./frontend:/app - /app/node_modules environment: - CHOKIDAR_USEPOLLING=true ports: - "5173:5173" depends_on: - backend networks: - hackathon-network restart: unless-stopped redis: image: redis:7-alpine container_name: redis ports: - "6379:6379" volumes: - redis-data:/data networks: - hackathon-network restart: unless-stopped command: redis-server --appendonly yes chromadb: build: context: ./chromadb dockerfile: Dockerfile container_name: chromadb ports: - "9000:9000" volumes: - chromadb-data:/chroma_data networks: - hackathon-network restart: unless-stopped networks: hackathon-network: driver: bridge volumes: redis-data: chromadb-data: ``` ### chromadb/requirements.txt ``` chromadb==1.2.1 fastapi==0.119.0 uvicorn==0.37.0 pydantic==2.12.0 ``` ### frontend/Dockerfile ``` # Frontend Dockerfile - Multi-stage build FROM node:20-alpine # Set working directory WORKDIR /app # Copy package files COPY package*.json ./ # Install dependencies RUN npm install # Copy source code COPY . . # Expose port EXPOSE 5173 CMD ["npm", "run", "dev", "--", "--host", "0.0.0.0", "--port", "5173"] ``` ### chromadb/Dockerfile ``` FROM python:3.11-slim WORKDIR /app # Copy requirements COPY requirements.txt . # Install dependencies (ChromaDB with protobuf 6.x - no conflict!) RUN pip install --no-cache-dir -r requirements.txt # Copy application COPY main.py . # Create data directory for ChromaDB persistent storage RUN mkdir -p /chroma_data # Expose port EXPOSE 9000 # Run the FastAPI server CMD ["python", "main.py"] ``` ### backend/Dockerfile ``` # Backend Dockerfile FROM python:3.11-slim # Set working directory WORKDIR /app # Copy requirements first for better caching COPY requirements.txt . # Install dependencies RUN pip install --no-cache-dir -r requirements.txt # Copy fix script and apply cosmpy protobuf fix COPY fix_cosmpy.sh . RUN chmod +x fix_cosmpy.sh && ./fix_cosmpy.sh # Copy application code COPY . . # Make startup script executable RUN chmod +x start.sh # Expose ports for FastAPI and all Agents EXPOSE 8000 EXPOSE 8001 EXPOSE 8002 EXPOSE 8003 EXPOSE 8004 # Run both applications via the startup script CMD ["/bin/bash", "./start.sh"] ``` ### backend/requirements.txt ``` aiohappyeyeballs==2.6.1 aiohttp==3.13.1 aiosignal==1.4.0 annotated-types==0.7.0 anyio==4.11.0 async-timeout==5.0.1 attrs==25.4.0 bech32==1.2.0 certifi==2025.10.5 charset-normalizer==3.4.4 click==8.3.0 cosmpy==0.11.1 distlib==0.4.0 distro==1.9.0 ecdsa==0.19.1 elastic-transport==9.2.0 elasticsearch==9.1.1 exceptiongroup==1.3.0 fastapi==0.119.0 filelock==3.20.0 frozenlist==1.8.0 googleapis-common-protos==1.70.0 groq==0.33.0 grpcio==1.75.1 h11==0.16.0 httpcore==1.0.9 httptools==0.7.1 httpx==0.28.1 idna==3.10 jsonschema==4.25.1 jsonschema-specifications==2025.9.1 multidict==6.7.0 platformdirs==4.5.0 propcache==0.4.1 protobuf==4.25.3 pycryptodome==3.23.0 pydantic==2.12.0 pydantic_core==2.41.1 python-dateutil==2.9.0.post0 python-dotenv==1.1.1 PyYAML==6.0.3 redis==6.4.0 referencing==0.37.0 requests==2.32.5 rpds-py==0.27.1 six==1.17.0 sniffio==1.3.1 sortedcontainers==2.4.0 starlette==0.48.0 typing-inspection==0.4.2 typing_extensions==4.15.0 uagents==0.22.10 uagents-core==0.3.11 urllib3==2.5.0 uvicorn==0.37.0 uvloop==0.22.1 virtualenv==20.35.3 watchfiles==1.1.1 websockets==15.0.1 yarl==1.22.0 ``` ### frontend/package.json ``` { "name": "frontend", "private": true, "version": "0.0.0", "type": "module", "scripts": { "dev": "vite", "build": "tsc -b && vite build", "lint": "eslint .", "preview": "vite preview" }, "dependencies": { "@radix-ui/react-dropdown-menu": "^2.1.16", "@radix-ui/react-icons": "^1.3.2", "@radix-ui/react-slot": "^1.2.3", "@tailwindcss/vite": "^4.1.16", "class-variance-authority": "^0.7.1", "clsx": "^2.1.1", "lucide-react": "^0.548.0", "react": "^19.1.1", "react-dom": "^19.1.1", "react-google-recaptcha": "^3.1.0", "react-router-dom": "^7.9.4", "recharts": "^3.3.0", "tailwind-merge": "^3.3.1", "tailwindcss": "^4.1.16" }, "devDependencies": { "@eslint/js": "^9.36.0", "@types/node": "^24.6.0", "@types/react": "^19.2.2", "@types/react-dom": "^19.2.2", "@vitejs/plugin-react": "^5.0.4", "eslint": "^9.36.0", "eslint-plugin-react-hooks": "^5.2.0", "eslint-plugin-react-refresh": "^0.4.22", "globals": "^16.4.0", "tw-animate-css": "^1.4.0", "typescript": "~5.9.3", "typescript-eslint": "^8.45.0", "vite": "^7.1.7" } } ``` [75 more indexed source files omitted to keep this export small. The full file list is in the Codebase structure section above.]