Technology

Architecture & technology stack

osctrl is a set of small, focused Go services sharing a common core, backed by PostgreSQL and Redis, with a modern React operator frontend.

Architecture

How the pieces fit together

osquery agents talk to the TLS endpoint. Operators and automation talk to the API. Everything shares one backend.

CLIENTS OSCTRL SERVICES STATE & INTEGRATIONS osquery agents Linux · macOS · Windows Operators Browser UI Automation Scripts · CI · SOAR osctrl-tls osquery remote API Frontend (React SPA) Operator UI osctrl-api REST API · JWT auth osctrl-cli Operator CLI Shared core Go packages (pkg/*) PostgreSQL Redis cache Log destinations Carve storage TLS remote API REST API

The legacy osctrl-admin HTML UI is still shipped but is being replaced by the React frontend.

Components

The services in detail

osctrl-tls

Implements the osquery remote API as a TLS endpoint. This is what your fleet talks to:

  • Node enrollment and configuration retrieval
  • Status and result log ingestion
  • Distributed query read/write, with optional accelerated reads
  • File carving uploads

osctrl-api

REST API service powering the frontend and automation:

  • JWT authentication by default, trusted proxy controls
  • Audit logging of operator actions
  • Authenticated osquery table metadata and sample query/carve libraries
  • Documented with an OpenAPI specification

Operator Frontend Primary UI

React single-page application served alongside the API:

  • Nodes, environments, queries, saved queries, carves, users, settings
  • Node activity views and optional posture data
  • Read-only node console with shell-like commands
  • osquery schema-aware query authoring

osctrl-cli

Command-line interface for operators and automation:

  • Manage environments, nodes, queries, users and settings
  • Works against the REST API, or in direct DB mode
  • Ideal for provisioning, scripting and CI/CD pipelines

osctrl-admin Legacy

The original server-rendered HTML admin interface. Still available, but deprecated in favor of the React frontend, which is the primary operator experience going forward.

Shared core (pkg/*)

All services build on the same Go packages: node state, environments, queries, carves, users and permissions, tags, caching, logging pipeline, audit log, GeoIP and posture ingestion, rate limiting and more.

Stack

Technology choices

Boring, proven infrastructure — chosen for performance and operational simplicity.

LayerTechnologyNotes
Backend services Go (1.26+) Single static binaries per component; fast, concurrent log and query handling.
Operator frontend React 19 · TypeScript · Vite · Tailwind CSS Modern SPA served with the API; Node.js 20+ for development.
Database PostgreSQL Primary datastore for nodes, environments, queries, users and results.
Cache Redis Caching and fast node state for high-throughput fleets.
Endpoint agent osquery Schema metadata shipped through osquery 5.23.1 for query authoring and console .tables.
Deployment Docker · systemd · nginx Docker Compose stack for development; provisioning script and configs for production.
API contract OpenAPI osctrl-api.yaml ships in the repository.
Security

Security-sensitive by design

🔑

Authenticated everything

JWT authentication is the default for the API. Table metadata and sample libraries require authentication too.

🧾

Audit logging

Operator actions are audit-logged, and trusted proxy controls keep client attribution honest behind load balancers.

🛡️

Least-privilege console

The node console is read-only, permission-checked, and scoped to the target node with fresh, active sessions only.

Found a vulnerability? Please follow the responsible disclosure guidelines.

Ready to see it running?

One command with Docker Compose, or deploy natively with the provisioning script.

Get Started Read the Docs