clawhatch

clawhatch

Security scanner for OpenClaw AI agents — 100-point audit with auto-fix.

Clawhatch runs 100 automated security checks against your OpenClaw installation, scores it on a 100-point scale (A+ to F), and can auto-fix safe issues. Think of it as npm audit for your AI agent.

Quick Start

npx clawhatch scan

No installation required. Clawhatch auto-detects your OpenClaw installation at ~/.openclaw (or %APPDATA%\openclaw on Windows).

Installation

npm install -g clawhatch

Usage

# Basic scan — auto-detects your OpenClaw config
clawhatch scan

# Scan with workspace files (SOUL.md, skills, markdown)
clawhatch scan --workspace .

# Deep scan — analyze full session logs (slower)
clawhatch scan --deep

# JSON output for scripting and CI
clawhatch scan --json

# HTML report
clawhatch scan --format html

# Auto-fix safe issues (prompts for behavioral changes)
clawhatch scan --fix

# Custom OpenClaw installation path
clawhatch scan --path /custom/path

# Combine flags
clawhatch scan --workspace . --deep --fix

Example Output

  Clawhatch Security Scanner v0.1.0

  Clawhatch Security Scan
  ==================================================

  Security Score: 72/100 (B — Acceptable)

  Platform: win32
  OpenClaw: 1.2.0
  Checks: 100 run, 94 passed, 6 findings
  Duration: 842ms
  Scanned: 14 files

  --------------------------------------------------

  HIGH (2 findings)

  ! Gateway auth token is weak
     Auth token is short or low-entropy (< 32 characters)
     Risk: Weak tokens can be brute-forced
     Fix: Generate a strong token: openssl rand -hex 32

  ! Session logs contain potential secrets
     API keys or tokens detected in session log files
     Risk: Secrets persisted in plaintext logs
     Fix: Enable log sanitization and rotate exposed keys

  MEDIUM (3 findings)

  ~ DM policy set to "open"
     Channel accepts messages from any sender
     Risk: Unauthorized users can interact with the agent
     Fix: Set dmPolicy to "allowlist" and configure allowFrom

  ~ No tool rate limiting configured
     Tool execution has no throttle (tools.rateLimit missing)
     Risk: Rapid tool invocation can spam external APIs
     Fix: Set tools.rateLimit in openclaw.json (e.g., 60)

  ~ Session log retention not configured
     No sessionLogTTL set — logs kept indefinitely
     Risk: Stale data accumulation and potential compliance issues
     Fix: Set retention.sessionLogTTL (e.g., 30 days)

  LOW (1 finding)

  - No health check endpoint configured
     Gateway has no monitoring.enabled setting
     Risk: No automated way to verify agent is running correctly
     Fix: Enable monitoring in openclaw.json

  ==================================================

  3 issue(s) can be auto-fixed. Run with --fix
  Run with --json for machine-readable output
  Run with --deep for thorough session log scanning

What It Checks

Clawhatch runs 100 checks across 10 security categories:

Category	Checks	What It Covers
Identity & Access	15	DM policies, allowlists, pairing config, access groups, OAuth, API key rotation
Network Exposure	10	Gateway binding, auth mode, TLS, trusted proxies, insecure auth flags
Sandbox Configuration	8	Sandbox mode, workspace access, Docker isolation, browser host control
Secret Scanning	10	Hardcoded API keys, .env permissions, secrets in markdown, session log leakage
Model Security	7	Model config, legacy models, injection resistance, SOUL.md analysis, fallback order
Cloud Sync	1	iCloud, OneDrive, Dropbox, Google Drive detection
Tool Security	20	Elevated tools, command injection, Docker socket exposure, audit logging
Skill Security	12	Untrusted sources, dangerous dependencies, native modules, sandboxing
Data Protection	10	PII in logs, retention policies, encryption at rest, log rotation
Operational	7	Logging config, monitoring, git secrets, health checks, dependency staleness

Scoring

Clawhatch uses a 100-point scoring system with severity-based penalties:

Severity	Penalty per finding
Critical	−15 points
High	−8 points
Medium	−3 points
Low	−1 point

Critical cap: Any critical finding hard-caps the score at 40, regardless of calculated total. Fix critical issues first.

Grade Scale

Score	Grade	Label
90–100	A+	Excellent
80–89	A	Good
70–79	B	Acceptable
50–69	C	Needs Work
30–49	D	Poor
0–29	F	Critical

Auto-Fix (--fix)

When you run clawhatch scan --fix, the scanner applies fixes in two tiers:

Safe fixes — applied automatically:

• File permission corrections (e.g., tightening .env to 600)
• Adding secrets to .gitignore
• Generating strong replacement tokens

Behavioral fixes — prompts for confirmation:

• Changing DM policies from "open" to "allowlist"
• Enabling sandbox mode
• Modifying gateway bind addresses

All fixes create timestamped backups (.bak.<timestamp>) before modifying any file.

JSON Export (--json)

clawhatch scan --json > report.json

Outputs a structured ScanResult object:

{
  "timestamp": "2026-02-06T12:00:00.000Z",
  "openclawVersion": "1.2.0",
  "score": 82,
  "findings": [
    {
      "id": "NETWORK-001",
      "severity": "CRITICAL",
      "confidence": "high",
      "category": "Network Exposure",
      "title": "Gateway bound to 0.0.0.0",
      "description": "...",
      "risk": "...",
      "remediation": "...",
      "autoFixable": true,
      "fixType": "behavioral"
    }
  ],
  "suggestions": [],
  "summary": {
    "score": 82,
    "grade": "A",
    "label": "Good",
    "critical": 0,
    "high": 1,
    "medium": 2,
    "low": 0,
    "suggestions": 3,
    "autoFixable": 1
  },
  "filesScanned": 14,
  "checksRun": 100,
  "checksPassed": 97,
  "duration": 1234,
  "platform": "win32"
}

Exit Codes

Code	Meaning
0	Scan passed (no critical findings)
1	Critical findings detected

Findings vs. Suggestions

Clawhatch separates output into two groups:

• Findings (high/medium confidence) — count toward your score and represent actionable security issues.
• Suggestions (low confidence) — informational recommendations that do not affect your score.

CI/CD Integration

GitHub Actions

name: Security Audit
on: [push, pull_request]

jobs:
  clawhatch:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '18'

      - name: Run Clawhatch scan
        run: npx clawhatch scan --workspace . --json > clawhatch-report.json

      - name: Check score
        run: |
          score=$(jq '.score' clawhatch-report.json)
          echo "Security score: $score"
          [ "$score" -ge 50 ] || exit 1

      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: clawhatch-report
          path: clawhatch-report.json

Platform Support

Platform	Status	Notes
Windows	✅ Supported	Full support including %APPDATA%\openclaw detection
Linux	🔄 Coming soon	Core checks work, platform-specific checks in progress
macOS	🔄 Coming soon	Core checks work, platform-specific checks in progress

Other Commands

clawhatch init

Generate a secure baseline OpenClaw configuration:

clawhatch init
clawhatch init --path /custom/path

Creates a hardened openclaw.json and .env template with secure defaults.

Community Threat Intelligence

Clawhatch includes a community threat intelligence network. When you share your scan results, they're anonymized and aggregated to protect everyone:

Share your results

clawhatch scan --share              # Anonymize and share with community
clawhatch scan --upload             # Same as --share

Only check IDs, severity levels, and categories are shared. No file paths, secrets, or descriptions ever leave your machine.

View community threats

clawhatch threats                   # View the community threat feed

Shows the top threats across all users, trending attacks, new advisories, and the community average score.

Subscribe to alerts

clawhatch subscribe --webhook https://discord.com/api/webhooks/...   # Discord
clawhatch subscribe --webhook https://hooks.slack.com/services/...   # Slack
clawhatch subscribe --threshold CRITICAL                             # Only critical alerts

When a new threat is detected across the community, subscribers are notified instantly via their configured webhook.

How it works

• You run clawhatch scan --share
• Findings are stripped to just check IDs + severity (no file paths, no secrets)
• Anonymized report is uploaded to the community feed
• If 45% of users suddenly have NETWORK-001, that's flagged as trending
• Subscribers with that vulnerability get an instant webhook alert

Privacy

• Instance ID is a SHA-256 hash of your hostname -- we never see your actual machine name
• No file paths, descriptions, or secret values are ever transmitted
• You can inspect exactly what's sent with clawhatch scan --json --share

Requirements

• Node.js >= 18.0.0
• OpenClaw installed (auto-detected or specify with --path)

Contributing

Contributions welcome! Please see the GitHub repository for details.

• Fork the repo
• Create a feature branch (git checkout -b feat/my-check)
• Add your checks following the existing pattern in src/checks/
• Run tests: npm test
• Submit a PR

License

MIT © Clawhatch