sso-manager-node/docs/agents.md

layout, title, nav_order

layout	title	nav_order
default	Theta Agent & Endpoint Management	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.

---

Core Functionality

1. Host Discovery & Inventory

Upon establishing a WebSocket connection, the agent immediately pushes a comprehensive discovery payload:

• Hostname & Network Interfaces: Hostname and all non-loopback IPv4 addresses and MACs.
• Operating System & Kernel: Linux distribution, platform, and kernel version.
• Hardware Specs: CPU model, total RAM (GB), and total root disk capacity (GB).
• Physical Location: Location identifier string (e.g. dc-01-rack-12) configured in agent.yml.

If the agent detects a network IP change, it automatically re-pushes an updated discovery payload to the SSO Manager.

2. Real-Time Telemetry Streaming

Every 30 seconds, the agent streams real-time performance metrics:

• CPU Load: System-wide CPU utilization percentage.
• Memory Utilization: RAM usage percentage and available memory.
• Disk Utilization: Root filesystem usage percentage.
• ZFS Storage Health: Health status of ZFS pools (e.g., ONLINE).
• NVIDIA GPU Load: GPU compute utilization percentage (via nvidia-smi).

---

Local-First Security & Capability Matrix

To protect hosts against unauthorized control, theta-agent enforces a strict, local-first capability matrix defined in /etc/theta42/agent.yml. Central SSO Manager requests are checked against local configuration before execution; permissions cannot be overridden remotely.

Capability	Config Key	Risk Level	Description & Impact
Telemetry	telemetry	Safe	Streams read-only system metrics (CPU, RAM, Disk, ZFS, GPU).
Configure LDAP	configure_ldap	Moderate	Writes updated SSSD configuration to /etc/sssd/sssd.conf & restarts sssd.
Service Control	service_control	High	Restarts systemd services listed in an explicit allowlist (e.g., ["nginx", "docker", "sssd"]).
Reboot	reboot	High	Triggers an immediate system reboot (systemctl reboot).
Arbitrary Bash	arbitrary_bash	Critical	Executes raw bash scripts sent from the SSO Manager as root (used for automated GitOps).

---

High-Risk Command Verification (Protocol v1.1.0)

High-risk management commands (reboot, service_restart, configure_ldap, arbitrary_bash, update_binary) are cryptographically verified using Ed25519 signatures:

1. The SSO Manager canonicalizes the command payload (sorted keys, no whitespace).
2. The payload is signed with the SSO Manager's Ed25519 private key.
3. The Base64 signature is appended to the message payload.
4. The agent verifies the signature against the configured public_key in /etc/theta42/agent.yml before executing the action.

---

Installation & Deployment

Quick One-Liner Install

Run the following command as root on the target Linux host:

curl -fsSL https://<SSO_HOST>/resources/theta-agent/install.sh | sh -s -- --url "https://<SSO_HOST>" --token "<HOST_TOKEN>"

Custom Config Wizard

You can generate a Base64-encoded custom configuration using the Install Agent button on the Directory Management page in the SSO Manager UI:

curl -fsSL https://<SSO_HOST>/resources/theta-agent/install.sh | sh -s -- "<BASE64_ENCODED_CONFIG>"

---

Configuration File Example (/etc/theta42/agent.yml)

# /etc/theta42/agent.yml
server_url: "wss://sso.example.com"
auth_token: "your-unique-host-token"
location: "dc-01-rack-12"
public_key: "MCowBQYDK2VwAyEA..."

capabilities:
  telemetry: true
  configure_ldap: true
  reboot: false
  service_control: ["nginx", "docker", "sssd"]
  arbitrary_bash: false