home / skills / openclaw / skills / clauditor

clauditor skill

unsafe

This skill monitors filesystem activity and logs tamper-evident evidence to detect and prevent forgery even if the agent is compromised.

npx playbooks add skill openclaw/skills --skill clauditor

Review the files below or copy the command above to add this skill to your agents.

Files (24)

SKILL.md

2.1 KB

---
name: clauditor
description: Tamper-resistant audit watchdog for Clawdbot agents. Detects and logs suspicious filesystem activity with HMAC-chained evidence.
homepage: https://github.com/apollostreetcompany/clauditor
metadata: {"clawdbot":{"emoji":"🛡️","requires":{"bins":["cargo","systemctl"],"os":"linux"}}}
---

# 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`.

Overview

This skill provides a tamper-resistant audit watchdog for Clawdbot agents that detects and logs suspicious filesystem activity with HMAC-chained evidence. It runs as a dedicated system user and creates immutable audit records so a compromised agent cannot erase or forge the trail. The skill includes a guided CLI wizard for step-by-step installation and verification.

How this skill works

The watchdog installs as a system service owned by a separate, non-login user and monitors configured filesystem paths. Events are appended to a log and chained with HMAC digests to make tampering evident; the chain and keys are stored under protected system paths. A CLI wizard drives installation, permission setup, key placement, and provides commands to generate signed digests for external verification.

When to use it

When you need reliable, tamper-evident audit logs for Clawdbot agents.
Before deploying agents to untrusted or semi-trusted environments.
To maintain forensic evidence after a suspected compromise.
When regulators or security policy require immutable audit trails.
During incident response to capture persistent filesystem activity.

Best practices

Install the watchdog using the provided wizard to ensure correct user, permissions, and service setup.
Store the HMAC key on a secure, access-restricted path and back it up securely offline.
Limit watch_paths to relevant directories to reduce noise and storage use.
Run periodic digest generation and export the digest to an external verifier or archive.
Monitor the watchdog service status and configure alerts for unexpected failures.

Example use cases

Deploy alongside Clawdbot agents to ensure activity on critical paths is recorded even if the agent is compromised.
Archival of agent versions and activity for long-term compliance and audit trails.
Incident response teams use the HMAC-chained logs to prove whether records were altered post-compromise.
Automated CI pipelines generate periodic digests and push them to a secure archive for tamper-evident backups.
Security teams restrict log access and use the digest command to create markdown or machine-readable summaries for reporting.

FAQ

How do I install the watchdog?

Use the CLI wizard: run the wizard status/next/verify loop or the quick installer script to create the sysaudit user, configure keys, and enable the service.

Where are logs and keys stored?

Configuration is under /etc/sysaudit/config.toml, the key at /etc/sysaudit/key, and logs at /var/lib/.sysd/.audit/events.log by default; edit config to adjust watch paths and target UID.