<img src="images/mural.jpeg" width="199%" style="float-left" />

Open User Behavior Analytics (v0.0.2)

A robust, flexible, and lightweight open source User & Entity Behavior Analytics (UEBA) framework used for Security Analytics. Developed with luv by Data Scientists & Security Analysts from the Cyber Security Industry.

| Status | Badge | Status | Badge | | --- | --- | --- | --- | | Build | | License | | | Issues | | Closed Issues | | | Pull Requests | | Last Commit | | | Top Language | | Code Size | | | Repo Size | | Contributors | | | Stars | | Forks | | | Releases | | Platform | | | Python | | TypeScript | | | FastAPI | | Next.js | | | PostgreSQL | | Kubernetes | | | Docker | | Spark | | | Elasticsearch | | PRs Welcome | | | Chat | | | |

---

Table of Contents

• Problem
• Solution
• Architecture
• Tech Stack
• Features
• Rule Canvas
• Model Library
• Model Execution Sandbox
• Workspaces & SDK
• Authentication and Access Control
• LLM Assistant
• Getting Started
• Development
• Makefile Reference
• Testing
• White Paper
• Community
• License

---

Problem

Many UBA platforms typically use a "black box" approach to data science practices, which may work best for security analysts who are not interested in the nuts and bolts of the underlying models being used to generate anomalies, baselines, and cases. These platforms view their models as IP.

Solution

OpenUBA takes an "open-model" approach, and is designed for the small subset of security analysts who have authentic curiosity about what models are doing, and how they work under the hood. We believe in the scientific computing community, and its contributions over the years (libraries, toolkits, etc). In security, rule/model transparency is key, for compliance, response/investigation, and decision making.

OpenUBA also makes use of a community-driven marketplace for models, similar to a plugin-store, where plugins are security models. This marketplace is where users of OpenUBA can install security models for their own use cases. Model developers can also upload their models, enabling other users to reuse them, whether for free or compensation -- the choice is up to the model developer to make.

---

<div align="center"> <img src="images/screenshot1.png" width="100%" alt="OpenUBA Dashboard" /> <br /><br /> <a href="https://youtu.be/tMppVt2v1nI?si=kyPrsZvQzHKxLZkf"> <img src="https://img.shields.io/badge/Watch%20Full%20Demo-FF0000?style=for-the-badge&logo=youtube&logoColor=white" alt="Watch Full Demo" /> </a> </div>

---

Architecture

<img src="images/diagram/architecture.svg" width="100%" />

OpenUBA v0.0.2 is a Kubernetes-native platform with a modular, cloud-native architecture. All components are containerized and deployable to a Kind cluster for development or a production Kubernetes cluster. The system is designed to remain lightweight -- no always-on per-model services, no heavy pipeline orchestrators, just the minimum infrastructure needed to run security analytics at scale.

| Layer | Description | | --- | --- | | Frontend | Next.js 14 React application with TailwindCSS, shadcn/ui components, and real-time GraphQL subscriptions | | Backend API | FastAPI application exposing REST endpoints with JWT authentication, model orchestration, rule engine, and scheduling | | GraphQL | PostGraphile auto-generates a full GraphQL API from the PostgreSQL schema, enabling subscriptions and efficient querying | | Operator | Custom Kubernetes operator (Kopf) watches UBATraining and UBAInference CRDs and creates ephemeral Jobs | | Data Layer | PostgreSQL (system of record), Elasticsearch (search/analytics), Apache Spark (distributed compute), backed by Persistent Volumes | | Execution Plane | Ephemeral K8s Jobs using framework-specific Docker images (sklearn, pytorch, tensorflow, networkx) for JIT model training and inference |

---

Tech Stack

Frontend

| Component | Technology | | --- | --- | | Framework | Next.js 14.0.4 (App Router) | | Language | TypeScript 5.3 | | UI System | TailwindCSS 3.4, Radix UI primitives, class-variance-authority | | Data Layer | Apollo Client 3.8 (GraphQL), Axios 1.6 (REST) | | Real-time | GraphQL subscriptions via graphql-ws 5.14 | | Charts | Recharts 3.5 | | Rule Canvas | @xyflow/react 12.10 (flow-based node editor) | | State | Zustand 4.5 (UI state), Apollo cache (server state) | | Markdown | react-markdown 10.1, react-syntax-highlighter 16.1 | | Command Palette | cmdk 0.2 | | Icons | lucide-react 0.309 |

Backend

| Component | Technology | | --- | --- | | Framework | FastAPI 0.104 (Uvicorn 0.24 ASGI) | | Language | Python 3.9 (typed, Pydantic 2.5) | | ORM | SQLAlchemy 2.0.23 | | Auth | JWT (python-jose 3.3), bcrypt via passlib 1.7 | | Scheduling | APScheduler 3.10 | | GraphQL | PostGraphile (auto-schema from PostgreSQL) | | Data Engines | PySpark 3.5, Elasticsearch client 8.11 | | Container Clients | docker-py 6.1, kubernetes-client 28.1 |

Infrastructure

| Component | Technology | | --- | --- | | Database | PostgreSQL 15 (Alpine) | | Search | Elasticsearch 8.11.0 | | Compute | Apache Spark 3.5.0 (Master + Worker) | | Orchestration | Kubernetes (Kind for dev, any cluster for prod) | | Operator | Custom OpenUBA Operator (Kopf, Python) | | Containers | Docker (framework-specific model runner images) | | Node.js Runtime | Node 18 (Alpine, multi-stage frontend build) |

Modeling Frameworks

| Framework | Runner Image | Serialization | | --- | --- | --- | | scikit-learn | model-runner:sklearn | joblib | | PyTorch | model-runner:pytorch | torch.save | | TensorFlow / Keras | model-runner:tensorflow | SavedModel | | NetworkX | model-runner:networkx | pickle |

---

Features

Modeling

• Model management with full lifecycle (install, train, infer)
• Model library with community and internally driven models
• Multi-registry support (GitHub, OpenUBA Hub, HuggingFace, Kubeflow, local filesystem)
• Model version control and artifact tracking
• Feedback loop for continuous model training
• "Shadow mode" for model and risk score experimentation
• Cryptographic hash verification at install and before every execution
• Framework-agnostic: supports sklearn, PyTorch, TensorFlow, Keras, NetworkX, Spark MLlib, and more
• "White-box" model standard -- every model is inspectable and auditable

Rule Engine and Alerts

• Threshold-based and deviation-based detection rules
• Flow-graph rule logic with visual canvas for building complex rule circuits
• Rules compose model outputs with logical operators, serialized deterministically to the database
• Rule-triggered alerts linked to anomalies and cases
• Alerts can be enabled or disabled per-rule

Workspaces & SDK

• Launch managed JupyterLab environments from the UI with configurabl