@denial-web/clawguard 0.1.0

package/docs/NEXT_SESSION.md

@@ -0,0 +1,110 @@
+# Next Session Checkpoint
+
+Saved: 2026-05-08 11:45 +07
+
+## Current Status
+
+ClawGuard now has a strong foundation:
+
+- Static scanner for OpenClaw-style skills and MCP configs.
+- OpenClaw `SKILL.md` frontmatter parsing.
+- Metadata mismatch checks for undeclared env vars, binaries, config paths, network access, and install behavior.
+- `.clawguard.json` config and policy presets.
+- Suppressions with required reasons and critical-finding guardrails.
+- SARIF output and GitHub Action metadata.
+- Self-contained HTML reports.
+- MCP/plugin config scanning for `.cursor/mcp.json`, `.openclaw/mcp.json`, `.openclaw/plugins.json`, and `mcp.json`.
+- OpenClaw workspace scanning for `skills/` and `.agents/skills/`.
+- Duplicate skill-name and risky override findings.
+- Versioned JSON report schema.
+- Central rule catalog and rule docs.
+- ClawHub metadata and lockfile scanning.
+- Dependency manifest and package lock scanning.
+- Local web demo for paste, folder, and example scans.
+- Web demo HTML report download.
+- README demo screenshots and launch assets under `docs/assets/`.
+- Fresh-copy validation from `/private/tmp`.
+- Real-world ClawHub validation notes against current public sources.
+- ClawHub `envVars` and `requiredEnv` declaration parsing.
+- First-class `openclaw.plugin.json` package manifest scanning.
+- OpenClaw plugin compatibility, runtime output, code execution, and sensitive capability rules.
+- GitHub bug report and fixture submission issue templates.
+- Pull request template.
+- Draft `v0.1.0` release notes.
+- Repeatable Playwright demo capture script with visible cursor movement.
+- Generated demo screenshots, HTML report, WebM, and MP4 assets.
+- Release package metadata, repository links, explicit npm package `files`, and visible MIT `LICENSE`.
+- `npm pack --dry-run` validated with a temporary npm cache.
+
+## Verification
+
+Last full test run:
+
+```bash
+npm test
+```
+
+Result: 70/70 passing.
+
+Fresh-copy validation also passed:
+
+```bash
+npm ci
+npm test
+node src/cli.js scan examples/risky-openclaw-plugin --html plugin-report.html --fail-on none
+```
+
+Useful smoke commands:
+
+```bash
+node src/cli.js scan examples/metadata-mismatch-skill --fail-on none
+node src/cli.js scan examples/risky-mcp-config --fail-on none
+node src/cli.js scan-workspace examples/openclaw-workspace --fail-on none
+node src/cli.js scan-workspace examples/openclaw-workspace --html /private/tmp/clawguard-workspace.html --fail-on none
+node src/cli.js scan examples/clawhub-workspace --fail-on none
+node src/cli.js scan examples/dependency-risky-skill --fail-on none
+node src/cli.js scan examples/dependency-safe-skill --fail-on none
+node src/cli.js scan examples/dependency-python-skill --fail-on none
+node src/cli.js scan examples/risky-openclaw-plugin --fail-on none
+node src/cli.js scan examples/safe-openclaw-plugin --fail-on none
+npm run web
+npm run web -- --port 4174
+npm run demo:capture
+npm --cache /private/tmp/clawguard-npm-cache pack --dry-run
+```
+
+## Best Next Step
+
+Prepare the final public launch package.
+
+Target inputs:
+
+- short demo GIF or video using `docs/DEMO_SCRIPT.md`
+- GitHub repository description and topics from `docs/GITHUB_REPO_SETUP.md`
+- first `v0.1.0` release notes
+- real installed OpenClaw/ClawHub skill folders if available locally
+
+Target findings:
+
+- optional ClawHub package digest/source verification
+- false-positive cleanup from real installed skills
+- publish repo, tag `v0.1.0`, and open first public feedback thread
+
+Suggested files:
+
+- `src/mcp-config.js`
+- `src/clawhub.js`
+- `src/skill-metadata.js`
+- `test/scanner.test.js`
+- `docs/REAL_WORLD_VALIDATION.md`
+- `docs/GITHUB_REPO_SETUP.md`
+- `README.md`
+- `docs/LAUNCH_CHECKLIST.md`
+
+## Good Commit Message Later
+
+```text
+Build ClawGuard security scanner foundation
+```
+
+This repo is still uncommitted. Run `git status --short` before committing so unrelated local changes are not accidentally included.

package/docs/NPM_PUBLISHING.md

@@ -0,0 +1,66 @@
+# npm Publishing
+
+ClawGuard is published as:
+
+```text
+@denial-web/clawguard
+```
+
+## Preferred Path: Trusted Publishing
+
+Use npm trusted publishing so GitHub Actions can publish with short-lived OIDC credentials instead of local OTPs or long-lived npm tokens.
+
+Workflow file:
+
+```text
+.github/workflows/publish.yml
+```
+
+Configure this on npmjs.com:
+
+```text
+Provider: GitHub Actions
+Organization or user: denial-web
+Repository: clawguard
+Workflow filename: publish.yml
+Environment name: leave blank
+```
+
+After the trusted publisher is connected, publish from GitHub Actions:
+
+1. Go to the GitHub repository.
+2. Open `Actions`.
+3. Select `Publish to npm`.
+4. Click `Run workflow`.
+
+The workflow also runs automatically when a GitHub release is published.
+
+## First Publish Notes
+
+If npm does not allow trusted publishing before the first package publish, publish manually once from a local terminal after enabling npm 2FA:
+
+```bash
+npm publish --access public
+```
+
+After the first package exists on npm, connect trusted publishing and use GitHub Actions for later releases.
+
+## Release Flow
+
+For a patch release:
+
+```bash
+npm version patch
+git push origin main --follow-tags
+gh release create v0.1.1 --generate-notes
+```
+
+The release event will trigger `.github/workflows/publish.yml`.
+
+## Verify
+
+After publishing, test the package from npm:
+
+```bash
+npx @denial-web/clawguard scan examples/risky-skill
+```

package/docs/OPENCLAW_CLAWHUB_RESEARCH.md

@@ -0,0 +1,128 @@
+# OpenClaw and ClawHub Research
+
+Checked: 2026-05-07
+
+This document captures the current public OpenClaw and ClawHub shape that ClawGuard should build around. It uses official OpenClaw and ClawHub sources only.
+
+## Official Sources
+
+- [OpenClaw GitHub repository](https://github.com/openclaw/openclaw)
+- [OpenClaw architecture docs](https://docs.openclaw.ai/concepts/architecture)
+- [OpenClaw skills docs](https://docs.openclaw.ai/tools/skills)
+- [ClawHub docs](https://docs.openclaw.ai/tools/clawhub)
+- [ClawHub GitHub repository](https://github.com/openclaw/clawhub)
+- [ClawHub skill format](https://github.com/openclaw/clawhub/blob/main/docs/skill-format.md)
+- [OpenClaw skills archive](https://github.com/openclaw/skills)
+
+## Current OpenClaw Shape
+
+OpenClaw is a personal AI assistant with a long-lived Gateway as the control plane. The Gateway owns messaging surfaces, exposes a WebSocket API, validates inbound frames against JSON Schema, and coordinates clients, nodes, tools, sessions, and events.
+
+Security-relevant facts:
+
+- The main session can run tools on the host, which means skills and tools should be treated as meaningful trust decisions.
+- Non-main sessions can be sandboxed with Docker, SSH, or OpenShell backends.
+- Typical sandbox policy allows core file/process/session tools and denies broader tools such as browser, canvas, nodes, cron, Discord, and gateway.
+- OpenClaw treats inbound direct messages as untrusted input and uses pairing/allowlist controls for remote surfaces.
+- Skills are loaded into the agent prompt and can influence how tools are used.
+- Plugins can ship skills, so plugin review and skill review are connected.
+
+## Current Skill Model
+
+OpenClaw uses AgentSkills-compatible folders. A skill is a directory containing `SKILL.md` with YAML frontmatter and instructions.
+
+Current skill locations and precedence:
+
+- Extra skill folders from `skills.load.extraDirs`
+- Bundled skills shipped with OpenClaw
+- Managed/local skills in `~/.openclaw/skills`
+- Personal agent skills in `~/.agents/skills`
+- Project agent skills in `<workspace>/.agents/skills`
+- Workspace skills in `<workspace>/skills`
+
+If names conflict, workspace skills take precedence over project, personal, managed/local, bundled, and extra-dir skills.
+
+Important implication: ClawGuard should scan the skill that actually wins by precedence, not only every folder it can see. A later phase should add `clawguard openclaw scan-workspace` to resolve and report effective skills.
+
+## Current ClawHub Shape
+
+ClawHub is the public registry for OpenClaw skills and plugins.
+
+Current registry roles:
+
+- Public browsing of skill content and metadata.
+- Versioned skill bundles with semver, changelogs, tags, and `latest`.
+- Downloads as zip bundles.
+- Search and discovery.
+- Stars, comments, moderation, reporting, hiding, deletion, and ban flows.
+- Plugin/package browsing with family, trust, and capability metadata.
+- Publish flows for skills and plugins.
+
+Native OpenClaw flows install ClawHub skills into the active workspace `skills/` directory. Native plugin installs validate advertised compatibility before archive installation, and ClawHub source metadata is persisted for future updates.
+
+The separate `clawhub` CLI can install skills into `./skills` under the current working directory and stores local state in `.clawhub/lock.json`.
+
+## Current Skill Format Signals
+
+The ClawHub skill format makes `SKILL.md` central:
+
+- `SKILL.md` or `skill.md` is required.
+- YAML frontmatter is optional but important for metadata extraction.
+- `description` is used for UI and search summary.
+- Runtime metadata is declared under `metadata.openclaw` with aliases for older names.
+- Important fields include `requires.env`, `requires.bins`, `requires.anyBins`, `requires.config`, `primaryEnv`, `envVars`, `install`, `os`, `homepage`, and related metadata.
+- Install kinds currently include `brew`, `node`, `go`, and `uv`.
+- Published skills accept text-based files only.
+- Server-side bundle size is capped at 50 MB.
+- Published ClawHub skills are MIT-0.
+
+ClawHub's own docs say its security analysis checks whether declarations match actual skill behavior. Example: a skill that references an API key but does not declare it should be flagged as a metadata mismatch.
+
+## ClawGuard Product Inference
+
+Inference from the sources: ClawGuard should not try to replace ClawHub security analysis. It should become an independent, explainable, local and CI-friendly enforcement layer that works before install, after install, and during pull requests.
+
+The strongest ClawGuard scope is:
+
+- Skill scanner for `SKILL.md` and supporting files.
+- Frontmatter mismatch scanner for declared requirements versus observed behavior.
+- MCP and plugin config scanner for tool/capability risk.
+- Install/update gate for OpenClaw and ClawHub workflows.
+- CI and GitHub Action for community repositories.
+- Web demo for quick "upload skill, get risk score" sharing.
+
+The strongest first public message is:
+
+> Run ClawGuard before trusting an OpenClaw skill or plugin.
+
+## Architecture Requirements From Research
+
+ClawGuard needs to support these inputs:
+
+- A single skill folder.
+- A workspace `skills/` folder.
+- Project agent skills in `.agents/skills`.
+- Managed/local skill folders when explicitly passed.
+- ClawHub local install metadata in `.clawhub/`.
+- OpenClaw plugin config and source metadata.
+- MCP configs from `.openclaw`, `.cursor`, and common MCP config paths.
+- ClawHub package metadata when supplied by a user or integration.
+
+ClawGuard needs to produce these outputs:
+
+- Human CLI report.
+- JSON report for automation.
+- Policy decision for install gates.
+- SARIF report for GitHub code scanning.
+- HTML report for demos and enterprise review.
+- JSONL audit events for later SIEM or governance use.
+
+## Research-Driven Priorities
+
+1. Parse `SKILL.md` frontmatter and compare declarations to observed behavior.
+2. Scan OpenClaw workspace skill folders and report effective precedence.
+3. Scan `.clawhub/lock.json` and origin metadata for source/version context.
+4. Scan plugin and MCP config for broad tools, unknown sources, install scripts, and network/system capabilities.
+5. Add policy presets for personal, governed, and enterprise use.
+6. Add GitHub Action and SARIF output.
+7. Add web demo and demo GIF around "Upload skill -> Risk score -> Explanation -> Safer action".

package/docs/POLICY_MODEL.md

@@ -0,0 +1,198 @@
+# Policy Model
+
+ClawGuard separates detection from decision-making.
+
+Detection answers:
+
+> What did we find?
+
+Policy answers:
+
+> What should happen before this skill or plugin is trusted?
+
+## Risk Levels
+
+`info`
+
+Useful context. Does not imply danger.
+
+Examples:
+
+- Missing optional metadata.
+- Skill has install requirements.
+- Workspace contains duplicate skill names.
+
+`low`
+
+Minor risk or maintenance issue.
+
+Examples:
+
+- Uses common external domains.
+- Declares broad tags without matching instructions.
+- Reads normal config files.
+
+`medium`
+
+The skill can surprise the user or expand trust.
+
+Examples:
+
+- Undeclared binary requirement.
+- Broad filesystem wording.
+- Network access that matches the skill purpose but is not declared.
+- Prompt instructions that ask the model to ignore unrelated context.
+
+`high`
+
+The skill can touch sensitive data, external systems, or powerful tools.
+
+Examples:
+
+- Reads environment variables or credential files.
+- Sends data to external endpoints.
+- Requests shell, browser, GitHub, Slack, email, calendar, or gateway capabilities.
+- Uses install scripts or opaque dependency setup.
+
+`critical`
+
+The skill can cause serious damage or execute untrusted logic.
+
+Examples:
+
+- Downloads and executes remote code.
+- Runs destructive shell commands.
+- Silently exfiltrates secrets.
+- Attempts to disable safety controls or approvals.
+- Uses obfuscation to hide execution or network behavior.
+
+## Decisions
+
+`allow`
+
+No blocking issues. The report may still show informational findings.
+
+`warn`
+
+Show the risk and allow the operator to continue.
+
+`manual_review`
+
+Require a human review before install, update, or merge.
+
+`sandbox_required`
+
+Allow only inside a sandbox or with limited tools.
+
+`dual_approval`
+
+Require two reviewers for high-risk enterprise workflows.
+
+`block`
+
+Do not install, enable, or merge.
+
+## Presets
+
+Personal:
+
+- Allow `info` and `low`.
+- Warn on `medium`.
+- Manual review on `high`.
+- Block `critical`.
+
+Governed:
+
+- Allow `info`.
+- Warn on `low`.
+- Manual review on `medium`.
+- Sandbox required on `high`.
+- Block `critical`.
+
+Enterprise:
+
+- Allow `info`.
+- Warn on `low`.
+- Manual review on `medium`.
+- Dual approval or sandbox required on `high`.
+- Block `critical`.
+- Block undeclared sensitive behavior even when the base severity is lower.
+
+## Policy Inputs
+
+Policy should consider:
+
+- Risk level and score.
+- Finding category.
+- Confidence.
+- Target kind.
+- Source trust.
+- Whether the behavior is declared in `SKILL.md`.
+- Whether the skill requires secrets.
+- Whether the skill requires install commands.
+- Whether sandboxing is available.
+- Whether a finding is in executable code, metadata, documentation, or tests.
+- Whether the repo has a known maintainer or pinned version.
+
+## OpenClaw-Specific Checks
+
+Policy should treat these as important:
+
+- Workspace skill overrides a safer managed or bundled skill.
+- Skill ships through a plugin and may load indirectly.
+- Agent allowlists are unrestricted.
+- Main session has host tool access.
+- Non-main sandbox is unavailable or disabled.
+- Skill asks for tools that typical sandbox defaults deny.
+
+## ClawHub-Specific Checks
+
+Policy should treat these as important:
+
+- Local install differs from registry origin metadata.
+- Lockfile version is old, missing, or inconsistent.
+- A skill references secrets not declared under `metadata.openclaw`.
+- A skill requires binaries not declared under `requires.bins` or `requires.anyBins`.
+- A skill includes install specs that fetch packages or binaries.
+- Plugin compatibility or source metadata is missing.
+
+## Suppressions
+
+Suppressions should be explicit and auditable.
+
+Recommended suppression shape:
+
+```json
+{
+  "findingId": "network-access",
+  "path": "skills/weather/SKILL.md",
+  "reason": "Weather skill is expected to call the weather API.",
+  "expires": "2026-12-31",
+  "reviewer": "security@example.com"
+}
+```
+
+Rules:
+
+- Suppressions require a reason.
+- Suppressions should expire.
+- Suppressions should match finding ID and path.
+- Suppressions must not hide critical remote execution by default.
+
+## Audit Events
+
+Policy decisions should be exportable as JSONL:
+
+```json
+{
+  "time": "2026-05-07T00:00:00Z",
+  "target": "skills/todoist",
+  "score": 68,
+  "level": "high",
+  "decision": "sandbox_required",
+  "preset": "governed",
+  "findingIds": ["credential-access", "network-access"]
+}
+```
+
+This gives enterprise users a path to governance without making the first product heavy.

package/docs/PROJECT_REVIEW.md

@@ -0,0 +1,108 @@
+# ClawGuard Project Review
+
+This review is focused on making ClawGuard strong, secure, and credible as a public companion tool for OpenClaw-style skills and MCP configs.
+
+## What Is Already Strong
+
+- The project has a sharp purpose: scan skills before users trust them.
+- The first product surface is small and useful: `clawguard scan <path>`.
+- The scanner is static-only. It does not execute untrusted skill code.
+- The scanner has no runtime dependencies, which reduces supply-chain risk.
+- Findings are explainable: rule ID, severity, file, line, evidence, and recommendation.
+- The CLI supports JSON output, so it can become a GitHub Action or CI gate.
+- The README uses the right positioning: companion project, not OpenClaw replacement.
+- The repo includes safe and risky example skills for demos and tests.
+
+## Most Important Security Properties
+
+- Never execute scanned files.
+- Never install dependencies from scanned projects.
+- Avoid following symlinks into unexpected paths.
+- Bound file size and work per scan.
+- Keep every finding explainable.
+- Prefer clear false positives over silent false negatives, but keep noisy rules under control.
+- Make CI behavior configurable with a fail threshold.
+
+## Improvements Already Added
+
+- File-size guard with a 1 MB default limit.
+- Symlink skipping.
+- Unreadable file reporting instead of whole-scan failure.
+- Multiple findings per rule while avoiding overlapping duplicate evidence.
+- `--fail-on` CLI threshold for CI usage.
+- `--max-file-size` CLI option.
+- More rules for install lifecycle scripts, obfuscated execution, and data exfiltration.
+- OpenClaw `SKILL.md` frontmatter parsing.
+- First metadata mismatch checks for undeclared env vars, binaries, config paths, network access, and install behavior.
+- `.clawguard.json` policy/config support.
+- Policy decisions for personal, governed, and enterprise presets.
+- Suppressions with required reasons and critical-finding guardrails.
+- SARIF reporter for GitHub code scanning.
+- Composite GitHub Action metadata.
+- MCP/plugin config scanning for `.cursor/mcp.json`, `.openclaw/mcp.json`, `.openclaw/plugins.json`, and `mcp.json`.
+- MCP/plugin findings for runtime package commands, unpinned packages, secret env injection, broad filesystem access, shell execution, remote URLs, and write-capable tools.
+- Versioned JSON report schema.
+- Rule metadata catalog with stable rule IDs.
+- Self-contained HTML report generation.
+- OpenClaw workspace skill precedence scanning for `skills/` and `.agents/skills/`.
+- ClawHub lockfile and per-skill origin metadata scanning.
+- ClawHub version drift, source drift, missing origin, missing lockfile, invalid metadata, and unusual source rules.
+- Dependency manifest and lockfile scanning for npm and Python skill bundles.
+- Dependency findings for install scripts, missing lockfiles, unpinned specs, direct sources, suspicious names, and invalid manifests.
+- CI workflow with read-only GitHub token permissions.
+- Lockfile for deterministic npm metadata.
+- Threat model documentation.
+
+## Highest-Value Next Features
+
+1. GitHub Action Hardening
+
+   Add end-to-end workflow examples, upload SARIF in this repo's own CI, and test the action from a clean checkout.
+
+2. Real Fixture Corpus
+
+   Add many safe and risky fixtures so rule quality improves without guessing.
+
+3. SARIF Report
+
+   Generate GitHub code scanning output for pull request annotations.
+
+4. HTML Report Polish
+
+   Add visual screenshots, print styling, and optional report branding once the demo flow is ready.
+
+5. Web Demo
+
+   Build "paste SKILL.md -> get risk score" first. Folder upload can come later.
+
+6. Rule Metadata Refinement
+
+   Add confidence, CWE-style tags where useful, and richer examples for each rule.
+
+## Product Direction
+
+The best version of ClawGuard is not a giant framework. It is a trusted review layer:
+
+- Fast local CLI
+- CI gate
+- GitHub Action
+- Web demo
+- Security checklist
+- OpenClaw ecosystem docs and examples
+
+The strongest identity is:
+
+> The simple security scanner developers run before trusting an agent skill.
+
+## Launch Bar
+
+Before public launch, ClawGuard should have:
+
+- At least 20 tests
+- At least 20 fixtures
+- A demo GIF
+- A GitHub Action example
+- A threat model
+- A short limitations section
+- A clear non-affiliation statement
+- A security reporting policy

package/docs/REAL_WORLD_VALIDATION.md

@@ -0,0 +1,57 @@
+# Real-World Validation
+
+Last checked: 2026-05-08.
+
+## Sources Checked
+
+- Official ClawHub repository: https://github.com/openclaw/clawhub
+- Official ClawHub skill format docs: https://github.com/openclaw/clawhub/blob/main/docs/skill-format.md
+- OpenClaw ClawHub docs: https://docs.openclaw.ai/tools/clawhub
+
+The official `openclaw/clawhub` repository was cloned at:
+
+```text
+f14d70759dcc14b24890f5a50e1f9ce06f38eacd
+```
+
+An attempted shallow clone of `https://github.com/openclaw/skills` returned `Repository not found` from GitHub in this environment, so validation used the current ClawHub source repository, docs, schema code, and a local skill fixture modeled on the current public skill-format docs.
+
+## Compatibility Signals
+
+Current ClawHub docs describe:
+
+- Skill folders with `SKILL.md` or `skill.md`.
+- Per-skill install metadata at `<skill>/.clawhub/origin.json`.
+- Workspace install state at `<workdir>/.clawhub/lock.json`.
+- Runtime declarations under `metadata.openclaw`.
+- Alias metadata namespaces: `metadata.clawdbot` and `metadata.clawdis`.
+- Required env declarations through `requires.env`, `primaryEnv`, and `envVars`.
+- Install specs under `metadata.openclaw.install`.
+- Install kinds including `brew`, `node`, `go`, and `uv`.
+
+## Validation Results
+
+ClawGuard already covered the main ClawHub surfaces:
+
+- `SKILL.md` and `skill.md` frontmatter parsing.
+- `.clawhub/origin.json` and `.clawhub/lock.json` scanning.
+- `openclaw.plugin.json` package manifest scanning.
+- Lock/origin drift detection.
+- Declared env, binary, config, network, and install behavior.
+- npm and Python dependency manifest checks.
+- MCP and OpenClaw plugin config checks.
+
+This validation added parser support for:
+
+- `metadata.openclaw.envVars` map entries.
+- `requiredEnv` declarations used by ClawHub config examples.
+- OpenClaw plugin package compatibility fields required by current ClawHub publishing flows.
+- TypeScript plugin runtime entries that need matching compiled JavaScript output.
+
+The latest-format validation fixture now scans without undeclared metadata findings. It only reports the expected low external-network signal for the example URL.
+
+## Remaining Real-World Gaps
+
+- Add optional digest/source verification for ClawHub plugin packages when metadata is available.
+- Validate against real installed skill folders once a public archive or local ClawHub install is available.
+- Add a small corpus of known-safe and known-risky public skills after manual review.