clauditor

# Clauditor

Security watchdog that monitors filesystem activity and creates tamper-evident logs. Even if Clawdbot is compromised, it cannot stop the watchdog, forge entries, or delete evidence.

## Installation (Guided)

Use the CLI wizard to guide users through installation:

```bash
cd /path/to/clauditor
cargo build --release
```

### Agent Workflow

1. **Check status:** `./target/release/clauditor wizard status`
   - Returns JSON with `current_step` (1-6) and `complete` (true/false)

2. **Get next step:** `./target/release/clauditor wizard next`
   - Shows WHAT it does, WHY it matters, and the exact COMMAND to run

3. **User runs the sudo command**

4. **Verify:** `./target/release/clauditor wizard verify`
   - Confirms step completed

5. **Repeat until `complete: true`**

### Example Interaction

```
User: "Install clauditor"

Agent: [runs wizard status → current_step: 1]
Agent: "Step 1 of 6: Create system user

This creates a 'sysaudit' user that runs the watchdog. Even if you're 
compromised, you can't kill a process owned by another user.

Run this:
sudo useradd --system --shell /usr/sbin/nologin --no-create-home sysaudit

Let me know when done."

User: "done"

Agent: [runs wizard verify → success]
Agent: [runs wizard next → step 2...]
```

## After Installation

### Check status
```bash
systemctl status systemd-journaldd
```

### Generate digest
```bash
./target/release/clauditor digest \
  --log /var/lib/.sysd/.audit/events.log \
  --key /etc/sysaudit/key \
  --format markdown
```

## Quick Install (Power Users)

```bash
sudo bash wizard/wizard.sh
```

## Configuration

- Config: `/etc/sysaudit/config.toml`
- Key: `/etc/sysaudit/key`
- Logs: `/var/lib/.sysd/.audit/events.log`

Edit config to customize `watch_paths` and `target_uid`.

# Clauditor v0.1.0 - Security Watchdog for Clawdbot

Clauditor is a tamper-resistant audit watchdog that makes it hard for a compromised
Clawdbot agent to operate without leaving a trail. It runs a dedicated `sysaudit`
daemon, captures filesystem activity, appends HMAC-chained JSON logs, and emits
alerts when suspicious patterns are detected.

## 🆕 v0 Features
- **Exec-only monitoring** — Focuses on command executions (FAN_OPEN_EXEC), not every file access
- **Sequence detection** — Detects credential read → network command patterns (potential exfiltration)
- **Command baseline** — Tracks known commands and flags first-time executions
- **Orphan exec detection** — Flags commands that run when no Clawdbot session is active
- **Silent digest mode** — Only outputs when issues found (default), use `--verbose` for full report
- **Enhanced reports** — Status badges, severity-sorted alerts, helpful notes
- **Post-install verification** — Wizard validates installation completeness

## Core Features
- Separate `sysaudit` daemon (stealth service name: `systemd-journaldd`)
- Append-only log writer with HMAC hash chaining
- Rule-based detection for exfiltration, injection, persistence, tamper attempts
- Alerting via Clawdbot wake, syslog, file, or command
- Sentinel integrity checks with heartbeat monitoring
- Interactive CLI wizard for guided installation

## Security Model

| Component | Owner | Permissions | Clawdbot Access |
|-----------|-------|-------------|-----------------|
| Daemon | sysaudit | runs as sysaudit user | ❌ Cannot kill |
| HMAC Key | root:sysaudit | 640 | ❌ Cannot read |
| Log Dir | sysaudit:sysaudit | 750 | ❌ Cannot write |
| Logs | sysaudit | 640 | ✅ Can read (tamper-evident) |

**Threat model:** Even if Clawdbot is fully compromised, it cannot:
- Stop the watchdog daemon
- Forge log entries (no key access)
- Delete evidence (no write access to logs)

## Installation

### Option 1: Guided Wizard (Recommended for Clawdbot users)

The CLI wizard guide...