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
• 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.

---

---

Architecture

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

Dashboard

• Modern Next.js + shadcn/ui interface with dark mode default
• Real-time updates via GraphQL subscriptions
• Global time range selector, command palette, and keyboard navigation
• Modular components with responsive layout
• Pages: Home, Models, Anomalies, Cases, Data, Entities, Rules, Alerts, Schedules, Settings, Users

Security and Access Control

• JWT authentication with role-based access control (admin, manager, triage, analyst)
• Per-page granular permissions (read/write) configurable by admins
• Persistent notifications system
• Audit logging for compliance

Core Capabilities

• Case management with anomaly linking and timeline
• Anomaly detection result browsing, filtering, and acknowledgment
• Entity management and risk tracking
• Data source management with ingestion status monitoring
• SIEM-agnostic architecture with flexible dataset support
• Integrated LLM assistant for contextual analysis
• Alerting and notification system
• Cron-based scheduling for automated model execution

---

Rule Canvas

OpenUBA includes a visual flow-based rule builder for creating detection logic. Rules compose model outputs with logical operators on an interactive canvas, similar to tools like n8n or Node-RED but purpose-built for security analytics. Analysts can wire together registered models, define threshold conditions, and chain logical gates to express complex detection criteria -- all without writing code.

Each rule's flow graph is serialized deterministically into the database as a structured JSON object, making rules fully reproducible, version-trackable, and auditable. When a rule's conditions are met, it fires an alert that can be linked to anomalies and cases.

---

Model Library

OpenUBA implements a model library and marketplace for hosting "ready-to-use" security models, both developed by the core team and the community. The official model catalog is served from openuba.org/registry/models.json, backed by the openuba-model-hub repository. Developers can also host their own model registries or install models from any GitHub repository or local filesystem.

The library tab in the dashboard lets analysts browse, search, inspect, and install models with a single click. Clicking a model opens a detail modal showing its metadata, parameters, tags, dependencies, and full source code -- fetched directly from GitHub. Installation downloads the model files, verifies their integrity, writes them to the model library on disk, and registers them in PostgreSQL.

Available Models (OpenUBA Hub)

Model	Framework	Description
basic_model	Python	Baseline example model for getting started
model_sklearn	scikit-learn	Isolation Forest anomaly detection
model_pytorch	PyTorch	Neural network-based behavior analysis
model_tensorflow	TensorFlow	Deep learning behavior model
model_keras	Keras	High-level API behavior model
model_networkx	NetworkX	Graph-based entity relationship analysis
model_1	Python	General-purpose analytics model

Model Interface

Models follow a simple Python interface. No heavy SDKs or complex pipeline definitions required -- model authors write straightforward Python logic using familiar libraries:

class Model:
    def train(self, ctx):
        # Train model, return summary
        ...

    def infer(self, ctx):
        # Run inference, return risk scores as DataFrame
        ...

Each model package is a directory containing a MODEL.py, an optional model.yaml manifest, and an optional requirements.txt. The runner handles all I/O, database access, and framework-specific serialization (joblib for sklearn, torch.save for PyTorch, SavedModel for TensorFlow).

Registry Adapters

The model registry uses a pluggable adapter pattern. Each adapter implements model disc