@denial-web/clawguard 0.1.0

package/src/clawhub.js

@@ -0,0 +1,383 @@
+import path from "node:path";
+
+export function analyzeClawHubMetadata(fileRecords, basePath = process.cwd()) {
+  const findings = [];
+  const metadataRecords = fileRecords.filter((record) => isClawHubMetadataFile(record.file, basePath));
+  const lockRecords = metadataRecords.filter((record) => isLockFile(record.file, basePath));
+  const originRecords = metadataRecords.filter((record) => isOriginFile(record.file, basePath));
+  const skillRecords = fileRecords.filter((record) => isSkillFile(record.file));
+  const skills = skillRecords.map((record) => parseSkill(record, basePath)).filter(Boolean);
+  const lock = parseLock(lockRecords[0], basePath, findings);
+  const origins = originRecords.map((record) => parseOrigin(record, basePath, findings)).filter(Boolean);
+
+  if (!lock && origins.length > 0) {
+    for (const origin of origins) {
+      findings.push(createFinding({
+        ruleId: "clawhub-missing-lockfile",
+        title: "ClawHub origin metadata exists without a lockfile",
+        severity: "medium",
+        recommendation: "Commit or regenerate .clawhub/lock.json so installed ClawHub skills have auditable source and version state.",
+        file: origin.file,
+        line: 1,
+        evidence: `${origin.skillDir} has origin metadata but no .clawhub/lock.json`
+      }));
+    }
+  }
+
+  if (lock) {
+    for (const entry of lock.entries) {
+      const origin = findMatchingOrigin(entry, origins);
+      const skill = findMatchingSkill(entry, skills);
+
+      if (!origin) {
+        findings.push(createFinding({
+          ruleId: "clawhub-missing-origin",
+          title: "ClawHub lock entry is missing local origin metadata",
+          severity: "medium",
+          recommendation: "Add per-skill origin metadata or reinstall from ClawHub so source provenance can be reviewed.",
+          file: lock.file,
+          line: 1,
+          evidence: `${entry.name} (${entry.skillDir})`
+        }));
+      }
+
+      findings.push(...compareVersions(entry, origin, skill, lock.file));
+      findings.push(...compareSources(entry, origin, lock.file));
+      findings.push(...checkSourceTrust(entry, origin, lock.file));
+    }
+  }
+
+  for (const origin of origins) {
+    findings.push(...checkSourceTrust(null, origin, origin.file));
+  }
+
+  return {
+    findings: dedupeFindings(findings),
+    clawhub: {
+      lockfile: lock?.file ?? null,
+      entries: lock?.entries.map(publicMetadata) ?? [],
+      origins: origins.map(publicMetadata)
+    }
+  };
+}
+
+export function isClawHubMetadataFile(filePath, basePath = process.cwd()) {
+  const relative = toPosixPath(relativePath(basePath, filePath));
+  return relative === ".clawhub/lock.json" || relative.endsWith("/.clawhub/origin.json") || relative === ".clawhub/origin.json";
+}
+
+function parseLock(record, basePath, findings) {
+  if (!record) {
+    return null;
+  }
+
+  const parsed = parseJsonRecord(record, basePath, findings);
+  if (!parsed.ok) {
+    return null;
+  }
+
+  return {
+    file: relativePath(basePath, record.file),
+    entries: extractLockEntries(parsed.value)
+  };
+}
+
+function parseOrigin(record, basePath, findings) {
+  const parsed = parseJsonRecord(record, basePath, findings);
+  if (!parsed.ok) {
+    return null;
+  }
+
+  const relative = toPosixPath(relativePath(basePath, record.file));
+  const skillDir = skillDirForOrigin(relative);
+  const metadata = normalizeMetadata(parsed.value, "", skillDir);
+
+  return {
+    ...metadata,
+    file: relative,
+    skillDir
+  };
+}
+
+function parseJsonRecord(record, basePath, findings) {
+  try {
+    return {
+      ok: true,
+      value: JSON.parse(record.text)
+    };
+  } catch (error) {
+    findings.push(createFinding({
+      ruleId: "invalid-clawhub-metadata",
+      title: "ClawHub metadata is not valid JSON",
+      severity: "medium",
+      recommendation: "Fix invalid ClawHub metadata so source and version provenance can be reviewed.",
+      file: relativePath(basePath, record.file),
+      line: 1,
+      evidence: error.message
+    }));
+
+    return { ok: false };
+  }
+}
+
+function extractLockEntries(value) {
+  const rawEntries = [];
+
+  if (Array.isArray(value?.skills)) {
+    rawEntries.push(...value.skills.map((entry) => [entry.name ?? entry.slug ?? "", entry]));
+  } else if (value?.skills && typeof value.skills === "object") {
+    rawEntries.push(...Object.entries(value.skills));
+  }
+
+  if (Array.isArray(value?.packages)) {
+    rawEntries.push(...value.packages.map((entry) => [entry.name ?? entry.slug ?? "", entry]));
+  } else if (value?.packages && typeof value.packages === "object") {
+    rawEntries.push(...Object.entries(value.packages));
+  }
+
+  if (rawEntries.length === 0 && value && typeof value === "object") {
+    for (const [key, entry] of Object.entries(value)) {
+      if (entry && typeof entry === "object" && hasMetadataShape(entry)) {
+        rawEntries.push([key, entry]);
+      }
+    }
+  }
+
+  return rawEntries.map(([key, entry]) => normalizeMetadata(entry, key)).filter((entry) => entry.name || entry.skillDir);
+}
+
+function normalizeMetadata(entry, fallbackName = "", fallbackSkillDir = "") {
+  const value = entry && typeof entry === "object" ? entry : {};
+  const name = clean(value.name ?? value.slug ?? value.id ?? value.package ?? fallbackName);
+  const version = clean(value.version ?? value.ref ?? value.tag ?? "");
+  const source = clean(value.source ?? value.repository ?? value.repo ?? value.url ?? value.origin ?? value.homepage ?? "");
+  const skillDir = toPosixPath(clean(value.path ?? value.dir ?? value.target ?? fallbackSkillDir ?? (name ? `skills/${name}` : "")));
+
+  return {
+    name,
+    version,
+    source,
+    skillDir
+  };
+}
+
+function parseSkill(record, basePath) {
+  const relative = toPosixPath(relativePath(basePath, record.file));
+  if (!relative.startsWith("skills/") && !relative.startsWith(".agents/skills/")) {
+    return null;
+  }
+
+  const lines = record.text.replace(/^\uFEFF/, "").split(/\r?\n/);
+  let name = path.basename(path.dirname(record.file));
+  let version = "";
+
+  if (lines[0]?.trim() === "---") {
+    const endIndex = lines.findIndex((line, index) => index > 0 && ["---", "..."].includes(line.trim()));
+    const end = endIndex === -1 ? lines.length : endIndex;
+
+    for (let index = 1; index < end; index += 1) {
+      const nameMatch = /^name\s*:\s*(.+)\s*$/i.exec(lines[index].trim());
+      const versionMatch = /^version\s*:\s*(.+)\s*$/i.exec(lines[index].trim());
+
+      if (nameMatch) {
+        name = clean(nameMatch[1]);
+      }
+
+      if (versionMatch) {
+        version = clean(versionMatch[1]);
+      }
+    }
+  }
+
+  return {
+    name,
+    version,
+    skillDir: toPosixPath(path.dirname(relative)),
+    file: relative
+  };
+}
+
+function compareVersions(lockEntry, origin, skill, lockFile) {
+  const findings = [];
+  const comparisons = [
+    ["lock", lockEntry?.version, "origin", origin?.version],
+    ["lock", lockEntry?.version, "skill", skill?.version],
+    ["origin", origin?.version, "skill", skill?.version]
+  ];
+
+  for (const [leftName, leftVersion, rightName, rightVersion] of comparisons) {
+    if (leftVersion && rightVersion && leftVersion !== rightVersion) {
+      findings.push(createFinding({
+        ruleId: "clawhub-version-drift",
+        title: "ClawHub metadata version differs from local skill state",
+        severity: "medium",
+        recommendation: "Review the installed skill version and refresh ClawHub metadata before trusting or publishing.",
+        file: skill?.file ?? origin?.file ?? lockFile,
+        line: 1,
+        evidence: `${lockEntry.name}: ${leftName}=${leftVersion}, ${rightName}=${rightVersion}`
+      }));
+    }
+  }
+
+  return findings;
+}
+
+function compareSources(lockEntry, origin, lockFile) {
+  if (!lockEntry?.source || !origin?.source || lockEntry.source === origin.source) {
+    return [];
+  }
+
+  return [
+    createFinding({
+      ruleId: "clawhub-source-drift",
+      title: "ClawHub lock source differs from origin metadata",
+      severity: "high",
+      recommendation: "Confirm whether the installed skill was moved, replaced, or modified outside the recorded ClawHub source.",
+      file: origin.file ?? lockFile,
+      line: 1,
+      evidence: `${lockEntry.name}: lock=${lockEntry.source}, origin=${origin.source}`
+    })
+  ];
+}
+
+function checkSourceTrust(lockEntry, origin, fallbackFile) {
+  const source = origin?.source || lockEntry?.source || "";
+
+  if (!source || isTrustedSource(source)) {
+    return [];
+  }
+
+  return [
+    createFinding({
+      ruleId: "clawhub-untrusted-source",
+      title: "ClawHub metadata references an untrusted or unusual source",
+      severity: "medium",
+      recommendation: "Review the source manually and prefer official ClawHub/OpenClaw or trusted organization repositories.",
+      file: origin?.file ?? fallbackFile,
+      line: 1,
+      evidence: source
+    })
+  ];
+}
+
+function findMatchingOrigin(entry, origins) {
+  return origins.find((origin) => metadataMatches(entry, origin));
+}
+
+function findMatchingSkill(entry, skills) {
+  return skills.find((skill) => metadataMatches(entry, skill));
+}
+
+function metadataMatches(left, right) {
+  if (!left || !right) {
+    return false;
+  }
+
+  return (
+    (left.skillDir && right.skillDir && left.skillDir === right.skillDir) ||
+    (left.name && right.name && left.name.toLowerCase() === right.name.toLowerCase())
+  );
+}
+
+function isTrustedSource(source) {
+  if (source.startsWith("clawhub:") || source.startsWith("openclaw:")) {
+    return true;
+  }
+
+  try {
+    const url = new URL(source);
+    const host = url.hostname.toLowerCase();
+    const pathname = url.pathname.toLowerCase();
+
+    return (
+      url.protocol === "https:" &&
+      (
+        host === "docs.openclaw.ai" ||
+        (host === "github.com" && (pathname.startsWith("/openclaw/") || pathname.startsWith("/denial-web/")))
+      )
+    );
+  } catch {
+    return false;
+  }
+}
+
+function skillDirForOrigin(relativePathValue) {
+  const normalized = toPosixPath(relativePathValue);
+
+  if (normalized === ".clawhub/origin.json") {
+    return "";
+  }
+
+  return toPosixPath(path.dirname(path.dirname(normalized)));
+}
+
+function hasMetadataShape(value) {
+  return ["version", "source", "repository", "repo", "url", "origin", "path", "dir", "target"].some((key) => key in value);
+}
+
+function isLockFile(filePath, basePath) {
+  return toPosixPath(relativePath(basePath, filePath)) === ".clawhub/lock.json";
+}
+
+function isOriginFile(filePath, basePath) {
+  const relative = toPosixPath(relativePath(basePath, filePath));
+  return relative.endsWith("/.clawhub/origin.json") || relative === ".clawhub/origin.json";
+}
+
+function isSkillFile(file) {
+  return ["skill.md", "SKILL.md"].includes(path.basename(file));
+}
+
+function publicMetadata(metadata) {
+  return {
+    name: metadata.name,
+    version: metadata.version,
+    source: metadata.source,
+    skillDir: metadata.skillDir
+  };
+}
+
+function dedupeFindings(findings) {
+  const seen = new Set();
+  const unique = [];
+
+  for (const finding of findings) {
+    const key = `${finding.ruleId}:${finding.file}:${finding.evidence}`;
+    if (seen.has(key)) {
+      continue;
+    }
+
+    seen.add(key);
+    unique.push(finding);
+  }
+
+  return unique;
+}
+
+function createFinding({ ruleId, title, severity, recommendation, file, line, evidence }) {
+  return {
+    ruleId,
+    title,
+    severity,
+    recommendation,
+    file,
+    line,
+    evidence
+  };
+}
+
+function clean(value) {
+  return String(value ?? "")
+    .trim()
+    .replace(/^["']+|["']+$/g, "")
+    .trim();
+}
+
+function toPosixPath(value) {
+  return String(value ?? "").split(path.sep).join("/");
+}
+
+function relativePath(basePath, filePath) {
+  const relative = path.relative(basePath, filePath);
+  return relative || path.basename(filePath);
+}

package/src/cli.js

@@ -0,0 +1,296 @@
+#!/usr/bin/env node
+
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { loadConfig, mergeConfig, parseSize } from "./config.js";
+import { policyShouldFail } from "./policy.js";
+import { createHtmlReport } from "./reporters/html.js";
+import { createSarifReport } from "./reporters/sarif.js";
+import { scanTarget } from "./scanner.js";
+
+const args = process.argv.slice(2);
+const failLevels = ["none", "low", "medium", "high", "critical"];
+const policyPresets = ["personal", "governed", "enterprise"];
+const policyFailDecisions = ["warn", "manual_review", "sandbox_required", "dual_approval", "block"];
+const riskOrder = {
+  info: 0,
+  low: 1,
+  medium: 2,
+  high: 3,
+  critical: 4
+};
+
+if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
+  printHelp();
+  process.exit(0);
+}
+
+const command = args[0];
+
+if (!["scan", "scan-workspace"].includes(command)) {
+  console.error(`Unknown command: ${command}`);
+  printHelp();
+  process.exit(1);
+}
+
+try {
+  const cliOptions = parseOptions(args.slice(1));
+  const loadedConfig = await loadConfig(cliOptions.target, cliOptions.configPath);
+  const options = mergeConfig(loadedConfig.config, cliOptions);
+  const result = await scanTarget(options.target, {
+    maxFileSizeBytes: options.maxFileSizeBytes,
+    maxFindingsPerRulePerFile: options.maxFindingsPerRulePerFile,
+    policy: options.policy,
+    suppressions: options.suppressions
+  });
+
+  result.configPath = loadedConfig.path;
+
+  if (options.sarifPath) {
+    await writeReportFile(options.sarifPath, JSON.stringify(createSarifReport(result), null, 2));
+  }
+
+  if (options.htmlPath) {
+    await writeReportFile(options.htmlPath, createHtmlReport(result));
+  }
+
+  if (options.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    printHumanResult(result, options);
+  }
+
+  process.exit(shouldFail(result, options) ? 2 : 0);
+} catch (error) {
+  console.error(`Scan failed: ${error.message}`);
+  process.exit(1);
+}
+
+function printHelp() {
+  console.log(`ClawGuard
+
+Usage:
+  clawguard scan <path> [--json] [--policy <preset>] [--fail-on <level>]
+  clawguard scan-workspace <path> [--json] [--policy <preset>]
+  npm run scan -- <path>
+
+Options:
+  --json                  Print machine-readable JSON.
+  --config <path>         Load a specific .clawguard.json config file.
+  --html <path>           Write a self-contained HTML report.
+  --sarif <path>          Write SARIF 2.1.0 report for GitHub code scanning.
+  --policy <preset>       Policy preset: personal, governed, enterprise.
+                          Default: personal, unless configured.
+  --fail-on <level>       Exit 2 at this level or higher. Levels: none, low, medium, high, critical.
+                          Default: critical.
+  --fail-on-policy        Exit 2 when policy decision reaches policyFailOn.
+  --policy-fail-on <name> Decision threshold for --fail-on-policy.
+                          Values: warn, manual_review, sandbox_required, dual_approval, block.
+                          Default: manual_review.
+  --max-file-size <size>  Skip individual files larger than this size. Examples: 512kb, 1mb.
+                          Default: 1mb.
+
+Examples:
+  npm run scan -- examples/risky-skill
+  npm run scan -- examples/metadata-mismatch-skill --policy governed --fail-on-policy
+  npm run scan -- examples/metadata-mismatch-skill --html clawguard.html
+  npm run scan -- examples/metadata-mismatch-skill --sarif clawguard.sarif
+  node src/cli.js scan-workspace examples/openclaw-workspace
+  npm run scan -- examples/risky-skill --fail-on medium
+  node src/cli.js scan examples/safe-skill --json
+`);
+}
+
+function printHumanResult(result, options) {
+  console.log(`ClawGuard scan: ${result.target}`);
+  console.log(`Risk: ${result.level.toUpperCase()} (${result.score}/100)`);
+  console.log(`Policy: ${result.policy.decision} (${result.policy.preset})`);
+  console.log(`Files scanned: ${result.filesScanned}`);
+  console.log(`Files skipped: ${result.filesSkipped}`);
+  console.log(`Fail threshold: ${options.failOn}`);
+  if (options.failOnPolicy) {
+    console.log(`Policy fail threshold: ${options.policyFailOn}`);
+  }
+  if (result.configPath) {
+    console.log(`Config: ${result.configPath}`);
+  }
+
+  if (result.policy.decision !== "allow") {
+    console.log(`Policy reason: ${result.policy.reason}`);
+    if (result.policy.requiredActions.length > 0) {
+      console.log(`Required actions: ${result.policy.requiredActions.join(", ")}`);
+    }
+  }
+
+  if (result.workspace?.skills?.length > 0) {
+    console.log(`Workspace skills: ${result.workspace.skills.length}`);
+    if (result.workspace.duplicates.length > 0) {
+      console.log(`Workspace duplicates: ${result.workspace.duplicates.length}`);
+    }
+  }
+
+  if (result.clawhub?.entries?.length > 0 || result.clawhub?.origins?.length > 0) {
+    console.log(`ClawHub lockfile: ${result.clawhub.lockfile ?? "none"}`);
+    console.log(`ClawHub entries: ${result.clawhub.entries?.length ?? 0}`);
+    console.log(`ClawHub origins: ${result.clawhub.origins?.length ?? 0}`);
+  }
+
+  if (result.dependencies?.manifests?.length > 0 || result.dependencies?.lockfiles?.length > 0) {
+    console.log(`Dependency manifests: ${result.dependencies.manifests?.length ?? 0}`);
+    console.log(`Dependency lockfiles: ${result.dependencies.lockfiles?.length ?? 0}`);
+  }
+
+  if (result.skippedFiles.length > 0) {
+    console.log("\nSkipped files:");
+    for (const skipped of result.skippedFiles) {
+      const detail = skipped.detail ? ` (${skipped.detail})` : "";
+      console.log(`- ${skipped.file}: ${skipped.reason}${detail}`);
+    }
+  }
+
+  if (result.findings.length === 0) {
+    console.log("\nNo risky patterns detected.");
+    return;
+  }
+
+  if (result.suppressedFindings.length > 0) {
+    console.log("\nSuppressed findings:");
+    for (const finding of result.suppressedFindings) {
+      console.log(`- [${finding.severity.toUpperCase()}] ${finding.title}`);
+      console.log(`  ${finding.file}:${finding.line}`);
+      console.log(`  Reason: ${finding.suppressionReason}`);
+    }
+  }
+
+  console.log("\nFindings:");
+  for (const finding of result.findings) {
+    console.log(`- [${finding.severity.toUpperCase()}] ${finding.title}`);
+    console.log(`  ${finding.file}:${finding.line}`);
+    console.log(`  Evidence: ${finding.evidence}`);
+    console.log(`  Recommendation: ${finding.recommendation}`);
+  }
+}
+
+function parseOptions(values) {
+  const options = {
+    json: false,
+    configPath: undefined,
+    htmlPath: undefined,
+    sarifPath: undefined,
+    failOn: undefined,
+    failOnPolicy: undefined,
+    policy: undefined,
+    policyFailOn: undefined,
+    maxFileSizeBytes: undefined,
+    target: "."
+  };
+  const paths = [];
+
+  for (let index = 0; index < values.length; index += 1) {
+    const value = values[index];
+
+    if (value === "--json") {
+      options.json = true;
+      continue;
+    }
+
+    if (value === "--sarif") {
+      options.sarifPath = requireNextValue(values, index, "--sarif");
+      index += 1;
+      continue;
+    }
+
+    if (value === "--html") {
+      options.htmlPath = requireNextValue(values, index, "--html");
+      index += 1;
+      continue;
+    }
+
+    if (value === "--") {
+      continue;
+    }
+
+    if (value === "--config") {
+      options.configPath = requireNextValue(values, index, "--config");
+      index += 1;
+      continue;
+    }
+
+    if (value === "--policy") {
+      const policy = requireNextValue(values, index, "--policy");
+      if (!policyPresets.includes(policy)) {
+        throw new Error(`Invalid --policy value. Use one of: ${policyPresets.join(", ")}`);
+      }
+      options.policy = policy;
+      index += 1;
+      continue;
+    }
+
+    if (value === "--fail-on") {
+      const level = requireNextValue(values, index, "--fail-on");
+      if (!failLevels.includes(level)) {
+        throw new Error(`Invalid --fail-on value. Use one of: ${failLevels.join(", ")}`);
+      }
+      options.failOn = level;
+      index += 1;
+      continue;
+    }
+
+    if (value === "--fail-on-policy") {
+      options.failOnPolicy = true;
+      continue;
+    }
+
+    if (value === "--policy-fail-on") {
+      const decision = requireNextValue(values, index, "--policy-fail-on");
+      if (!policyFailDecisions.includes(decision)) {
+        throw new Error(`Invalid --policy-fail-on value. Use one of: ${policyFailDecisions.join(", ")}`);
+      }
+      options.policyFailOn = decision;
+      index += 1;
+      continue;
+    }
+
+    if (value === "--max-file-size") {
+      const size = requireNextValue(values, index, "--max-file-size");
+      options.maxFileSizeBytes = parseSize(size);
+      index += 1;
+      continue;
+    }
+
+    if (value.startsWith("--")) {
+      throw new Error(`Unknown option: ${value}`);
+    }
+
+    paths.push(value);
+  }
+
+  options.target = paths[0] ?? ".";
+  return options;
+}
+
+async function writeReportFile(outputPath, content) {
+  const resolvedPath = path.resolve(outputPath);
+  await fs.mkdir(path.dirname(resolvedPath), { recursive: true });
+  await fs.writeFile(resolvedPath, `${content}\n`);
+}
+
+function requireNextValue(values, index, optionName) {
+  const value = values[index + 1];
+  if (!value || value.startsWith("--")) {
+    throw new Error(`Missing value for ${optionName}`);
+  }
+  return value;
+}
+
+function shouldFail(result, options) {
+  if (options.failOn !== "none" && riskOrder[result.level] >= riskOrder[options.failOn]) {
+    return true;
+  }
+
+  if (!options.failOnPolicy) {
+    return false;
+  }
+
+  return policyShouldFail(result.policy, options.policyFailOn);
+}