diff --git a/README.md b/README.md index 4fe8c5f8..a23260b2 100644 --- a/README.md +++ b/README.md @@ -12,9 +12,6 @@ Build Status - - Go Report Card -

@@ -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] @@ -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) @@ -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 @@ -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. @@ -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 @@ -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 diff --git a/frontend/README.md b/frontend/README.md index c8e28d57..5ddf7a56 100644 --- a/frontend/README.md +++ b/frontend/README.md @@ -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 @@ -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 @@ -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)