Production-grade MVP for an AI supervisor system that monitors and can block risky actions performed by an external agent (e.g. OpenClaw). ClawBigBrother runs as an independent long-running service and relies on side-channel signals (webhooks, proxy logs, filesystem watcher, optional social gateway) that you control. It does not wrap or modify the OpenClaw agent code.
Goals
Observe — Ingest events from multiple collectors into a unified event schema.
Decide — Evaluate each event with a policy engine (rules-first, optional LLM judge stub).
Intervene — Produce enforcement actions (ALLOW / DENY / HOLD / RATE_LIMIT) and support blocking via an egress proxy decision endpoint and a manual review queue.
Audit — Persist all events, decisions, and evidence hashes into Postgres.
Report — Generate a daily security report summary and expose APIs + minimal UI.
Run forever — Docker Compose–based local deployment with healthchecks, retries, and a worker service.
# Start Postgres + Redis, run migrations, then API + worker
make up
# Or step by step:
docker-compose up -d postgres redis
sleep 5
make migrate
docker-compose up -d clawbigbrother clawbigbrother-worker
API: http://localhost:8000
Docs: http://localhost:8000/docs
Dashboard: http://localhost:8000/ui
Review queue: http://localhost:8000/ui/review
Run locally (no Docker for app)
# Start only Postgres + Redis
docker-compose up -d postgres redis
export CLAWBB_DATABASE_URL=postgresql+asyncpg://clawbb:clawbb@localhost:5432/clawbb
export CLAWBB_REDIS_URL=redis://localhost:6379/0
make migrate
poetry run uvicorn clawbigbrother.main:app --reload --host 0.0.0.0
# In another terminal: run the event consumer (processes events from Redis)
poetry run python -m clawbigbrother.workers.event_consumer
Example requests
See examples/ for curl scripts. Quick sanity check:
Sensitive data: store hashes and redacted previews; avoid storing full sensitive plaintext by default.
Reporting
Daily report job: Aggregates last 24h (counts by outcome, top blocked domains, top policy hits, top actors); stores one row in daily_reports.
API:GET /reports/latest returns the latest report.
Minimal UI
Dashboard:/ui — Totals + last 50 events.
Review queue:/ui/review — Pending items with Approve/Reject (POST forms).
Threat model and safety
ClawBigBrother is designed to supervise an agent you already control (e.g. OpenClaw) using side-channel signals you own. The following principles apply:
Data minimization
Ingest only what is needed for policy and audit (URLs, domains, action types, content hashes, short previews).
Store content_hash and content_preview (length-limited) instead of full body when possible.
Avoid logging or persisting secrets, tokens, or PII in plaintext.
Auditability
Every ingested event and every decision is persisted (events + decisions tables).
Policy versions are hashed and stored (policy_versions) so you can reproduce why a decision was made.
Structured JSON logs (structlog) support trace_id and event_id for correlation.
Least privilege
The service does not execute agent code; it only observes and decides on events.
DB and Redis credentials are configurable and should be restricted in production.
Review queue actions (approve/reject) are explicit and logged.
Safe defaults
Deny by default for high-risk action types (e.g. COMMAND_EXEC denied unless policy explicitly allows).
Blocklist-first for domains; allowlist is optional and configurable.
HOLD for suspicious content (e.g. keyword hits) so a human can review before allowing.
Non-goals
No stealth. The system is an explicit supervisor, not hidden monitoring.
No spying on accounts you don’t control. Assume you have authorization to monitor the agent and the side-channel sources (webhooks, proxy, workspace, social gateway).
No storage of sensitive plaintext by default. Prefer hashes and redacted previews.
Makefile
| Command | Description |
|------------|--------------------------------------|
| make up | Start Postgres, Redis, migrate, API, worker |
| make down| Stop all services |
| make build | Build Docker images |
| make test | Run pytest |
| make fmt | Black + Ruff fix |
| make lint | Ruff + mypy |
| make migrate | Run Alembic upgrade head |
| make examples | Run example curl scripts |