clawarmor 1.2.0 → 2.0.0-alpha.2

package/cli.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
-// ClawArmor v1.2.0 — Security armor for OpenClaw agents
+// ClawArmor v2.0.0-alpha.2 — Security armor for OpenClaw agents
 
 import { paint } from './lib/output/colors.js';
 
-const VERSION = '1.2.0';
+const VERSION = '2.0.0-alpha.1';
 const GATEWAY_PORT_DEFAULT = 18789;
 
 function isLocalhost(host) {
@@ -45,6 +45,10 @@ function usage() {
   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(`    ${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('log')}      View the audit event log`);
   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`);
@@ -153,5 +157,43 @@ if (cmd === 'fix') {
   process.exit(await runFix(fixFlags));
 }
 
+if (cmd === 'watch') {
+  const { runWatch } = await import('./lib/watch.js');
+  const watchFlags = { daemon: args.includes('--daemon') };
+  process.exit(await runWatch(watchFlags));
+}
+
+if (cmd === 'protect') {
+  const { runProtect } = await import('./lib/protect.js');
+  const protectFlags = {
+    install: args.includes('--install'),
+    uninstall: args.includes('--uninstall'),
+    status: args.includes('--status'),
+  };
+  process.exit(await runProtect(protectFlags));
+}
+
+if (cmd === 'prescan') {
+  const skillArg = args[1];
+  if (!skillArg) {
+    console.log(`  Usage: clawarmor prescan <skill-name>`);
+    process.exit(1);
+  }
+  const { runPrescan } = await import('./lib/prescan.js');
+  process.exit(await runPrescan(skillArg));
+}
+
+if (cmd === 'log') {
+  const sinceIdx = args.indexOf('--since');
+  const sinceArg = sinceIdx !== -1 ? args[sinceIdx + 1] : null;
+  const logFlags = {
+    json: args.includes('--json'),
+    tokens: args.includes('--tokens'),
+    since: sinceArg || null,
+  };
+  const { runLog } = await import('./lib/log-viewer.js');
+  process.exit(await runLog(logFlags));
+}
+
 console.log(`  ${paint.red('✗')} Unknown command: ${paint.bold(cmd)}`);
 usage(); process.exit(1);

package/lib/audit-log.js

@@ -0,0 +1,38 @@
+// ClawArmor v2.0 — Security Audit Log
+// Appends one JSONL line per event to ~/.clawarmor/audit.log
+// Schema: { ts, cmd, trigger, score, delta, findings, blocked, skill }
+
+import { mkdirSync, appendFileSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+const LOG_DIR = join(homedir(), '.clawarmor');
+const LOG_FILE = join(LOG_DIR, 'audit.log');
+
+/**
+ * Append one audit event to ~/.clawarmor/audit.log (JSONL format).
+ * @param {object} entry
+ * @param {string}        entry.cmd       - 'audit' | 'scan' | 'prescan' | 'watch'
+ * @param {string}        entry.trigger   - 'manual' | 'gateway:startup' | 'watch' | 'prescan'
+ * @param {number|null}   entry.score     - numeric score (audit only)
+ * @param {number|null}   entry.delta     - score change from previous run
+ * @param {Array}         entry.findings  - [{ id, severity }]
+ * @param {boolean|null}  entry.blocked   - prescan blocked install
+ * @param {string|null}   entry.skill     - skill name (prescan / scan per-skill)
+ */
+export function append(entry) {
+  try {
+    mkdirSync(LOG_DIR, { recursive: true });
+    const line = JSON.stringify({
+      ts: new Date().toISOString(),
+      cmd: entry.cmd ?? null,
+      trigger: entry.trigger ?? 'manual',
+      score: entry.score ?? null,
+      delta: entry.delta ?? null,
+      findings: Array.isArray(entry.findings) ? entry.findings : [],
+      blocked: entry.blocked ?? null,
+      skill: entry.skill ?? null,
+    }) + '\n';
+    appendFileSync(LOG_FILE, line, 'utf8');
+  } catch { /* non-fatal — never crash the main command */ }
+}

package/lib/audit.js

@@ -11,15 +11,21 @@ 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 { writeFileSync, mkdirSync, existsSync, readFileSync, renameSync } from 'fs';
 import { join } from 'path';
 import { homedir } from 'os';
 import { checkIntegrity, updateBaseline } from './integrity.js';
+import { append as auditLogAppend } from './audit-log.js';
+import credentialFilesChecks from './checks/credential-files.js';
 
 const W = { CRITICAL: 25, HIGH: 15, MEDIUM: 8, LOW: 3, INFO: 0 };
 const SEP = paint.dim('─'.repeat(52));
 const W52 = 52;
-const VERSION = '1.2.0';
+const VERSION = '2.0.0-alpha.1';
 
 const HISTORY_DIR = join(homedir(), '.clawarmor');
 const HISTORY_FILE = join(HISTORY_DIR, 'history.json');
@@ -156,6 +162,9 @@ export async function runAudit(flags = {}) {
     ...gatewayChecks, ...filesystemChecks, ...channelChecks,
     ...authChecks, ...toolChecks, ...versionChecks, ...hooksChecks,
     ...allowFromChecks,
+    ...tokenAgeChecks, ...execApprovalChecks, ...skillPinningChecks,
+    ...gitCredentialLeakChecks,
+    ...credentialFilesChecks,
   ];
   const staticResults = [];
   for (const check of allChecks) {
@@ -207,6 +216,18 @@ export async function runAudit(flags = {}) {
 
   if (flags.json) {
     console.log(JSON.stringify({score,grade,failed,passed},null,2));
+    const histJ = loadHistory();
+    const prevScoreJ = histJ.length ? histJ[histJ.length - 1].score : null;
+    const deltaJ = prevScoreJ != null ? score - prevScoreJ : null;
+    auditLogAppend({
+      cmd: 'audit',
+      trigger: 'manual',
+      score,
+      delta: deltaJ,
+      findings: failed.map(f => ({ id: f.id, severity: f.severity })),
+      blocked: null,
+      skill: null,
+    });
     appendHistory({ timestamp: new Date().toISOString(), score, grade,
       findings: failed.length, criticals, version: VERSION,
       failedIds: failed.map(f => f.id) });
@@ -261,7 +282,21 @@ export async function runAudit(flags = {}) {
     console.log(`  ${paint.green('✓')}  Config baseline updated.`);
   }
 
-    // Persist history (atomic)
+    // Audit log (JSONL) — compute delta from history before writing
+  const hist = loadHistory();
+  const prevScore = hist.length ? hist[hist.length - 1].score : null;
+  const delta = prevScore != null ? score - prevScore : null;
+  auditLogAppend({
+    cmd: 'audit',
+    trigger: 'manual',
+    score,
+    delta,
+    findings: failed.map(f => ({ id: f.id, severity: f.severity })),
+    blocked: null,
+    skill: null,
+  });
+
+  // Persist history (atomic)
   appendHistory({
     timestamp: new Date().toISOString(),
     score,

package/lib/checks/credential-files.js

@@ -0,0 +1,156 @@
+// T-CRED-001 — Credential File Permission Hygiene
+// Checks ~/.openclaw/ directory and file permissions, and scans JSON
+// files for API key patterns (key names only — never values).
+
+import { existsSync, readdirSync, statSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+const HOME = homedir();
+const OPENCLAW_DIR = join(HOME, '.openclaw');
+
+// Same pattern shape as git-credential-leak: matches key names + long value
+// We only use this to DETECT presence — we never log the value
+const SECRET_PATTERN = /(?:api[_-]?key|token|secret|password|credential)["']?\s*[:=]\s*["']?([a-zA-Z0-9_\-]{16,})/i;
+
+// ── check 1: directory permissions ─────────────────────────────────────────
+
+export function checkCredDirPermissions() {
+  if (!existsSync(OPENCLAW_DIR)) {
+    return { id: 'cred.dir_permissions', severity: 'MEDIUM', passed: true,
+      passedMsg: '~/.openclaw/ not found — credential directory check skipped' };
+  }
+
+  let dirStat;
+  try { dirStat = statSync(OPENCLAW_DIR); }
+  catch {
+    return { id: 'cred.dir_permissions', severity: 'MEDIUM', passed: true,
+      passedMsg: 'Could not stat ~/.openclaw/ — skipped' };
+  }
+
+  const mode = dirStat.mode & 0o777;
+  if (mode > 0o700) {
+    return {
+      id: 'cred.dir_permissions',
+      severity: 'MEDIUM',
+      passed: false,
+      title: `~/.openclaw/ directory permissions are too open (${mode.toString(8)})`,
+      description: `The directory containing your credentials has permissions ${mode.toString(8)}.\nIt should be 700 (owner-only access). Overly permissive directory permissions\nallow other users or groups to list and access your credential files.`,
+      fix: `chmod 700 ${OPENCLAW_DIR}`,
+    };
+  }
+
+  return { id: 'cred.dir_permissions', severity: 'MEDIUM', passed: true,
+    passedMsg: `~/.openclaw/ directory permissions are secure (${mode.toString(8)})` };
+}
+
+// ── check 2: file permissions ───────────────────────────────────────────────
+
+export function checkCredFilePermissions() {
+  if (!existsSync(OPENCLAW_DIR)) {
+    return { id: 'cred.file_permissions', severity: 'CRITICAL', passed: true,
+      passedMsg: '~/.openclaw/ not found — credential file permission check skipped' };
+  }
+
+  let entries;
+  try { entries = readdirSync(OPENCLAW_DIR, { withFileTypes: true }); }
+  catch {
+    return { id: 'cred.file_permissions', severity: 'CRITICAL', passed: true,
+      passedMsg: 'Could not read ~/.openclaw/ — skipped' };
+  }
+
+  const worldReadable = [];
+  const groupReadable = [];
+
+  for (const entry of entries) {
+    if (!entry.isFile()) continue;
+    const filePath = join(OPENCLAW_DIR, entry.name);
+    let s;
+    try { s = statSync(filePath); } catch { continue; }
+    const mode = s.mode & 0o777;
+
+    if (mode & 0o004) {
+      // world-readable bit set → CRITICAL
+      worldReadable.push({ name: entry.name, path: filePath, mode: mode.toString(8) });
+    } else if (mode & 0o040) {
+      // group-readable bit set (but not world) → HIGH
+      groupReadable.push({ name: entry.name, path: filePath, mode: mode.toString(8) });
+    }
+  }
+
+  if (worldReadable.length) {
+    const fixLines = worldReadable.map(f => `  chmod 600 ${f.path}`).join('\n');
+    const fileList = worldReadable.map(f => `• ${f.name} (${f.mode})`).join('\n');
+    return {
+      id: 'cred.file_permissions',
+      severity: 'CRITICAL',
+      passed: false,
+      title: `World-readable credential files in ~/.openclaw/ (${worldReadable.length})`,
+      description: `The following files are readable by any user on the system:\n${fileList}\n\nAny local process or user can read your API keys and tokens.`,
+      fix: `Fix immediately:\n${fixLines}`,
+    };
+  }
+
+  if (groupReadable.length) {
+    const fixLines = groupReadable.map(f => `  chmod 600 ${f.path}`).join('\n');
+    const fileList = groupReadable.map(f => `• ${f.name} (${f.mode})`).join('\n');
+    return {
+      id: 'cred.file_permissions',
+      severity: 'HIGH',
+      passed: false,
+      title: `Group-readable credential files in ~/.openclaw/ (${groupReadable.length})`,
+      description: `The following files are readable by your Unix group:\n${fileList}\n\nOther users in your group can read your credentials.`,
+      fix: `Fix:\n${fixLines}`,
+    };
+  }
+
+  return { id: 'cred.file_permissions', severity: 'CRITICAL', passed: true,
+    passedMsg: 'Credential file permissions are secure (all ≤ 0600)' };
+}
+
+// ── check 3: JSON content scan for API key patterns ─────────────────────────
+
+export function checkCredJsonSecrets() {
+  if (!existsSync(OPENCLAW_DIR)) {
+    return { id: 'cred.json_secrets', severity: 'HIGH', passed: true,
+      passedMsg: '~/.openclaw/ not found — JSON secret pattern check skipped' };
+  }
+
+  let entries;
+  try { entries = readdirSync(OPENCLAW_DIR, { withFileTypes: true }); }
+  catch {
+    return { id: 'cred.json_secrets', severity: 'HIGH', passed: true,
+      passedMsg: 'Could not read ~/.openclaw/ — skipped' };
+  }
+
+  const flagged = [];
+
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith('.json')) continue;
+    const filePath = join(OPENCLAW_DIR, entry.name);
+    let content;
+    try { content = readFileSync(filePath, 'utf8'); }
+    catch { continue; }
+    if (content.length > 1_000_000) continue;
+
+    if (SECRET_PATTERN.test(content)) {
+      flagged.push(entry.name);
+    }
+  }
+
+  if (!flagged.length) {
+    return { id: 'cred.json_secrets', severity: 'HIGH', passed: true,
+      passedMsg: 'No API key patterns found in ~/.openclaw/ JSON files' };
+  }
+
+  return {
+    id: 'cred.json_secrets',
+    severity: 'HIGH',
+    passed: false,
+    title: `API key patterns found in ~/.openclaw/ JSON files (${flagged.length} file${flagged.length > 1 ? 's' : ''})`,
+    description: `The following JSON files in ~/.openclaw/ contain patterns matching API keys or secrets:\n${flagged.map(f => `• ${f}`).join('\n')}\n\nNote: Only key name patterns are detected — actual values are never read or stored.\nCredentials in the wrong files may be at risk if file permissions are too open.`,
+    fix: `Ensure all credential files use 0600 permissions:\n  chmod 600 ~/.openclaw/*.json\n\nIf credentials are in unexpected files, move them to agent-accounts.json.`,
+  };
+}
+
+export default [checkCredDirPermissions, checkCredFilePermissions, checkCredJsonSecrets];

package/lib/checks/exec-approval.js

@@ -0,0 +1,64 @@
+// T-EXEC-004 — Exec Approval Coverage
+// Checks that exec commands require user approval.
+
+import { get } from '../config.js';
+
+export function checkExecApproval(config) {
+  const ask = get(config, 'tools.exec.ask', null);
+  const allowed = get(config, 'tools.exec.allowed', null);
+  const hasAllowlist = Array.isArray(allowed) && allowed.length > 0;
+
+  // ask === 'off' — no approvals at all
+  if (ask === 'off') {
+    return {
+      id: 'exec.approval',
+      severity: 'HIGH',
+      passed: false,
+      title: 'Exec approval disabled — all shell commands run without confirmation',
+      description: `tools.exec.ask="off" means every shell command the agent triggers\nruns immediately with zero user approval. Any prompt injection or malicious\nskill can execute arbitrary commands on your system without you seeing them.\nAttack: attacker injects "run rm -rf ~/important" — it executes silently.`,
+      fix: `openclaw config set tools.exec.ask always\n# or, to allow a specific set without prompts:\nopenctl config set tools.exec.ask on-miss\nopenctl config set tools.exec.allowed '["git","npm","node"]'`,
+    };
+  }
+
+  // ask === 'on-miss' with no allowlist — unbounded
+  if (ask === 'on-miss' && !hasAllowlist) {
+    return {
+      id: 'exec.approval',
+      severity: 'MEDIUM',
+      passed: false,
+      title: 'Exec approval set to on-miss but no allowlist defined',
+      description: `tools.exec.ask="on-miss" only prompts for commands not on the allowed list.\nWith no allowed list set, the effective behaviour depends on how openclaw handles\nan empty list — this is ambiguous and may allow all commands silently.\nAttack: attacker runs any command that happens to be implicitly allowed.`,
+      fix: `Either require approval for everything:\n  openclaw config set tools.exec.ask always\nOr define an explicit allowlist:\n  openclaw config set tools.exec.allowed '["git","npm","node"]'`,
+    };
+  }
+
+  // ask === 'always' — best practice
+  if (ask === 'always') {
+    return { id: 'exec.approval', severity: 'HIGH', passed: true,
+      passedMsg: 'Exec approval set to always — all commands require confirmation' };
+  }
+
+  // ask === 'on-miss' with a non-empty allowlist — acceptable
+  if (ask === 'on-miss' && hasAllowlist) {
+    return { id: 'exec.approval', severity: 'HIGH', passed: true,
+      passedMsg: `Exec approval: on-miss with ${allowed.length}-command allowlist` };
+  }
+
+  // ask is null/undefined — default behaviour is unknown; treat as warn
+  if (ask == null) {
+    return {
+      id: 'exec.approval',
+      severity: 'MEDIUM',
+      passed: false,
+      title: 'Exec approval not explicitly configured',
+      description: `tools.exec.ask is not set. The default approval behaviour is unknown\nand may change across openclaw versions. Explicit configuration is safer.`,
+      fix: `openclaw config set tools.exec.ask always`,
+    };
+  }
+
+  // Unknown value — pass with info
+  return { id: 'exec.approval', severity: 'HIGH', passed: true,
+    passedMsg: `Exec approval: ask="${ask}"` };
+}
+
+export default [checkExecApproval];

package/lib/checks/git-credential-leak.js

@@ -0,0 +1,135 @@
+// T-EXFIL-003 — Workspace Git Credential Leak
+// Scans the workspace git history and .env files for committed secrets.
+// NEVER prints actual secret values — only reports key names and locations.
+
+import { existsSync, readdirSync, readFileSync } from 'fs';
+import { join, basename } from 'path';
+import { homedir } from 'os';
+import { execSync } from 'child_process';
+import { get } from '../config.js';
+
+const HOME = homedir();
+const DEFAULT_WORKSPACE = join(HOME, 'clawd');
+
+// Pattern: key/token/secret = "value_at_least_16_chars"
+// NEVER logs the value; only the matched key name
+const SECRET_PATTERN = /(?:api[_-]?key|token|secret|password|credential)["']?\s*[:=]\s*["']?([a-zA-Z0-9_\-]{16,})/i;
+// Pattern to find the key name from the line (for reporting)
+const KEY_NAME_PATTERN = /^[^=:]*?(api[_-]?key|token|secret|password|credential)/i;
+
+const ENV_FILE_NAMES = ['.env', '.env.local', '.env.production', '.env.staging', '.env.development'];
+
+function isGitRepo(dir) {
+  return existsSync(join(dir, '.git'));
+}
+
+function scanEnvFiles(workspaceDir) {
+  const findings = [];
+
+  // Scan workspace root for .env files
+  let files;
+  try { files = readdirSync(workspaceDir); }
+  catch { return findings; }
+
+  for (const filename of files) {
+    if (!ENV_FILE_NAMES.includes(filename)) continue;
+    const filePath = join(workspaceDir, filename);
+    let lines;
+    try {
+      lines = readFileSync(filePath, 'utf8').split('\n');
+    } catch { continue; }
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      if (SECRET_PATTERN.test(line)) {
+        const keyMatch = line.match(KEY_NAME_PATTERN);
+        const keyName = keyMatch ? keyMatch[0].trim().replace(/["']/g, '') : 'unknown-key';
+        findings.push(`${filename}:${i + 1} — key matching "${keyName.slice(0, 40)}"`);
+      }
+    }
+  }
+
+  return findings;
+}
+
+function scanGitLog(workspaceDir) {
+  const findings = [];
+
+  try {
+    // Get last 50 commits' diffs — limit output to avoid huge repos
+    const output = execSync(
+      'git log -p --max-count=50 --no-color --unified=0',
+      { cwd: workspaceDir, timeout: 15000, maxBuffer: 5 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'] }
+    ).toString('utf8');
+
+    const lines = output.split('\n');
+    let currentCommit = '';
+    let currentFile = '';
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+
+      if (line.startsWith('commit ')) {
+        currentCommit = line.slice(7, 15); // short hash
+        continue;
+      }
+      if (line.startsWith('+++ b/')) {
+        currentFile = line.slice(6);
+        continue;
+      }
+      // Only check added lines (prefixed with +)
+      if (!line.startsWith('+') || line.startsWith('+++')) continue;
+
+      if (SECRET_PATTERN.test(line)) {
+        const keyMatch = line.match(KEY_NAME_PATTERN);
+        const keyName = keyMatch ? keyMatch[0].trim().replace(/["']/g, '') : 'unknown-key';
+        const location = `commit ${currentCommit}, file ${currentFile || 'unknown'}, line pattern "${keyName.slice(0, 40)}"`;
+        if (!findings.includes(location)) {
+          findings.push(location);
+        }
+      }
+    }
+  } catch {
+    // git not available, not a git repo, or timeout — skip silently
+  }
+
+  return findings;
+}
+
+export async function checkGitCredentialLeak(config) {
+  // Resolve workspace directory from config or default
+  const workspaceDir = get(config, 'workspace.dir', null) || DEFAULT_WORKSPACE;
+
+  if (!existsSync(workspaceDir)) {
+    return { id: 'exfil.git_credential_leak', severity: 'CRITICAL', passed: true,
+      passedMsg: 'Workspace directory not found — git credential leak check skipped' };
+  }
+
+  const envFindings = scanEnvFiles(workspaceDir);
+
+  let gitFindings = [];
+  if (isGitRepo(workspaceDir)) {
+    gitFindings = scanGitLog(workspaceDir);
+  }
+
+  const allFindings = [...envFindings, ...gitFindings];
+
+  if (!allFindings.length) {
+    return { id: 'exfil.git_credential_leak', severity: 'CRITICAL', passed: true,
+      passedMsg: 'No credential patterns found in workspace .env files or git history' };
+  }
+
+  const list = allFindings.slice(0, 10).map(f => `• ${f}`).join('\n');
+  const more = allFindings.length > 10 ? `\n  ...and ${allFindings.length - 10} more` : '';
+
+  return {
+    id: 'exfil.git_credential_leak',
+    severity: 'CRITICAL',
+    passed: false,
+    title: `Credential patterns found in workspace (${allFindings.length} location${allFindings.length > 1 ? 's' : ''})`,
+    description: `Secret-like patterns matching credential keys were found in your workspace.\nThis may mean API keys or tokens were committed to git or left in .env files.\n\n${list}${more}\n\nNote: Only key names are shown — no actual values are printed.`,
+    fix: `For .env files: add them to .gitignore immediately:\n  echo '.env*' >> ${workspaceDir}/.gitignore\n\nFor committed secrets, scrub git history:\n  git filter-repo --path-glob '*.env' --invert-paths\n  # or: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/removing-sensitive-data-from-a-repository\n\nRotate any exposed credentials immediately.`,
+  };
+}
+
+export default [checkGitCredentialLeak];