# Open-Source Agentic Threat Detection & Triage Platform
OpenClue is an automated security engine designed to ingest raw network telemetry and isolate indicators of compromise using local-first LLMs. Modeled after enterprise-grade Network Detection and Response (NDR) platforms, OpenClue uses an iterative self-healing pipeline to verify threats with high fidelity.
## The Core Innovation
OpenClue addresses the semantic weakness of standard reasoning models by wrapping them in a **Deterministic Hardening Gate**.
1. **Passive Ingestion**: Scans raw `tshark`, `tcpdump`, and `syslog` streams directly from the network interface.
2. **Deterministic Pre-Scan**: A Python-based engine establishes ground-truth markers (Absolute Truth) before the AI analyzes the data.
3. **Iterative Self-Healing**: If the AI logic engine misses a critical deterministic threat or provides a contradictory verdict, the backend automatically triggers a correction loop (up to 4 turns) until the audit passes strict semantic validation.
4. **Smart Context Truncation**: Automatically trims multi-hour telemetry streams down to the most critical, recent 15,000-character heartbeat, preventing token limit exhaustion.
## Tools & Tech Stack
* **Frontend Dashboard:** Next.js 14 (App Router), Tailwind CSS, Lucide Icons. Features an industrial monochrome aesthetic.
* **Sensor Node:** Node.js stream processor utilizing local `tshark` binaries for real-time BPF (Berkeley Packet Filter) hardware monitoring.
* **Core Orchestration Engine:** Python 3.12 (Standard Library First) handles deterministic parsing, pipeline routing, and state processing loops.
* **Inference Providers:** Supports local execution (Ollama) and cloud routing (OpenRouter, OpenAI, NVIDIA NIM, Xiaomi MiLM) using highly optimized models (e.g., Llama 3 70B, GPT-4o-mini).
* **Persistence Layer:** Structured Atomic File-System Storage saves state histories and session records locally to preserve privacy.
## OpenAI Codex Workflows
OpenAI Codex and advanced LLM tooling were heavily utilized to architect and accelerate the development of OpenClue:
* **UI Architecture**: Codex was used to generate the complex React state-management required for the multi-step "Investigation Sandbox" wizard, translating industrial design mockups into Tailwind CSS components.
* **Backend Piping**: We utilized Codex to bridge the gap between low-level C-based hardware tools (`tshark`) and high-level Python logic, specifically generating the regex parsing logic and Node.js child-process spawning required to pipe raw hex safely into the engine.
* **Output Structuring**: Codex assisted in building the strict `json_schema` constraints that force the AI to return data that maps perfectly to our visual React topology graph.
## Ideal Customer Profile & Target Audience
**Primary Audience: DevSecOps & Security Analysts**
Junior incident response teams and defensive security developers drowning in unstructured log text. OpenClue compresses their multi-step command-line verification chores into an instantaneous 3-step automated triage matrix.
## Installation & Setup Guide
OpenClue requires low-level access to your network interface card to sniff packets.
### 1. Prerequisites
You must have Wireshark/tshark installed on your machine.
**macOS:**
brew install wireshark
**Ubuntu/Debian:**
sudo apt update
sudo apt install tshark
**Windows:**
Download and install the [Wireshark executable](https://www.wireshark.org/download.html). Ensure `tshark` is added to your system PATH.
### 2. Project Setup
Clone the repository and install dependencies for both the frontend and the local Python engine.
git clone https://github.com/tejasprasad2008-afk/OpenClue.git
cd OpenClue
# Install frontend Node dependencies
npm install
# (Optional) Set up Python virtual environment
python3 -m venv venv
source venv/bin/activate
### 3. Configuration
Duplicate the environment template and add your preferred provider's API key. You only need to provide the key for the service you plan to use.
cp .env.example .env
*(Edit `.env` to include `OPENROUTER_API_KEY`, `NVIDIA_API_KEY`, etc. No key is required for local Ollama usage).*
### 4. Running the Application
You need two terminal windows to run the full Live Sensor suite.
**Terminal 1: Start the Dashboard**
npm run dev
*(Navigate to `http://localhost:3000` in your browser).*
**Terminal 2: Attach the Hardware Sensor**
Find your active network interface (e.g., `en0` for Mac Wi-Fi, `eth0` or `wlan0` for Linux).
sudo node scripts/live-tshark.mjs --interface en0
## Disclaimer
*This project was built for the AI Builders Hackathon. It performs active network inspection. Do not run this tool on enterprise networks without explicit authorization from your network administrator. Use for educational and research purposes only.*
© 2026 OpenClue Platform