How Umbra works

Umbra is the sensor; DefOpSec is the command center. Together they capture what an attacker does after compromising a honeypot, and give you a replayable record.

On this page

The model

A honeypot is a machine you intend to let attackers compromise. The Umbra agent runs inside that host and records activity at the kernel/OS level, then ships normalized events to the DefOpSec command center. Because the honeypot is meant to be rooted, it runs as an isolated VM — a hardware-virtualization boundary — so a guest-kernel exploit stays in the guest and you can roll back from a snapshot.

1 · Honeypot
Umbra agent captures activity in-host.
2 · Ship
Batched, gzipped NDJSON over HTTPS, authenticated by a per-sensor key.
3 · Collector
Normalizes, correlates into sessions, stores per tenant.
4 · You
Dashboard, live feed, session replay, world map.

Data flow

The agent emits a single event schema regardless of platform. Events batch and upload asynchronously; if the collector is unreachable they spool to disk and drain on recovery, so nothing is lost across a collector restart or a network blip. The sensor's long-lived upload key lives only in /etc/umbra/sensor.key on the honeypot and is never passed on a command line.

What gets captured (per OS)

Linux

eBPF CO-RE (kernel 5.8+ with BTF).

  • Process exec with full argv (tracepoint)
  • Outbound TCP connect — remote IP/port + pid (kprobe)
  • DNS queries (libc getaddrinfo uprobe)
  • Typed commands via a bash readline uprobe — catches builtins and failed commands
  • Session + login-uid correlation

macOS

Apple Endpoint Security (built-in eslogger, no entitlement needed).

  • Process exec + file create/unlink/rename
  • SSH login with attacker source IP + user
  • TCP connect + DNS via libpcap

Windows

ETW (Windows 10/11 & Server 2016+).

  • Process creation (Kernel-Process)
  • DNS client queries
  • Outbound connects (Kernel-Network)
  • Typed PowerShell (ScriptBlock logging)

Enrolling a honeypot

In Sensors → Add sensor you get a one-time enrollment code and a copy-paste line. Run it as root on the honeypot:

curl -fsSL https://<command-center>/install.sh | sudo sh -s -- UMBRA-xxxxxxxx

The installer checks preflight requirements, downloads the matching prebuilt agent and verifies its checksum, asks a short questionnaire (operator, location/region, honeypot kind, what's exposed), redeems the code for the sensor key, and installs a service. The code is single-use and short-lived; the key is generated server-side and returned only to the honeypot — never shown in the browser. The location/region you provide is what places your honeypot on the world map (country-level only).

Sessions & replay

Every exec, connect, DNS lookup and command carries a session id and login-uid, so Umbra ties all of an intrusion's activity to one login and separates it from background daemon noise. The Sessions view lists correlated intrusions (system-only noise hidden by default); opening one gives a chronological, keystroke-level replay timeline.

Isolation & privacy

DefOpSec is multi-tenant: each account sees only its own honeypots and data, enforced on every query by an account id derived from your session — never from anything the browser sends. The public world map shows only country-level aggregate counts and OS mix; it never exposes IPs, sensor names, or which tenant owns a honeypot. Captured attacker strings are always rendered as text, never as HTML, so a hostile payload can't execute in your browser.