feat: initial theta-agent repository structure and security model

2026-08-02 01:33:38 -04:00
commit 7150a6dcd9
7 changed files with 177 additions and 0 deletions
@@ -0,0 +1,44 @@
+# Theta Agent
+
+Theta Agent is a unified endpoint management daemon for the theta42 stack. It replaces legacy bash installation scripts (like `ldap-client`) and one-way metric scripts (`telemetry-agent`) with a powerful, 2-way Command & Control (C2) Go daemon.
+
+The agent dials out to the central SSO Manager via a persistent WebSocket connection, enabling:
+- **Continuous Telemetry:** Streams CPU/RAM/ZFS/GPU health to the central inventory.
+- **Dynamic Discovery:** Automatically updates host IP and metadata on changes.
+- **Remote Operations:** Allows SSO Manager administrators to remotely configure LDAP, restart systemd services, or execute maintenance scripts.
+
+## The Security Model (Blast Radius & Zero-Trust)
+
+Because Theta Agent runs as `root` (required to configure `/etc/sssd/sssd.conf`, restart services, and read hardware sensors), it represents a high-value target. If the central SSO Manager were compromised, a naive agent would allow an attacker to gain root shell execution on every server in the fleet.
+
+To prevent lateral movement and contain the blast radius, **Theta Agent operates on a strict, local-first capability matrix.**
+
+### 1. Local Configuration Wins
+The agent will **only** execute commands that are explicitly enabled in its local configuration file (`/etc/theta/agent.yml`). 
+- By default, the agent is locked down to read-only telemetry and basic LDAP configuration.
+- The central SSO Manager cannot override these settings. An administrator must physically (or via local config management) edit the local `agent.yml` file to grant the agent more permissions.
+
+### 2. The Capability Matrix
+Capabilities are segmented into modules. You only enable what a specific server needs:
+
+| Capability | Risk Level | Description |
+|------------|------------|-------------|
+| `telemetry` | Safe | Read-only. Pushes system metrics back to the SSO Manager. |
+| `configure_ldap` | Moderate | Allows the SSO manager to push down an updated SSSD configuration file. |
+| `reboot` | High | Allows the SSO Manager to trigger a system reboot. |
+| `service_control` | High | Allows starting/stopping/restarting systemd services. **Must be scoped** to specific services (e.g., `['gitea', 'nginx']`). |
+| `arbitrary_bash` | CRITICAL | Allows the execution of raw bash scripts sent from the SSO Manager. Useful for GitOps deployments on worker nodes, but highly dangerous. |
+
+### 3. Outbound-Only Communication
+The agent does not open any listening ports on the host firewall. It uses a long-lived outbound WebSocket connection to the SSO Manager. 
+
+### 4. Cryptographic Authentication
+Every agent is issued a unique, long-lived host token during installation. The SSO Manager verifies this token to ensure commands are only routed to the intended host, and telemetry is properly attributed.
+
+## Example Configuration
+
+See `agent.yml.example` for a secure baseline configuration.
+
+## Installation
+
+*(Coming soon: Build instructions and `theta-agent install` guide)*