Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 29 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,9 +12,6 @@
<a href="https://github.com/jmpsec/osctrl">
<img alt="Build Status" src="https://github.com/jmpsec/osctrl/actions/workflows/build_and_test_main_merge.yml/badge.svg?branch=main&fuckgithubcache=1">
</a>
<a href="https://goreportcard.com/report/github.com/jmpsec/osctrl">
<img alt="Go Report Card" src="https://goreportcard.com/badge/github.com/jmpsec/osctrl?style=flat-square&fuckgithubcache=1">
</a>
</p>
</p>

Expand All @@ -28,7 +25,9 @@ With **osctrl** you can:
- 📦 Distribute its configuration fast
- 📊 Collect all the status and result logs
- ⚡ Run on-demand queries
- 🖥️ Open a read-only, shell-like node console backed by osquery
- 🗂️ Carve files and directories
- 🧭 Track node posture, GeoIP country metadata, and node activity in the modern UI
- ⚙️ Scale from **hundreds to hundreds of thousands of nodes**

> [!IMPORTANT]
Expand All @@ -41,6 +40,15 @@ With **osctrl** you can:

Whether you’re running a small deployment or managing large fleets, **osctrl** gives you visibility and control over your osquery endpoints without compromising security or performance.

## ✨ Current Highlights

- **Modern operator UI**: React SPA powered by `osctrl-api`, with views for nodes, environments, queries, saved queries, carves, users, settings, node activity, and optional posture data.
- **Node console**: Read-only console for a specific node using hidden accelerated distributed queries. It supports shell-like commands such as `pwd`, `cd`, `ls`, `stat`, `ps`, `sql`, `osquery`, `.tables`, and `get` for permission-checked file carves.
- **Accelerated distributed queries**: Optional osquery accelerated query reads, defaulting to a 5 second interval when enabled. Console acceleration is scoped to the target node and fresh active console sessions.
- **osquery schema awareness**: Ships osquery table metadata through 5.23.1 and exposes authenticated table metadata to the UI/API for query authoring and console `.tables`.
- **Security-sensitive API defaults**: JWT authentication by default for `osctrl-api`, trusted proxy controls, audit logging, and authenticated access to query/carve sample libraries.
- **Posture and enrichment hooks**: Optional posture ingestion from scheduled query prefixes, optional MaxMind GeoIP country enrichment, and node activity tracking.

## 👉 Documentation

You can find the documentation of the project in [https://osctrl.net](https://osctrl.net)
Expand All @@ -56,16 +64,24 @@ osctrl/
│ └── tls/ # osctrl-tls (osquery remote API endpoint)
├── frontend/ # React SPA frontend for the operator UI
├── pkg/ # Shared application packages
│ ├── activity/ # Node activity tracking
│ ├── auditlog/ # Audit log manager
│ ├── auth/ # Shared auth helpers
│ ├── backend/ # DB manager/bootstrap
│ ├── cache/ # Redis/cache managers
│ ├── carves/ # File carve logic/storage integrations
│ ├── config/ # Config structs/flags/validation
│ ├── console/ # Node console sessions/commands/parser
│ ├── dbutil/ # Database query helpers
│ ├── environments/ # Environment management
│ ├── geoip/ # MaxMind GeoIP enrichment
│ ├── handlers/ # Shared HTTP handlers
│ ├── logging/ # Log pipeline + logger backends
│ ├── nodes/ # Node state/registration/cache
│ ├── osquery/ # osquery schema/table metadata helpers
│ ├── posture/ # Optional posture ingestion and storage
│ ├── queries/ # Query management/scheduling/results
│ ├── ratelimit/ # Rate limiting helpers
│ ├── settings/ # Runtime settings
│ ├── tags/ # Tag management
│ ├── users/ # User and permissions management
Expand Down Expand Up @@ -148,6 +164,14 @@ For frontend-only development details, see [frontend/README.md](./frontend/READM

Ultimately you can just execute `make docker_dev` and it will automagically build and run `osctrl` locally in docker, for development purposes.

### 📦 Runtime and tooling versions

- Go module target: **Go 1.26.3**
- Frontend runtime: **Node.js 20+**
- Frontend stack: **React 19**, **TypeScript 6**, **Vite 8**, **Tailwind CSS 4**
- osquery schema data included through **osquery 5.23.1**
- Default database/cache stack: **PostgreSQL** and **Redis**

### 🤖 Using provisioning script

Using the provided `deploy/provision.sh` script, you can set up a development environment on your local machine. This script will install all necessary dependencies and configure the environment for **osctrl** development in a latest Ubuntu LTS system.
Expand All @@ -158,7 +182,7 @@ Ultimately the script can also be used to deploy **osctrl** in production system

### 🏗 Building from source

To build **osctrl** from source, ensure you have [Go](https://golang.org/dl/) installed (version 1.25 or higher is recommended). Then, clone the repository and run the following commands:
To build **osctrl** from source, ensure you have [Go](https://golang.org/dl/) installed (version 1.26.3 or higher is recommended). Then, clone the repository and run the following commands:

```bash
git clone https://github.com/jmpsec/osctrl.git
Expand All @@ -168,7 +192,7 @@ make

This will compile all the **osctrl** [components](https://osctrl.net/components/) (`osctrl-tls`, `osctrl-admin`, `osctrl-api`, `osctrl-cli`), placing the binaries in the `bin/` directory.

If you are working on the new operator UI, the frontend SPA lives in `frontend/` and is built separately from the Go binaries.
The default `make`/`make build` target also builds the frontend bundle. If you are working on the operator UI directly, the frontend SPA lives in `frontend/` and can be run with `make frontend-dev` or `cd frontend && npm run dev`.

## 💬 Slack

Expand Down
12 changes: 7 additions & 5 deletions frontend/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,8 @@ Talks exclusively to `osctrl-api` (port 8081 by default). Served as static files
## 🤔 What is the frontend?

The **osctrl frontend** is the modern operator UI for managing environments,
nodes, queries, carves, tags, users, and settings through `osctrl-api`.
nodes, node console sessions, queries, saved queries, carves, tags, users,
settings, and optional posture data through `osctrl-api`.

### 🚀 Why it exists

Expand Down Expand Up @@ -54,7 +55,7 @@ frontend/

```bash
# Terminal 1 — osctrl API (Go)
make api-dev # starts osctrl-api on :8081
osctrl-api # start osctrl-api on :8081 for the Vite proxy

# Terminal 2 — React SPA
cd frontend
Expand Down Expand Up @@ -88,13 +89,14 @@ Output: `frontend/dist/`. Deploy options:

## ⚙️ Tech stack

- React 19 + TypeScript 5 (strict)
- Vite 7
- React 19 + TypeScript 6 (strict)
- Vite 8
- TanStack Router (typed routing)
- TanStack Query 5 (server state)
- TanStack Table 8 (headless table)
- Tailwind CSS v4 via `@tailwindcss/vite`
- Radix UI primitives (à la carte)
- react-hook-form 7 + zod 3
- react-hook-form 7 + zod 4
- Monaco Editor
- Vitest + @testing-library/react + jsdom
- Playwright (e2e)
Loading