diff --git a/docs/security/clauditor.md b/docs/security/clauditor.md new file mode 100644 index 000000000..4e4a18685 --- /dev/null +++ b/docs/security/clauditor.md @@ -0,0 +1,105 @@ +--- +summary: "Tamper-resistant audit watchdog for VPS deployments" +read_when: + - You want to detect if your agent is compromised + - You need tamper-evident logging for Clawdbot activity + - You're running Clawdbot on a production VPS +--- +# Clauditor + +Clauditor is a security watchdog that monitors filesystem activity and creates tamper-evident logs. Even if Clawdbot is compromised, it cannot stop the watchdog, forge log entries, or delete evidence. + +**GitHub:** [apollostreetcompany/clauditor](https://github.com/apollostreetcompany/clauditor) +**ClawdHub:** `clawdhub install clauditor` + +## Why Clauditor? + +When you give an AI agent access to your system, you're trusting it not to: +- Exfiltrate sensitive data (credentials, keys, personal files) +- Install persistence mechanisms (cron jobs, SSH keys) +- Cover its tracks by deleting logs + +Clauditor creates an independent audit trail that the agent **cannot tamper with**, even if fully compromised. + +## Security Model + +| Component | Owner | Clawdbot Access | +|-----------|-------|-----------------| +| Daemon | sysaudit user | ❌ Cannot kill | +| HMAC Key | root:sysaudit | ❌ Cannot read | +| Log Directory | sysaudit | ❌ Cannot write | +| Logs | sysaudit | ✅ Can read (tamper-evident) | + +The watchdog runs as a separate system user (`sysaudit`). Even with full control of the `clawdbot` account, an attacker cannot: +- Stop the monitoring daemon +- Forge log entries (no access to HMAC key) +- Delete evidence (no write access to logs) + +## Features + +- **HMAC hash-chained logs** — Any tampering breaks the chain +- **Exec monitoring** — Tracks all command executions +- **Exfiltration detection** — Flags credential reads followed by network commands +- **Baseline tracking** — Alerts on first-time command usage +- **Orphan detection** — Flags commands running when no Clawdbot session is active +- **Digest reports** — Human-readable security summaries + +## Installation + +Clauditor includes an interactive wizard that guides you through installation: + +```bash +# Clone and build +git clone https://github.com/apollostreetcompany/clauditor.git +cd clauditor +cargo build --release + +# Run the wizard (follow prompts) +./target/release/clauditor wizard status +./target/release/clauditor wizard next +# Run the sudo command it shows, then: +./target/release/clauditor wizard verify +# Repeat until complete +``` + +Or use the automated script: + +```bash +sudo bash wizard/wizard.sh +``` + +## Usage + +### Check daemon status +```bash +systemctl status systemd-journaldd +``` + +### Generate security report +```bash +# Silent mode (only outputs if issues found) +clauditor digest --log /var/lib/.sysd/.audit/events.log --key /etc/sysaudit/key + +# Verbose mode (full report) +clauditor digest --log /var/lib/.sysd/.audit/events.log --key /etc/sysaudit/key --verbose +``` + +### Automated daily digest +```bash +# Add to root's crontab +0 6 * * * /usr/local/sbin/systemd-journaldd digest --log /var/lib/.sysd/.audit/events.log --key /etc/sysaudit/key || echo "Anomalies detected" | mail -s "Clauditor Alert" you@example.com +``` + +## Requirements + +- Linux with systemd +- Rust toolchain (for building) +- Root access (for installation) + +## Recommended For + +- **Production VPS deployments** — Where Clawdbot has access to sensitive data +- **Multi-user environments** — Where audit trails matter +- **High-trust setups** — Where you've given Clawdbot elevated permissions + +For local development or sandboxed environments, Clauditor is optional but still useful for understanding agent behavior patterns. diff --git a/docs/vps.md b/docs/vps.md index 08910733f..5c0e5f138 100644 --- a/docs/vps.md +++ b/docs/vps.md @@ -32,6 +32,18 @@ deployments work at a high level. Remote access: [Gateway remote](/gateway/remote) Platforms hub: [Platforms](/platforms) +## Hardening your VPS + +Running Clawdbot on a production VPS? Consider these security measures: + +- **SSH key-only auth** — Disable password authentication +- **fail2ban** — Auto-ban IPs after failed login attempts +- **Clauditor** — Tamper-resistant audit watchdog for agent activity monitoring + +Clauditor creates an independent audit trail that the agent cannot tamper with, even if compromised. It tracks command executions, detects exfiltration patterns, and alerts on suspicious behavior. + +Docs: [Clauditor](/security/clauditor) + ## Using nodes with a VPS You can keep the Gateway in the cloud and pair **nodes** on your local devices