openclaw-doctor

name	openclaw-doctor
description	Security audit for OpenClaw installations — detects malicious skills, credential exposure, invisible injection, and 7 attack surfaces. Use after installing skills, before production deploy, or for periodic security checks.
allowed-tools	["Read","Glob","Grep","Bash"]

OpenClaw Doctor

Read-only security audit for OpenClaw installations. Three phases: SEARCH (find install, enumerate targets) → VERIFY (run modular detection rules) → REPORT (present findings with evidence and fixes).

Covers 7 attack surfaces: skill supply chain (including invisible encoding-layer injection), credential exposure, file permissions, network exposure, instruction integrity, memory poisoning, and persistence mechanisms.

When to Use

• After installing a new OpenClaw skill from ClawHub or any source
• Before deploying an OpenClaw instance to production or exposing it to the network
• Reviewing an existing OpenClaw installation's security posture
• After discovering suspicious agent behavior (unexpected network calls, credential prompts)
• When onboarding to a project that uses OpenClaw
• Periodically as a security hygiene check

When NOT to Use

• Runtime monitoring — this skill runs point-in-time checks, not continuous monitoring
• CI/CD pipeline scanning — use a deterministic CLI tool for reproducible, automated checks
• Enterprise compliance audits — agent output is non-deterministic and cannot produce SARIF/compliance artifacts
• Securing the OpenClaw codebase itself — this audits installations, not source code

Rationalizations to Reject

You MUST NOT accept these excuses to skip or soften findings:

Rationalization	Why It's Wrong
"The skill is popular / has many stars"	ClawHavoc's top malicious skill had 2,000+ installs before discovery
"The API key is only for a free tier"	Free-tier keys enable credential stuffing, lateral movement, and billing fraud
"The config file is only readable by me"	Malicious skills run as YOU — your permissions are their permissions
"I trust this skill author"	12 publisher accounts were compromised in the ClawHavoc campaign
"It's just a local install, not exposed"	CVE-2026-25253 exploits localhost via browser pivot — 1-click RCE
"This looks like a false positive"	Report it anyway with evidence. Let the user decide. Never suppress findings.

Phase 1: SEARCH — Discovery

Find the OpenClaw installation and enumerate all audit targets. Tell the user what you're doing at each step.

Step 1: Locate OpenClaw State Directory

OpenClaw stores its state in a state directory (default: ~/.openclaw/). The config file is openclaw.json inside it.

Search in this order — stop at first match:

# Check environment override first
Bash: echo $OPENCLAW_STATE_DIR
Bash: echo $CLAWDBOT_STATE_DIR

# Check default and legacy state directories
Glob: ~/.openclaw/openclaw.json
Glob: ~/.clawdbot/clawdbot.json
Glob: ~/.moldbot/moldbot.json
Glob: ~/.moltbot/moltbot.json

# Check for explicit config path override
Bash: echo $OPENCLAW_CONFIG_PATH

# Check if running as container or process
Bash: docker ps 2>/dev/null | grep -i openclaw
Bash: ps aux 2>/dev/null | grep -i openclaw | grep -v grep

Use the parent directory of the found config file as the state directory. Tell the user: "Found OpenClaw state directory at: [path]"

If no install found:

1. Tell the user: "I couldn't find an OpenClaw installation in the default locations. Could you provide the path to your OpenClaw state directory?"
2. Help them locate it:
   • "Try: find ~ -name 'openclaw.json' -maxdepth 4 2>/dev/null"
   • "Legacy installs may use ~/.clawdbot/, ~/.moldbot/, or ~/.moltbot/"
   • "Docker: check docker inspect <container> for volume mounts to /home/node/.openclaw"
   • "Or run openclaw config path if the CLI is installed"
3. If user provides a path, use it as state dir and continue
4. If user confirms no install exists, report INFO: "No OpenClaw installation detected" and stop

Step 2: Enumerate Audit Targets

From the state directory, use Glob to find all targets. Run these in parallel:

# Config files (may use legacy names)
Glob: {state_dir}/openclaw.json
Glob: {state_dir}/clawdbot.json
Glob: {state_dir}/moldbot.json
Glob: {state_dir}/moltbot.json

# OAuth / credentials
Glob: {state_dir}/credentials/**/*

# Agent directories (per-agent memory, sessions, config)
Glob: {state_dir}/agents/*/agent/MEMORY.md
Glob: {state_dir}/agents/*/agent/memory/**/*.md

# Skills — multiple possible locations:
# 1. Bundled skills (next to openclaw binary)
Bash: which openclaw 2>/dev/null && ls "$(dirname $(which openclaw))/skills" 2>/dev/null
# 2. Managed/installed skills (ClawHub installs)
Glob: {state_dir}/skills/**/*
# 3. Workspace skills (in project directories)
# Ask user: "Do you have a workspace directory with OpenClaw skills?"

# Environment files
Glob: {state_dir}/.env*
Glob: {state_dir}/../.env*

# Docker config (if applicable)
Glob: {state_dir}/../docker-compose.yml

Key paths to record:

Target	Real Path	Purpose
Main config	{state_dir}/openclaw.json	API keys, gateway settings, agent config
Legacy configs	{state_dir}/clawdbot.json etc.	Same, older naming
OAuth credentials	{state_dir}/credentials/oauth.json	OAuth tokens, session keys
Agent memory	{state_dir}/agents/{id}/agent/MEMORY.md	Persistent agent state
Agent memory dir	{state_dir}/agents/{id}/agent/memory/*.md	Extended memory files
Installed skills	{state_dir}/skills/ or bundled	All installed skills
Environment	.env files near state dir	Environment secrets

Tell the user what was found: "Found X config files, Y agent memory files, Z skills."

If skills directory contains 50+ skills: Tell the user "Large skill directory detected (N skills)." Offer to scan in batches:

• Batch mode: "I'll scan skills in batches of 20. Want me to proceed, or focus on specific skills first?"
• Let the user choose: scan all (batched), scan recently installed only, or scan specific skills by name
• Never skip or sample randomly — malicious skills are often buried among legitimate ones

Phase 2: VERIFY — Detection Rules

Run ALL Always-Check rules. Run Context-Triggered rules when their target files exist.

Progress: Tell the user which rule you're running before each rule. Report findings immediately as discovered.

Always-Check Rules

Read and execute EVERY rule file:

1. ocd-1-credential-patterns — Plaintext secrets in configs, env files, memory
2. ocd-1-file-permissions — Overly permissive file modes on sensitive files

Context-Triggered Rules (run when target files exist)

Skill supply chain (run when skills/ directory exists — apply to EACH skill):

3. ocd-0-skill-prompt-injection — Hidden prompt injection directives
4. ocd-0-skill-suspicious-commands — Malicious shell commands
5. ocd-0-skill-external-urls — Exfiltration/payload download URLs
6. ocd-0-skill-obfuscation — Code obfuscation hiding malicious intent
7. ocd-0-skill-permission-mismatch — Claimed vs actual capability mismatch
8. ocd-0-skill-data-exfil — Access to sensitive local data stores
9. ocd-0-invisible-injection — Unicode tag smuggling, zero-width binary encoding, BIDI overrides, homoglyphs, whitespace steganography

Infrastructure (run when config/Docker/OS targets exist):

10. ocd-0-network-exposure — Gateway bind, ports, auth, Docker mapping
11. ocd-0-instruction-integrity — SOUL.md/AGENTS.md/CLAUDE.md tampering
12. ocd-0-memory-poisoning — Behavioral injection in agent memory
13. ocd-0-persistence-mechanisms — Cron, launchd, systemd, startup scripts

Instruction: Read and execute EVERY linked rule file. For each rule, read the file, then run the detection commands specified within.

User-Requested Checks

After running all built-in rules, ask the user:

"All built-in checks are complete. Do you have any specific concerns you'd like me to investigate? For example:

• A specific skill you're suspicious of (I'll do a deep manual review)
• A specific file or directory to scan
• A custom pattern or keyword to search for
• A CVE you want to check against your installation
• Anything else that feels off about your setup"

If the user provides a custom check:

1. Clarify scope — which files/directories to scan
2. Run the check using Grep, Bash, or Read as appropriate
3. Report findings using the same format as built-in rules, with rule ID OCD-USER-{description}

If the user says no or skips, proceed directly to Phase 3.

Phase 3: REPORT — Findings

After all rules have been checked, present findings to the user.

Finding Format

[SEVERITY] Rule-ID: Title
  File: /path/to/file (line N)
  Evidence: <exact matched content, truncated to 200 chars>
  Risk: <1-sentence explanation of what an attacker could do>
  Fix: <specific remediation action>

Report Structure

1. Summary line: OpenClaw Doctor: X critical, Y high, Z warnings, W info findings
2. Critical findings first, then High, Warning, Info
3. Per-skill grouping for supply chain findings
4. Overall risk assessment:
   • If any CRITICAL → "This installation has critical security issues. Address immediately."
   • If HIGH only → "This installation has significant security risks. Review and remediate."
   • If WARNING only → "This installation has minor security concerns. Consider addressing."
   • If INFO only → "This installation looks healthy. Minor improvements suggested."
   • If no findings → "No security issues detected. Installation looks clean."

Severity Classification

Severity	Criteria	Examples
CRITICAL	Active exploitation likely, immediate data loss risk	Malicious skill, plaintext production API key, reverse shell, prompt injection
HIGH	Significant risk, exploitation requires minor effort	Suspicious commands, credentials in world-readable file, unknown external URLs
WARNING	Elevated risk, not immediately exploitable	JWT in config, file permissions too open, skill with no declared scope
INFO	Best practice recommendation	Suggestion to use env vars, skill with no README