audit-openclaw-security

Teach the agent to perform a defensive, permissioned security audit of an OpenClaw deployment and produce an actionable report + remediation plan.

OpenClaw is a local-first personal AI assistant with a Gateway control plane, multi-channel inbox, tools (browser/fs/exec/nodes), and optional remote access patterns. The goal of this skill is to reduce attack surface (network + identity), minimise agent permissions, and protect secrets/transcripts.

Scope and safety rules (non-negotiable)

1. Only audit systems you own or have explicit permission to test.
2. Do not request or handle raw secrets. Never ask for:
   • gateway tokens/passwords
   • model API keys / OAuth tokens
   • WhatsApp creds, Slack tokens, Discord tokens, etc.
3. Prefer outputs that are designed to be shareable/redacted:
   • openclaw status --all
   • openclaw security audit --json (and --deep --json)
4. Treat any remote browser control / node pairing as admin-equivalent access and audit accordingly.
5. Default to audit-only. If the user wants remediation, propose changes and get explicit approval before running any:
   • openclaw security audit --fix
   • config edits (openclaw config set, Control UI Config, config.apply / config.patch)
   • firewall edits
   • restarts

What “good” looks like (target posture)

• Gateway binds to loopback unless there is a strong reason otherwise.
• Strong Gateway auth (token/password, rotated) is enabled.
• No public internet exposure (no open security group / port-forward / Tailscale Funnel / accidental reverse proxy bypass).
• DMs require pairing or strict allowlists; group chats require mention-gating.
• Tooling is least-privilege (deny/ask for exec; workspace-only FS; deny control-plane tools on untrusted surfaces).
• Secrets are stored with tight filesystem permissions; logs/transcripts have a retention plan.
• Plugins/skills are explicitly trusted, minimal, and protected from unauthorised modification.

Workflow

Step 0 — Establish context (fast)

Collect just enough context to pick the right audit path:

• Where is OpenClaw running?
  • Mac mini (always-on home host)
  • Personal laptop (macOS/Windows/Linux)
  • Docker (local or on a VM)
  • Cloud host (AWS EC2 / VPS)
• Install type?
  • native install vs Docker Compose vs source checkout
• Do we have local shell access?
  • Claude Code: can run commands directly
  • Claude.ai: user must run commands and paste outputs

Then pick one of these modes:

• Mode A: Assisted self-audit (Claude.ai) — user runs commands/scripts, shares redacted output.
• Mode B: Automated local audit (Claude Code) — run scripts directly and generate a report.

---

Mode A — Assisted self-audit (no local shell access)

Ask the user to run the following on the OpenClaw host and paste results.

If they are worried about sharing output, reassure them that openclaw status --all and openclaw security audit --json are intended to be shareable. If they still refuse, provide high-level hardening guidance without requesting outputs.

1) Collect OpenClaw posture (recommended minimum)

openclaw --version
openclaw status --all
openclaw doctor
openclaw security audit --json
openclaw security audit --deep --json

Helpful extras (for supply-chain + snapshot context):

openclaw health --json
openclaw skills list --eligible --json
openclaw plugins list --json

If the user is comfortable sharing a config for review, prefer targeted reads over full-file sharing:

openclaw config get gateway.bind
openclaw config get gateway.auth.mode
openclaw config get discovery.mdns.mode
openclaw config get session.dmScope

If they must share the full config, remind them OpenClaw config is JSON5 (~/.openclaw/openclaw.json), not strict JSON, and have them use the redaction script:

python3 scripts/redact_openclaw_config.py ~/.openclaw/openclaw.json > openclaw.json5.redacted

2) Collect host/network posture (pick the right block)

macOS (Mac mini / Mac laptop):

whoami
sw_vers
uname -a
lsof -nP -iTCP -sTCP:LISTEN
/usr/libexec/ApplicationFirewall/socketfilterfw --getglobalstate
/usr/libexec/ApplicationFirewall/socketfilterfw --getstealthmode
fdesetup status || true

Linux (EC2/VPS):

whoami
cat /etc/os-release
uname -a
ss -ltnp
sudo ufw status verbose || true
sudo nft list ruleset || true
sudo iptables -S || true

Docker deployments (local or on a VM):

docker ps
# confirm published listeners (should be 127.0.0.1:18789, not 0.0.0.0:18789)
docker port openclaw-gateway 18789 || true
docker compose ps || true

---

Mode B — Automated local audit (Claude Code)

If shell tools are available, run:

bash scripts/collect_openclaw_audit.sh --out ./openclaw-audit
python3 scripts/render_report.py --input ./openclaw-audit --output ./openclaw-security-report.md

Then open openclaw-security-report.md, refine wording, and present the report to the user.

---

Analysis and reporting

Step 1 — Triage findings by severity

Use OpenClaw’s audit output as the source of truth. Prioritise in this order:

1. Anything “open” + tools enabled (lock down DMs/groups first; then tighten tools/sandbox)
2. Public network exposure (LAN bind, Tailscale Funnel, reverse proxy mistakes, missing auth)
3. Browser control / nodes exposure (treat like operator access)
4. File permissions on ~/.openclaw (config/state/credentials)
5. Plugins/extensions + dynamic skill loading (supply chain)
6. Model hygiene + prompt-injection resilience (important, but secondary to access control)

Step 2 — Translate findings into a clear risk narrative

For each finding, capture:

• What was observed (quote checkId + summary; do not paste secrets)
• Why it matters
• Impact (data exfiltration, account takeover, unauthorised actions, persistence)
• Concrete remediation steps
• Verification (usually rerun openclaw security audit --deep)

Step 3 — Recommend a secure baseline configuration (when appropriate)

Offer the baseline in references/openclaw-baseline-config.md as a starting point and adapt based on needs:

• single-user vs shared inbox
• required tools
• remote access method (SSH tunnel / Tailscale Serve)

Step 4 — Platform-specific guidance

Use the platform playbooks:

• references/platform-mac-mini.md
• references/platform-personal-laptop.md
• references/platform-aws-ec2.md
• references/platform-docker.md

---

Deliverable

Produce a Markdown security audit report using assets/report-template.md:

• Executive summary (1–2 paragraphs)
• Environment overview (host type, install type, exposure)
• Findings table (Critical/High/Medium/Low)
• Remediation plan (sequenced)
• Verification steps
• Residual risk + operational practices (patching, token rotation, retention)

---

Common remediation patterns (use with care)

Network exposure

• Prefer Gateway bound to loopback and remote access via SSH tunnel or Tailscale Serve.
• Avoid Tailscale Funnel for the Gateway.
• Never expose the Gateway control UI directly to the public internet.
• If you must run a reverse proxy, configure trusted proxies and block direct access to the Gateway port.

Identity & access

• Use token/password auth; rotate periodically and after any suspected leakage.
• If you need a token generated in automation: openclaw doctor --generate-gateway-token.
• Require DM pairing or strict allowlists.
• In groups, require mention gating; avoid always-on bots in large groups.

Control-plane tools

• The gateway and cron tool surfaces can create persistence (config changes, scheduled jobs). Deny them on any surface that handles untrusted content.

Least privilege tools

• Keep filesystem tools workspace-only.
• Keep exec denied or “ask always” unless the user is present and approving actions.
• Treat browser control like operator access; keep it tailnet/local only.

Secrets, transcripts, and logs

• Tight permissions on ~/.openclaw and ~/.openclaw/openclaw.json.
• Treat session transcripts as sensitive (~/.openclaw/agents/<agentId>/sessions/*.jsonl).
• Gateway logs default under /tmp/openclaw/openclaw-YYYY-MM-DD.log (or logging.file).
• Keep redaction enabled and set a retention/pruning policy.

---

Troubleshooting

“openclaw: command not found”

• Confirm OpenClaw CLI is installed and on PATH.
• If using Windows, prefer WSL2.
• Re-run installation via the official method for your platform; then re-run openclaw --version.

“refusing to bind ... without auth”

• Expected guardrail: non-loopback binds require auth. Do not bypass.

Audit output is empty or inconsistent

• Ensure the Gateway is running: openclaw gateway status
• Re-run with --deep for best-effort live probing.

---

Trigger tests (for skill author)

Should trigger:

• “Can you audit my OpenClaw setup for security?”
• “My OpenClaw gateway is on port 18789 — is that safe?”
• “I deployed OpenClaw on EC2; give me a hardening checklist.”
• “Run openclaw security audit and interpret the results.”
• “I’m running OpenClaw in Docker—how do I lock it down?”

Should NOT trigger:

• General macOS security advice unrelated to OpenClaw
• Generic AWS hardening unrelated to OpenClaw
• Unrelated software audits