release: v1.32.0 - Subtype Drivers Engine, Explicit Secret Inheritance & App Tokens consolidation
This commit is contained in:
+19
-6
@@ -6,12 +6,25 @@ nav_order: 5
|
||||
|
||||
# Theta Agent & Endpoint Management
|
||||
|
||||
The **Theta Agent** (`theta-agent`) is a unified, 2-way Command & Control (C2)
|
||||
endpoint management daemon written in Go for Linux hosts across your home lab,
|
||||
infrastructure, or data center. It connects outbound via a long-lived WebSocket
|
||||
connection to the central **SSO Manager** (`wss://<sso-host>/api/agent/ws`),
|
||||
enabling real-time host telemetry, automated host discovery, and local-first
|
||||
administrative management.
|
||||
The **Theta Agent** (`theta-agent`) is a unified, 2-way Command & Control (C2) endpoint management daemon written in Go with native cross-platform binaries for **Linux (x86_64, ARM64, ARMv7)**, **Windows (x86_64, ARM64)**, and **macOS (Intel, Apple Silicon M1/M2/M3/M4)**. It connects outbound via a long-lived WebSocket connection to the central **SSO Manager** (`wss://<sso-host>/api/agent/ws`), enabling real-time host telemetry, automated host discovery, and local-first administrative management.
|
||||
|
||||
---
|
||||
|
||||
## Supported Architectures & Operating Systems
|
||||
|
||||
The agent is compiled for 7 target platform binaries with zero external runtime dependencies:
|
||||
|
||||
| Operating System | Architecture | Binary Name | Typical Target Devices |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| **Linux** | `amd64` (x86_64) | `theta-agent-linux-amd64` | Intel/AMD Servers, Cloud VMs, Proxmox Hypervisors |
|
||||
| **Linux** | `arm64` (aarch64) | `theta-agent-linux-arm64` | Raspberry Pi 4/5, Graviton, Ampere Altra |
|
||||
| **Linux** | `armv7` (32-bit ARM) | `theta-agent-linux-armv7` | Raspberry Pi 2/3/Zero 2W, ARM IoT Gateways |
|
||||
| **Windows** | `amd64` (x86_64) | `theta-agent-windows-amd64.exe` | Windows Server, Windows 10/11 Desktop |
|
||||
| **Windows** | `arm64` | `theta-agent-windows-arm64.exe` | Windows on ARM, Surface Pro |
|
||||
| **macOS** | `amd64` | `theta-agent-darwin-amd64` | Intel Macs |
|
||||
| **macOS** | `arm64` | `theta-agent-darwin-arm64` | Apple Silicon Macs (M1/M2/M3/M4) |
|
||||
|
||||
The `install.sh` script automatically detects `uname -s` and `uname -m` to download the exact binary for the host.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -139,6 +139,32 @@ The inventory graph isn't just documentation — other components read it to mak
|
||||
|
||||
Planned consumers (end-user catalog, firewall/DNS generation) and the model/API gaps they need are tracked in [`directory_spec.md`](https://github.com/theta42/sso-manager-node/blob/master/directory_spec.md) §9.
|
||||
|
||||
## Subtype Management & Metrics Drivers Architecture
|
||||
|
||||
The Directory includes a **4-tier Driver Resolution Engine** (`services/driver_registry.js`) that binds a resource's `subType` metadata to specific operational protocols for real-time telemetry, log streaming, and remote lifecycle management:
|
||||
|
||||
1. **Direct Agent Execution** (`ThetaAgentDriver`): Used when a `theta-agent` daemon is connected to the resource (`systemd`, `docker`, `zfs_pool`, `desktop_linux`, `openrc`, `wireguard`).
|
||||
2. **Specialized Subtype Drivers**:
|
||||
- `ProxmoxDriver`: Proxmox VE hypervisors & `lxc` / `kvm` guest controls.
|
||||
- `DockerSocketDriver`: Docker Engine API & `docker_compose` stacks.
|
||||
- `DbDriver`: `postgresql`, `redis`, `openbao_vault`.
|
||||
- `NetworkDriver`: `wireguard`, `unifi_ap`, `unifi_switch`, `pfsense`.
|
||||
- `K8sDriver`: `k8s_pod`, `k8s_deployment`.
|
||||
3. **Ancestor / Hypervisor Provider Fallback**: If an LXC/KVM guest lacks a direct agent, the engine automatically queries its parent Proxmox hypervisor node for VMID telemetry and power controls.
|
||||
4. **Unmanaged Fallback**: Reports unmanaged status cleanly.
|
||||
|
||||
### Subtype Operations API
|
||||
- `GET /api/directory-admin/resources/:id/driver-metrics` — Real-time telemetry payload
|
||||
- `POST /api/directory-admin/resources/:id/driver-action` — Execute management actions (`{ action, params }`)
|
||||
- `GET /api/directory-admin/resources/:id/driver-logs` — Tail operational log output (`?lines=100`)
|
||||
|
||||
## Explicit Secret Inheritance Mode
|
||||
|
||||
Resource secrets stored in OpenBao (`secret/data/resources/<slug>/conf`) use **Explicit Secret Inheritance Mode** with strict upward ancestor lineage:
|
||||
|
||||
- **Strict Ancestor Lineage**: When viewing candidate secrets for inheritance, the dropdown strictly filters to **direct upward ancestors** in the directory hierarchy (Resource $\rightarrow$ Parent Host $\rightarrow$ Cluster $\rightarrow$ Site). Sibling resources across the directory are never exposed.
|
||||
- **Explicit Assignment**: Secret pointers (`INHERIT:<parentSlug>:<parentKey>`) are explicitly saved per resource, guaranteeing precise secret scoping across hosts, LXC/KVM containers, and services.
|
||||
|
||||
## API
|
||||
|
||||
All of the above uses the same admin API the UI does (group `app_sso_directory_admin` or `app_sso_admin`):
|
||||
|
||||
+9
-37
@@ -10,48 +10,20 @@ description: OpenBao-backed personal, shared, and external-app secret storage bu
|
||||
|
||||
The Vault Secrets feature integrates with OpenBao to provide a secure key-value store for your environment. It allows you to store sensitive information like passwords, API keys, and credentials, ensuring they are encrypted and access-controlled.
|
||||
|
||||
## Usage
|
||||
## Location & Access
|
||||
|
||||
You can access the Vault UI from the application's top navigation bar.
|
||||
- **External App Tokens**: Managed under **Configuration** (`/conf` -> **App Tokens** tab). Admins can mint and view periodic OpenBao app tokens scoped to `secret/apps/<name>/*`.
|
||||
- **Resource Secrets**: Managed under **Directory** (`/directory`) inside each resource's modal under the **Secrets** tab. Stored in OpenBao under `secret/data/resources/<slug>/conf`.
|
||||
|
||||
### Creating Secrets
|
||||
## External App Tokens (Admin)
|
||||
|
||||
1. Click on the **New Secret** button.
|
||||
2. Enter a **Secret Path**. This acts as the name/identifier of your secret (e.g., `db-credentials`).
|
||||
3. Enter the **Secret Data** in JSON format. For example:
|
||||
```json
|
||||
{
|
||||
"username": "admin",
|
||||
"password": "supersecretpassword123"
|
||||
}
|
||||
```
|
||||
4. Click **Save Secret**.
|
||||
The **App Tokens** tab in **Configuration** (`/conf`) mints a scoped OpenBao token for an **external application** or script so it can read its own configuration out of OpenBao.
|
||||
|
||||
### Reading and Editing Secrets
|
||||
1. Enter an app **name** (e.g. `build-agent`) and click **Mint token**.
|
||||
2. A token is shown **once** — copy it into the external app now; it cannot be recovered later. The app uses it as the `X-Vault-Token` header against `secret/apps/<name>/*`.
|
||||
3. The **Active App Tokens** list shows every token created (metadata only — the token itself is never stored). sso-manager keeps each token alive by renewing it periodically.
|
||||
|
||||
* To view a secret, click on its name in the **Secrets List**.
|
||||
* To update an existing secret, select it and click the **Edit** button. You can then modify the JSON data and save your changes.
|
||||
|
||||
### OpenBao Integration
|
||||
|
||||
The secrets are stored in a real, initialized-and-unsealed OpenBao backend
|
||||
(`setup.sh` handles init/unseal on first run) — not OpenBao's ephemeral dev
|
||||
mode, which auto-unseals with an in-memory store and loses everything on
|
||||
restart. The default KV (Key-Value) version 2 engine is mounted at `secret/`.
|
||||
The built-in UI proxies through `/api/vault/secret/…`, authenticated the same
|
||||
way as the rest of the app (session cookie or a personal API token) — the
|
||||
server resolves your OpenBao access itself and injects the right scoped
|
||||
token; you never see or handle a raw OpenBao token as a UI user.
|
||||
|
||||
## Apps tab (admin)
|
||||
|
||||
The **Apps** tab mints a scoped OpenBao token for an **external application** so it can read its own configuration out of OpenBao — a downstream-app credential, not a per-user secret.
|
||||
|
||||
1. Enter an app **name** (e.g. `my-service`) and click **Mint token**.
|
||||
2. A token is shown **once** — copy it into the external app now; it cannot be recovered later. The app uses it as the `X-Vault-Token` header against `secret/apps/<name>/*` (see the connection convention shown on the page).
|
||||
3. The **Minted apps** list shows every token you've created (metadata only — the token itself is never stored). sso keeps each token alive by renewing it periodically, so a downstream app's credential stays valid as long as sso runs. If an app shows a **renewal error**, re-mint it here — that revokes the old token and issues a fresh one.
|
||||
|
||||
The token is scoped to `secret/apps/<name>/*` only (policy `app-<name>`), so a compromised token can't touch any other secret.
|
||||
The token is strictly scoped to `secret/apps/<name>/*` (policy `app-<name>`), so a compromised token can't touch any other secret.
|
||||
|
||||
## Shared tab
|
||||
|
||||
|
||||
Reference in New Issue
Block a user