A production-ready User & Entity Behaviour Analytics (UEBA) engine that ingests multi-source activity logs, builds baselines, detects anomalies, scores risk, and emits SOC-grade alerts via CLI and API interfaces.
Insider threats and credential misuse remain top drivers of security incidents. UEBA platforms model normal behaviour to detect deviations such as privilege abuse, impossible travel, and sudden data exfiltration—accelerating triage for SOC teams.
flowchart TD
A[Log Sources] --> B[Ingestion & Normalisation]
B --> C[Baseline Modelling]
C --> D[Statistical Anomaly Detection]
D --> E[Rule-Based Detectors]
E --> F[Risk Scoring]
F --> G[Reporting / Alerting]
G --> H[API & CLI]
See docs/ARCHITECTURE.md for deeper design notes and component responsibilities.
- Multi-source ingestion: CSV/JSONL logs for login events, file activity, privileged operations, and network/file transfer metadata.
- Behavioural baselines: Rolling aggregation of login hours, file access frequency, data volume, and privilege usage per user.
- Anomaly detection: Statistical deviation checks for login time variance, file access spikes, and geo anomalies.
- Rule-based detectors: Impossible travel, privilege misuse, data exfiltration thresholds, and sensitive resource access.
- Risk engine: Weighted scoring across severity, anomaly count, peer deviation, and identity confidence.
- Reporting: JSON summaries and Markdown case files rendered via Jinja templates.
- Interfaces:
uebactlCLI and FastAPI service with documented endpoints (docs/API.md).
- Python 3.11+
pipandvirtualenv
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt # runtime dependencies
# for contributors
pip install -r requirements-dev.txt- Ingest sample logs and build baselines
uebactl ingest ueba_engine/examples/sample_logs.csv
- Run anomaly detection
uebactl detect ueba_engine/examples/sample_logs.csv
- Generate alerts (JSON or Markdown)
uebactl alerts ueba_engine/examples/sample_logs.csv --format markdown
- Start the API
uvicorn ueba_engine.api.server:app --reload --host 0.0.0.0 --port 8000
Environment overrides:
UEBA_BASELINE_PATH— change where baselines persist for CLI and API.
- Interactive docs:
http://localhost:8000/docs - Reference: docs/API.md
- Example:
curl "http://localhost:8000/alerts?path=ueba_engine/examples/sample_logs.csv"
ueba_engine/ingestion/— log loading and validationueba_engine/analytics/— baselines, anomalies, peer groups, risk scoringueba_engine/detectors/— rule-based detectors (travel, privilege, exfiltration, sensitive access)ueba_engine/reporting/— alert rendering and templatesueba_engine/api/— FastAPI serviceueba_engine/cli/—uebactlCLI entrypointueba_engine/examples/— sample logsueba_engine/tests/— pytest suitedocs/— architecture and API references
- Baseline storage:
.ueba/baselines.json(CLI) and/tmp/ueba_baseline.json(API). Override by adjusting the constructor arguments inBaselineModel. - Risk weights:
RiskSignaldefaults inanalytics/risk_score.py. - Detector thresholds: constructor arguments in each detector (e.g.,
DataExfiltrationDetector(threshold_mb=500)). - Sensitive resources:
RareAccessDetectoraccepts a custom list.
- Logging is enabled across ingestion, analytics, detectors, reporting, CLI, and API layers for traceability.
- Input validation enforces required fields and ISO-8601 timestamps; API surfaces return structured errors for bad requests.
- Minimal dependencies, no embedded secrets, and guidance for responsible disclosure in SECURITY.md.
See docs/OPERATIONS.md for operational runbooks and deployment tips.
pytestDevelopment tooling (configured in pyproject.toml):
ruff check
black .Please review CONTRIBUTING.md and CODE_OF_CONDUCT.md before submitting changes.
Released under the MIT License. See LICENSE.
Built an Insider Threat Detection Engine (UEBA) with behavioural analytics, anomaly detection, risk scoring, and SOC-grade alerting across multi-source activity logs.