@denial-web/clawguard 0.1.0

package/docs/ARCHITECTURE_ROADMAP.md

@@ -0,0 +1,267 @@
+# Architecture Roadmap
+
+This roadmap turns the current ClawGuard starter into a complete, strong, secure companion project.
+
+## Phase 0: Current Foundation
+
+Status: started
+
+Already present:
+
+- Static CLI scanner.
+- Explainable findings.
+- JSON output.
+- CI fail threshold.
+- File-size limit.
+- Symlink skipping.
+- Safe and risky example skills.
+- Unit tests.
+- Threat model.
+- Security reporting policy.
+
+Finish before public announcement:
+
+- Add at least 20 fixtures.
+- Add at least 20 tests.
+- Add rule documentation.
+- Add config file support.
+- Add stable report schema.
+
+## Phase 1: OpenClaw Skill Intelligence
+
+Goal: make ClawGuard understand real OpenClaw-style skill structure.
+
+Build:
+
+- `SKILL.md` and `skill.md` detection.
+- YAML frontmatter parser.
+- `metadata.openclaw` normalizer.
+- Required field checks.
+- Runtime requirement extraction.
+- Declared versus observed mismatch rules.
+
+Rules:
+
+- Env var used but not declared.
+- Binary used but not declared.
+- Config path read but not declared.
+- Install requirement mentioned but not declared.
+- Broad permission language without clear purpose.
+- Skill name/version/description missing.
+
+Success demo:
+
+```bash
+clawguard scan examples/risky-skill
+```
+
+Report should say not only "risky pattern found", but also "the skill did not declare this requirement".
+
+## Phase 2: Workspace and Precedence
+
+Goal: scan what OpenClaw will actually load.
+
+Status: started
+
+Build:
+
+- `scan-workspace` command.
+- Workspace `skills/` scanner.
+- Project `.agents/skills` scanner.
+- Duplicate skill-name detection.
+- Effective skill precedence report.
+- Optional managed/global scan when explicitly passed.
+
+Already present:
+
+- `scan-workspace` alias.
+- Workspace `skills/` discovery.
+- Project `.agents/skills` discovery.
+- Duplicate skill-name findings.
+- Higher-precedence override findings.
+- Riskier winning-skill override findings.
+
+Success demo:
+
+```bash
+clawguard scan-workspace ~/.openclaw/workspace
+```
+
+Output should explain which duplicate skill wins and whether the winning copy has higher risk.
+
+## Phase 3: Policy Engine
+
+Goal: turn findings into decisions.
+
+Build:
+
+- Presets: personal, governed, enterprise.
+- Decisions: allow, warn, manual review, sandbox required, dual approval, block.
+- `.clawguard.json` config.
+- Suppressions with reason and optional expiry.
+- Policy check command for saved reports.
+
+Success demo:
+
+```bash
+clawguard scan ./skills --policy governed --fail-on-policy
+```
+
+## Phase 4: Reports and CI
+
+Goal: make ClawGuard easy to adopt by maintainers.
+
+Build:
+
+- Stable JSON schema.
+- SARIF reporter.
+- GitHub Action.
+- PR annotation examples.
+- HTML report.
+- JSONL audit output.
+
+Success demo:
+
+- Add ClawGuard to a sample skill repo.
+- Open a PR with a risky skill.
+- Show SARIF annotations and failed policy gate.
+
+## Phase 5: MCP and Plugin Config Scanner
+
+Goal: cover the second half of the OpenClaw/ClawHub surface: tools and plugins.
+
+Status: started
+
+Build:
+
+- `.openclaw/plugins.json` parser.
+- `.openclaw/mcp.json` parser.
+- `.cursor/mcp.json` parser.
+- Generic `mcp.json` parser.
+- Plugin capability rule pack.
+- Environment injection risk checks.
+- Package/source trust checks.
+
+Already present:
+
+- Config path detection for `.cursor/mcp.json`, `.openclaw/mcp.json`, `.openclaw/plugins.json`, and `mcp.json`.
+- JSON parsing with invalid-config findings.
+- Runtime package command checks.
+- Unpinned package checks.
+- Secret env checks.
+- Broad filesystem checks.
+- Shell execution checks.
+- Remote URL checks.
+- Write-capability checks.
+
+Success demo:
+
+```bash
+clawguard scan-mcp .cursor/mcp.json
+```
+
+Output should explain which tools are powerful and what approval/sandbox action is recommended.
+
+## Phase 6: ClawHub Metadata
+
+Goal: connect local scans to registry context.
+
+Status: started
+
+Build:
+
+- `.clawhub/lock.json` parser.
+- `.clawhub/origin.json` parser.
+- Version/source reporting.
+- Local drift detection.
+- Metadata comparison.
+- Optional `clawhub inspect` adapter.
+
+Already present:
+
+- `.clawhub/lock.json` detection and parsing.
+- Per-skill `.clawhub/origin.json` detection and parsing.
+- Version drift findings across lockfile, origin metadata, and local `SKILL.md`.
+- Source drift findings across lockfile and origin metadata.
+- Missing lockfile and missing origin findings.
+- Untrusted or unusual source findings.
+- JSON, CLI, and HTML report summaries for ClawHub metadata.
+
+Success demo:
+
+```bash
+clawguard scan examples/clawhub-workspace --fail-on none
+```
+
+Output should show version/source context and mismatches.
+
+## Phase 7: Web Demo
+
+Goal: create the visibility engine.
+
+Status: started
+
+Build:
+
+- Paste `SKILL.md` scanner.
+- Folder or zip scanner.
+- Visual risk score.
+- Shareable report.
+- Demo GIF script.
+
+Already present:
+
+- Local no-dependency web server.
+- Paste `SKILL.md` scan flow.
+- Built-in examples for static, metadata, workspace, ClawHub, dependency, and MCP risk.
+- Policy selector.
+- Visual score, policy decision, required actions, finding counts, metadata summaries, and finding cards.
+- Copy JSON action.
+
+Success demo:
+
+> Upload OpenClaw skill -> ClawGuard scans -> Risk score -> Risk explanation -> Safer install recommendation.
+
+This should be the first viral surface.
+
+## Phase 8: MCP Server and Install Gate
+
+Goal: make ClawGuard available inside agent workflows.
+
+Build:
+
+- Read-only MCP server.
+- `scan_skill` tool.
+- `scan_mcp_config` tool.
+- `policy_decision` tool.
+- Optional install wrapper.
+
+Success demo:
+
+An agent can ask ClawGuard to review a skill before recommending installation.
+
+## Phase 9: Authority Assets
+
+Goal: turn the project into a visible ecosystem security resource.
+
+Build:
+
+- `awesome-openclaw-security` companion repo.
+- Security articles.
+- Demo videos.
+- OpenClaw/ClawHub PRs for docs and safer defaults.
+- Fixture corpus from public safe/risky examples.
+- Public rule documentation.
+
+## Build Order Recommendation
+
+Do this next:
+
+1. Polish dependency/package lock scanning against real installed examples.
+2. Add web paste demo.
+3. Add demo GIF script and launch README assets.
+4. Add optional ClawHub pre-install wrapper.
+5. Prepare upstream OpenClaw/ClawHub docs PRs.
+6. Create the first public security checklist.
+
+This sequence gives the fastest path to a credible public release.

package/docs/CLAWHUB_METADATA.md

@@ -0,0 +1,57 @@
+# ClawHub Metadata Scanning
+
+ClawGuard can inspect local ClawHub install metadata without contacting the network.
+
+## What It Reads
+
+- Workspace lockfile: `.clawhub/lock.json`
+- Per-skill origin metadata: `skills/<name>/.clawhub/origin.json`
+- Root origin metadata: `.clawhub/origin.json`
+- Local skill metadata from `skills/<name>/SKILL.md`
+
+The parser accepts a few lockfile shapes so it can work with early or changing ClawHub metadata:
+
+- `skills` or `packages` arrays
+- `skills` or `packages` objects keyed by skill name
+- Top-level objects that contain metadata-like fields such as `version`, `source`, `repo`, `url`, `path`, or `dir`
+
+## What It Reports
+
+ClawHub scanning adds a `clawhub` block to JSON reports:
+
+```json
+{
+  "clawhub": {
+    "lockfile": ".clawhub/lock.json",
+    "entries": [
+      {
+        "name": "weather-helper",
+        "version": "1.0.0",
+        "source": "https://github.com/openclaw/skills/weather-helper",
+        "skillDir": "skills/weather-helper"
+      }
+    ],
+    "origins": []
+  }
+}
+```
+
+It also emits findings when provenance cannot be trusted:
+
+- Invalid ClawHub JSON metadata.
+- Installed origin metadata exists but the workspace lockfile is missing.
+- A lock entry has no matching local origin metadata.
+- Lock, origin, and local `SKILL.md` versions drift apart.
+- Lock source and origin source disagree.
+- Source metadata points to an untrusted or unusual location.
+
+## Example
+
+```bash
+node src/cli.js scan examples/clawhub-workspace --fail-on none
+node src/cli.js scan examples/clawhub-workspace --json --fail-on none
+```
+
+## Trust Model
+
+This is a local provenance check, not a registry verifier. ClawGuard does not fetch ClawHub data or prove that a remote source is safe. It highlights drift and unusual sources so users can pause before installing, updating, publishing, or recommending a skill.

package/docs/DEMO_CAPTURE.md

@@ -0,0 +1,25 @@
+# Demo Capture
+
+Use this command to regenerate launch demo assets:
+
+```bash
+npm run demo:capture
+```
+
+The capture script starts a temporary local ClawGuard web server, opens the web demo in Playwright, moves a visible cursor through the `Dependency Risk` flow, clicks `Download HTML`, and writes assets to `docs/assets`.
+
+Generated files:
+
+- `docs/assets/clawguard-web-demo.png`
+- `docs/assets/clawguard-html-report.png`
+- `docs/assets/clawguard-dependency-risk-report.html`
+- `docs/assets/clawguard-demo.webm`
+- `docs/assets/clawguard-demo.mp4` when `ffmpeg` is installed
+
+The script does not install skill dependencies, run scanned code, or contact external registries. It scans local fixtures through the same web API used by the demo.
+
+If Playwright browsers are missing, install them once:
+
+```bash
+npx playwright install chromium
+```

package/docs/DEMO_SCRIPT.md

@@ -0,0 +1,87 @@
+# Demo Script
+
+Use this script for a short ClawGuard demo, README GIF, launch post, or maintainer walkthrough.
+
+## One-Minute Web Demo
+
+Setup:
+
+```bash
+npm test
+npm run web -- --port 4176
+```
+
+Open:
+
+```text
+http://127.0.0.1:4176
+```
+
+Talk track:
+
+> ClawGuard is a companion security layer for OpenClaw-style skills, ClawHub installs, MCP configs, and skill dependencies. Before trusting a skill, it gives you a local risk score, policy decision, evidence, and an HTML report you can share.
+
+Click path:
+
+1. Open the local web demo.
+2. Click `Dependency Risk`.
+3. Point at the score: `100`, `Critical`, `Block`.
+4. Point at required actions: `Manual Review`, `Do Not Install`, `Pin Dependencies`.
+5. Point at findings:
+   - Install lifecycle script.
+   - Direct Git dependency.
+   - Missing lockfile.
+   - Unpinned dependency.
+   - Suspicious dependency name.
+6. Click `Download HTML`.
+7. Say:
+
+> This report is self-contained. A maintainer can attach it to an issue, PR, or internal review without running the scanner again.
+
+## Thirty-Second ClawHub Demo
+
+Click path:
+
+1. Click `ClawHub Drift`.
+2. Point at source drift and version drift findings.
+3. Say:
+
+> ClawGuard reads local ClawHub metadata and tells you when the installed skill no longer matches the lockfile or origin metadata.
+
+## Thirty-Second Workspace Demo
+
+Click path:
+
+1. Click `Workspace Override`.
+2. Point at duplicate skill and override findings.
+3. Say:
+
+> OpenClaw workspace precedence matters. ClawGuard shows which skill wins and whether the winning copy is riskier.
+
+## Paste Demo
+
+Click path:
+
+1. Click `Load sample`.
+2. Click `Scan Paste`.
+3. Point at the network declaration mismatch.
+4. Say:
+
+> Even a simple pasted `SKILL.md` can be checked for declared-versus-observed behavior before a user installs it.
+
+## Folder Demo
+
+Click path:
+
+1. Click `Choose File` or `Skill Folder`.
+2. Select a local skill folder.
+3. Click `Scan Folder`.
+4. Say:
+
+> Folder scan is the real install-review workflow: choose a skill bundle, scan everything locally, and review evidence before trust.
+
+## Demo Close
+
+Use this close:
+
+> ClawGuard does not replace OpenClaw or ClawHub. It is the review layer around them: local, explainable, CI-friendly, and designed to make third-party skills safer to install.

package/docs/DEPENDENCY_SCANNING.md

@@ -0,0 +1,61 @@
+# Dependency Scanning
+
+ClawGuard can inspect common dependency manifests and lockfiles inside skill bundles and workspaces.
+
+## What It Reads
+
+- `package.json`
+- `package-lock.json`
+- `pnpm-lock.yaml`
+- `yarn.lock`
+- `requirements.txt`
+- `pyproject.toml`
+
+## What It Reports
+
+Dependency scanning adds a `dependencies` block to JSON reports:
+
+```json
+{
+  "dependencies": {
+    "manifests": [
+      {
+        "ecosystem": "npm",
+        "file": "package.json",
+        "directory": ".",
+        "name": "my-skill",
+        "dependencyCount": 3,
+        "scriptCount": 1
+      }
+    ],
+    "lockfiles": [
+      {
+        "file": "package-lock.json",
+        "ecosystem": "npm",
+        "directory": "."
+      }
+    ]
+  }
+}
+```
+
+It emits findings for:
+
+- Invalid dependency manifests.
+- Install lifecycle scripts such as `preinstall`, `install`, `postinstall`, and `prepare`.
+- Npm dependency manifests without a matching lockfile in the same directory.
+- Unpinned dependency specs such as ranges, tags, or wildcards.
+- Direct Git, URL, GitHub shorthand, or local file dependency sources.
+- Dependency names containing security-sensitive terms such as `token`, `secret`, `credential`, `stealer`, `keylogger`, or `backdoor`.
+
+## Examples
+
+```bash
+node src/cli.js scan examples/dependency-risky-skill --fail-on none
+node src/cli.js scan examples/dependency-safe-skill --json --fail-on none
+node src/cli.js scan examples/dependency-python-skill --fail-on none
+```
+
+## Trust Model
+
+Dependency scanning is static and local. It does not install packages, execute lifecycle scripts, contact registries, or claim that a package is safe. It highlights supply-chain risk signals so reviewers can pin versions, commit lockfiles, avoid install-time code, and manually review direct sources before enabling a skill.

package/docs/GITHUB_ACTION.md

@@ -0,0 +1,56 @@
+# GitHub Action
+
+ClawGuard can run in pull requests as a policy gate and emit SARIF for GitHub code scanning.
+
+## Example Workflow
+
+```yaml
+name: ClawGuard
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+  security-events: write
+
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: denial-web/clawguard@v1
+        with:
+          target: skills
+          policy: governed
+          fail-on: critical
+          fail-on-policy: "true"
+          policy-fail-on: manual_review
+          sarif: clawguard.sarif
+
+      - uses: github/codeql-action/upload-sarif@v3
+        if: always()
+        with:
+          sarif_file: clawguard.sarif
+```
+
+## Inputs
+
+- `target`: path to scan. Default: `.`
+- `policy`: `personal`, `governed`, or `enterprise`. Default: `governed`
+- `fail-on`: risk level that fails the workflow. Default: `critical`
+- `fail-on-policy`: whether policy decisions fail the workflow. Default: `true`
+- `policy-fail-on`: policy decision threshold. Default: `manual_review`
+- `config`: optional `.clawguard.json` path
+- `sarif`: optional SARIF output path. Default: `clawguard.sarif`
+
+## Notes
+
+- The action is read-only. It scans files already present in the checked-out workspace.
+- The action does not install scanned skill dependencies.
+- Use `if: always()` for SARIF upload so GitHub receives results even when ClawGuard fails the policy gate.

package/docs/GITHUB_REPO_SETUP.md

@@ -0,0 +1,76 @@
+# GitHub Repository Setup
+
+Use this when publishing the ClawGuard repository.
+
+## Repository Identity
+
+Description:
+
+```text
+Governance and security scanner for OpenClaw skills, ClawHub installs, MCP configs, and skill dependencies.
+```
+
+Topics:
+
+```text
+openclaw, clawhub, mcp, security, ai-agents, scanner, governance, supply-chain
+```
+
+Short positioning:
+
+```text
+ClawGuard is an independent companion security layer for OpenClaw-style skills and MCP tool configs. It scans locally, explains risk, and helps teams decide whether to allow, review, sandbox, or block a skill before trusting it.
+```
+
+## Recommended Settings
+
+- Make the license visible from the repository root.
+- Keep [SECURITY.md](../SECURITY.md) in the repository root.
+- Enable Dependabot alerts for the repository.
+- Enable GitHub code scanning if SARIF upload is used.
+- Protect `main` once the first stable release exists.
+- Require CI before merge after the project is public.
+- Add screenshots from [docs/assets](assets) near the top of the README.
+- Keep issue templates and the pull request template enabled.
+
+## First Release
+
+Recommended tag:
+
+```text
+v0.1.0
+```
+
+Release title:
+
+```text
+ClawGuard v0.1.0 - local OpenClaw skill and MCP risk scanner
+```
+
+Release notes:
+
+```text
+Initial public preview of ClawGuard.
+
+- Static scanning for OpenClaw-style SKILL.md files.
+- Metadata mismatch checks for declared env vars, tools, config, network, and install behavior.
+- MCP/plugin configuration scanning.
+- OpenClaw workspace precedence scanning.
+- ClawHub lockfile and origin metadata scanning.
+- npm and Python dependency manifest scanning.
+- CLI, JSON, SARIF, and self-contained HTML reports.
+- Local web demo with paste scan, folder scan, built-in examples, JSON copy, and HTML export.
+- OpenClaw plugin manifest checks for compatibility metadata, runtime code, missing compiled outputs, and sensitive host capabilities.
+
+ClawGuard is static analysis. Findings are risk signals, not proof of malicious intent or proof of safety.
+```
+
+## Launch Post
+
+```text
+I am building ClawGuard, a companion governance/security scanner for OpenClaw-style skills, ClawHub installs, MCP configs, and skill dependencies.
+
+It gives a local risk score, policy decision, evidence, and shareable HTML report before you trust a third-party skill.
+
+It is static analysis, so findings are risk signals rather than proof of malicious intent. I would love safe/risky skill fixtures and feedback from people building with OpenClaw-style agents.
+```

package/docs/HTML_REPORTS.md

@@ -0,0 +1,27 @@
+# HTML Reports
+
+ClawGuard can generate a self-contained HTML report for humans.
+
+## Generate A Report
+
+```bash
+npm run scan -- examples/metadata-mismatch-skill --html clawguard.html --fail-on none
+```
+
+The report includes:
+
+- Risk score and level.
+- Policy decision and required actions.
+- Finding counts by severity.
+- Findings grouped by severity.
+- Evidence and recommendations.
+- Suppressed findings.
+- Skipped files.
+- Scan options and config path.
+
+## Security Notes
+
+- The report is generated from static scan data.
+- Finding evidence is HTML-escaped before rendering.
+- The report does not load external scripts, fonts, or styles.
+- The report is meant for review and sharing, not proof that a skill is safe.