@denial-web/clawguard 0.1.1 → 0.1.2

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.2",
   "description": "Explainable security scanner for OpenClaw-style skills and MCP tool configs.",
   "type": "module",
   "repository": {

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)
   };
 }