clawarmor 3.4.0 → 3.5.0

package/README.md

@@ -52,6 +52,7 @@ ClawArmor sits at the foundation and orchestrates the layers above it:
 | `audit` | Score your OpenClaw config (0–100), live gateway probes, plain-English verdict |
 | `scan` | Scan all installed skill files for malicious code and SKILL.md instructions |
 | `scan --json` | Machine-readable scan output — pipe to CI, scripts, or dashboards |
+| `scan --report` | Write structured JSON + Markdown reports after scanning (v3.5.0) |
 | `prescan <skill>` | Pre-scan a skill before installing — blocks on CRITICAL findings |
 | `skill verify <name>` | Deep-verify a specific installed skill — checks SKILL.md + all referenced scripts |
 | `fix` | Auto-apply safe fixes (--dry-run to preview, --apply to run) |
@@ -164,6 +165,34 @@ clawarmor harden --auto --report
 
 Report structure includes: version, timestamp, OS/OpenClaw info, summary counts (hardened/skipped/already-good), and per-check action details with before/after values.
 
+**Scan reports** (v3.5.0) — Export a structured report after scanning skills:
+
+```bash
+# Write JSON + Markdown reports (e.g. ~/.openclaw/clawarmor-scan-report-2025-03-08.json + .md)
+clawarmor scan --report
+```
+
+Two files are always written together:
+- `clawarmor-scan-report-YYYY-MM-DD.json` — machine-readable, includes per-skill status, severity, findings, and overall score
+- `clawarmor-scan-report-YYYY-MM-DD.md` — human-readable with executive summary table, findings detail, and remediation steps
+
+Example JSON structure:
+```json
+{
+  "version": "3.5.0",
+  "timestamp": "2025-03-08T12:00:00.000Z",
+  "system": { "hostname": "myhost", "platform": "darwin", "node_version": "v20.0.0", "openclaw_version": "1.2.0" },
+  "verdict": "PASS",
+  "score": 100,
+  "summary": { "total": 12, "passed": 12, "failed": 0, "warnings": 0, "critical_findings": 0, "high_findings": 0 },
+  "checks": [
+    { "name": "weather", "status": "pass", "severity": "NONE", "detail": "No findings", "type": "user" }
+  ]
+}
+```
+
+Terminal output is still shown when `--report` is used — the flag only adds file output on top.
+
 ## Philosophy
 
 ClawArmor runs entirely on your machine — no telemetry, no cloud, no accounts.

package/cli.js

@@ -3,7 +3,7 @@
 
 import { paint } from './lib/output/colors.js';
 
-const VERSION = '3.4.0';
+const VERSION = '3.5.0';
 const GATEWAY_PORT_DEFAULT = 18789;
 
 function isLocalhost(host) {
@@ -144,8 +144,13 @@ if (cmd === 'audit') {
 }
 
 if (cmd === 'scan') {
+  const scanReportIdx = args.indexOf('--report');
+  const scanFlags = {
+    json: flags.json,
+    report: scanReportIdx !== -1,
+  };
   const { runScan } = await import('./lib/scan.js');
-  process.exit(await runScan({ json: flags.json }));
+  process.exit(await runScan(scanFlags));
 }
 
 if (cmd === 'verify') {

package/lib/scan.js

@@ -1,3 +1,7 @@
+import { existsSync, writeFileSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
+import { homedir, hostname, platform } from 'os';
+import { spawnSync } from 'child_process';
 import { paint, severityColor } from './output/colors.js';
 import { scanFile } from './scanner/file-scanner.js';
 import { findInstalledSkills } from './scanner/skill-finder.js';
@@ -5,7 +9,8 @@ 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 || '';
+const HOME = homedir();
+const VERSION = '3.5.0';
 
 function short(p) { return p.replace(HOME,'~'); }
 
@@ -16,8 +21,224 @@ function box(title) {
     paint.dim('╚'+'═'.repeat(W-2)+'╝')].join('\n');
 }
 
+// ── Report support ────────────────────────────────────────────────────────────
+
+function getSystemInfo() {
+  let ocVersion = 'unknown';
+  try {
+    const r = spawnSync('openclaw', ['--version'], { encoding: 'utf8', timeout: 5000 });
+    if (r.stdout) ocVersion = r.stdout.trim().split('\n')[0] || 'unknown';
+  } catch { /* non-fatal */ }
+  return {
+    hostname: hostname(),
+    platform: platform(),
+    node_version: process.version,
+    openclaw_version: ocVersion,
+  };
+}
+
+function defaultReportBasePath() {
+  const date = new Date().toISOString().slice(0, 10); // YYYY-MM-DD
+  return join(HOME, '.openclaw', `clawarmor-scan-report-${date}`);
+}
+
+function computeScanScore(findings) {
+  let score = 100;
+  for (const f of findings) {
+    if (f.severity === 'CRITICAL') score -= 25;
+    else if (f.severity === 'HIGH') score -= 10;
+    else if (f.severity === 'MEDIUM') score -= 3;
+  }
+  return Math.max(0, score);
+}
+
+function buildReportChecks(skills, allJsonFindings) {
+  // Build per-skill check entries
+  const checks = [];
+
+  // Skills with no findings
+  for (const skill of skills) {
+    const skillFindings = allJsonFindings.filter(f => f.skill === skill.name);
+    if (!skillFindings.length) {
+      checks.push({
+        name: skill.name,
+        status: 'pass',
+        severity: 'NONE',
+        detail: 'No findings',
+        type: skill.isBuiltin ? 'builtin' : 'user',
+      });
+    } else {
+      const maxSev = ['CRITICAL','HIGH','MEDIUM','LOW','INFO'].find(s =>
+        skillFindings.some(f => f.severity === s)
+      ) || 'INFO';
+      const status = maxSev === 'CRITICAL' ? 'block' : maxSev === 'HIGH' ? 'warn' : 'info';
+      checks.push({
+        name: skill.name,
+        status,
+        severity: maxSev,
+        detail: `${skillFindings.length} finding(s): ${skillFindings.map(f => f.patternId).join(', ')}`,
+        type: skill.isBuiltin ? 'builtin' : 'user',
+        findings: skillFindings.map(f => ({
+          patternId: f.patternId,
+          severity: f.severity,
+          message: f.message,
+          file: f.file,
+          line: f.line,
+        })),
+      });
+    }
+  }
+  return checks;
+}
+
+function writeJsonReport(reportPath, { skills, allJsonFindings, totalCritical, totalHigh }) {
+  const sysInfo = getSystemInfo();
+  const checks = buildReportChecks(skills, allJsonFindings);
+  const score = computeScanScore(allJsonFindings);
+  const passed = checks.filter(c => c.status === 'pass').length;
+  const failed = checks.filter(c => c.status === 'block').length;
+  const warnings = checks.filter(c => c.status === 'warn').length;
+
+  let verdict = 'PASS';
+  if (totalCritical > 0) verdict = 'BLOCK';
+  else if (totalHigh > 0) verdict = 'WARN';
+
+  const report = {
+    version: VERSION,
+    timestamp: new Date().toISOString(),
+    system: sysInfo,
+    verdict,
+    score,
+    summary: {
+      total: checks.length,
+      passed,
+      failed,
+      warnings,
+      critical_findings: totalCritical,
+      high_findings: totalHigh,
+    },
+    checks,
+  };
+
+  try { mkdirSync(dirname(reportPath), { recursive: true }); } catch {}
+  writeFileSync(reportPath, JSON.stringify(report, null, 2), 'utf8');
+  return report;
+}
+
+function writeMarkdownReport(reportPath, { skills, allJsonFindings, totalCritical, totalHigh }) {
+  const sysInfo = getSystemInfo();
+  const checks = buildReportChecks(skills, allJsonFindings);
+  const score = computeScanScore(allJsonFindings);
+  const passed = checks.filter(c => c.status === 'pass').length;
+  const failed = checks.filter(c => c.status === 'block').length;
+  const warnings = checks.filter(c => c.status === 'warn').length;
+
+  let verdict = 'PASS';
+  if (totalCritical > 0) verdict = 'BLOCK';
+  else if (totalHigh > 0) verdict = 'WARN';
+
+  const now = new Date();
+  const dateStr = now.toLocaleString('en-US', {
+    year: 'numeric', month: '2-digit', day: '2-digit',
+    hour: '2-digit', minute: '2-digit', hour12: false
+  });
+
+  let verdictEmoji = verdict === 'BLOCK' ? '🔴' : verdict === 'WARN' ? '🟡' : '🟢';
+
+  let md = `# ClawArmor Skill Scan Report
+Generated: ${dateStr}
+ClawArmor: v${VERSION} | Hostname: ${sysInfo.hostname} | Platform: ${sysInfo.platform} | Node: ${sysInfo.node_version} | OpenClaw: ${sysInfo.openclaw_version}
+
+## Executive Summary
+
+| Metric | Value |
+|--------|-------|
+| Verdict | ${verdictEmoji} **${verdict}** |
+| Score | ${score}/100 |
+| Total Skills | ${skills.length} |
+| Passed (clean) | ✅ ${passed} |
+| Warnings | ⚠️ ${warnings} |
+| Blocked (critical) | ❌ ${failed} |
+| Critical Findings | ${totalCritical} |
+| High Findings | ${totalHigh} |
+
+`;
+
+  if (checks.some(c => c.status !== 'pass')) {
+    md += `## Skill Check Results
+
+| Skill | Type | Status | Severity | Detail |
+|-------|------|--------|----------|--------|
+`;
+    for (const check of checks) {
+      const statusEmoji = check.status === 'pass' ? '✅ pass' : check.status === 'block' ? '❌ block' : '⚠️ warn';
+      md += `| ${check.name} | ${check.type} | ${statusEmoji} | ${check.severity} | ${check.detail} |\n`;
+    }
+  } else {
+    md += `## Skill Check Results
+
+All ${skills.length} skills are clean. No findings detected.
+`;
+  }
+
+  // Detailed findings for flagged skills
+  const flaggedChecks = checks.filter(c => c.status !== 'pass' && c.findings && c.findings.length);
+  if (flaggedChecks.length) {
+    md += `
+## Findings Detail
+
+`;
+    for (const check of flaggedChecks) {
+      md += `### ${check.name} (${check.type})\n\n`;
+      md += `| Pattern ID | Severity | Message | File | Line |\n`;
+      md += `|------------|----------|---------|------|------|\n`;
+      for (const f of check.findings) {
+        md += `| ${f.patternId} | ${f.severity} | ${f.message || '—'} | ${f.file || '—'} | ${f.line ?? '—'} |\n`;
+      }
+      md += '\n';
+    }
+  }
+
+  // Remediation
+  md += `## Remediation Steps
+
+`;
+  if (totalCritical > 0) {
+    md += `### 🔴 Critical — Immediate Action Required
+
+- Remove or replace any skill with CRITICAL findings immediately
+- Run \`clawarmor prescan <skill-name>\` before reinstalling
+- Check for data exfiltration attempts: look for external HTTP calls, encoded payloads
+- Review git history of the skill if available
+
+`;
+  }
+  if (totalHigh > 0) {
+    md += `### 🟡 High — Review Before Next Session
+
+- Audit HIGH-severity skills before running your agent
+- Run \`clawarmor skill verify <name>\` for a deeper inspection
+- Consider disabling suspect skills temporarily: check your OpenClaw skill config
+
+`;
+  }
+  md += `### General
+
+- Run \`clawarmor scan\` regularly to catch new findings
+- Use \`clawarmor prescan <skill-name>\` before installing any new skill
+- Keep skills updated — malicious patterns are added to ClawArmor signatures continuously
+- Run \`clawarmor audit\` to check your broader OpenClaw configuration
+`;
+
+  try { mkdirSync(dirname(reportPath), { recursive: true }); } catch {}
+  writeFileSync(reportPath, md, 'utf8');
+}
+
+// ── Main export ───────────────────────────────────────────────────────────────
+
 export async function runScan(flags = {}) {
   const jsonMode = flags.json || false;
+  const reportMode = flags.report || false;
 
   if (!jsonMode) {
     console.log(''); console.log(box('ClawArmor Skill Scan  v0.6')); console.log('');
@@ -33,6 +254,17 @@ export async function runScan(flags = {}) {
     } else {
       console.log(`  ${paint.dim('No installed skills found.')}`); console.log('');
     }
+
+    if (reportMode) {
+      const basePath = defaultReportBasePath();
+      const jsonPath = basePath + '.json';
+      const mdPath = basePath + '.md';
+      writeJsonReport(jsonPath, { skills: [], allJsonFindings: [], totalCritical: 0, totalHigh: 0 });
+      writeMarkdownReport(mdPath, { skills: [], allJsonFindings: [], totalCritical: 0, totalHigh: 0 });
+      const date = new Date().toISOString().slice(0, 10);
+      console.log(`\n  ${paint.dim('Report saved:')} clawarmor-scan-report-${date}.json + .md`);
+    }
+
     return 0;
   }
 
@@ -46,7 +278,7 @@ export async function runScan(flags = {}) {
   let totalCritical = 0, totalHigh = 0;
   const flagged = [];
   const auditFindings = []; // accumulated for audit log
-  const jsonFindings = []; // for --json output
+  const jsonFindings = []; // for --json output and --report
 
   for (const skill of skills) {
     if (!jsonMode) process.stdout.write(`  ${skill.isBuiltin ? paint.dim('⊙') : paint.cyan('▶')} ${paint.bold(skill.name)}${paint.dim(skill.isBuiltin?' [built-in]':' [user]')}...`);
@@ -68,7 +300,7 @@ export async function runScan(flags = {}) {
 
     totalCritical += critical.length; totalHigh += high.length;
 
-    // Collect findings for JSON output
+    // Collect findings for JSON output and report
     for (const f of allFindings) {
       if (['CRITICAL','HIGH','MEDIUM','LOW'].includes(f.severity)) {
         for (const m of (f.matches || [])) {
@@ -113,13 +345,7 @@ export async function runScan(flags = {}) {
   // JSON output mode
   if (jsonMode) {
     // Compute scan score: start 100, -25 per CRITICAL, -10 per HIGH, -3 per MEDIUM
-    let scanScore = 100;
-    for (const f of jsonFindings) {
-      if (f.severity === 'CRITICAL') scanScore -= 25;
-      else if (f.severity === 'HIGH') scanScore -= 10;
-      else if (f.severity === 'MEDIUM') scanScore -= 3;
-    }
-    scanScore = Math.max(0, scanScore);
+    const scanScore = computeScanScore(jsonFindings);
 
     let verdict = 'PASS';
     if (totalCritical > 0) verdict = 'BLOCK';
@@ -210,5 +436,18 @@ export async function runScan(flags = {}) {
     skill: null,
   });
 
+  // ── Write report if requested ──────────────────────────────────────────────
+  if (reportMode) {
+    const basePath = defaultReportBasePath();
+    const jsonPath = basePath + '.json';
+    const mdPath = basePath + '.md';
+    const reportData = { skills, allJsonFindings: jsonFindings, totalCritical, totalHigh };
+    writeJsonReport(jsonPath, reportData);
+    writeMarkdownReport(mdPath, reportData);
+    const date = new Date().toISOString().slice(0, 10);
+    console.log(`  ${paint.dim('Report saved:')} clawarmor-scan-report-${date}.json + .md`);
+    console.log('');
+  }
+
   return totalCritical > 0 ? 1 : 0;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "clawarmor",
-  "version": "3.4.0",
-  "description": "Security armor for OpenClaw agents — audit, scan, monitor",
+  "version": "3.5.0",
+  "description": "Security armor for OpenClaw agents \u2014 audit, scan, monitor",
   "bin": {
     "clawarmor": "cli.js"
   },

package/sprint-output/v340-done.txt

@@ -0,0 +1,28 @@
+## What Was Shipped
+
+`clawarmor harden --report` — structured hardening report command
+
+### Changes:
+- `lib/harden.js`: Added full report support — JSON + Markdown writers, per-check tracking,
+  system info capture, report summary printer. Existing behavior unchanged when --report not passed.
+- `cli.js`: Added --report, --report-format flag parsing for harden command
+- `package.json`: Version bumped 3.3.0 → 3.4.0
+- `README.md`: Added "Hardening reports (v3.4.0)" section with all usage examples
+- `CHANGELOG.md`: Added [3.4.0] entry
+
+### Commands now supported:
+  clawarmor harden --report
+  clawarmor harden --report /path/to/report.json
+  clawarmor harden --report /path/to/report.md --report-format text
+  clawarmor harden --auto --report
+
+## npm Publish Status
+
+✅ SUCCESS — clawarmor@3.4.0 published to npm (tag: latest)
+
+## Issues Encountered
+
+None. All three test cases passed:
+1. `clawarmor harden --report` → wrote valid JSON to default path
+2. `clawarmor harden --report /tmp/test-report.md --report-format text` → wrote clean Markdown
+3. `clawarmor harden --auto --report /tmp/test-report.json` → wrote valid JSON

package/sprint-output/v340-sprint-report.md

@@ -0,0 +1,130 @@
+# ClawArmor v3.4.0 Sprint Report
+**Sprint:** `harden --report` feature
+**Date:** 2026-03-08
+**Status:** ✅ SHIPPED
+
+---
+
+## Summary
+
+Shipped `clawarmor harden --report` — a portable hardening report command that exports a structured summary of every hardening run.
+
+## Done Criteria
+
+- [x] `clawarmor harden --report` runs and writes JSON report to `~/.openclaw/clawarmor-harden-report-YYYY-MM-DD.json`
+- [x] `clawarmor harden --report /tmp/test.md --report-format text` writes Markdown report
+- [x] `npm publish` succeeded — v3.4.0 live on npm
+- [x] README updated with new `--report` flag and example output
+- [x] Sprint report written to `~/clawarmor/sprint-output/v340-sprint-report.md`
+
+---
+
+## Changes Shipped
+
+### `lib/harden.js`
+- Added `--report` flag support via `flags.report`, `flags.reportPath`, `flags.reportFormat`
+- Added `getSystemInfo()` — captures OS and OpenClaw version for report metadata
+- Added `defaultReportPath(format)` — auto-generates path `~/.openclaw/clawarmor-harden-report-YYYY-MM-DD.{json|md}`
+- Added `buildReportItems()` — assembles per-check items from applied/skipped/failed tracking
+- Added `writeJsonReport()` — writes structured JSON with version, timestamp, system, summary, items
+- Added `writeMarkdownReport()` — writes human-readable Markdown table with summary, actions, skipped, failed
+- Added `printReportSummary()` — prints inline summary to stdout after writing the report
+- Modified main loop to track `appliedIds`, `skippedIds`, `failedIds`, `applyResults` per fix
+- Added `_reportBefore` and `_reportAfter` fields to each fix for before/after capture
+- Existing behavior **fully preserved** when `--report` not passed
+
+### `cli.js`
+- Added `--report`, `--report-format`, `--report-path` flag parsing for `harden` command
+- `--report` can be bare flag or `--report <path>` (path detected if next arg doesn't start with `--`)
+- Version constant bumped: `3.3.0` → `3.4.0`
+
+### `package.json`
+- Version bumped to `3.4.0`
+
+### `README.md`
+- Updated harden command row to include `--report`
+- Added new "Hardening reports (v3.4.0)" section with all usage examples
+
+### `CHANGELOG.md`
+- Added `[3.4.0]` entry with full feature description and examples
+
+---
+
+## Report Format: JSON
+
+```json
+{
+  "version": "3.4.0",
+  "timestamp": "2026-03-08T07:11:00.023Z",
+  "system": {
+    "os": "darwin 24.3.0",
+    "openclaw_version": "2026.2.26"
+  },
+  "summary": {
+    "total_checks": 3,
+    "hardened": 1,
+    "already_good": 0,
+    "skipped": 2,
+    "failed": 0
+  },
+  "items": [
+    {
+      "check": "exec.ask.off",
+      "status": "hardened",
+      "before": "off",
+      "after": "on-miss",
+      "action": "Enable exec approval for unrecognized commands"
+    },
+    {
+      "check": "gateway.host.open",
+      "status": "skipped",
+      "skipped_reason": "Breaking fix — skipped in auto mode (use --auto --force to include)"
+    }
+  ]
+}
+```
+
+## Report Format: Markdown
+
+```markdown
+# ClawArmor Hardening Report
+Generated: 03/07/2026, 23:07
+ClawArmor: v3.4.0 | OS: darwin 24.3.0 | OpenClaw: 2026.2.26
+
+## Summary
+- ✅ 0 checks already good
+- 🔧 1 hardened
+- ⚠️  2 skipped
+
+## Actions Taken
+
+| Check | Before | After | Action |
+|-------|--------|-------|--------|
+| exec.ask.off | off | on-miss | Enable exec approval... |
+
+## Skipped
+
+- **gateway.host.open**: Breaking fix — skipped in auto mode
+```
+
+---
+
+## npm Publish
+
+```
+npm notice name: clawarmor
+npm notice version: 3.4.0
+npm notice total files: 67
++ clawarmor@3.4.0
+```
+
+Published with tag: `latest`
+Registry: https://registry.npmjs.org/
+
+---
+
+## Git
+
+- Commit: `d856232`
+- Branch: `main`
+- Pushed: `origin/main`