108 lines
4.3 KiB
Markdown
108 lines
4.3 KiB
Markdown
|
# Overlord Lite
|
||
|
|
|
||
|
|
Overlord Lite is a deliberately small Rust agent that proves the Overlord wire
|
||
|
|
protocol works independently of the full Go agent. It supports authenticated
|
||
|
|
server sessions, TLS identity pinning, heartbeats, and reconnection. It does
|
||
|
|
not advertise or execute remote commands beyond its interactive TTY console.
|
||
|
|
|
||
|
|
## Supported
|
||
|
|
|
||
|
|
- Agent-token authentication through `x-agent-token`
|
||
|
|
- TLS 1.3-only encrypted transport, with public-root or pinned self-signed identities
|
||
|
|
- Persistent Ed25519 identity and enrollment challenge signing
|
||
|
|
- MessagePack protocol negotiation
|
||
|
|
- Ping/pong heartbeat and reconnect/server rotation
|
||
|
|
- Interactive TTY console sessions with resize support
|
||
|
|
|
||
|
|
Plugins, desktop, file-manager, audio, webcam, persistence, update,
|
||
|
|
and other full-agent commands are intentionally omitted.
|
||
|
|
|
||
|
|
## Build
|
||
|
|
|
||
|
|
Rust 1.88 or newer is required.
|
||
|
|
|
||
|
|
```text
|
||
|
|
cd Overlord-Lite
|
||
|
|
cargo build --release
|
||
|
|
```
|
||
|
|
|
||
|
|
The output is `target/release/overlord-lite` (`overlord-lite.exe` on Windows).
|
||
|
|
The release profile enables size optimization, LTO, symbol stripping, and
|
||
|
|
abort-on-panic.
|
||
|
|
|
||
|
|
String literals that should not appear in plaintext in the executable can use
|
||
|
|
the local `obfstr!` procedural macro:
|
||
|
|
|
||
|
|
```rust
|
||
|
|
let header = overlord_lite::obfstr!("x-agent-token");
|
||
|
|
```
|
||
|
|
|
||
|
|
The macro encrypts the literal while compiling and returns a decrypted
|
||
|
|
`String` only when the expression runs. Builder-embedded server URLs, agent
|
||
|
|
tokens, build tags, TLS pins, and advertised Lite command names use it
|
||
|
|
automatically. This is binary obfuscation rather than secret storage: because
|
||
|
|
the executable must decrypt its own values, a determined analyst can still
|
||
|
|
recover them at runtime.
|
||
|
|
|
||
|
|
For Build-page integration, install `plugins/rust-lite-builder/rust-lite-builder.zip`
|
||
|
|
through the Plugin Manager. The Agent Type selector will then offer **Rust
|
||
|
|
Lite** and route selected targets through Cargo while retaining normal build
|
||
|
|
permissions, history, downloads, hooks, and file-share upload behavior. Cargo
|
||
|
|
and the requested Rust targets/linkers must be installed on the server host.
|
||
|
|
|
||
|
|
## Run
|
||
|
|
|
||
|
|
Configure the agent with the same token used by the server:
|
||
|
|
|
||
|
|
```powershell
|
||
|
|
$env:OVERLORD_SERVER = "wss://overlord.example.com:5173"
|
||
|
|
$env:OVERLORD_AGENT_TOKEN = "your-agent-token"
|
||
|
|
cargo run --release
|
||
|
|
```
|
||
|
|
|
||
|
|
Multiple servers may be comma-separated. Bare hosts default to `wss://`.
|
||
|
|
|
||
|
|
For a local development server using a self-signed certificate:
|
||
|
|
|
||
|
|
```powershell
|
||
|
|
$env:OVERLORD_SERVER = "wss://localhost:5173"
|
||
|
|
$env:OVERLORD_TLS_INSECURE_SKIP_VERIFY = "true"
|
||
|
|
cargo run
|
||
|
|
```
|
||
|
|
|
||
|
|
Disabling certificate verification also permits plaintext `ws://`. Do not
|
||
|
|
enable it for production deployments.
|
||
|
|
|
||
|
|
Builder-produced binaries automatically embed the server's active TLS SPKI
|
||
|
|
pin, so they securely accept its generated self-signed certificate without the
|
||
|
|
development bypass. For manual builds, `OVERLORD_TLS_SPKI_PINS` accepts one or
|
||
|
|
more comma-separated `sha256/<base64>` public-key pins.
|
||
|
|
|
||
|
|
## Configuration
|
||
|
|
|
||
|
|
| Variable | Default | Purpose |
|
||
|
|
| --- | --- | --- |
|
||
|
|
| `OVERLORD_SERVER` | `wss://127.0.0.1:5173` | One server, or a comma-separated rotation list |
|
||
|
|
| `OVERLORD_AGENT_TOKEN` | empty | Shared server agent token |
|
||
|
|
| `OVERLORD_BUILD_TAG` | compiled build tag | Runtime override for server build attribution |
|
||
|
|
| `OVERLORD_TLS_SPKI_PINS` | compiled server pins | Comma-separated trusted server public-key pins |
|
||
|
|
| `OVERLORD_TLS_INSECURE_SKIP_VERIFY` | `false` | Development-only TLS bypass |
|
||
|
|
| `OVERLORD_LITE_STATE_DIR` | platform state directory | Persistent client ID and Ed25519 seed |
|
||
|
|
| `OVERLORD_RECONNECT_DELAY_MS` | `5000` | Delay between connection attempts |
|
||
|
|
| `OVERLORD_PING_INTERVAL_MS` | `30000` | Application heartbeat interval |
|
||
|
|
|
||
|
|
The identity file is created once as `identity.json`. Keep it private: deleting
|
||
|
|
it creates a new identity that must enroll again.
|
||
|
|
|
||
|
|
The builder compiles `OVERLORD_LITE_DEFAULT_SERVER`,
|
||
|
|
`OVERLORD_LITE_DEFAULT_AGENT_TOKEN`, and `OVERLORD_LITE_DEFAULT_BUILD_TAG` into
|
||
|
|
the binary along with the server's TLS SPKI pins. Their corresponding runtime
|
||
|
|
variables take precedence, so one binary can still be redirected deliberately
|
||
|
|
after deployment.
|
||
|
|
|
||
|
|
## Protocol compatibility
|
||
|
|
|
||
|
|
`build.rs` reads `../protocol/wire-contract.json` during every build and
|
||
|
|
generates the Lite client's protocol version from the canonical contract. The
|
||
|
|
client advertises only the four version 1 console commands it implements.
|