@denial-web/clawguard 0.1.0 → 0.1.2

package/README.md

@@ -1,6 +1,6 @@
 # ClawGuard
 
-Independent governance and security scanner for OpenClaw-style skills and MCP tool configs.
+Security gate and governance scanner for OpenClaw-style skills, ClawHub installs, MCP configs, and agent tools.
 
 ClawGuard helps developers answer one simple question before enabling a skill:
 
@@ -8,6 +8,8 @@ ClawGuard helps developers answer one simple question before enabling a skill:
 
 This project is compatible with OpenClaw-style skill directories, but it is not affiliated with OpenClaw.
 
+ClawGuard is user-triggered today: run it before install, in CI, or as a local review step. It does not yet automatically intercept OpenClaw or ClawHub installs.
+
 ## Demo Preview
 
 [Watch the repeatable demo video](docs/assets/clawguard-demo.mp4), or regenerate it locally with `npm run demo:capture`.
@@ -41,7 +43,23 @@ Run ClawGuard directly from npm:
 npx @denial-web/clawguard scan ./path/to/skill
 ```
 
-Or run the local checkout:
+Use gate mode before installing or trusting a skill:
+
+```bash
+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
 npm test
@@ -172,6 +190,8 @@ Findings:
 ## Roadmap
 
 - `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

@@ -1,6 +1,6 @@
 # ClawGuard Architecture
 
-ClawGuard is an independent static governance layer for OpenClaw-style skills, ClawHub packages, and MCP/tool configs. It should stay compatible with OpenClaw without pretending to be OpenClaw.
+ClawGuard is an independent static governance gate for OpenClaw-style skills, ClawHub packages, and MCP/tool configs. It should stay compatible with OpenClaw without pretending to be OpenClaw.
 
 ## Mission
 
@@ -18,11 +18,13 @@ The product should be small, explainable, and useful in three moments:
 
 1. CLI
 
-   Current surface: `clawguard scan <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>`
@@ -47,7 +49,17 @@ The product should be small, explainable, and useful in three moments:
 
 6. Install gate
 
-   Optional wrapper or integration pattern around OpenClaw/ClawHub install/update flows. It should scan a downloaded bundle before the user enables it.
+   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:
+
+   - `0`: allow
+   - `1`: warn, manual review, sandbox required, or dual approval
+   - `2`: block
+
+   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

@@ -99,14 +99,24 @@ Build:
 - Decisions: allow, warn, manual review, sandbox required, dual approval, block.
 - `.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
 ```
 
+Gate exit codes:
+
+- `0`: allow
+- `1`: warn, manual review, sandbox required, or dual approval
+- `2`: block
+
 ## Phase 4: Reports and CI
 
 Goal: make ClawGuard easy to adopt by maintainers.

package/docs/LAUNCH_CHECKLIST.md

@@ -25,8 +25,8 @@ Use this before sharing ClawGuard publicly.
 
 ## GitHub Repository
 
-- [ ] Repo description: `Governance and security scanner for OpenClaw skills, ClawHub installs, MCP configs, and skill dependencies.`
-- [ ] Topics: `openclaw`, `clawhub`, `mcp`, `security`, `ai-agents`, `scanner`, `governance`, `supply-chain`.
+- [x] Repo description: `Governance and security scanner for OpenClaw skills, ClawHub installs, MCP configs, and skill dependencies.`
+- [x] Topics: `openclaw`, `clawhub`, `mcp`, `security`, `ai-agents`, `scanner`, `governance`, `supply-chain`.
 - [x] License is visible.
 - [x] Security policy is visible.
 - [x] GitHub Action example is documented.
@@ -60,5 +60,4 @@ Include:
 
 - Record a short GIF or video using [docs/DEMO_SCRIPT.md](DEMO_SCRIPT.md).
 - Regenerate demo assets with `npm run demo:capture` after visual UI changes.
-- Apply the repository description and topics in GitHub after the repo is created.
 - Validate against real installed skill folders once a public skill archive or local ClawHub install is available.

package/docs/NPM_PUBLISHING.md

@@ -23,7 +23,7 @@ Provider: GitHub Actions
 Organization or user: denial-web
 Repository: clawguard
 Workflow filename: publish.yml
-Environment name: leave blank
+Environment name: blank
 ```
 
 After the trusted publisher is connected, publish from GitHub Actions:
@@ -62,5 +62,13 @@ The release event will trigger `.github/workflows/publish.yml`.
 After publishing, test the package from npm:
 
 ```bash
+cd /private/tmp
 npx @denial-web/clawguard scan examples/risky-skill
 ```
+
+When testing from outside the repository, point the scan command at a real skill path. For example:
+
+```bash
+cd /private/tmp
+npx @denial-web/clawguard scan /Users/hy/CascadeProjects/ClawGuard/examples/risky-skill
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@denial-web/clawguard",
-  "version": "0.1.0",
+  "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"].includes(command)) {
+if (!["scan", "scan-workspace", "gate", "install"].includes(command)) {
   console.error(`Unknown command: ${command}`);
   printHelp();
   process.exit(1);
@@ -54,15 +54,28 @@ try {
     await writeReportFile(options.htmlPath, createHtmlReport(result));
   }
 
-  if (options.json) {
+  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 {
+      printGateResult(result, options);
+    }
+  } else if (options.json) {
     console.log(JSON.stringify(result, null, 2));
   } else {
     printHumanResult(result, options);
   }
 
-  process.exit(shouldFail(result, options) ? 2 : 0);
+  process.exit(["gate", "install"].includes(command) ? gateExitCode(result.policy.decision) : shouldFail(result, options) ? 2 : 0);
 } catch (error) {
-  console.error(`Scan failed: ${error.message}`);
+  console.error(`${commandLabel(command)} failed: ${error.message}`);
   process.exit(1);
 }
 
@@ -71,6 +84,8 @@ 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>
 
@@ -89,8 +104,19 @@ 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
+  1 = warn, manual review, sandbox required, or dual approval
+  2 = block
 
 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
@@ -171,6 +197,229 @@ function printHumanResult(result, options) {
   }
 }
 
+function printGateResult(result, options) {
+  const decision = result.policy.decision;
+  console.log(`ClawGuard gate: ${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(`Reason: ${result.policy.reason}`);
+
+  if (result.configPath) {
+    console.log(`Config: ${result.configPath}`);
+  }
+
+  if (result.policy.requiredActions.length > 0) {
+    console.log(`Required actions: ${result.policy.requiredActions.join(", ")}`);
+  }
+
+  if (result.findings.length > 0) {
+    console.log(`Findings: ${result.findings.length}`);
+    const topFindings = result.findings.slice(0, 5);
+    for (const finding of topFindings) {
+      console.log(`- [${finding.severity.toUpperCase()}] ${finding.title}`);
+      console.log(`  ${finding.file}:${finding.line}`);
+    }
+
+    if (result.findings.length > topFindings.length) {
+      console.log(`- ${result.findings.length - topFindings.length} more finding(s). Run scan for full details.`);
+    }
+  }
+
+  if (decision === "allow") {
+    console.log("\nGate result: safe to continue under the selected policy.");
+  } else if (decision === "block") {
+    console.log("\nGate result: block install or trust until reviewed.");
+  } else {
+    console.log("\nGate result: pause before install or trust.");
+  }
+}
+
+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,
+    decision: result.policy.decision,
+    exitCode: gateExitCode(result.policy.decision),
+    risk: {
+      level: result.level,
+      score: result.score
+    },
+    policy: {
+      preset: result.policy.preset,
+      reason: result.policy.reason,
+      requiredActions: result.policy.requiredActions
+    },
+    summary: result.summary,
+    findings: result.findings.map((finding) => ({
+      ruleId: finding.ruleId,
+      severity: finding.severity,
+      title: finding.title,
+      file: finding.file,
+      line: finding.line,
+      recommendation: finding.recommendation
+    }))
+  };
+}
+
+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();
+}
+
+function gateExitCode(decision) {
+  if (decision === "allow") {
+    return 0;
+  }
+
+  if (decision === "block") {
+    return 2;
+  }
+
+  return 1;
+}
+
 function parseOptions(values) {
   const options = {
     json: false,
@@ -182,6 +431,9 @@ function parseOptions(values) {
     policy: undefined,
     policyFailOn: undefined,
     maxFileSizeBytes: undefined,
+    installDir: undefined,
+    installName: undefined,
+    dryRun: false,
     target: "."
   };
   const paths = [];
@@ -258,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/examples/safe-openclaw-plugin/dist/index.js

@@ -1 +0,0 @@
-export const safe = true;