clawarmor 1.2.0 → 2.0.0-alpha.2

package/lib/protect.js

@@ -0,0 +1,333 @@
+// clawarmor protect — Install/uninstall/status the full ClawArmor guard system.
+// --install:   writes hook files, adds shell intercept, starts watch daemon
+// --uninstall: reverses all of the above cleanly
+// --status:    shows current state without modifying anything
+
+import {
+  existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync, readdirSync, rmSync,
+} from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import { spawnSync } from 'child_process';
+import { watchDaemonStatus } from './watch.js';
+
+const HOME = homedir();
+const OC_DIR = join(HOME, '.openclaw');
+const CLAWARMOR_DIR = join(HOME, '.clawarmor');
+const HOOKS_DIR = join(OC_DIR, 'hooks');
+const GUARD_HOOK_DIR = join(HOOKS_DIR, 'clawarmor-guard');
+const CLI_PATH = new URL('../cli.js', import.meta.url).pathname;
+
+const SHELL_FUNCTION = `
+# ClawArmor intercept — added by: clawarmor protect --install
+# Wraps 'openclaw clawhub install' to scan skills before activation.
+openclaw() {
+  if [ "$1" = "clawhub" ] && [ "$2" = "install" ] && [ -n "$3" ]; then
+    echo "ClawArmor: scanning $3 before install..."
+    clawarmor prescan "$3" || { echo "Blocked by ClawArmor. Use --force to override."; return 1; }
+  fi
+  command openclaw "$@"
+}
+# End ClawArmor intercept
+`;
+
+const SHELL_MARKER_START = '# ClawArmor intercept — added by: clawarmor protect --install';
+const SHELL_MARKER_END = '# End ClawArmor intercept';
+
+const HOOK_MD = `---
+name: clawarmor-guard
+description: Runs a silent security audit on gateway startup and alerts on regressions
+events:
+  - gateway:startup
+requires:
+  bins:
+    - clawarmor
+---
+
+# clawarmor-guard
+
+Fires on every gateway startup. Runs \`clawarmor audit --json\` in the background,
+compares the score to the last known baseline, and alerts the agent if the score
+drops by 5 or more points, or if a new CRITICAL finding appears.
+
+Install with: \`clawarmor protect --install\`
+`;
+
+const HANDLER_JS = `// clawarmor-guard hook handler
+// Fires on gateway:startup. Silent unless score drops or CRITICAL finding appears.
+// No external dependencies.
+
+import { spawnSync } from 'child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+const HOME = homedir();
+const CLAWARMOR_DIR = join(HOME, '.clawarmor');
+const LAST_SCORE_FILE = join(CLAWARMOR_DIR, 'last-score.json');
+
+function readLastScore() {
+  try {
+    if (existsSync(LAST_SCORE_FILE)) return JSON.parse(readFileSync(LAST_SCORE_FILE, 'utf8'));
+  } catch {}
+  return null;
+}
+
+function writeLastScore(data) {
+  try {
+    mkdirSync(CLAWARMOR_DIR, { recursive: true });
+    writeFileSync(LAST_SCORE_FILE, JSON.stringify(data, null, 2), 'utf8');
+  } catch {}
+}
+
+function runAuditJson() {
+  try {
+    const result = spawnSync('clawarmor', ['audit', '--json'], {
+      encoding: 'utf8',
+      timeout: 30000,
+      maxBuffer: 1024 * 1024,
+    });
+    if (result.stdout) {
+      const jsonStart = result.stdout.indexOf('{');
+      if (jsonStart !== -1) return JSON.parse(result.stdout.slice(jsonStart));
+    }
+  } catch {}
+  return null;
+}
+
+// Main hook entry point — called by openclaw on gateway:startup
+export default async function handler(event) {
+  let auditResult;
+  try {
+    auditResult = runAuditJson();
+  } catch (e) {
+    // If clawarmor itself fails, don't block startup
+    return;
+  }
+
+  if (!auditResult) return;
+
+  const newScore = auditResult.score ?? null;
+  const lastState = readLastScore();
+  const lastScore = lastState?.score ?? null;
+  const isFirstRun = lastScore === null;
+
+  if (newScore !== null) {
+    if (isFirstRun) {
+      writeLastScore({ score: newScore, grade: auditResult.grade, timestamp: new Date().toISOString() });
+      // First run — establish baseline silently
+      return;
+    }
+
+    const drop = lastScore - newScore;
+    const newCriticals = (auditResult.failed || []).filter(f => f.severity === 'CRITICAL');
+    const hadCriticals = (lastState?.criticals || 0);
+    const newCriticalCount = newCriticals.length;
+
+    writeLastScore({
+      score: newScore,
+      grade: auditResult.grade,
+      criticals: newCriticalCount,
+      timestamp: new Date().toISOString(),
+    });
+
+    if (newCriticalCount > hadCriticals) {
+      // New CRITICAL finding — alert immediately
+      const names = newCriticals.map(f => f.id || f.title).join(', ');
+      console.error(\`[ClawArmor] CRITICAL security finding: \${names}\`);
+      console.error(\`[ClawArmor] Run: clawarmor audit   for details and fix commands.\`);
+      return;
+    }
+
+    if (drop >= 5) {
+      console.error(\`[ClawArmor] Security score dropped \${drop} points (\${lastScore} → \${newScore})\`);
+      console.error(\`[ClawArmor] Run: clawarmor audit   to see what changed.\`);
+    }
+    // Score improved or unchanged — no output (don't interrupt users with good news)
+  }
+}
+`;
+
+// ── Install ──────────────────────────────────────────────────────────────────
+
+function writeHookFiles() {
+  mkdirSync(GUARD_HOOK_DIR, { recursive: true });
+  writeFileSync(join(GUARD_HOOK_DIR, 'HOOK.md'), HOOK_MD, 'utf8');
+  writeFileSync(join(GUARD_HOOK_DIR, 'handler.js'), HANDLER_JS, 'utf8');
+}
+
+function removeHookFiles() {
+  if (!existsSync(GUARD_HOOK_DIR)) return false;
+  try {
+    rmSync(GUARD_HOOK_DIR, { recursive: true, force: true });
+    return true;
+  } catch { return false; }
+}
+
+function hookFilesExist() {
+  return existsSync(join(GUARD_HOOK_DIR, 'HOOK.md')) &&
+         existsSync(join(GUARD_HOOK_DIR, 'handler.js'));
+}
+
+// ── Shell function ────────────────────────────────────────────────────────────
+
+function shellFunctionPresent(rcPath) {
+  if (!existsSync(rcPath)) return false;
+  try {
+    return readFileSync(rcPath, 'utf8').includes(SHELL_MARKER_START);
+  } catch { return false; }
+}
+
+function injectShellFunction(rcPath) {
+  if (!existsSync(rcPath)) return false;
+  if (shellFunctionPresent(rcPath)) return true; // already there
+  try {
+    const existing = readFileSync(rcPath, 'utf8');
+    writeFileSync(rcPath, existing + '\n' + SHELL_FUNCTION, 'utf8');
+    return true;
+  } catch { return false; }
+}
+
+function removeShellFunction(rcPath) {
+  if (!existsSync(rcPath)) return false;
+  try {
+    const content = readFileSync(rcPath, 'utf8');
+    const start = content.indexOf(SHELL_MARKER_START);
+    const end = content.indexOf(SHELL_MARKER_END);
+    if (start === -1) return false;
+    const after = end !== -1 ? end + SHELL_MARKER_END.length : start;
+    const newContent = content.slice(0, start).trimEnd() + '\n' + content.slice(after + 1);
+    writeFileSync(rcPath, newContent, 'utf8');
+    return true;
+  } catch { return false; }
+}
+
+function startWatchDaemon() {
+  const result = spawnSync(process.execPath, [CLI_PATH, 'watch', '--daemon'], {
+    encoding: 'utf8',
+    timeout: 10000,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  return result.status === 0;
+}
+
+// ── Public API ────────────────────────────────────────────────────────────────
+
+export async function runProtect(flags = {}) {
+  const zshrc = join(HOME, '.zshrc');
+  const bashrc = join(HOME, '.bashrc');
+
+  if (flags.install) {
+    console.log('\n  ClawArmor Protect — installing...\n');
+
+    // 1. Hook files
+    writeHookFiles();
+    console.log(`  ✓  Hook files written to: ~/.openclaw/hooks/clawarmor-guard/`);
+
+    // 2. Shell intercept
+    let shellInstalled = false;
+    if (injectShellFunction(zshrc)) {
+      console.log(`  ✓  Shell intercept added to ~/.zshrc`);
+      shellInstalled = true;
+    }
+    if (injectShellFunction(bashrc)) {
+      console.log(`  ✓  Shell intercept added to ~/.bashrc`);
+      shellInstalled = true;
+    }
+    if (!shellInstalled) {
+      console.log(`  !  No ~/.zshrc or ~/.bashrc found — shell intercept skipped`);
+    }
+
+    // 3. Start watch daemon
+    const daemonStarted = startWatchDaemon();
+    if (daemonStarted) {
+      console.log(`  ✓  Watch daemon started`);
+    } else {
+      console.log(`  !  Watch daemon could not be started automatically`);
+      console.log(`     Run manually: clawarmor watch --daemon`);
+    }
+
+    console.log('\n  ClawArmor Protect is now active.\n');
+    console.log(`  The guard hook fires on every gateway startup.`);
+    console.log(`  The watcher monitors config and skill changes in real time.`);
+    if (shellInstalled) {
+      console.log(`  Restart your shell (or: source ~/.zshrc) for the intercept to take effect.`);
+    }
+    console.log('');
+    return 0;
+  }
+
+  if (flags.uninstall) {
+    console.log('\n  ClawArmor Protect — uninstalling...\n');
+
+    // 1. Hook files
+    if (removeHookFiles()) {
+      console.log(`  ✓  Hook files removed`);
+    } else {
+      console.log(`  -  Hook files were not present`);
+    }
+
+    // 2. Shell function
+    let shellRemoved = false;
+    if (removeShellFunction(zshrc)) {
+      console.log(`  ✓  Shell intercept removed from ~/.zshrc`);
+      shellRemoved = true;
+    }
+    if (removeShellFunction(bashrc)) {
+      console.log(`  ✓  Shell intercept removed from ~/.bashrc`);
+      shellRemoved = true;
+    }
+    if (!shellRemoved) {
+      console.log(`  -  No shell intercept found to remove`);
+    }
+
+    // 3. Stop watch daemon
+    const { stopDaemon } = await import('./watch.js');
+    stopDaemon();
+
+    console.log('\n  ClawArmor Protect has been uninstalled.\n');
+    return 0;
+  }
+
+  if (flags.status) {
+    console.log('\n  ClawArmor Protect — Status\n');
+
+    // Hook files
+    const hookOk = hookFilesExist();
+    console.log(`  Hook (gateway:startup)   ${hookOk ? '✓ installed' : '✗ not installed'}`);
+
+    // Watch daemon
+    const daemon = watchDaemonStatus();
+    console.log(`  Watch daemon             ${daemon.running ? `● running  (PID ${daemon.pid})` : '○ not running'}`);
+
+    // Shell function
+    const inZsh = shellFunctionPresent(zshrc);
+    const inBash = shellFunctionPresent(bashrc);
+    if (inZsh || inBash) {
+      const where = [inZsh && '~/.zshrc', inBash && '~/.bashrc'].filter(Boolean).join(', ');
+      console.log(`  Shell intercept          ✓ active  (${where})`);
+    } else {
+      console.log(`  Shell intercept          ✗ not installed`);
+    }
+
+    const allActive = hookOk && daemon.running && (inZsh || inBash);
+    console.log('');
+    if (allActive) {
+      console.log(`  Full protection active.`);
+    } else {
+      console.log(`  Protection incomplete. Run: clawarmor protect --install`);
+    }
+    console.log('');
+    return 0;
+  }
+
+  // No flag — show usage
+  console.log('');
+  console.log(`  Usage: clawarmor protect [--install | --uninstall | --status]`);
+  console.log('');
+  console.log(`    --install    Install the guard hook, shell intercept, and watch daemon`);
+  console.log(`    --uninstall  Remove all ClawArmor protect components`);
+  console.log(`    --status     Show current protection state`);
+  console.log('');
+  return 0;
+}

package/lib/scan.js

@@ -2,6 +2,7 @@ import { paint, severityColor } from './output/colors.js';
 import { scanFile } from './scanner/file-scanner.js';
 import { findInstalledSkills } from './scanner/skill-finder.js';
 import { scanSkillMdFiles } from './scanner/skill-md-scanner.js';
+import { append as auditLogAppend } from './audit-log.js';
 
 const SEP = paint.dim('─'.repeat(52));
 const HOME = process.env.HOME || '';
@@ -33,6 +34,7 @@ export async function runScan() {
 
   let totalCritical = 0, totalHigh = 0;
   const flagged = [];
+  const auditFindings = []; // accumulated for audit log
 
   for (const skill of skills) {
     process.stdout.write(`  ${skill.isBuiltin ? paint.dim('⊙') : paint.cyan('▶')} ${paint.bold(skill.name)}${paint.dim(skill.isBuiltin?' [built-in]':' [user]')}...`);
@@ -45,6 +47,7 @@ export async function runScan() {
     const mdFindings = mdResults.flatMap(r => r.findings);
 
     const allFindings = [...codeFindings, ...mdFindings];
+    for (const f of allFindings) auditFindings.push({ id: f.patternId || f.id || '?', severity: f.severity });
 
     const critical = allFindings.filter(f => f.severity==='CRITICAL');
     const high = allFindings.filter(f => f.severity==='HIGH');
@@ -125,5 +128,16 @@ export async function runScan() {
   }
   console.log(`  ${paint.dim('Run')} ${paint.cyan('clawarmor audit')} ${paint.dim('to check your config.')}`);
   console.log('');
+
+  auditLogAppend({
+    cmd: 'scan',
+    trigger: 'manual',
+    score: null,
+    delta: null,
+    findings: auditFindings,
+    blocked: null,
+    skill: null,
+  });
+
   return totalCritical > 0 ? 1 : 0;
 }

package/lib/watch.js

@@ -0,0 +1,235 @@
+// clawarmor watch — Real-time file watcher for OpenClaw config and skills.
+// Uses Node.js built-in fs.watch only. Zero new dependencies.
+
+import { watch, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, unlinkSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import { spawnSync, fork } from 'child_process';
+
+const HOME = homedir();
+const OC_DIR = join(HOME, '.openclaw');
+const CLAWARMOR_DIR = join(HOME, '.clawarmor');
+const PID_FILE = join(CLAWARMOR_DIR, 'watch.pid');
+const LAST_SCORE_FILE = join(CLAWARMOR_DIR, 'last-score.json');
+const CONFIG_FILE = join(OC_DIR, 'openclaw.json');
+const SKILLS_DIR = join(OC_DIR, 'skills');
+const CLI_PATH = new URL('../cli.js', import.meta.url).pathname;
+
+// Dynamically detect npm global skills dir
+function detectNpmSkillsDir() {
+  try {
+    const result = spawnSync('npm', ['root', '-g'], { encoding: 'utf8', timeout: 5000 });
+    if (result.status === 0 && result.stdout) {
+      const npmRoot = result.stdout.trim();
+      const candidate = join(npmRoot, 'openclaw', 'skills');
+      if (existsSync(candidate)) return candidate;
+    }
+  } catch { /* skip */ }
+  return null;
+}
+
+function readLastScore() {
+  try {
+    if (existsSync(LAST_SCORE_FILE)) {
+      return JSON.parse(readFileSync(LAST_SCORE_FILE, 'utf8'));
+    }
+  } catch { /* ignore */ }
+  return null;
+}
+
+function writeLastScore(data) {
+  try {
+    mkdirSync(CLAWARMOR_DIR, { recursive: true });
+    writeFileSync(LAST_SCORE_FILE, JSON.stringify(data, null, 2), 'utf8');
+  } catch { /* non-fatal */ }
+}
+
+function runAuditJson() {
+  try {
+    const result = spawnSync(process.execPath, [CLI_PATH, 'audit', '--json'], {
+      encoding: 'utf8',
+      timeout: 30000,
+      maxBuffer: 1024 * 1024,
+    });
+    if (result.stdout) {
+      // Find the JSON blob in output (audit --json may mix some text before JSON)
+      const jsonStart = result.stdout.indexOf('{');
+      if (jsonStart !== -1) {
+        return JSON.parse(result.stdout.slice(jsonStart));
+      }
+    }
+  } catch { /* non-fatal */ }
+  return null;
+}
+
+function timestamp() {
+  return new Date().toLocaleTimeString('en-US', { hour12: false });
+}
+
+function onConfigChange() {
+  console.log(`[${timestamp()}] Config changed — re-running audit...`);
+
+  const auditResult = runAuditJson();
+  if (!auditResult) {
+    console.log(`[${timestamp()}] Could not parse audit output.`);
+    return;
+  }
+
+  const newScore = auditResult.score ?? null;
+  const lastState = readLastScore();
+
+  if (newScore !== null) {
+    const lastScore = lastState?.score ?? null;
+    if (lastScore !== null && newScore < lastScore) {
+      const drop = lastScore - newScore;
+      console.log(`[${timestamp()}] ALERT: Security score dropped ${drop} points (${lastScore} → ${newScore})`);
+      const newCriticals = (auditResult.failed || []).filter(f => f.severity === 'CRITICAL');
+      if (newCriticals.length) {
+        console.log(`[${timestamp()}] CRITICAL findings: ${newCriticals.map(f => f.id || f.title).join(', ')}`);
+      }
+    } else if (lastScore !== null && newScore > lastScore) {
+      console.log(`[${timestamp()}] Score improved: ${lastScore} → ${newScore}`);
+    } else {
+      console.log(`[${timestamp()}] Score unchanged: ${newScore}/100`);
+    }
+    writeLastScore({ score: newScore, grade: auditResult.grade, timestamp: new Date().toISOString() });
+  }
+}
+
+function onNewSkill(skillName) {
+  console.log(`[${timestamp()}] New skill detected: ${skillName}`);
+  console.log(`[${timestamp()}] Run: clawarmor scan   to check for malicious patterns`);
+}
+
+export async function runWatch(flags = {}) {
+  if (flags.daemon) {
+    return startDaemon();
+  }
+
+  // Ensure ~/.clawarmor/ exists
+  mkdirSync(CLAWARMOR_DIR, { recursive: true });
+
+  const watchTargets = [];
+
+  if (existsSync(CONFIG_FILE)) {
+    watchTargets.push({ path: CONFIG_FILE, label: 'openclaw.json', type: 'config' });
+  }
+
+  if (!existsSync(OC_DIR)) {
+    console.log(`  [watch] ~/.openclaw/ not found — waiting for it to appear is not supported.`);
+    console.log(`  [watch] Run: openclaw doctor  to set up OpenClaw first.`);
+    return 1;
+  }
+
+  // Watch skills dir (may not exist yet)
+  if (existsSync(SKILLS_DIR)) {
+    watchTargets.push({ path: SKILLS_DIR, label: 'skills/', type: 'skills' });
+  }
+
+  const npmSkillsDir = detectNpmSkillsDir();
+  if (npmSkillsDir) {
+    watchTargets.push({ path: npmSkillsDir, label: 'npm skills/', type: 'skills' });
+  }
+
+  if (!watchTargets.length) {
+    console.log(`  [watch] Nothing to watch — no config or skills directories found.`);
+    return 1;
+  }
+
+  console.log(`  ClawArmor Watch — monitoring ${watchTargets.length} path(s)`);
+  for (const t of watchTargets) console.log(`    ${t.label}  (${t.path})`);
+  console.log(`  Press Ctrl+C to stop.\n`);
+
+  const debounceMap = new Map();
+  const DEBOUNCE_MS = 500;
+
+  // Track skill dirs seen
+  const seenSkills = new Set();
+  try {
+    if (existsSync(SKILLS_DIR)) {
+      readdirSync(SKILLS_DIR).forEach(d => seenSkills.add(d));
+    }
+  } catch { /* ignore */ }
+
+  for (const target of watchTargets) {
+    try {
+      watch(target.path, { recursive: target.type === 'skills' }, (eventType, filename) => {
+        const key = `${target.path}::${filename}`;
+        if (debounceMap.has(key)) clearTimeout(debounceMap.get(key));
+
+        debounceMap.set(key, setTimeout(() => {
+          debounceMap.delete(key);
+
+          if (target.type === 'config') {
+            onConfigChange();
+          } else if (target.type === 'skills' && filename) {
+            // Check if this is a new top-level skill directory
+            const topDir = filename.split('/')[0];
+            if (topDir && !seenSkills.has(topDir)) {
+              seenSkills.add(topDir);
+              onNewSkill(topDir);
+            }
+          }
+        }, DEBOUNCE_MS));
+      });
+    } catch (e) {
+      console.log(`  [watch] Could not watch ${target.label}: ${e.message}`);
+    }
+  }
+
+  // Keep alive
+  return new Promise(() => {});
+}
+
+function startDaemon() {
+  mkdirSync(CLAWARMOR_DIR, { recursive: true });
+
+  const child = fork(CLI_PATH, ['watch'], {
+    detached: true,
+    stdio: 'ignore',
+    env: { ...process.env, CLAWARMOR_DAEMON: '1' },
+  });
+
+  child.unref();
+
+  try {
+    writeFileSync(PID_FILE, String(child.pid), 'utf8');
+  } catch { /* non-fatal */ }
+
+  console.log(`  ClawArmor Watch daemon started (PID ${child.pid})`);
+  console.log(`  PID written to: ${PID_FILE}`);
+  console.log(`  Stop with: kill $(cat ${PID_FILE})`);
+  return 0;
+}
+
+export function stopDaemon() {
+  if (!existsSync(PID_FILE)) {
+    console.log('  No watch daemon PID file found.');
+    return false;
+  }
+  try {
+    const pid = parseInt(readFileSync(PID_FILE, 'utf8').trim(), 10);
+    if (isNaN(pid)) { console.log('  Invalid PID in watch.pid'); return false; }
+    process.kill(pid, 'SIGTERM');
+    // Remove PID file
+    try { unlinkSync(PID_FILE); } catch { /* ignore */ }
+    console.log(`  Watch daemon (PID ${pid}) stopped.`);
+    return true;
+  } catch (e) {
+    console.log(`  Could not stop watch daemon: ${e.message}`);
+    return false;
+  }
+}
+
+export function watchDaemonStatus() {
+  if (!existsSync(PID_FILE)) return { running: false, pid: null };
+  try {
+    const pid = parseInt(readFileSync(PID_FILE, 'utf8').trim(), 10);
+    if (isNaN(pid)) return { running: false, pid: null };
+    // Check if the process is alive
+    process.kill(pid, 0); // throws if not running
+    return { running: true, pid };
+  } catch {
+    return { running: false, pid: null };
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawarmor",
-  "version": "1.2.0",
+  "version": "2.0.0-alpha.2",
   "description": "Security armor for OpenClaw agents — audit, scan, monitor",
   "bin": {
     "clawarmor": "cli.js"