@denial-web/clawguard 0.1.3 → 0.1.4

package/README.md

@@ -59,6 +59,15 @@ npx @denial-web/clawguard install ./path/to/skill --to ./.agents/skills --policy
 
 Install mode never executes scanned files or installs dependencies. It refuses warn/review/sandbox/block decisions before copying files.
 
+For agent systems that search and install skills automatically, keep discovery native and gate only the install step:
+
+```bash
+npx @denial-web/clawguard openclaw install ./candidate-skill --to ./.agents/skills --approval-out ./.clawguard/approvals.jsonl
+npx @denial-web/clawguard hermes install ./candidate-skill --to ~/.hermes/skills --approval-out ./.clawguard/approvals.jsonl
+```
+
+The approval JSONL payload is designed for a bot or daemon to forward to WhatsApp, Telegram, Slack, Discord, or another owner channel before any files are copied into a trusted skill folder.
+
 When testing the published package, run `npx` from outside this repository. From inside the ClawGuard source checkout, use the local commands instead:
 
 ```bash

package/docs/INTEGRATION_SPEC.md

@@ -13,6 +13,32 @@ This spec defines how ClawGuard should work with OpenClaw, ClawHub, GitHub, web
 
 ## OpenClaw Integration
 
+### Guarded Install With Owner Approval
+
+Current wrapper pattern:
+
+```bash
+clawguard openclaw install ./candidate-skill \
+  --to ./.agents/skills \
+  --approval-out ./.clawguard/approvals.jsonl
+```
+
+This does not block OpenClaw or ClawHub discovery. Search and candidate selection can stay native. ClawGuard sits between the downloaded candidate and the trusted skill folder:
+
+```text
+native search/discovery
+        ↓
+candidate skill bundle
+        ↓
+clawguard openclaw install
+        ↓
+allow / approval request / block
+        ↓
+trusted skill folder
+```
+
+If `--approval-out` is set, non-allow decisions create a pending approval JSON payload instead of copying files. With `--approval-mode always`, even allow decisions pause for explicit owner approval. A messaging adapter can forward the `message` field to WhatsApp, Telegram, Slack, Discord, or another owner channel.
+
 ### Skill Folder Scan
 
 Command:
@@ -107,6 +133,20 @@ Current implementation:
 - Reports missing lockfile, missing origin metadata, version drift, source drift, invalid metadata, and unusual source URLs.
 - Adds a `clawhub` summary to JSON and HTML reports.
 
+## Hermes Agent Integration
+
+Current wrapper pattern:
+
+```bash
+clawguard hermes install ./candidate-skill \
+  --to ~/.hermes/skills \
+  --approval-out ./.clawguard/approvals.jsonl
+```
+
+The first integration target is the same as OpenClaw: do not interfere with search or discovery. Scan the candidate before it is copied into a trusted Hermes skill directory, and emit an approval request when policy says the owner should decide.
+
+ClawGuard is independent and not affiliated with Hermes Agent or Nous Research.
+
 ### Metadata Comparison
 
 ClawGuard should compare:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@denial-web/clawguard",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Explainable security scanner for OpenClaw-style skills and MCP tool configs.",
   "type": "module",
   "repository": {

package/src/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 import { promises as fs } from "node:fs";
+import { randomUUID } from "node:crypto";
 import path from "node:path";
 import { loadConfig, mergeConfig, parseSize } from "./config.js";
 import { policyShouldFail } from "./policy.js";
@@ -25,7 +26,8 @@ if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
   process.exit(0);
 }
 
-const command = args[0];
+const commandContext = parseCommand(args);
+const { command, framework, optionValues } = commandContext;
 
 if (!["scan", "scan-workspace", "gate", "install"].includes(command)) {
   console.error(`Unknown command: ${command}`);
@@ -34,9 +36,11 @@ if (!["scan", "scan-workspace", "gate", "install"].includes(command)) {
 }
 
 try {
-  const cliOptions = parseOptions(args.slice(1));
+  const cliOptions = parseOptions(optionValues);
+  cliOptions.framework = framework;
   const loadedConfig = await loadConfig(cliOptions.target, cliOptions.configPath);
   const options = mergeConfig(loadedConfig.config, cliOptions);
+  options.framework = framework;
   const result = await scanTarget(options.target, {
     maxFileSizeBytes: options.maxFileSizeBytes,
     maxFindingsPerRulePerFile: options.maxFindingsPerRulePerFile,
@@ -54,6 +58,8 @@ try {
     await writeReportFile(options.htmlPath, createHtmlReport(result));
   }
 
+  let exitCode;
+
   if (command === "install") {
     const install = await handleInstall(result, options);
     if (options.json) {
@@ -61,6 +67,7 @@ try {
     } else {
       printInstallResult(result, install);
     }
+    exitCode = installExitCode(result.policy.decision, install);
   } else if (command === "gate") {
     if (options.json) {
       console.log(JSON.stringify(createGateResult(result), null, 2));
@@ -73,7 +80,7 @@ try {
     printHumanResult(result, options);
   }
 
-  process.exit(["gate", "install"].includes(command) ? gateExitCode(result.policy.decision) : shouldFail(result, options) ? 2 : 0);
+  process.exit(exitCode ?? (command === "gate" ? gateExitCode(result.policy.decision) : shouldFail(result, options) ? 2 : 0));
 } catch (error) {
   console.error(`${commandLabel(command)} failed: ${error.message}`);
   process.exit(1);
@@ -86,6 +93,8 @@ Usage:
   clawguard scan <path> [--json] [--policy <preset>] [--fail-on <level>]
   clawguard gate <path> [--json] [--policy <preset>]
   clawguard install <path> --to <dir> [--policy <preset>] [--dry-run]
+  clawguard openclaw install <path> --to <dir> [--approval-out <path>]
+  clawguard hermes install <path> --to <dir> [--approval-out <path>]
   clawguard scan-workspace <path> [--json] [--policy <preset>]
   npm run scan -- <path>
 
@@ -107,6 +116,9 @@ Options:
   --to <dir>              Install destination parent directory for install mode.
   --name <name>           Install folder/file name. Defaults to the source basename.
   --dry-run               Run install gate and show the destination without copying files.
+  --approval-out <path>   Write a pending approval JSON request before copying.
+                          Use .jsonl to append JSON lines for bot/daemon integrations.
+  --approval-mode <mode>  Approval mode: non-allow, always. Default: non-allow.
 
 Gate exit codes:
   0 = allow
@@ -117,6 +129,8 @@ Examples:
   npx @denial-web/clawguard gate ./skills/my-skill
   npx @denial-web/clawguard gate ./skills/my-skill --policy governed
   npx @denial-web/clawguard install ./skills/my-skill --to ./.agents/skills --policy governed
+  npx @denial-web/clawguard openclaw install ./skills/my-skill --to ./.agents/skills --approval-out ./.clawguard/approvals.jsonl
+  npx @denial-web/clawguard hermes install ./skills/my-skill --to ~/.hermes/skills --approval-out ./.clawguard/approvals.jsonl
   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
@@ -197,6 +211,42 @@ function printHumanResult(result, options) {
   }
 }
 
+function parseCommand(values) {
+  const rawCommand = values[0];
+
+  if (["openclaw", "hermes"].includes(rawCommand)) {
+    const nestedCommand = values[1];
+
+    if (!nestedCommand) {
+      return {
+        command: "",
+        framework: rawCommand,
+        optionValues: []
+      };
+    }
+
+    if (!["gate", "install"].includes(nestedCommand)) {
+      return {
+        command: `${rawCommand} ${nestedCommand}`,
+        framework: rawCommand,
+        optionValues: values.slice(2)
+      };
+    }
+
+    return {
+      command: nestedCommand,
+      framework: rawCommand,
+      optionValues: values.slice(2)
+    };
+  }
+
+  return {
+    command: rawCommand,
+    framework: undefined,
+    optionValues: values.slice(1)
+  };
+}
+
 function printGateResult(result, options) {
   const decision = result.policy.decision;
   console.log(`ClawGuard gate: ${result.target}`);
@@ -243,10 +293,18 @@ async function handleInstall(result, options) {
   const install = {
     destination,
     dryRun: options.dryRun,
+    framework: options.framework,
     installed: false,
-    skipped: decision !== "allow"
+    skipped: decision !== "allow",
+    approvalRequest: null
   };
 
+  if (shouldCreateApprovalRequest(decision, options)) {
+    install.approvalRequest = await writeApprovalRequest(result, install, options);
+    install.skipped = true;
+    return install;
+  }
+
   if (decision !== "allow") {
     return install;
   }
@@ -277,10 +335,13 @@ async function handleInstall(result, options) {
 function printInstallResult(result, install) {
   const decision = result.policy.decision;
   console.log(`ClawGuard install: ${result.target}`);
+  if (install.framework) {
+    console.log(`Framework: ${displayFramework(install.framework)}`);
+  }
   console.log(`Decision: ${formatDecision(decision)}`);
   console.log(`Risk: ${result.level.toUpperCase()} (${result.score}/100)`);
   console.log(`Policy: ${result.policy.preset}`);
-  console.log(`Exit code: ${gateExitCode(decision)}`);
+  console.log(`Exit code: ${installExitCode(decision, install)}`);
   console.log(`Destination: ${install.destination ?? "not selected"}`);
   console.log(`Installed: ${install.installed ? "yes" : "no"}`);
 
@@ -292,7 +353,11 @@ function printInstallResult(result, install) {
     console.log(`Required actions: ${result.policy.requiredActions.join(", ")}`);
   }
 
-  if (decision === "allow" && install.installed) {
+  if (install.approvalRequest) {
+    console.log(`Approval request: ${install.approvalRequest.path}`);
+    console.log(`Approval id: ${install.approvalRequest.id}`);
+    console.log("\nInstall result: pending user approval before copying files.");
+  } else if (decision === "allow" && install.installed) {
     console.log("\nInstall result: copied after passing the selected policy.");
   } else if (decision === "allow" && install.dryRun) {
     console.log("\nInstall result: dry run passed; no files were copied.");
@@ -308,10 +373,13 @@ function printInstallResult(result, install) {
 function createInstallResult(result, install) {
   return {
     ...createGateResult(result),
+    exitCode: installExitCode(result.policy.decision, install),
+    framework: install.framework,
     destination: install.destination,
     installed: install.installed,
     dryRun: install.dryRun,
-    skipped: install.skipped
+    skipped: install.skipped,
+    approvalRequest: install.approvalRequest
   };
 }
 
@@ -350,6 +418,106 @@ function resolveInstallDestination(sourcePath, options) {
   return path.resolve(options.installDir, installName);
 }
 
+function shouldCreateApprovalRequest(decision, options) {
+  if (!options.approvalOut) {
+    return false;
+  }
+
+  if (options.approvalMode === "always") {
+    return true;
+  }
+
+  return decision !== "allow";
+}
+
+async function writeApprovalRequest(result, install, options) {
+  const request = createApprovalRequest(result, install, options);
+  const outputPath = path.resolve(options.approvalOut);
+  await fs.mkdir(path.dirname(outputPath), { recursive: true });
+
+  if (outputPath.endsWith(".jsonl")) {
+    await fs.appendFile(outputPath, `${JSON.stringify(request)}\n`);
+  } else {
+    await fs.writeFile(outputPath, `${JSON.stringify(request, null, 2)}\n`, { flag: "wx" });
+  }
+
+  return {
+    id: request.id,
+    path: outputPath,
+    status: request.status,
+    message: request.message
+  };
+}
+
+function createApprovalRequest(result, install, options) {
+  const id = randomUUID();
+  const decision = result.policy.decision;
+  const framework = options.framework ?? "generic";
+  const target = path.resolve(options.target);
+  const topFindings = result.findings.slice(0, 5).map((finding) => ({
+    ruleId: finding.ruleId,
+    severity: finding.severity,
+    title: finding.title,
+    file: finding.file,
+    line: finding.line,
+    recommendation: finding.recommendation
+  }));
+
+  return {
+    schemaVersion: "clawguard.approval.v1",
+    id,
+    status: "pending",
+    createdAt: new Date().toISOString(),
+    framework,
+    target,
+    destination: install.destination,
+    decision,
+    risk: {
+      level: result.level,
+      score: result.score
+    },
+    policy: {
+      preset: result.policy.preset,
+      reason: result.policy.reason,
+      requiredActions: result.policy.requiredActions
+    },
+    install: {
+      dryRun: install.dryRun,
+      installed: false,
+      skipped: true
+    },
+    summary: result.summary,
+    findings: topFindings,
+    message: createApprovalMessage({
+      framework,
+      target,
+      destination: install.destination,
+      decision,
+      risk: result.level,
+      score: result.score,
+      requiredActions: result.policy.requiredActions,
+      findings: topFindings
+    })
+  };
+}
+
+function createApprovalMessage(details) {
+  const findingLines = details.findings.length === 0
+    ? "No findings were reported."
+    : details.findings.map((finding) => `- ${finding.severity.toUpperCase()}: ${finding.title}`).join("\n");
+
+  return [
+    `ClawGuard approval needed for ${displayFramework(details.framework)} skill install.`,
+    `Decision: ${formatDecision(details.decision)}`,
+    `Risk: ${details.risk.toUpperCase()} (${details.score}/100)`,
+    `Source: ${details.target}`,
+    `Destination: ${details.destination ?? "not selected"}`,
+    `Required actions: ${details.requiredActions.length > 0 ? details.requiredActions.join(", ") : "none"}`,
+    "Top findings:",
+    findingLines
+  ].join("\n");
+}
+
 async function assertInstallableSource(sourcePath) {
   const stats = await fs.lstat(sourcePath);
 
@@ -404,6 +572,18 @@ function commandLabel(commandName) {
   return "Scan";
 }
 
+function displayFramework(value) {
+  if (value === "openclaw") {
+    return "OpenClaw";
+  }
+
+  if (value === "hermes") {
+    return "Hermes Agent";
+  }
+
+  return "agent";
+}
+
 function formatDecision(decision) {
   return decision.replaceAll("_", " ").toUpperCase();
 }
@@ -420,6 +600,14 @@ function gateExitCode(decision) {
   return 1;
 }
 
+function installExitCode(decision, install) {
+  if (install.approvalRequest) {
+    return 1;
+  }
+
+  return gateExitCode(decision);
+}
+
 function parseOptions(values) {
   const options = {
     json: false,
@@ -434,6 +622,9 @@ function parseOptions(values) {
     installDir: undefined,
     installName: undefined,
     dryRun: false,
+    approvalOut: undefined,
+    approvalMode: "non-allow",
+    framework: undefined,
     target: "."
   };
   const paths = [];
@@ -527,6 +718,22 @@ function parseOptions(values) {
       continue;
     }
 
+    if (value === "--approval-out") {
+      options.approvalOut = requireNextValue(values, index, "--approval-out");
+      index += 1;
+      continue;
+    }
+
+    if (value === "--approval-mode") {
+      const mode = requireNextValue(values, index, "--approval-mode");
+      if (!["non-allow", "always"].includes(mode)) {
+        throw new Error("Invalid --approval-mode value. Use one of: non-allow, always");
+      }
+      options.approvalMode = mode;
+      index += 1;
+      continue;
+    }
+
     if (value.startsWith("--")) {
       throw new Error(`Unknown option: ${value}`);
     }

package/src/config.js

@@ -64,7 +64,9 @@ export function mergeConfig(config, cliOptions = {}) {
     sarifPath: cliOptions.sarifPath,
     installDir: cliOptions.installDir,
     installName: cliOptions.installName,
-    dryRun: Boolean(cliOptions.dryRun)
+    dryRun: Boolean(cliOptions.dryRun),
+    approvalOut: cliOptions.approvalOut,
+    approvalMode: cliOptions.approvalMode ?? "non-allow"
   };
 }
 

package/web/index.html

@@ -4,7 +4,7 @@
   <meta charset="utf-8">
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <title>ClawGuard Web Demo</title>
-  <link rel="stylesheet" href="/styles.css">
+  <link rel="stylesheet" href="styles.css">
 </head>
 <body>
   <main class="shell">
@@ -125,6 +125,6 @@
       </section>
     </section>
   </main>
-  <script src="/app.js" type="module"></script>
+  <script src="app.js" type="module"></script>
 </body>
 </html>