Metadata-Version: 2.4
Name: cryptolabs-sre-agent
Version: 0.1.0
Summary: CryptoLabs SRE reverse-tunnel agent — connects your server to CryptoLabs AI SRE
Author-email: CryptoLabs <support@cryptolabs.co.za>
License-Expression: MIT
Requires-Python: >=3.10
Requires-Dist: aiohttp>=3.9
Requires-Dist: click>=8.1
Requires-Dist: websockets>=12.0
Description-Content-Type: text/markdown

# CryptoLabs SRE Agent

A lightweight reverse-tunnel agent that connects your server to the
[CryptoLabs AI SRE](https://www.cryptolabs.co.za/ai-sre/) investigation
platform — **no SSH keys, no port forwarding, no firewall changes**.

## Quick Start

```bash
# Install (requires Python 3.10+)
pipx install cryptolabs-sre-agent

# Connect using the token from your CryptoLabs SRE dashboard
# Option 1: token file (recommended — not visible in process list)
echo "YOUR_TOKEN" > /etc/sre-agent.token
chmod 600 /etc/sre-agent.token
sudo sre-agent connect --token-file /etc/sre-agent.token

# Option 2: environment variable
export SRE_AGENT_TOKEN="YOUR_TOKEN"
sudo sre-agent connect

# Option 3: CLI flag (token visible in `ps aux` — use for quick testing only)
sudo sre-agent connect --token YOUR_TOKEN
```

## How it Works

1. **Install** — `pipx install cryptolabs-sre-agent`
2. **Run** — `sudo sre-agent connect --token-file /etc/sre-agent.token`
3. The agent opens an outbound WebSocket (`wss://`) to `sre.ai.cryptolabs.co.za`
4. The token links this agent to your registered server on the dashboard
5. Commands are sent by the SRE system, executed locally, results returned

## Security

### Network
- **TLS enforced** — agent refuses non-`wss://` connections in production
- **Outbound only** — no inbound ports opened on your machine
- **Heartbeat timeout** — server drops idle connections after 90s of silence

### Authentication
- **HMAC-SHA256 signed tokens** — cryptographically bound to a single server
- **Token hashed in storage** — only a SHA-256 hash is stored server-side (not the raw token)
- **Rate limiting** — 10 failed auth attempts per IP triggers a 5-minute lockout
- **10-second auth deadline** — connections that don't authenticate are dropped

### Execution Safety
- **Server-side allowlist** — commands are validated by the SRE API's command
  allowlist *before* reaching the agent
- **Agent-side blocklist** — defense-in-depth: the agent independently blocks
  catastrophic commands (`rm -rf /`, `mkfs`, `dd` to disk, fork bombs,
  `halt`/`poweroff`, writes to `/etc/shadow`, `/root/.ssh/authorized_keys`)
- **Output truncation** — stdout/stderr capped at 1 MB per field
- **Concurrent limit** — max 10 commands in parallel to prevent resource exhaustion
- **Command timeout** — every command has a configurable timeout (default 300s)

### Token Handling
- **`--token-file` recommended** — avoids exposing token in process list
- **Environment variable** (`SRE_AGENT_TOKEN`) — alternative to file
- **CLI flag** (`--token`) — agent warns when this is used

### Revocation
- Deleting the server from the dashboard instantly disconnects the agent
- Token revocation via API (`DELETE /agent/token/{server_id}`)
- Agent auto-shuts down when server sends disconnect message

## Environment Variables

| Variable | Description |
|----------|-------------|
| `SRE_AGENT_TOKEN` | Alternative to `--token` flag |
| `SRE_AGENT_TOKEN_FILE` | Alternative to `--token-file` flag |
| `SRE_RELAY_URL` | Override the relay URL (default: `wss://sre.ai.cryptolabs.co.za/agent/ws`) |

## Running as a Service

```bash
# systemd (Linux) — using token file for security
sudo tee /etc/systemd/system/sre-agent.service << 'EOF'
[Unit]
Description=CryptoLabs SRE Agent
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=/root/.local/bin/sre-agent connect --token-file /etc/sre-agent.token
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl enable --now sre-agent
```

## Development

```bash
cd services/sre-agent
pip install -e ".[dev]"
pytest
```
