clawarmor 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pinzas AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,163 @@
+<div align="center">
+
+# 🛡 ClawArmor
+
+**The security auditor for OpenClaw agents.**
+
+Checks your config. Probes your live gateway. Scans your skills.  
+Runs in 30 seconds. Finds what config-only tools miss. Free forever.
+
+[![npm version](https://img.shields.io/npm/v/clawarmor?color=3fb950&label=npm&style=flat-square)](https://www.npmjs.com/package/clawarmor)
+[![license](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)
+[![node](https://img.shields.io/badge/node-%3E%3D18-green?style=flat-square)](package.json)
+
+```bash
+npm install -g clawarmor && clawarmor audit
+```
+
+</div>
+
+---
+
+```
+  ℹ  Reads: ~/.openclaw/openclaw.json + file permissions only
+     Network: registry.npmjs.org (version check) + 127.0.0.1:18789 (live probes)
+     Sends nothing. Source: github.com/pinzasai/clawarmor
+
+  ── LIVE GATEWAY PROBES  (connecting to 127.0.0.1) ──
+  ✓ Gateway running on port 18789
+  ✓ Not reachable on network interfaces (probed live)
+  ✓ Authentication required (WebSocket probe confirmed)
+  ✓ /health endpoint does not leak sensitive data
+  ✓ CORS not open to arbitrary origins
+
+  Security Score: 100/100  ┃  Grade: A
+  ████████████████████  100%
+
+  Verdict: Your instance is secure. No issues found.
+
+  ── PASSED (30 checks) ──────────────────────────────
+  ✓ Gateway bound to loopback only
+  ✓ Auth token is strong
+  ✓ Agent sandbox mode: "non-main" (sessions isolated)
+  ✓ Browser SSRF to private networks blocked
+  ✓ All channel allowFrom settings are restricted
+  ... 25 more
+```
+
+---
+
+## Why ClawArmor
+
+Every other OpenClaw security tool reads your config file and tells you if things look right on paper.
+
+**ClawArmor also connects locally to your running gateway and verifies live behavior.**
+
+Config says `bind: loopback`. Is your gateway *actually* unreachable on LAN? Config says auth is enabled. Does the live WebSocket endpoint *actually* reject unauthenticated connections? A misconfigured nginx in front can make your config lie. Live probes can't be faked.
+
+> All probes connect from your machine to `127.0.0.1` (and your local network interfaces). Nothing leaves your machine.
+
+---
+
+## Five commands
+
+```bash
+clawarmor audit     # 30 checks + 5 live gateway probes. Score 0-100. Plain-English verdict.
+clawarmor scan      # Scan every skill file (.js .sh .py .ts SKILL.md) for malicious code.
+clawarmor fix       # Auto-apply safe fixes. --dry-run to preview, --apply to execute.
+clawarmor verify    # Re-run only previously-failed checks. Exit 0 if all fixed (CI-friendly).
+clawarmor trend     # ASCII chart of your security score over time.
+```
+
+---
+
+## What it checks
+
+### Live gateway probes (behavioral — not just config reads)
+
+| Probe | What it checks |
+|---|---|
+| Port reachability | TCP-connects to gateway on every non-loopback interface |
+| Auth enforcement | WebSocket handshake without token — does server reject it? |
+| Health endpoint | GET /health — does response contain config data or secrets? |
+| CORS headers | OPTIONS with `Origin: https://evil.example.com` |
+
+These probes are **read-only and non-destructive**. They observe — they don't modify anything.
+
+### Config audit (30 checks)
+
+Gateway bind · auth mode · token strength · dangerous flags · mDNS exposure · real-IP fallback · trusted proxy config · file permissions (`~/.openclaw/`, `openclaw.json`, `agent-accounts.json`, `credentials/`) · channel allowFrom policies · wildcard detection · group policies · elevated tools · exec sandbox · tool restrictions (filesystem scope, apply_patch scope) · browser SSRF policy · plugin allowlist · log redaction · version currency · webhook security · multi-user trust model
+
+### Skill supply chain scan
+
+Scans **all files** in every installed skill — `.js`, `.ts`, `.sh`, `.py`, `.rb` and `SKILL.md`. Not just markdown.
+
+**Code patterns:** `eval()`, `new Function()`, `child_process`, credential file reads, pipe-to-shell, known exfil domains, large base64 blobs, dynamic `require()`
+
+**SKILL.md instruction patterns:** credential read instructions, system prompt overrides, exfiltration instructions, deception instructions, hardcoded IP fetches
+
+> **Honest limitation:** The scanner catches unsophisticated threats and common patterns. Obfuscated code (string concatenation, encoded payloads) can bypass static analysis. Treat a clean scan as a good signal, not a guarantee.
+
+---
+
+## What it protects against
+
+| Threat | Covered | Notes |
+|---|---|---|
+| T-ACCESS-003: Token/config exposure | ✅ | File permission checks + config hardening |
+| T-PERSIST-001: Malicious skill supply chain | ✅ | All skill files scanned, not just SKILL.md |
+| T-EXEC-001/002: Prompt injection | ❌ | Runtime policy layer — use [SupraWall](https://suprawall.io) |
+| T-EXFIL-001: Data exfiltration | ❌ | Runtime policy layer — use SupraWall |
+
+ClawArmor hardens your configuration and detects supply chain threats. It does not provide runtime policy enforcement — that's a different layer.
+
+---
+
+## Auto-fix
+
+```bash
+clawarmor fix --dry-run   # preview what would change
+clawarmor fix --apply     # apply safe one-liner fixes + gateway restart instructions
+```
+
+Sandbox isolation is enabled safely: if Docker is installed, `fix --apply` sets `sandbox.mode=non-main` + `workspaceAccess=rw` so your Telegram/group sessions keep workspace access.
+
+---
+
+## CI integration
+
+```bash
+# Fail CI if security score drops
+clawarmor verify   # exit 0 = all previously-failed checks now pass
+                   # exit 1 = still failing
+```
+
+Score history persists in `~/.clawarmor/history.json`.
+
+---
+
+## Privacy & security
+
+- `audit`, `scan`, `fix`, `verify`, `trend` run **entirely locally**
+- One optional network call: `registry.npmjs.org` for version check (skippable with `--offline`)
+- Every run prints exactly what files it reads and what network calls it makes before executing
+- Nothing is sent anywhere
+
+**Found a vulnerability in ClawArmor itself?** Please email `pinzasrojas@proton.me` before public disclosure.
+
+---
+
+## Installation
+
+```bash
+npm install -g clawarmor   # requires Node.js 18+
+clawarmor audit
+```
+
+Zero runtime npm dependencies. Node.js built-ins only (`net`, `http`, `os`, `fs`, `crypto`).
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE)

package/SECURITY.md

@@ -0,0 +1,40 @@
+# Security Policy & Ethics Statement
+
+## What ClawArmor scans
+
+**`clawarmor audit`** reads a single file: `~/.openclaw/openclaw.json`. It checks configuration values — bind address, auth mode, file permissions, channel policies. It never reads credentials or sends any data over the network.
+
+**`clawarmor scan`** reads source files in installed skill directories. It runs regex patterns against file content to detect suspicious code. It does not execute any skill code. It never sends file contents anywhere.
+
+**`clawarmor monitor`** is a planned future command. Details TBD.
+
+## What ClawArmor never does
+
+- Sends your config, credentials, or file contents to any server
+- Stores anything on disk beyond what you explicitly configure
+- Executes skill code during scanning
+- Makes outbound network calls during `audit` or `scan` (except: `clawarmor audit` fetches the latest OpenClaw version from the npm registry to check if you're up to date — this is a GET request with no identifying information)
+- Shares scan results with third parties
+
+## Responsible disclosure
+
+ClawArmor is built on research into exposed OpenClaw instances. We follow responsible disclosure principles:
+
+1. We notify owners before publishing any findings about their specific instances
+2. We do not exploit vulnerabilities we discover — we report them
+3. We do not store or log the content of notifications sent to exposed instances
+4. We maintain a public transparency log of notifications sent (IP + timestamp + message hash, no content)
+
+## Reporting vulnerabilities in ClawArmor
+
+If you find a security vulnerability in ClawArmor itself, please email **pinzasrojas@proton.me** before public disclosure. We commit to:
+
+- Acknowledging your report within 48 hours
+- Providing a fix or mitigation within 14 days for critical issues
+- Crediting you in the release notes (if desired)
+
+## False positives
+
+ClawArmor's `scan` command uses static pattern matching. Some findings — particularly in built-in skills — are legitimate uses of flagged patterns (e.g., `spawnSync` in a TTS binary wrapper). Always review findings in context before taking action.
+
+If you believe a pattern produces excessive false positives, please open an issue at github.com/pinzasai/clawarmor.

package/SKILL.md

@@ -0,0 +1,87 @@
+# ClawArmor
+
+Security armor for your OpenClaw agent. Audits your config, probes your live gateway, and scans installed skills for threats.
+
+## When to use this skill
+
+Call `clawarmor` when you want to:
+- Check if your OpenClaw instance is securely configured
+- Verify your live gateway actually requires authentication (not just config)
+- Scan installed skills for malicious code or dangerous instructions
+- Auto-fix common misconfigurations
+- Track your security score over time
+
+## Commands
+
+### Audit (most important — run this first)
+```
+Run: clawarmor audit
+```
+Performs 32 security checks including live behavioral probes of the running gateway. Returns a 0-100 score, letter grade, plain-English verdict, and specific findings with fix commands.
+
+### Scan installed skills
+```
+Run: clawarmor scan
+```
+Scans all installed skill files (.js, .sh, .py, .ts, SKILL.md) for malicious patterns: credential theft, RCE, exfiltration, prompt injection.
+
+### Auto-fix safe issues
+```
+Run: clawarmor fix --dry-run   # preview what would change
+Run: clawarmor fix --apply     # apply safe one-liner fixes
+```
+
+### Verify fixes worked
+```
+Run: clawarmor verify
+```
+Re-runs only previously-failed checks. Exits 0 if all now pass.
+
+### Track score over time
+```
+Run: clawarmor trend
+```
+Shows ASCII chart of score history across all previous audits.
+
+## What it checks
+
+**Live gateway probes** (behavioral — not just config reads):
+- Is the gateway port actually open on non-loopback network interfaces?
+- Does the live WebSocket endpoint reject connections without an auth token?
+- Does the /health endpoint leak sensitive config data?
+- Are CORS headers misconfigured to allow arbitrary origins?
+
+**Config audit** (32 static checks):
+- Gateway bind address, auth mode, token strength
+- File permissions on ~/.openclaw/, openclaw.json, agent-accounts.json, credentials/
+- Channel allowFrom policies — allowlist enforcement, wildcard detection
+- Tool restrictions — filesystem scope, apply_patch scope, elevated tools
+- Sandbox isolation configuration
+- Plugin allowlist enforcement
+- OpenClaw version currency
+- Browser SSRF policy
+- Webhook security
+- mDNS exposure mode
+- Multi-user trust model vs sandbox isolation
+
+**Skill supply chain scan**:
+- Malicious code patterns in .js, .sh, .py, .ts skill scripts
+- Dangerous natural language instructions in SKILL.md files
+- Context-aware severity: built-in skills capped at INFO, user-installed get full severity
+
+## Installation
+
+```
+npm install -g clawarmor
+```
+
+Zero runtime dependencies. Node.js 18+ required. Local only — nothing sent to external servers except one version check to registry.npmjs.org.
+
+Source and full documentation: https://github.com/pinzasai/clawarmor
+
+## Notes
+
+- Run `clawarmor audit` after any config change to verify your security posture
+- The `verify` command is CI-friendly (exit codes: 0 = all fixed, 1 = still failing)
+- Score history is stored at `~/.clawarmor/history.json`
+- This skill does NOT replace runtime policy enforcement (see SupraWall for that)

package/cli.js

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+// ClawArmor v1.1.0 — Security armor for OpenClaw agents
+
+import { paint } from './lib/output/colors.js';
+
+const VERSION = '1.1.0';
+const GATEWAY_PORT_DEFAULT = 18789;
+
+function isLocalhost(host) {
+  return host === '127.0.0.1' || host === 'localhost' || host === '::1';
+}
+
+function parseUrlFlag(urlArg) {
+  // Accepts host:port or plain host (defaults to GATEWAY_PORT_DEFAULT)
+  if (!urlArg) return null;
+  const lastColon = urlArg.lastIndexOf(':');
+  if (lastColon !== -1 && lastColon !== 0) {
+    const maybePort = urlArg.slice(lastColon + 1);
+    if (/^\d+$/.test(maybePort)) {
+      return { host: urlArg.slice(0, lastColon), port: parseInt(maybePort, 10) };
+    }
+  }
+  return { host: urlArg, port: GATEWAY_PORT_DEFAULT };
+}
+
+function trustHeader(port, targetHost) {
+  const isRemote = targetHost && !isLocalhost(targetHost);
+  const probeTarget = targetHost ? `${targetHost}:${port}` : `127.0.0.1:${port}`;
+  console.log('');
+  console.log(`  ${paint.dim('ℹ')}  ${paint.dim('Config: local (~/.openclaw/openclaw.json)')}`);
+  console.log(`     ${paint.dim('Probes: ' + probeTarget + (isRemote ? ' (remote)' : ' (local)'))}`);
+  console.log(`     ${paint.dim('Sends nothing. Source: github.com/pinzasai/clawarmor')}`);
+}
+
+function usage() {
+  console.log('');
+  console.log(`  ${paint.bold('ClawArmor')} ${paint.dim('v'+VERSION)} — Security armor for OpenClaw agents`);
+  console.log('');
+  console.log(`  ${paint.cyan('Usage:')}  clawarmor <command> [flags]`);
+  console.log('');
+  console.log(`  ${paint.bold('Commands:')}`);
+  console.log(`    ${paint.cyan('audit')}    Score your OpenClaw config (0-100), zero false positives`);
+  console.log(`    ${paint.cyan('scan')}     Scan ALL skill files for malicious code + SKILL.md instructions`);
+  console.log(`    ${paint.cyan('verify')}   Re-check only previously-failed items`);
+  console.log(`    ${paint.cyan('trend')}    Show score over last N audits (ASCII chart)`);
+  console.log(`    ${paint.cyan('compare')}  Compare coverage vs openclaw security audit`);
+  console.log(`    ${paint.cyan('fix')}      Auto-apply safe fixes (--dry-run to preview, --apply to run)`);
+  console.log('');
+  console.log(`  ${paint.dim('Flags:')}`);
+  console.log(`    ${paint.dim('--url <host:port>')}   Probe a specific host:port instead of 127.0.0.1`);
+  console.log(`    ${paint.dim('--config <path>')}     Use a specific config file instead of ~/.openclaw/openclaw.json`);
+  console.log(`    ${paint.dim('--json')}              Machine-readable JSON output (audit only)`);
+  console.log(`    ${paint.dim('--explain-reads')}     Print every file read and network call before executing`);
+  console.log('');
+  console.log(`  ${paint.dim('Examples:')}`);
+  console.log(`    ${paint.dim('clawarmor audit')}                         ${paint.dim('# local, default')}`);
+  console.log(`    ${paint.dim('clawarmor audit --url 10.0.0.5:18789')}    ${paint.dim('# probe LAN instance')}`);
+  console.log(`    ${paint.dim('clawarmor audit --url myserver.com:18789')} ${paint.dim('# probe remote (auth warning)')}`);
+  console.log('');
+  console.log(`  ${paint.dim('github.com/pinzasai/clawarmor')}`);
+  console.log('');
+}
+
+const args = process.argv.slice(2);
+const cmd = args[0];
+
+// Parse --url flag
+const urlIdx = args.indexOf('--url');
+const urlArg = urlIdx !== -1 ? args[urlIdx + 1] : null;
+const parsedUrl = parseUrlFlag(urlArg);
+
+// Parse --config flag
+const configIdx = args.indexOf('--config');
+const configPathArg = configIdx !== -1 ? args[configIdx + 1] : null;
+
+const flags = {
+  json: args.includes('--json'),
+  explainReads: args.includes('--explain-reads'),
+  targetHost: parsedUrl?.host || null,
+  targetPort: parsedUrl?.port || null,
+  configPath: configPathArg || null,
+};
+
+if (!cmd || cmd === '--help' || cmd === '-h' || cmd === 'help') { usage(); process.exit(0); }
+if (cmd === '--version' || cmd === '-v') { console.log(VERSION); process.exit(0); }
+
+// Load config once for port info (used in trust header)
+const { loadConfig } = await import('./lib/config.js');
+const { config } = loadConfig(flags.configPath);
+const gatewayPort = flags.targetPort || config?.gateway?.port || GATEWAY_PORT_DEFAULT;
+const targetHost = flags.targetHost || null;
+
+if (flags.explainReads) {
+  const probeTarget = targetHost ? `${targetHost}:${gatewayPort}` : `127.0.0.1:${gatewayPort}`;
+  console.log('');
+  console.log(`  ${paint.cyan('--explain-reads')} — files and network calls this command will make:`);
+  console.log(`    ${paint.dim('Read:')}    ${flags.configPath || '~/.openclaw/openclaw.json'}`);
+  console.log(`    ${paint.dim('Read:')}    ~/.openclaw/agent-accounts.json (permissions only)`);
+  console.log(`    ${paint.dim('Read:')}    ~/.openclaw/ (directory permissions)`);
+  console.log(`    ${paint.dim('Read:')}    ~/.clawarmor/history.json (audit history)`);
+  if (['audit', 'verify'].includes(cmd)) {
+    console.log(`    ${paint.dim('Network:')} ${probeTarget} (TCP/WebSocket/HTTP live probes — gateway only)`);
+  }
+  console.log(`    ${paint.dim('Network:')} registry.npmjs.org (version check)`);
+  console.log('');
+}
+
+// Remote host warning (printed before trust header so it's prominent)
+if (targetHost && !isLocalhost(targetHost)) {
+  console.log('');
+  console.log(`  ${paint.yellow('⚠')}  ${paint.bold('Probing remote host — ensure you have authorization')}`);
+  console.log(`     ${paint.dim('Target: ' + targetHost + ':' + gatewayPort)}`);
+}
+
+// Print trust header before every command (except --json mode)
+if (!flags.json) {
+  trustHeader(gatewayPort, targetHost);
+}
+
+if (cmd === 'audit') {
+  const { runAudit } = await import('./lib/audit.js');
+  process.exit(await runAudit(flags));
+}
+
+if (cmd === 'scan') {
+  const { runScan } = await import('./lib/scan.js');
+  process.exit(await runScan());
+}
+
+if (cmd === 'verify') {
+  const { runVerify } = await import('./lib/verify.js');
+  process.exit(await runVerify());
+}
+
+if (cmd === 'trend') {
+  const idx = args.indexOf('--last');
+  const n = (idx !== -1 && args[idx+1]) ? (parseInt(args[idx+1], 10) || 10) : 10;
+  const { runTrend } = await import('./lib/trend.js');
+  process.exit(await runTrend({ n }));
+}
+
+if (cmd === 'compare') {
+  const { runCompare } = await import('./lib/compare.js');
+  process.exit(await runCompare());
+}
+
+
+if (cmd === 'fix') {
+  const { runFix } = await import('./lib/fix.js');
+  const fixFlags = { apply: process.argv.includes('--apply'), dryRun: process.argv.includes('--dry-run') };
+  process.exit(await runFix(fixFlags));
+}
+
+console.log(`  ${paint.red('✗')} Unknown command: ${paint.bold(cmd)}`);
+usage(); process.exit(1);