@denial-web/clawguard 0.1.0

package/docs/INTEGRATION_SPEC.md

@@ -0,0 +1,253 @@
+# Integration Spec
+
+This spec defines how ClawGuard should work with OpenClaw, ClawHub, GitHub, web demos, and MCP without replacing any of them.
+
+## Integration Principles
+
+- Stay independent and compatible.
+- Prefer read-only scanning.
+- Run before trust is granted.
+- Use OpenClaw and ClawHub metadata when available.
+- Verify declarations against local file behavior.
+- Make output easy to paste into issues, PRs, and docs.
+
+## OpenClaw Integration
+
+### Skill Folder Scan
+
+Command:
+
+```bash
+clawguard scan-skill ./skills/my-skill
+```
+
+Behavior:
+
+- Locate `SKILL.md` or `skill.md`.
+- Parse frontmatter.
+- Scan supporting files.
+- Detect declared versus observed mismatch.
+- Produce risk score and policy decision.
+
+### Workspace Scan
+
+Command:
+
+```bash
+clawguard scan-workspace ~/.openclaw/workspace
+```
+
+Behavior:
+
+- Scan `<workspace>/skills`.
+- Scan `<workspace>/.agents/skills` if present.
+- Report duplicate skill names.
+- Report effective winning skills by precedence.
+- Report project-level skill risk.
+- Detect `.clawhub/lock.json` when present.
+
+Later:
+
+- Optionally inspect `~/.openclaw/skills` when explicitly requested.
+- Optionally inspect `~/.agents/skills` when explicitly requested.
+- Read OpenClaw config to understand agent skill allowlists.
+
+### Plugin-Aware Skill Scan
+
+Plugins can ship skills. ClawGuard should eventually parse plugin manifests and inspect bundled skill folders before the plugin is enabled.
+
+Checks:
+
+- Plugin-declared skills.
+- Plugin capabilities.
+- Install scripts or setup commands.
+- Compatibility metadata.
+- Required environment variables.
+- Tool surface exposed by the plugin.
+
+## ClawHub Integration
+
+### Pre-Install Gate
+
+Target command pattern:
+
+```bash
+clawguard clawhub inspect <slug>
+clawguard clawhub install --gate <slug>
+```
+
+Behavior:
+
+- Fetch or receive a skill bundle.
+- Scan before writing into the active workspace.
+- Show policy decision.
+- Continue only when policy allows or the operator approves.
+
+Network fetching should be opt-in. The first implementation can scan bundles already downloaded by `clawhub inspect` or native OpenClaw commands.
+
+### Post-Install Audit
+
+Command:
+
+```bash
+clawguard scan ./skills
+```
+
+Behavior:
+
+- Scan installed skills.
+- Read `.clawhub/lock.json` if present.
+- Read per-skill `.clawhub/origin.json` if present.
+- Detect local drift from registry metadata when enough information exists.
+
+Current implementation:
+
+- Normalizes lockfile entries from `skills` or `packages` arrays and objects.
+- Normalizes origin metadata from per-skill `.clawhub/origin.json` files.
+- Reports missing lockfile, missing origin metadata, version drift, source drift, invalid metadata, and unusual source URLs.
+- Adds a `clawhub` summary to JSON and HTML reports.
+
+### Metadata Comparison
+
+ClawGuard should compare:
+
+- Declared `requires.env` versus observed env var usage.
+- Declared `primaryEnv` and `envVars` versus observed credential usage.
+- Declared `requires.bins` or `requires.anyBins` versus observed shell commands.
+- Declared `requires.config` versus observed config reads.
+- Declared `install` specs versus package files and setup instructions.
+- Declared homepage/source versus remote URLs used by the skill.
+
+## MCP and Tool Config Integration
+
+Initial config paths:
+
+- `.openclaw/plugins.json`
+- `.openclaw/mcp.json`
+- `.cursor/mcp.json`
+- `mcp.json`
+- Common project-local MCP config files discovered later.
+
+Checks:
+
+- Unknown command sources.
+- Broad filesystem access.
+- Environment variable injection.
+- Tools that can send messages, browse, write files, run shell, control gateway, or call external APIs.
+- Unpinned package specs.
+- Install commands.
+- Remote endpoints.
+
+Current implementation:
+
+- Scans `.openclaw/plugins.json`, `.openclaw/mcp.json`, `.cursor/mcp.json`, and `mcp.json`.
+- Reports runtime package commands, unpinned packages, shell execution, secret env injection, broad filesystem access, remote URLs, and write-capable external tools.
+
+Command:
+
+```bash
+clawguard scan-mcp .cursor/mcp.json
+```
+
+## GitHub Action
+
+Use cases:
+
+- Scan pull requests adding or changing skills.
+- Scan `SKILL.md` metadata before publishing to ClawHub.
+- Upload SARIF to GitHub code scanning.
+- Fail PRs based on policy preset.
+
+Example:
+
+```yaml
+name: ClawGuard
+
+on:
+  pull_request:
+
+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
+          sarif: clawguard.sarif
+```
+
+## Web Demo
+
+First demo:
+
+- Paste `SKILL.md`.
+- Click scan.
+- Show risk score.
+- Show findings with line evidence.
+- Show safer action.
+
+Second demo:
+
+- Upload a skill folder as zip.
+- Scan files in browser where possible.
+- Keep uploads local-only if feasible.
+
+The web demo should be visual and shareable, but the security model must be clear: static analysis helps review risk, it does not prove safety.
+
+## MCP Server
+
+Optional later server:
+
+Tools:
+
+- `scan_skill`
+- `scan_directory`
+- `scan_mcp_config`
+- `explain_finding`
+- `policy_decision`
+
+Rules:
+
+- Read-only by default.
+- No remote fetching unless explicitly enabled.
+- No command execution.
+- Return structured results.
+- Keep evidence bounded.
+
+## Output Compatibility
+
+All integrations should use one shared core report schema. Surfaces can format differently, but the underlying result should be stable.
+
+Required report fields:
+
+- `target`
+- `targetKind`
+- `source`
+- `score`
+- `level`
+- `decision`
+- `findings`
+- `filesScanned`
+- `filesSkipped`
+- `scanOptions`
+- `limitations`
+
+## First Integration Sequence
+
+1. `SKILL.md` frontmatter parser.
+2. Metadata mismatch checks.
+3. Workspace scan with duplicate/effective skill reporting.
+4. JSON schema for reports.
+5. GitHub Action wrapper.
+6. SARIF reporter.
+7. Web paste demo.
+8. MCP config parser.
+9. ClawHub origin/lockfile parser.
+10. Dependency and package lock scanner.
+11. Optional ClawHub pre-install wrapper.

package/docs/LAUNCH_CHECKLIST.md

@@ -0,0 +1,64 @@
+# Launch Checklist
+
+Use this before sharing ClawGuard publicly.
+
+## Product Readiness
+
+- [x] `npm test` passes.
+- [x] `npm run web` starts locally.
+- [x] Paste scan works.
+- [x] Folder scan works.
+- [x] Example scans work for safe, risky, ClawHub, dependency, workspace, and MCP cases.
+- [x] HTML report download works.
+- [x] JSON copy works or fails gracefully when browser clipboard permission is blocked.
+- [x] README Quick Start is accurate.
+- [x] Security model and limitations are clear.
+
+## Demo Assets
+
+- [x] Record a short web demo video.
+- [x] Capture a screenshot of the `Dependency Risk` scan.
+- [x] Capture a screenshot of the downloaded HTML report.
+- [x] Add screenshot or GIF links to README.
+- [x] Prepare a 30-second demo script from [docs/DEMO_SCRIPT.md](DEMO_SCRIPT.md).
+- [x] Add repeatable demo capture command.
+
+## 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] License is visible.
+- [x] Security policy is visible.
+- [x] GitHub Action example is documented.
+- [x] Rule catalog is documented.
+- [x] Bug report issue template is available.
+- [x] Fixture submission issue template is available.
+- [x] Pull request template is available.
+- [x] v0.1.0 release notes are drafted.
+- [x] Package metadata and npm package contents are validated.
+
+## First Launch Post
+
+Suggested post:
+
+> 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.
+
+Include:
+
+- One screenshot or GIF.
+- Link to README.
+- One sentence about static-analysis limitations.
+- Invitation for safe/risky fixture contributions.
+
+## Do Not Launch Until
+
+- [x] The demo can be run by someone else from a fresh clone.
+- [x] The README explains that ClawGuard is independent and not affiliated with OpenClaw.
+- [x] Findings are clearly described as risk signals, not proof of malicious intent.
+
+## Remaining Before Public Launch
+
+- 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/LAUNCH_PLAN.md

@@ -0,0 +1,40 @@
+# ClawGuard Launch Plan
+
+## Week 1: Useful MVP
+
+- Keep the CLI dependency-free and easy to run. Status: done.
+- Improve detection for `SKILL.md`, MCP configs, package scripts, shell scripts, and install instructions. Status: done.
+- Add JSON output examples for CI usage. Status: done.
+- Add a local web demo with paste, folder, examples, JSON copy, and HTML report export. Status: done.
+- Record a short web demo GIF. Status: next.
+
+## Week 2: GitHub Visibility
+
+- Publish the repo with a clear README and demo GIF.
+- Submit small upstream PRs: safety checklist, skill review guidance, metadata suggestions.
+- Open useful OpenClaw ecosystem discussions without promoting aggressively.
+- Write one technical article: "How to Audit OpenClaw Skills Before Running Them".
+
+## Week 3: Shareable Tooling
+
+- Add a simple web scanner: upload skill folder or paste `SKILL.md`. Status: done.
+- Add a GitHub Action wrapper. Status: done.
+- Add a badge format: `ClawGuard: scanned`.
+- Generate shareable HTML reports. Status: done.
+
+## Week 4: Authority
+
+- Publish a small "OpenClaw Skill Security Checklist".
+- Start `awesome-openclaw-security` only after ClawGuard has real usage.
+- Document threat models: prompt injection, secret access, tool abuse, remote code execution.
+- Invite feedback from maintainers and security researchers.
+
+## Positioning Rule
+
+Be the companion security layer for the ecosystem. Do not position ClawGuard as an OpenClaw replacement.
+
+## Immediate Next
+
+1. Capture screenshots and a short GIF using [docs/DEMO_SCRIPT.md](DEMO_SCRIPT.md).
+2. Add the screenshot/GIF to the README.
+3. Run the launch checklist in [docs/LAUNCH_CHECKLIST.md](LAUNCH_CHECKLIST.md).

package/docs/LOCAL_PROJECT_ASSETS.md

@@ -0,0 +1,250 @@
+# Local Project Assets For ClawGuard
+
+This file maps useful material found in nearby local projects under `/Users/hy/CascadeProjects`.
+
+The goal is not to blindly merge projects. The strongest path is to reuse patterns, tests, fixtures, and architecture ideas that make ClawGuard more credible as a focused OpenClaw-style skill and MCP security scanner.
+
+## Best Reuse Candidates
+
+### 1. AegisBrain Skill Scanner
+
+Source:
+
+- `/Users/hy/CascadeProjects/aegisbrain/packages/skill-runtime/src/scanner.ts`
+- `/Users/hy/CascadeProjects/aegisbrain/docs/SECURITY_MODEL.md`
+- `/Users/hy/CascadeProjects/aegisbrain/packages/policies/governed/default.policy.json`
+- `/Users/hy/CascadeProjects/aegisbrain/packages/policies/consumer/default.policy.json`
+
+Useful ideas:
+
+- Manifest integrity checks
+- Blocked tool allowlist
+- Declared risk-level validation
+- Step-count limits
+- Permission-scope audit
+- Trust levels: `verified`, `scanned`, `untrusted`
+- Security model language: default deny, fail closed, audit trail, separation of planning and execution
+
+Best ClawGuard use:
+
+- Add structured `manifest` checks when a skill has JSON metadata.
+- Add trust-level output next to the numeric risk score.
+- Add policy presets: `consumer`, `governed`, and later `enterprise`.
+
+### 2. ToolGovernor / Agent-Immune
+
+Source:
+
+- `/Users/hy/CascadeProjects/toolgovernor/src/agent_immune/core/output_scanner.py`
+- `/Users/hy/CascadeProjects/toolgovernor/src/agent_immune/mcp_server.py`
+- `/Users/hy/CascadeProjects/toolgovernor/tests/test_output_scanner.py`
+- `/Users/hy/CascadeProjects/toolgovernor/docs/mcp_marketplaces.md`
+- `/Users/hy/CascadeProjects/toolgovernor/SECURITY.md`
+
+Useful ideas:
+
+- Credential and PII detection patterns
+- Base64, hex, data URI, JWT, and long-query exfiltration detection
+- System-prompt leak heuristics
+- Output scanning as a separate product surface
+- MCP server packaging and marketplace checklist
+- Stronger security policy disclosure language
+
+Best ClawGuard use:
+
+- Import the test-case ideas into JavaScript fixtures.
+- Add an optional `scan-output` command later.
+- Add MCP marketplace positioning once ClawGuard has an MCP server.
+
+Security note:
+
+- Token-looking local files exist in `toolgovernor` (`.mcpregistry_*`). They appear ignored by git status, but do not read or copy them into ClawGuard.
+
+### 3. Nexus Agent Immune Scanner
+
+Source:
+
+- `/Users/hy/CascadeProjects/nexus-agent/app/core/immune/scanner.py`
+- `/Users/hy/CascadeProjects/nexus-agent/tests/test_mcp_proxy.py`
+- `/Users/hy/CascadeProjects/nexus-agent/tests/test_audit_export.py`
+
+Useful ideas:
+
+- Unicode normalization for zero-width characters and confusables
+- Multi-language prompt-injection patterns
+- Session escalation tracking
+- Tool-call boundary rule: block any non-pass verdict
+- SIEM-style JSONL audit export tests
+- MCP governance proxy tests
+
+Best ClawGuard use:
+
+- Add Unicode normalization before regex scanning.
+- Add multi-language prompt-injection fixtures.
+- Add JSONL report export later.
+- Use the MCP proxy tests as inspiration for future MCP config/tool scanning.
+
+### 4. Sidekick-OS Governor
+
+Source:
+
+- `/Users/hy/CascadeProjects/Sidekick-OS/functions/src/governor/policyEngine.ts`
+- `/Users/hy/CascadeProjects/Sidekick-OS/functions/src/governor/toolGate.ts`
+- `/Users/hy/CascadeProjects/Sidekick-OS/functions/src/governor/auditLogger.ts`
+- `/Users/hy/CascadeProjects/Sidekick-OS/functions/src/security/promptPolicy.ts`
+- `/Users/hy/CascadeProjects/Sidekick-OS/.cursor/skills/firebase-iam-triage/SKILL.md`
+
+Useful ideas:
+
+- Policy actions: `REJECT`, `ESCALATE`, `INJECT_CONSTRAINT`, `REQUIRE_DUAL_APPROVAL`
+- Tool-name to action-type mapping
+- Hash-chained audit log
+- Prompt role sanitization
+- Real Cursor-style skill file to use as a safe/operational fixture
+
+Best ClawGuard use:
+
+- Add policy-action terminology to ClawGuard recommendations.
+- Add a future `--policy governed` mode.
+- Add the Firebase IAM skill as a safe fixture after removing project-specific identifiers if publishing publicly.
+
+### 5. Minister Governor / Covernor Platform
+
+Source:
+
+- `/Users/hy/CascadeProjects/minister-governor-platform/src/core/governor/policies/engine.ts`
+- `/Users/hy/CascadeProjects/minister-governor-platform/src/config/policies.json`
+- `/Users/hy/CascadeProjects/minister-governor-platform/src/core/policy/capability.registry.ts`
+- `/Users/hy/CascadeProjects/minister-governor-platform/src/core/policy/schema.validator.ts`
+- `/Users/hy/CascadeProjects/minister-governor-platform/src/db/audit.logger.ts`
+- `/Users/hy/CascadeProjects/minister-governor-platform/tests/unit/policy-engine.spec.ts`
+- `/Users/hy/CascadeProjects/minister-governor-platform/docs/STRATEGIC_OPTIONS.md`
+
+Useful ideas:
+
+- Capability registry that maps raw tools to high-level capabilities
+- Policy engine with conditions and constraints
+- Provenance-required policy for financial routing
+- Dual approval for very high-risk actions
+- Schema validation for LLM-proposed actions
+- Serializable hash-chain audit logging
+
+Best ClawGuard use:
+
+- Add capability categories to scanner findings: filesystem, network, credential, shell, browser, finance, communication.
+- Add policy recommendations like `block`, `approve_with_constraints`, `manual_review`, `dual_approval`.
+- Use the unit tests as a pattern for policy-mode tests.
+
+### 6. Sidekick Studio Skills
+
+Source:
+
+- `/Users/hy/CascadeProjects/sidekick-studio/.cursor/skills/*/SKILL.md`
+- `/Users/hy/CascadeProjects/sidekick-studio/.cursor/skills/security-auditor/SKILL.md`
+- `/Users/hy/CascadeProjects/sidekick-studio/.cursor/mcp.json`
+- `/Users/hy/CascadeProjects/sidekick-studio/packages/authz/src/policy.ts`
+
+Useful ideas:
+
+- Many real `SKILL.md` examples for fixture testing
+- Security-auditor skill rubric
+- MCP config with stdio and HTTP servers
+- Workspace role/capability model
+
+Best ClawGuard use:
+
+- Build a fixture corpus of realistic benign skills.
+- Add MCP config scanning for risky commands such as `npx -y`, broad external MCPs, and missing descriptions.
+- Add role/capability language later for enterprise reports.
+
+### 7. A-S-FLC Security Guard
+
+Source:
+
+- `/Users/hy/CascadeProjects/a-s-flc-llm-enhancer/core/policy_guard.py`
+- `/Users/hy/CascadeProjects/a-s-flc-llm-enhancer/tests/test_policy_guard.py`
+- `/Users/hy/CascadeProjects/a-s-flc-llm-enhancer/training/security_query_bank.json`
+- `/Users/hy/CascadeProjects/a-s-flc-llm-enhancer/SECURITY_ADAPTER.md`
+
+Useful ideas:
+
+- Deterministic pre-LLM guard framing
+- Security query bank for evaluation data
+- Scam, credential-harvesting, PII, and prompt-injection categories
+- Good product language: keep secret handling and escalation in code, not model weights
+
+Best ClawGuard use:
+
+- Use as inspiration for fixture categories and docs.
+- Add an evaluation corpus later, separate from unit tests.
+
+### 8. Khmer Chatbot Security Scripts
+
+Source:
+
+- `/Users/hy/CascadeProjects/khmer-chatbot-ai/security-check.py`
+- `/Users/hy/CascadeProjects/khmer-chatbot-ai/quick-security-check.py`
+- `/Users/hy/CascadeProjects/khmer-chatbot-ai/docs/security-checklist.md`
+
+Useful ideas:
+
+- Deployment-oriented checks for secrets, env files, Dockerfiles, and `.gitignore`
+- Clear pass/fail CLI output
+- Security checklist format
+
+Best ClawGuard use:
+
+- Add repository hygiene checks later: `.env`, service account keys, Dockerfile root user, missing `.gitignore`.
+- Keep these separate from skill scanning so the MVP stays focused.
+
+### 9. Doc Intelligence MCP
+
+Source:
+
+- `/Users/hy/CascadeProjects/doc-intelligence-mcp/src/server.ts`
+- `/Users/hy/CascadeProjects/doc-intelligence-mcp/package.json`
+- `/Users/hy/CascadeProjects/doc-intelligence-mcp/AGENTS.md`
+- `/Users/hy/CascadeProjects/doc-intelligence-mcp/API_REFERENCE.md`
+
+Useful ideas:
+
+- Real MCP server with 28 tools
+- Tool inventory and descriptions
+- Input schemas and tool metadata
+- HTTP/SSE transport example
+
+Best ClawGuard use:
+
+- Use as a realistic MCP scanning fixture.
+- Extract tool inventory patterns for future MCP risk reports.
+
+## Recommended Import Order
+
+1. Unicode normalization and extra prompt-injection fixtures from `nexus-agent`.
+2. Credential/output leak patterns and tests from `toolgovernor`.
+3. Manifest/trust-level checks from `aegisbrain`.
+4. Policy recommendation language from `minister-governor-platform` and `Sidekick-OS`.
+5. Real benign `SKILL.md` fixtures from `sidekick-studio`.
+6. MCP config scanning using `sidekick-studio/.cursor/mcp.json` and `doc-intelligence-mcp`.
+7. Hash-chained audit and JSONL report ideas after the CLI is stable.
+
+## What Not To Do
+
+- Do not merge whole projects into ClawGuard.
+- Do not add Python dependencies to the current Node CLI just to reuse Python logic.
+- Do not copy token files, local environment files, or project-specific secrets.
+- Do not make ClawGuard a full governance runtime yet.
+- Do not chase enterprise approval flows before the scanner has excellent fixtures and demos.
+
+## Strongest Product Path
+
+ClawGuard should become:
+
+- `clawguard scan <skill-dir>`
+- `clawguard scan-mcp <mcp.json>`
+- `clawguard scan-output <text-file>`
+- GitHub Action
+- Web demo
+- Explainable HTML/JSON report
+
+The local codebase already contains enough material to make ClawGuard much stronger without inventing from scratch.

package/docs/MCP_PLUGIN_SCANNING.md

@@ -0,0 +1,53 @@
+# MCP and Plugin Config Scanning
+
+ClawGuard scans MCP and plugin config files as part of the normal `scan` command.
+
+## Supported Paths
+
+Current paths:
+
+- `.cursor/mcp.json`
+- `.openclaw/mcp.json`
+- `.openclaw/plugins.json`
+- `mcp.json`
+- `openclaw.plugin.json`
+
+These paths matter because skills can be low-risk on paper while the tool layer they activate is powerful.
+
+## Checks
+
+ClawGuard currently reports:
+
+- Runtime package commands such as `npx`, `uvx`, and `pnpm dlx`.
+- Unpinned package specs used by runtime package commands.
+- Shell or dynamic execution through `bash -c`, `python -c`, `node -e`, and similar patterns.
+- Secret environment injection such as `GITHUB_TOKEN`, `OPENAI_API_KEY`, or other token-like names.
+- Broad filesystem access such as `$HOME`, `~/`, `/`, or user home paths.
+- Remote URLs.
+- Write-capable browser, email, calendar, Slack, and GitHub capabilities.
+- Invalid JSON in recognized config files.
+- OpenClaw plugin packages with missing `package.json` metadata.
+- Missing ClawHub compatibility metadata in plugin package manifests.
+- Local runtime code execution through `openclaw.extensions` or `openclaw.runtimeExtensions`.
+- TypeScript plugin entries without matching compiled JavaScript runtime output.
+- Sensitive host capabilities such as shell, process, and filesystem access.
+
+## Example
+
+```bash
+npm run scan -- examples/risky-mcp-config
+```
+
+Useful fixtures:
+
+- `examples/safe-mcp-config`
+- `examples/risky-mcp-config`
+- `examples/openclaw-plugin-config`
+- `examples/safe-openclaw-plugin`
+- `examples/risky-openclaw-plugin`
+
+## Security Model
+
+The scanner does not start MCP servers, install packages, or execute configured commands. It reads the config as data and reports risk signals.
+
+This keeps ClawGuard safe to run on untrusted repositories and pull requests.