@denial-web/clawguard 0.1.1 → 0.1.3

package/README.md

@@ -51,6 +51,14 @@ npx @denial-web/clawguard gate ./path/to/skill --policy governed
 
 Gate mode exits with `0` for allow, `1` for warn/review/sandbox decisions, and `2` for block.
 
+Use install mode to copy a skill only after the policy gate allows it:
+
+```bash
+npx @denial-web/clawguard install ./path/to/skill --to ./.agents/skills --policy governed
+```
+
+Install mode never executes scanned files or installs dependencies. It refuses warn/review/sandbox/block decisions before copying files.
+
 When testing the published package, run `npx` from outside this repository. From inside the ClawGuard source checkout, use the local commands instead:
 
 ```bash
@@ -183,6 +191,7 @@ Findings:
 
 - `clawguard scan <path>` CLI
 - `clawguard gate <path>` policy gate
+- `clawguard install <path> --to <dir>` guarded copy installer
 - OpenClaw `SKILL.md` metadata mismatch checks
 - `.clawguard.json` policy/config support
 - MCP/plugin config scanning

package/docs/ARCHITECTURE.md

@@ -18,12 +18,13 @@ The product should be small, explainable, and useful in three moments:
 
 1. CLI
 
-   Current surfaces: `clawguard scan <path>` and `clawguard gate <path>`.
+   Current surfaces: `clawguard scan <path>`, `clawguard gate <path>`, and `clawguard install <path> --to <dir>`.
 
    Target surface:
 
    - `clawguard scan <path>`
    - `clawguard gate <path>`
+   - `clawguard install <path> --to <dir>`
    - `clawguard scan-skill <skill-dir>`
    - `clawguard scan-workspace <workspace-dir>`
    - `clawguard scan-mcp <config-path>`
@@ -48,7 +49,7 @@ The product should be small, explainable, and useful in three moments:
 
 6. Install gate
 
-   Current surface: `clawguard gate <path>`.
+   Current surfaces: `clawguard gate <path>` and `clawguard install <path> --to <dir>`.
 
    Gate mode maps scan results into allow, warn, sandbox, or block decisions and exits with install-wrapper friendly codes:
 
@@ -56,7 +57,9 @@ The product should be small, explainable, and useful in three moments:
    - `1`: warn, manual review, sandbox required, or dual approval
    - `2`: block
 
-   Future surface: wrapper or integration pattern around OpenClaw/ClawHub install/update flows. It should scan a downloaded bundle before the user enables it.
+   Install mode is a conservative wrapper: it scans first, copies only on `allow`, refuses non-allow decisions before copying, rejects symlink sources, and never executes scanned files or dependency install scripts.
+
+   Future surface: direct integration pattern around OpenClaw/ClawHub install/update flows. It should scan a downloaded bundle before the user enables it.
 
 ## Trust Boundaries
 

package/docs/ARCHITECTURE_ROADMAP.md

@@ -100,12 +100,14 @@ Build:
 - `.clawguard.json` config.
 - Suppressions with reason and optional expiry.
 - Install gate command with policy exit codes.
+- Guarded install command that copies only after an `allow` decision.
 - Policy check command for saved reports.
 
 Success demo:
 
 ```bash
 clawguard gate ./skills/my-skill --policy governed
+clawguard install ./skills/my-skill --to ./.agents/skills --policy governed
 clawguard scan ./skills --policy governed --fail-on-policy
 ```
 

package/package.json

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

package/scripts/capture-demo.js

@@ -89,7 +89,8 @@ async function main() {
     await pause(250);
     await dependencyRisk.click();
     await page.getByRole("heading", { name: "Dependency Risk" }).waitFor();
-    await page.getByText("Block").waitFor();
+    await page.getByRole("heading", { name: "Block", exact: true }).waitFor();
+    await page.getByRole("heading", { name: "Install blocked" }).waitFor();
     await pause(700);
 
     await page.screenshot({

package/src/cli.js

@@ -27,7 +27,7 @@ if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
 
 const command = args[0];
 
-if (!["scan", "scan-workspace", "gate"].includes(command)) {
+if (!["scan", "scan-workspace", "gate", "install"].includes(command)) {
   console.error(`Unknown command: ${command}`);
   printHelp();
   process.exit(1);
@@ -54,7 +54,14 @@ try {
     await writeReportFile(options.htmlPath, createHtmlReport(result));
   }
 
-  if (command === "gate") {
+  if (command === "install") {
+    const install = await handleInstall(result, options);
+    if (options.json) {
+      console.log(JSON.stringify(createInstallResult(result, install), null, 2));
+    } else {
+      printInstallResult(result, install);
+    }
+  } else if (command === "gate") {
     if (options.json) {
       console.log(JSON.stringify(createGateResult(result), null, 2));
     } else {
@@ -66,9 +73,9 @@ try {
     printHumanResult(result, options);
   }
 
-  process.exit(command === "gate" ? gateExitCode(result.policy.decision) : shouldFail(result, options) ? 2 : 0);
+  process.exit(["gate", "install"].includes(command) ? gateExitCode(result.policy.decision) : shouldFail(result, options) ? 2 : 0);
 } catch (error) {
-  console.error(`${command === "gate" ? "Gate" : "Scan"} failed: ${error.message}`);
+  console.error(`${commandLabel(command)} failed: ${error.message}`);
   process.exit(1);
 }
 
@@ -78,6 +85,7 @@ function printHelp() {
 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 scan-workspace <path> [--json] [--policy <preset>]
   npm run scan -- <path>
 
@@ -96,6 +104,9 @@ Options:
                           Default: manual_review.
   --max-file-size <size>  Skip individual files larger than this size. Examples: 512kb, 1mb.
                           Default: 1mb.
+  --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.
 
 Gate exit codes:
   0 = allow
@@ -105,6 +116,7 @@ Gate exit codes:
 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
   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
@@ -224,6 +236,85 @@ function printGateResult(result, options) {
   }
 }
 
+async function handleInstall(result, options) {
+  const decision = result.policy.decision;
+  const sourcePath = path.resolve(options.target);
+  const destination = resolveInstallDestination(sourcePath, options);
+  const install = {
+    destination,
+    dryRun: options.dryRun,
+    installed: false,
+    skipped: decision !== "allow"
+  };
+
+  if (decision !== "allow") {
+    return install;
+  }
+
+  if (!options.installDir) {
+    throw new Error("install requires --to <dir>. ClawGuard will not guess an install location.");
+  }
+
+  if (options.dryRun) {
+    return install;
+  }
+
+  await assertInstallableSource(sourcePath);
+  await assertDestinationAvailable(destination);
+  await fs.mkdir(path.dirname(destination), { recursive: true });
+  await fs.cp(sourcePath, destination, {
+    recursive: true,
+    errorOnExist: true,
+    force: false,
+    verbatimSymlinks: true
+  });
+
+  install.installed = true;
+  install.skipped = false;
+  return install;
+}
+
+function printInstallResult(result, install) {
+  const decision = result.policy.decision;
+  console.log(`ClawGuard install: ${result.target}`);
+  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(`Destination: ${install.destination ?? "not selected"}`);
+  console.log(`Installed: ${install.installed ? "yes" : "no"}`);
+
+  if (install.dryRun) {
+    console.log("Dry run: yes");
+  }
+
+  if (result.policy.requiredActions.length > 0) {
+    console.log(`Required actions: ${result.policy.requiredActions.join(", ")}`);
+  }
+
+  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.");
+  } else if (decision === "allow") {
+    console.log("\nInstall result: ready to copy after passing the selected policy.");
+  } else if (decision === "block") {
+    console.log("\nInstall result: blocked before copying files.");
+  } else {
+    console.log("\nInstall result: paused before copying files.");
+  }
+}
+
+function createInstallResult(result, install) {
+  return {
+    ...createGateResult(result),
+    destination: install.destination,
+    installed: install.installed,
+    dryRun: install.dryRun,
+    skipped: install.skipped
+  };
+}
+
 function createGateResult(result) {
   return {
     target: result.target,
@@ -250,6 +341,69 @@ function createGateResult(result) {
   };
 }
 
+function resolveInstallDestination(sourcePath, options) {
+  if (!options.installDir) {
+    return undefined;
+  }
+
+  const installName = options.installName ?? path.basename(sourcePath);
+  return path.resolve(options.installDir, installName);
+}
+
+async function assertInstallableSource(sourcePath) {
+  const stats = await fs.lstat(sourcePath);
+
+  if (stats.isSymbolicLink()) {
+    throw new Error("install source cannot be a symlink");
+  }
+
+  if (stats.isDirectory()) {
+    await assertDirectoryHasNoSymlinks(sourcePath);
+  }
+}
+
+async function assertDirectoryHasNoSymlinks(directory) {
+  const entries = await fs.readdir(directory, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const entryPath = path.join(directory, entry.name);
+
+    if (entry.isSymbolicLink()) {
+      throw new Error(`install source contains a symlink: ${entryPath}`);
+    }
+
+    if (entry.isDirectory()) {
+      await assertDirectoryHasNoSymlinks(entryPath);
+    }
+  }
+}
+
+async function assertDestinationAvailable(destination) {
+  try {
+    await fs.lstat(destination);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return;
+    }
+
+    throw error;
+  }
+
+  throw new Error(`install destination already exists: ${destination}`);
+}
+
+function commandLabel(commandName) {
+  if (commandName === "gate") {
+    return "Gate";
+  }
+
+  if (commandName === "install") {
+    return "Install";
+  }
+
+  return "Scan";
+}
+
 function formatDecision(decision) {
   return decision.replaceAll("_", " ").toUpperCase();
 }
@@ -277,6 +431,9 @@ function parseOptions(values) {
     policy: undefined,
     policyFailOn: undefined,
     maxFileSizeBytes: undefined,
+    installDir: undefined,
+    installName: undefined,
+    dryRun: false,
     target: "."
   };
   const paths = [];
@@ -353,6 +510,23 @@ function parseOptions(values) {
       continue;
     }
 
+    if (value === "--to") {
+      options.installDir = requireNextValue(values, index, "--to");
+      index += 1;
+      continue;
+    }
+
+    if (value === "--name") {
+      options.installName = requireNextValue(values, index, "--name");
+      index += 1;
+      continue;
+    }
+
+    if (value === "--dry-run") {
+      options.dryRun = true;
+      continue;
+    }
+
     if (value.startsWith("--")) {
       throw new Error(`Unknown option: ${value}`);
     }

package/src/config.js

@@ -61,7 +61,10 @@ export function mergeConfig(config, cliOptions = {}) {
     json: Boolean(cliOptions.json),
     configPath: cliOptions.configPath,
     htmlPath: cliOptions.htmlPath,
-    sarifPath: cliOptions.sarifPath
+    sarifPath: cliOptions.sarifPath,
+    installDir: cliOptions.installDir,
+    installName: cliOptions.installName,
+    dryRun: Boolean(cliOptions.dryRun)
   };
 }
 

package/web/app.js

@@ -37,6 +37,9 @@ const elements = {
   level: document.querySelector("#level"),
   decision: document.querySelector("#decision"),
   reason: document.querySelector("#reason"),
+  installVerdict: document.querySelector("#install-verdict"),
+  installMessage: document.querySelector("#install-message"),
+  installCommand: document.querySelector("#install-command"),
   actions: document.querySelector("#actions"),
   critical: document.querySelector("#critical-count"),
   high: document.querySelector("#high-count"),
@@ -235,9 +238,36 @@ function renderResult(result) {
   elements.downloadHtml.textContent = "Download HTML";
   elements.downloadHtml.disabled = false;
 
+  renderInstallGate(result);
   renderFindings(scan.findings ?? []);
 }
 
+function renderInstallGate(result) {
+  const scan = result.scan;
+  const policy = scan.policy ?? {};
+  const decision = policy.decision ?? "allow";
+  const target = installTargetFor(result);
+  const installName = safeInstallName(result.displayTarget ?? "skill");
+  const command = `npx @denial-web/clawguard install ${target} --to ./.agents/skills --name ${installName} --policy ${policy.preset ?? elements.policy.value}`;
+
+  elements.installCommand.textContent = command;
+
+  if (decision === "allow") {
+    elements.installVerdict.textContent = "Install allowed";
+    elements.installMessage.textContent = "ClawGuard would copy this skill into the destination after the policy gate passes.";
+    return;
+  }
+
+  if (decision === "block") {
+    elements.installVerdict.textContent = "Install blocked";
+    elements.installMessage.textContent = "ClawGuard would stop before copying files. Review the findings before trusting this skill.";
+    return;
+  }
+
+  elements.installVerdict.textContent = "Install paused";
+  elements.installMessage.textContent = "ClawGuard would require review, sandboxing, or approval before copying files.";
+}
+
 function renderFindings(findings) {
   if (findings.length === 0) {
     elements.findings.className = "findings empty-state";
@@ -342,6 +372,27 @@ function safeFilename(value) {
     .slice(0, 80) || "scan";
 }
 
+function safeInstallName(value) {
+  return String(value || "skill")
+    .toLowerCase()
+    .replace(/[^a-z0-9_.-]/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "")
+    .slice(0, 60) || "skill";
+}
+
+function installTargetFor(result) {
+  if (result.source === "example" && result.example?.path) {
+    return result.example.path;
+  }
+
+  if (result.source === "folder") {
+    return "./uploaded-skill";
+  }
+
+  return "./pasted-skill";
+}
+
 async function fetchJson(url, options = {}) {
   const response = await fetch(url, {
     headers: {

package/web/index.html

@@ -75,6 +75,17 @@
           </div>
         </section>
 
+        <section class="install-panel" aria-label="Pre-install gate">
+          <div>
+            <p class="eyebrow">Pre-Install Gate</p>
+            <h2 id="install-verdict">Waiting for scan</h2>
+            <p id="install-message">Run a scan to see whether ClawGuard would install, pause, or block before files are trusted.</p>
+          </div>
+          <div class="command-box">
+            <code id="install-command">npx @denial-web/clawguard install ./skill --to ./.agents/skills --policy governed</code>
+          </div>
+        </section>
+
         <section class="metrics" aria-label="Finding summary">
           <div><span>Critical</span><strong id="critical-count">0</strong></div>
           <div><span>High</span><strong id="high-count">0</strong></div>

package/web/styles.css

@@ -264,7 +264,7 @@ input[type="file"] {
   align-items: stretch;
 }
 
-.score-ring, .decision, .metrics div, .metadata-grid div, .finding-card, .empty-state {
+.score-ring, .decision, .install-panel, .metrics div, .metadata-grid div, .finding-card, .empty-state {
   border: 1px solid var(--line);
   border-radius: 8px;
   background: var(--panel);
@@ -302,6 +302,43 @@ input[type="file"] {
   text-transform: uppercase;
 }
 
+.install-panel {
+  display: grid;
+  grid-template-columns: minmax(220px, 0.8fr) minmax(0, 1.2fr);
+  gap: 14px;
+  align-items: stretch;
+  padding: 16px;
+}
+
+.install-panel h2 {
+  margin-top: 5px;
+  font-size: 24px;
+  text-transform: uppercase;
+}
+
+#install-message {
+  margin-top: 6px;
+  color: var(--muted);
+  line-height: 1.4;
+}
+
+.command-box {
+  min-width: 0;
+  display: grid;
+  align-items: center;
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  background: var(--field);
+  padding: 12px;
+}
+
+.command-box code {
+  font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  font-size: 13px;
+  line-height: 1.45;
+  overflow-wrap: anywhere;
+}
+
 .action-tags {
   display: flex;
   flex-wrap: wrap;
@@ -422,7 +459,7 @@ input[type="file"] {
 }
 
 @media (max-width: 900px) {
-  .workbench, .score-panel {
+  .workbench, .score-panel, .install-panel {
     grid-template-columns: 1fr;
   }