clawarmor 3.1.0 → 3.4.0

package/clawgear-skills/incident-response-playbook/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: incident-response-playbook
+description: Automated incident response for OpenClaw agents. When clawarmor audit finds a CRITICAL or HIGH finding, this playbook quarantines the affected extension, rolls back config to the last known-good snapshot, creates a structured incident log, and sends a Telegram alert. The action layer on top of ClawArmor detection.
+category: security
+tags: [security, incident-response, clawarmor, automation]
+requires: clawarmor >= 3.2.0
+---
+
+# incident-response-playbook
+
+ClawArmor detects security issues. This skill responds to them. Automatically.
+
+When a CRITICAL finding is detected, the playbook:
+1. **Quarantines** the affected extension
+2. **Rolls back** config to the last known-good snapshot
+3. **Creates a structured incident log** via `clawarmor incident create`
+4. **Sends a Telegram alert** via `openclaw system event`
+
+Designed to run from your HEARTBEAT.md so it fires automatically on every cycle.
+
+---
+
+## Scripts
+
+### `quarantine.sh`
+
+Disables a named extension and restarts the gateway.
+
+```bash
+#!/usr/bin/env bash
+# quarantine.sh — disable an extension immediately
+# Usage: bash quarantine.sh <extension-name>
+# requires: elevated
+
+EXTENSION="$1"
+
+if [ -z "$EXTENSION" ]; then
+  echo "Usage: bash quarantine.sh <extension-name>"
+  exit 1
+fi
+
+echo "[quarantine] Disabling extension: $EXTENSION"
+openclaw config set "extensions.${EXTENSION}.disabled" true
+openclaw gateway restart
+
+echo "[quarantine] Extension '$EXTENSION' quarantined. Gateway restarted."
+```
+
+### `respond.sh`
+
+Full automated incident response: rollback, incident log, Telegram alert.
+
+```bash
+#!/usr/bin/env bash
+# respond.sh — full incident response for a security finding
+# Usage: bash respond.sh "<finding-description>" <CRITICAL|HIGH|MEDIUM>
+# requires: clawarmor >= 3.2.0, elevated
+
+FINDING="$1"
+SEVERITY="${2:-CRITICAL}"
+
+if [ -z "$FINDING" ]; then
+  echo "Usage: bash respond.sh \"<finding-description>\" <CRITICAL|HIGH|MEDIUM>"
+  exit 1
+fi
+
+echo ""
+echo "[respond] Incident Response Triggered"
+echo "[respond] Finding: $FINDING"
+echo "[respond] Severity: $SEVERITY"
+echo ""
+
+# Step 1: Rollback config
+echo "[respond] Rolling back to last known-good snapshot..."
+ROLLBACK_OUTPUT=$(clawarmor rollback 2>&1)
+ROLLBACK_STATUS=$?
+
+if [ $ROLLBACK_STATUS -ne 0 ]; then
+  echo "[respond] WARNING: Rollback failed or no snapshots available."
+  echo "[respond] Operator must review config manually."
+  ROLLBACK_NOTE="Rollback failed — manual review required"
+else
+  echo "[respond] Config rolled back."
+  ROLLBACK_NOTE="Config rolled back via clawarmor rollback"
+fi
+
+# Step 2: Create incident log
+echo "[respond] Creating incident log..."
+INCIDENT_FILE=$(clawarmor incident create \
+  --finding "$FINDING" \
+  --severity "$SEVERITY" \
+  --action rollback \
+  2>&1 | grep "File:" | awk '{print $2}')
+echo "[respond] Incident logged: ${INCIDENT_FILE:-unknown}"
+
+# Step 3: Send Telegram alert
+echo "[respond] Sending alert..."
+openclaw system event \
+  --text "🚨 Security Incident: $FINDING (Severity: $SEVERITY) — Config rolled back. Check: clawarmor incident list" \
+  --mode now
+
+echo ""
+echo "[respond] Done. Incident response complete."
+echo ""
+```
+
+### `check-and-respond.sh`
+
+Runs `clawarmor audit --json`, finds CRITICAL findings, auto-triggers `respond.sh` for each.
+
+```bash
+#!/usr/bin/env bash
+# check-and-respond.sh — auto-respond to new CRITICAL findings
+# Add to HEARTBEAT.md to run automatically on every cycle
+# requires: clawarmor >= 3.2.0, elevated
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+echo "[check-and-respond] Running security audit..."
+AUDIT_JSON=$(clawarmor audit --json 2>/dev/null || echo '{"failed":[]}')
+
+# Extract CRITICAL findings
+CRITICALS=$(echo "$AUDIT_JSON" | python3 -c "
+import sys, json
+d = json.load(sys.stdin)
+failed = d.get('failed', [])
+for f in failed:
+    if f.get('severity') == 'CRITICAL' and not f.get('_profileExpected'):
+        print(f.get('title', f.get('id', 'Unknown finding')))
+" 2>/dev/null)
+
+if [ -z "$CRITICALS" ]; then
+  echo "[check-and-respond] No CRITICAL findings. Posture clean."
+  exit 0
+fi
+
+echo "[check-and-respond] CRITICAL findings detected — triggering response..."
+echo ""
+
+while IFS= read -r finding; do
+  if [ -n "$finding" ]; then
+    echo "[check-and-respond] Responding to: $finding"
+    bash "$SCRIPT_DIR/respond.sh" "$finding" "CRITICAL"
+  fi
+done <<< "$CRITICALS"
+
+echo "[check-and-respond] All findings processed."
+```
+
+---
+
+## Heartbeat integration
+
+Add this to your `HEARTBEAT.md` to auto-respond to new CRITICAL findings on every cycle:
+
+```markdown
+## Security Incident Response
+
+Run bash check-and-respond.sh from skills/incident-response-playbook/ — automatically respond to any CRITICAL security findings found during audit.
+```
+
+---
+
+## Manual usage
+
+```bash
+# Respond to a specific finding manually
+bash ~/.openclaw/workspace/skills/incident-response-playbook/respond.sh \
+  "Malicious skill detected: bad-skill-v2" \
+  CRITICAL
+
+# Quarantine a specific extension
+bash ~/.openclaw/workspace/skills/incident-response-playbook/quarantine.sh \
+  bad-extension-name
+
+# Run audit and auto-respond to everything critical
+bash ~/.openclaw/workspace/skills/incident-response-playbook/check-and-respond.sh
+```
+
+---
+
+## Notes
+
+- **Rollback** uses ClawArmor's snapshot system (`clawarmor rollback`). If no snapshot exists (e.g., hardening was never run), rollback is skipped and the operator is alerted to review manually
+- **Quarantine** requires `openclaw config set` and `openclaw gateway restart` to be available — these are standard OpenClaw commands
+- **Telegram delivery** requires `openclaw system event` to be configured with a Telegram channel
+- The `--action rollback` flag on `clawarmor incident create` also triggers rollback automatically — `respond.sh` calls both for belt-and-suspenders reliability
+- Requires clawarmor 3.2.0+ for `clawarmor incident` and `clawarmor audit --json`
+- The scripts use `set -e` for fail-fast behavior — if any step errors, the script exits immediately. Check logs if a step is skipped unexpectedly

package/clawgear-skills/skill-security-scanner/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: skill-security-scanner
+description: Pre-install security gate for OpenClaw skills. Before installing any skill from ClawHub or ClawMart, run this scanner. Uses clawarmor scan --json to check for obfuscation, malicious patterns, and credential exposure. Blocks installs that score BLOCK verdict.
+category: security
+tags: [security, skills, pre-install, scanning, clawarmor]
+requires: clawarmor >= 3.2.0
+---
+
+# skill-security-scanner
+
+A security gate that sits between you and any skill you're about to install. Before an untrusted skill hits your agent, run it through this scanner. BLOCK verdict means don't install. WARN means review first.
+
+## The problem it solves
+
+In early 2026, a malicious skill called `openclaw-web-search` was distributed on a third-party registry. It appeared functional but contained an obfuscated payload that sent session tokens to an attacker-controlled DNS server. It was installed by dozens of operators without inspection.
+
+This scanner would have caught it. The obfuscation patterns and DNS module import are both CRITICAL-severity matches in ClawArmor's pattern library.
+
+**Never install a skill without scanning it first.**
+
+---
+
+## Scripts
+
+### `scan-gate.sh`
+
+The main gate script. Takes a skill directory path as argument.
+
+```bash
+#!/usr/bin/env bash
+# scan-gate.sh — pre-install security gate for OpenClaw skills
+# Usage: bash scan-gate.sh <skill-path>
+# Exit: 0=safe, 1=warn (manual review), 2=blocked
+
+set -e
+
+SKILL_PATH="$1"
+
+if [ -z "$SKILL_PATH" ]; then
+  echo "Usage: bash scan-gate.sh <skill-path>"
+  exit 1
+fi
+
+if [ ! -d "$SKILL_PATH" ]; then
+  echo "Error: directory not found: $SKILL_PATH"
+  exit 1
+fi
+
+echo "[scan-gate] Scanning: $SKILL_PATH"
+
+# Run clawarmor scan --json and capture output
+SCAN_JSON=$(clawarmor scan --json 2>/dev/null || echo '{"verdict":"BLOCK","score":0,"findings":[]}')
+
+VERDICT=$(echo "$SCAN_JSON" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('verdict','BLOCK'))")
+SCORE=$(echo "$SCAN_JSON" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('score',0))")
+FINDINGS=$(echo "$SCAN_JSON" | python3 -c "import sys,json; d=json.load(sys.stdin); print(len(d.get('findings',[])))")
+
+echo "[scan-gate] Verdict: $VERDICT | Score: $SCORE | Findings: $FINDINGS"
+
+if [ "$VERDICT" = "BLOCK" ]; then
+  echo ""
+  echo "❌ BLOCKED — skill has CRITICAL findings and must not be installed."
+  echo ""
+  echo "$SCAN_JSON" | python3 -c "
+import sys, json
+d = json.load(sys.stdin)
+for f in d.get('findings', []):
+    if f.get('severity') in ('CRITICAL', 'HIGH'):
+        print(f\"  [{f['severity']}] {f.get('skill','?')} — {f.get('message','')}\")
+"
+  echo ""
+  # Log to registry
+  bash "$(dirname "$0")/scan-registry.sh" "$SKILL_PATH" "$SCAN_JSON"
+  exit 2
+fi
+
+if [ "$VERDICT" = "WARN" ]; then
+  echo ""
+  echo "⚠️  WARNING — skill has HIGH findings. Review before installing."
+  echo ""
+  echo "$SCAN_JSON" | python3 -c "
+import sys, json
+d = json.load(sys.stdin)
+for f in d.get('findings', []):
+    print(f\"  [{f['severity']}] {f.get('skill','?')} — {f.get('message','')}\")
+"
+  echo ""
+  read -p "Install anyway? [y/N] " confirm
+  if [ "$confirm" != "y" ] && [ "$confirm" != "Y" ]; then
+    echo "Aborted."
+    bash "$(dirname "$0")/scan-registry.sh" "$SKILL_PATH" "$SCAN_JSON"
+    exit 1
+  fi
+fi
+
+echo ""
+echo "✅ PASS — skill cleared for install."
+bash "$(dirname "$0")/scan-registry.sh" "$SKILL_PATH" "$SCAN_JSON"
+exit 0
+```
+
+### `scan-registry.sh`
+
+Logs all scan results to a JSONL registry for audit trail.
+
+```bash
+#!/usr/bin/env bash
+# scan-registry.sh — log scan results to registry
+# Usage: bash scan-registry.sh <skill-path> <scan-json>
+
+SKILL_PATH="$1"
+SCAN_JSON="$2"
+REGISTRY="$HOME/.openclaw/workspace/memory/skill-scan-registry.jsonl"
+
+mkdir -p "$(dirname "$REGISTRY")"
+
+ENTRY=$(echo "$SCAN_JSON" | python3 -c "
+import sys, json
+d = json.load(sys.stdin)
+import datetime
+d['skillPath'] = '$SKILL_PATH'
+d['loggedAt'] = datetime.datetime.utcnow().isoformat() + 'Z'
+print(json.dumps(d))
+" 2>/dev/null || echo '{}')
+
+echo "$ENTRY" >> "$REGISTRY"
+echo "[scan-registry] Logged to $REGISTRY"
+```
+
+---
+
+## Usage
+
+```bash
+# Before installing a skill:
+bash ~/.openclaw/workspace/skills/skill-security-scanner/scan-gate.sh \
+  ~/.openclaw/workspace/skills/some-skill/
+
+# If it exits 0 (PASS), safe to proceed with install
+# If it exits 1 (WARN), review findings then decide
+# If it exits 2 (BLOCK), do not install
+```
+
+### In a CI/CD pipeline
+
+```bash
+# Fail pipeline if skill doesn't pass scan
+bash scan-gate.sh ./my-new-skill/
+if [ $? -eq 2 ]; then
+  echo "Skill failed security scan — aborting deploy"
+  exit 1
+fi
+```
+
+---
+
+## Trust levels
+
+Even WARN skills from known sources (clawhub.com, shopclawmart.com) should be reviewed. The source of a skill doesn't guarantee its safety — supply chain attacks compromise trusted publishers too.
+
+The only safe default is: **scan everything, trust nothing unverified**.
+
+---
+
+## Notes
+
+- Requires clawarmor 3.2.0+ for `scan --json`
+- The registry at `~/.openclaw/workspace/memory/skill-scan-registry.jsonl` provides a complete audit trail of all scanned skills
+- BLOCK = CRITICAL findings — patterns like eval, child_process with network, obfuscated code
+- WARN = HIGH findings — patterns like credential file reads, WebSocket usage, cleartext HTTP

package/cli.js

@@ -3,7 +3,7 @@
 
 import { paint } from './lib/output/colors.js';
 
-const VERSION = '3.1.0';
+const VERSION = '3.4.0';
 const GATEWAY_PORT_DEFAULT = 18789;
 
 function isLocalhost(host) {
@@ -51,7 +51,11 @@ function usage() {
   console.log(`    ${paint.cyan('watch')}    Monitor config and skill changes in real time`);
   console.log(`    ${paint.cyan('protect')}  Install/uninstall/status the full guard system`);
   console.log(`    ${paint.cyan('prescan')}  Pre-scan a skill before installing it`);
+  console.log(`    ${paint.cyan('baseline')}      Save, list, and diff security baselines (save|list|diff)`);
+  console.log(`    ${paint.cyan('incident')}      Log and manage security incidents (create|list)`);
   console.log(`    ${paint.cyan('stack')}         Security orchestrator — deploy Invariant + IronCurtain from audit data`);
+  console.log(`    ${paint.cyan('invariant')}      Invariant deep integration — sync findings → runtime policies (v3.3.0)`);
+  console.log(`    ${paint.cyan('skill')}         Skill utilities — verify a skill directory (skill verify <dir>)`);
   console.log(`    ${paint.cyan('skill-report')}  Show post-install audit impact of last skill install`);
   console.log(`    ${paint.cyan('profile')}       Manage contextual hardening profiles`);
   console.log(`    ${paint.cyan('log')}            View the audit event log`);
@@ -60,7 +64,7 @@ function usage() {
   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('--json')}              Machine-readable JSON output (audit, scan)`);
   console.log(`    ${paint.dim('--explain-reads')}     Print every file read and network call before executing
     ${paint.dim('--accept-changes')}    Update config baseline after reviewing detected changes`);
   console.log('');
@@ -141,7 +145,7 @@ if (cmd === 'audit') {
 
 if (cmd === 'scan') {
   const { runScan } = await import('./lib/scan.js');
-  process.exit(await runScan());
+  process.exit(await runScan({ json: flags.json }));
 }
 
 if (cmd === 'verify') {
@@ -208,6 +212,12 @@ if (cmd === 'log') {
 
 if (cmd === 'harden') {
   const hardenProfileIdx = args.indexOf('--profile');
+  const reportIdx = args.indexOf('--report');
+  const reportFormatIdx = args.indexOf('--report-format');
+  // --report can be a flag alone or --report <path>
+  const reportNext = reportIdx !== -1 ? args[reportIdx + 1] : null;
+  const reportPath = (reportNext && !reportNext.startsWith('--')) ? reportNext : null;
+  const reportFormat = reportFormatIdx !== -1 ? (args[reportFormatIdx + 1] || 'json') : 'json';
   const hardenFlags = {
     dryRun: args.includes('--dry-run'),
     auto: args.includes('--auto'),
@@ -216,6 +226,9 @@ if (cmd === 'harden') {
     monitorReport: args.includes('--monitor-report'),
     monitorOff: args.includes('--monitor-off'),
     profile: hardenProfileIdx !== -1 ? args[hardenProfileIdx + 1] : null,
+    report: reportIdx !== -1,
+    reportPath: reportPath,
+    reportFormat: reportFormat,
   };
   const { runHarden } = await import('./lib/harden.js');
   process.exit(await runHarden(hardenFlags));
@@ -259,5 +272,54 @@ if (cmd === 'profile') {
   process.exit(await runProfileCmd(profileArgs));
 }
 
+if (cmd === 'baseline') {
+  const { runBaseline } = await import('./lib/baseline-cmd.js');
+  const baselineArgs = args.slice(1);
+  process.exit(await runBaseline(baselineArgs));
+}
+
+if (cmd === 'incident') {
+  const { runIncident } = await import('./lib/incident-cmd.js');
+  const incidentArgs = args.slice(1);
+  process.exit(await runIncident(incidentArgs));
+}
+
+if (cmd === 'skill') {
+  const sub = args[1];
+  if (sub === 'verify') {
+    const skillDir = args[2];
+    const { runSkillVerify } = await import('./lib/skill-verify.js');
+    process.exit(await runSkillVerify(skillDir));
+  }
+  console.log(`  ${paint.dim('Usage:')} clawarmor skill verify <skill-dir>`);
+  process.exit(1);
+}
+
+
+if (cmd === 'invariant') {
+  const sub = args[1];
+  const invArgs = args.slice(2);
+
+  if (!sub || sub === 'status') {
+    const { runInvariantStatus } = await import('./lib/invariant-sync.js');
+    process.exit(await runInvariantStatus());
+  }
+
+  if (sub === 'sync') {
+    const { runInvariantSync } = await import('./lib/invariant-sync.js');
+    process.exit(await runInvariantSync(invArgs));
+  }
+
+  console.log('');
+  console.log(`  Invariant subcommands:`);
+  console.log(`    clawarmor invariant status              # show policy + last sync`);
+  console.log(`    clawarmor invariant sync                # generate policies from latest audit`);
+  console.log(`    clawarmor invariant sync --dry-run      # preview without writing`);
+  console.log(`    clawarmor invariant sync --push         # generate + push to Invariant instance`);
+  console.log(`    clawarmor invariant sync --push --host <host> --port <port>`);
+  console.log('');
+  process.exit(1);
+}
+
 console.log(`  ${paint.red('✗')} Unknown command: ${paint.bold(cmd)}`);
 usage(); process.exit(1);

package/lib/audit-quiet.js

@@ -0,0 +1,89 @@
+// audit-quiet.js — runs audit checks and returns results without printing.
+// Used by baseline save to capture the current security posture.
+
+import { loadConfig } from './config.js';
+import { getProfile, isExpectedFinding } from './profiles.js';
+import gatewayChecks from './checks/gateway.js';
+import filesystemChecks from './checks/filesystem.js';
+import channelChecks from './checks/channels.js';
+import authChecks from './checks/auth.js';
+import toolChecks from './checks/tools.js';
+import versionChecks from './checks/version.js';
+import hooksChecks from './checks/hooks.js';
+import allowFromChecks from './checks/allowfrom.js';
+import tokenAgeChecks from './checks/token-age.js';
+import execApprovalChecks from './checks/exec-approval.js';
+import skillPinningChecks from './checks/skill-pinning.js';
+import gitCredentialLeakChecks from './checks/git-credential-leak.js';
+import credentialFilesChecks from './checks/credential-files.js';
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+const W = { CRITICAL: 25, HIGH: 15, MEDIUM: 8, LOW: 3, INFO: 0 };
+
+/**
+ * Run audit checks silently and return { score, findings, profile }.
+ * findings is an array of { id, severity, title, skill }.
+ */
+export async function runAuditQuiet(flags = {}) {
+  let profileName = flags.profile || null;
+  if (!profileName) {
+    try {
+      const pFile = join(homedir(), '.clawarmor', 'profile.json');
+      if (existsSync(pFile)) profileName = JSON.parse(readFileSync(pFile, 'utf8')).name || null;
+    } catch { /* non-fatal */ }
+  }
+  const activeProfile = profileName ? getProfile(profileName) : null;
+
+  const { config, error } = loadConfig(flags.configPath || null);
+  if (error) throw new Error(error);
+
+  const allChecks = [
+    ...gatewayChecks, ...filesystemChecks, ...channelChecks,
+    ...authChecks, ...toolChecks, ...versionChecks, ...hooksChecks,
+    ...allowFromChecks,
+    ...tokenAgeChecks, ...execApprovalChecks, ...skillPinningChecks,
+    ...gitCredentialLeakChecks,
+    ...credentialFilesChecks,
+  ];
+
+  const staticResults = [];
+  for (const check of allChecks) {
+    try { staticResults.push(await check(config)); }
+    catch (e) { staticResults.push({ id: 'err', severity: 'LOW', passed: true, passedMsg: `Check error: ${e.message}` }); }
+  }
+
+  const failed = staticResults.filter(r => !r.passed);
+
+  const annotatedFailed = failed.map(f => {
+    if (activeProfile && isExpectedFinding(activeProfile.name, f.id)) {
+      return { ...f, _profileExpected: true };
+    }
+    return f;
+  });
+
+  const scoringFailed = activeProfile
+    ? annotatedFailed.filter(f => !f._profileExpected)
+    : annotatedFailed;
+
+  const criticals = scoringFailed.filter(r => r.severity === 'CRITICAL').length;
+
+  let score = 100;
+  for (const f of scoringFailed) score -= (W[f.severity] || 0);
+  score = Math.max(0, score);
+  if (criticals >= 2) score = Math.min(score, 25);
+  else if (criticals >= 1) score = Math.min(score, 50);
+
+  const findings = annotatedFailed.map(f => ({
+    id: f.id,
+    severity: f.severity,
+    title: f.title || f.id,
+    patternId: f.id,
+    skill: f.skill || null,
+    message: f.title || f.description || '',
+    _profileExpected: f._profileExpected || false,
+  }));
+
+  return { score, findings, profile: profileName };
+}