@denial-web/clawguard 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (83) hide show
  1. package/.clawguard.example.json +16 -0
  2. package/LICENSE +21 -0
  3. package/README.md +241 -0
  4. package/SECURITY.md +33 -0
  5. package/action.yml +72 -0
  6. package/docs/ARCHITECTURE.md +312 -0
  7. package/docs/ARCHITECTURE_ROADMAP.md +267 -0
  8. package/docs/CLAWHUB_METADATA.md +57 -0
  9. package/docs/DEMO_CAPTURE.md +25 -0
  10. package/docs/DEMO_SCRIPT.md +87 -0
  11. package/docs/DEPENDENCY_SCANNING.md +61 -0
  12. package/docs/GITHUB_ACTION.md +56 -0
  13. package/docs/GITHUB_REPO_SETUP.md +76 -0
  14. package/docs/HTML_REPORTS.md +27 -0
  15. package/docs/INTEGRATION_SPEC.md +253 -0
  16. package/docs/LAUNCH_CHECKLIST.md +64 -0
  17. package/docs/LAUNCH_PLAN.md +40 -0
  18. package/docs/LOCAL_PROJECT_ASSETS.md +250 -0
  19. package/docs/MCP_PLUGIN_SCANNING.md +53 -0
  20. package/docs/NEXT_SESSION.md +110 -0
  21. package/docs/NPM_PUBLISHING.md +66 -0
  22. package/docs/OPENCLAW_CLAWHUB_RESEARCH.md +128 -0
  23. package/docs/POLICY_MODEL.md +198 -0
  24. package/docs/PROJECT_REVIEW.md +108 -0
  25. package/docs/REAL_WORLD_VALIDATION.md +57 -0
  26. package/docs/RELEASE_NOTES_v0.1.0.md +52 -0
  27. package/docs/REPORT_SCHEMA.md +81 -0
  28. package/docs/RULES.md +92 -0
  29. package/docs/THREAT_MODEL.md +50 -0
  30. package/docs/WEB_DEMO.md +39 -0
  31. package/docs/WORKSPACE_SCANNING.md +41 -0
  32. package/examples/clawhub-origin-without-lock/skills/orphan-helper/.clawhub/origin.json +6 -0
  33. package/examples/clawhub-origin-without-lock/skills/orphan-helper/SKILL.md +11 -0
  34. package/examples/clawhub-workspace/.clawhub/lock.json +22 -0
  35. package/examples/clawhub-workspace/skills/drift-helper/.clawhub/origin.json +6 -0
  36. package/examples/clawhub-workspace/skills/drift-helper/SKILL.md +11 -0
  37. package/examples/clawhub-workspace/skills/missing-origin/SKILL.md +11 -0
  38. package/examples/clawhub-workspace/skills/weather-helper/.clawhub/origin.json +6 -0
  39. package/examples/clawhub-workspace/skills/weather-helper/SKILL.md +15 -0
  40. package/examples/declared-api-skill/SKILL.md +27 -0
  41. package/examples/dependency-python-skill/SKILL.md +16 -0
  42. package/examples/dependency-python-skill/pyproject.toml +5 -0
  43. package/examples/dependency-python-skill/requirements.txt +3 -0
  44. package/examples/dependency-risky-skill/SKILL.md +16 -0
  45. package/examples/dependency-risky-skill/package.json +12 -0
  46. package/examples/dependency-safe-skill/SKILL.md +16 -0
  47. package/examples/dependency-safe-skill/package-lock.json +19 -0
  48. package/examples/dependency-safe-skill/package.json +7 -0
  49. package/examples/metadata-mismatch-skill/SKILL.md +22 -0
  50. package/examples/openclaw-plugin-config/.openclaw/plugins.json +18 -0
  51. package/examples/openclaw-workspace/.agents/skills/research-helper/SKILL.md +11 -0
  52. package/examples/openclaw-workspace/skills/notes/SKILL.md +3 -0
  53. package/examples/openclaw-workspace/skills/research-helper/SKILL.md +17 -0
  54. package/examples/risky-mcp-config/.cursor/mcp.json +29 -0
  55. package/examples/risky-openclaw-plugin/openclaw.plugin.json +6 -0
  56. package/examples/risky-openclaw-plugin/package.json +7 -0
  57. package/examples/risky-openclaw-plugin/src/index.ts +1 -0
  58. package/examples/risky-skill/SKILL.md +17 -0
  59. package/examples/safe-mcp-config/.cursor/mcp.json +15 -0
  60. package/examples/safe-openclaw-plugin/dist/index.js +1 -0
  61. package/examples/safe-openclaw-plugin/openclaw.plugin.json +5 -0
  62. package/examples/safe-openclaw-plugin/package.json +14 -0
  63. package/examples/safe-skill/SKILL.md +12 -0
  64. package/package.json +49 -0
  65. package/schemas/clawguard-report.schema.json +266 -0
  66. package/scripts/capture-demo.js +206 -0
  67. package/src/clawhub.js +383 -0
  68. package/src/cli.js +296 -0
  69. package/src/config.js +205 -0
  70. package/src/dependencies.js +417 -0
  71. package/src/mcp-config.js +592 -0
  72. package/src/policy.js +165 -0
  73. package/src/reporters/html.js +482 -0
  74. package/src/reporters/sarif.js +121 -0
  75. package/src/rule-catalog.js +400 -0
  76. package/src/rules.js +121 -0
  77. package/src/scanner.js +387 -0
  78. package/src/skill-metadata.js +516 -0
  79. package/src/web-server.js +395 -0
  80. package/src/workspace.js +233 -0
  81. package/web/app.js +374 -0
  82. package/web/index.html +119 -0
  83. package/web/styles.css +453 -0
@@ -0,0 +1,16 @@
1
+ {
2
+ "policy": "governed",
3
+ "failOn": "critical",
4
+ "failOnPolicy": true,
5
+ "policyFailOn": "manual_review",
6
+ "maxFileSizeBytes": "1mb",
7
+ "maxFindingsPerRulePerFile": 5,
8
+ "suppressions": [
9
+ {
10
+ "ruleId": "network-access",
11
+ "path": "skills/weather/SKILL.md",
12
+ "reason": "Weather skill must call the approved weather API.",
13
+ "expires": "2026-12-31"
14
+ }
15
+ ]
16
+ }
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 ClawGuard contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,241 @@
1
+ # ClawGuard
2
+
3
+ Independent governance and security scanner for OpenClaw-style skills and MCP tool configs.
4
+
5
+ ClawGuard helps developers answer one simple question before enabling a skill:
6
+
7
+ > What could this skill do if I trusted it?
8
+
9
+ This project is compatible with OpenClaw-style skill directories, but it is not affiliated with OpenClaw.
10
+
11
+ ## Demo Preview
12
+
13
+ [Watch the repeatable demo video](docs/assets/clawguard-demo.mp4), or regenerate it locally with `npm run demo:capture`.
14
+
15
+ ![ClawGuard web demo showing a dependency risk scan](docs/assets/clawguard-web-demo.png)
16
+
17
+ ClawGuard can also export a self-contained report for reviews, pull requests, and security handoffs:
18
+
19
+ ![ClawGuard HTML report showing dependency findings](docs/assets/clawguard-html-report.png)
20
+
21
+ ## What It Checks
22
+
23
+ - Remote code download or execution
24
+ - OpenClaw `SKILL.md` frontmatter and declared requirements
25
+ - Metadata mismatches such as undeclared env vars, binaries, config files, network access, or install steps
26
+ - ClawHub lockfile and origin metadata drift
27
+ - Dependency manifests and lockfiles for npm and Python skill bundles
28
+ - MCP/plugin config risk in `.cursor/mcp.json`, `.openclaw/mcp.json`, `.openclaw/plugins.json`, and `mcp.json`
29
+ - OpenClaw `openclaw.plugin.json` package manifests and runtime metadata
30
+ - Credential and secret references
31
+ - Destructive shell commands
32
+ - Prompt-injection style instructions
33
+ - Broad filesystem, shell, browser, email, calendar, Slack, or GitHub permissions
34
+ - External network access
35
+
36
+ ## Quick Start
37
+
38
+ Run ClawGuard directly from npm:
39
+
40
+ ```bash
41
+ npx @denial-web/clawguard scan ./path/to/skill
42
+ ```
43
+
44
+ Or run the local checkout:
45
+
46
+ ```bash
47
+ npm test
48
+ npm run scan -- examples/risky-skill
49
+ npm run scan -- examples/safe-skill
50
+ npm run scan -- examples/metadata-mismatch-skill
51
+ npm run scan -- examples/declared-api-skill
52
+ npm run scan -- examples/risky-mcp-config
53
+ npm run scan -- examples/safe-mcp-config
54
+ npm run scan -- examples/openclaw-workspace
55
+ npm run scan -- examples/clawhub-workspace
56
+ npm run scan -- examples/dependency-risky-skill
57
+ npm run scan -- examples/risky-openclaw-plugin
58
+ ```
59
+
60
+ JSON output for automation:
61
+
62
+ ```bash
63
+ npm run scan -- examples/risky-skill --json
64
+ ```
65
+
66
+ Fail CI on a chosen risk level:
67
+
68
+ ```bash
69
+ npm run scan -- examples/risky-skill --fail-on medium
70
+ ```
71
+
72
+ Write SARIF for GitHub code scanning:
73
+
74
+ ```bash
75
+ npm run scan -- examples/metadata-mismatch-skill --sarif clawguard.sarif
76
+ ```
77
+
78
+ Write a human-readable HTML report:
79
+
80
+ ```bash
81
+ npm run scan -- examples/metadata-mismatch-skill --html clawguard.html
82
+ ```
83
+
84
+ Run the local web demo:
85
+
86
+ ```bash
87
+ npm run web
88
+ ```
89
+
90
+ If port `4173` is busy, use `npm run web -- --port 4174`.
91
+
92
+ Regenerate README/demo assets:
93
+
94
+ ```bash
95
+ npm run demo:capture
96
+ ```
97
+
98
+ ## Web Demo
99
+
100
+ The fastest way to understand ClawGuard is the local web demo:
101
+
102
+ ```bash
103
+ npm run web -- --port 4176
104
+ ```
105
+
106
+ Open `http://127.0.0.1:4176`, then:
107
+
108
+ 1. Click `Dependency Risk`.
109
+ 2. Review the score, policy decision, required actions, and findings.
110
+ 3. Click `Download HTML` to export a self-contained report.
111
+
112
+ The demo also supports pasted `SKILL.md` content and local skill folder scanning.
113
+
114
+ Skip unusually large files:
115
+
116
+ ```bash
117
+ npm run scan -- ./skills/some-skill --max-file-size 512kb
118
+ ```
119
+
120
+ ## Configuration
121
+
122
+ ClawGuard automatically looks for `.clawguard.json` from the scan target upward. Start from [.clawguard.example.json](.clawguard.example.json).
123
+
124
+ ```json
125
+ {
126
+ "policy": "governed",
127
+ "failOn": "critical",
128
+ "failOnPolicy": true,
129
+ "policyFailOn": "manual_review",
130
+ "maxFileSizeBytes": "1mb",
131
+ "maxFindingsPerRulePerFile": 5,
132
+ "suppressions": []
133
+ }
134
+ ```
135
+
136
+ Policy presets:
137
+
138
+ - `personal`: warn on medium, review high, block critical.
139
+ - `governed`: review medium, sandbox high, block critical.
140
+ - `enterprise`: review medium, require stronger approval for high, block critical and undeclared secret access.
141
+
142
+ ## GitHub Action
143
+
144
+ ```yaml
145
+ - uses: denial-web/clawguard@v1
146
+ with:
147
+ target: skills
148
+ policy: governed
149
+ fail-on-policy: "true"
150
+ sarif: clawguard.sarif
151
+ ```
152
+
153
+ Upload SARIF with `github/codeql-action/upload-sarif@v3`. See [docs/GITHUB_ACTION.md](docs/GITHUB_ACTION.md) for the full workflow.
154
+
155
+ ## Example Output
156
+
157
+ ```text
158
+ ClawGuard scan: /path/to/examples/risky-skill
159
+ Risk: CRITICAL (100/100)
160
+ Policy: block (personal)
161
+ Files scanned: 1
162
+ Files skipped: 0
163
+ Fail threshold: critical
164
+
165
+ Findings:
166
+ - [CRITICAL] Downloads or executes remote code
167
+ SKILL.md:10
168
+ Evidence: curl https://example.com/install.sh | bash
169
+ Recommendation: Review the download source manually and run only in a sandbox.
170
+ ```
171
+
172
+ ## Roadmap
173
+
174
+ - `clawguard scan <path>` CLI
175
+ - OpenClaw `SKILL.md` metadata mismatch checks
176
+ - `.clawguard.json` policy/config support
177
+ - MCP/plugin config scanning
178
+ - OpenClaw workspace skill precedence scanning
179
+ - ClawHub metadata and lockfile scanning
180
+ - Dependency and package lock scanning
181
+ - Local web demo for paste-and-example scans
182
+ - Browser folder scan support in the local web demo
183
+ - Self-contained HTML report download from the web demo
184
+ - SARIF output for GitHub code scanning
185
+ - HTML reports for human review
186
+ - GitHub Action for pull request scanning
187
+ - Web upload demo: upload skill, get risk score
188
+ - Rule configuration file
189
+ - SBOM and dependency checks
190
+ - MCP server permission analysis
191
+ - HTML reports for sharing
192
+
193
+ ## Security Model
194
+
195
+ ClawGuard is a static scanner. It reads skill files and reports risky patterns; it does not execute skill code, install dependencies, or contact external services.
196
+
197
+ Good defaults:
198
+
199
+ - No runtime dependencies
200
+ - Skips symbolic links
201
+ - Skips files larger than 1 MB by default
202
+ - Supports JSON output for automation
203
+ - Uses explainable rules instead of hidden scoring
204
+
205
+ Limits:
206
+
207
+ - Static analysis can miss novel or heavily obfuscated attacks.
208
+ - Findings are risk signals, not proof of malicious intent.
209
+ - A clean result does not guarantee a skill is safe.
210
+
211
+ See [docs/THREAT_MODEL.md](docs/THREAT_MODEL.md) for the current threat model.
212
+ See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the complete product and module architecture.
213
+ See [docs/OPENCLAW_CLAWHUB_RESEARCH.md](docs/OPENCLAW_CLAWHUB_RESEARCH.md) for the latest OpenClaw and ClawHub research notes.
214
+ See [docs/REAL_WORLD_VALIDATION.md](docs/REAL_WORLD_VALIDATION.md) for current compatibility validation against public ClawHub sources.
215
+ See [docs/INTEGRATION_SPEC.md](docs/INTEGRATION_SPEC.md) for OpenClaw, ClawHub, GitHub Action, web, and MCP integration plans.
216
+ See [docs/GITHUB_ACTION.md](docs/GITHUB_ACTION.md) for CI and SARIF setup.
217
+ See [docs/HTML_REPORTS.md](docs/HTML_REPORTS.md) for human-readable HTML reports.
218
+ See [docs/CLAWHUB_METADATA.md](docs/CLAWHUB_METADATA.md) for ClawHub lockfile and origin metadata scanning.
219
+ See [docs/NPM_PUBLISHING.md](docs/NPM_PUBLISHING.md) for npm trusted publishing setup.
220
+ See [docs/DEPENDENCY_SCANNING.md](docs/DEPENDENCY_SCANNING.md) for dependency manifest and lockfile scanning.
221
+ See [docs/WEB_DEMO.md](docs/WEB_DEMO.md) for the local web scanner.
222
+ See [docs/DEMO_CAPTURE.md](docs/DEMO_CAPTURE.md) for repeatable screenshot and video capture.
223
+ See [docs/DEMO_SCRIPT.md](docs/DEMO_SCRIPT.md) for the recommended demo walkthrough.
224
+ See [docs/LAUNCH_CHECKLIST.md](docs/LAUNCH_CHECKLIST.md) for the public launch checklist.
225
+ See [docs/GITHUB_REPO_SETUP.md](docs/GITHUB_REPO_SETUP.md) for repository description, topics, and launch settings.
226
+ See [docs/MCP_PLUGIN_SCANNING.md](docs/MCP_PLUGIN_SCANNING.md) for MCP and plugin config scanning.
227
+ See [docs/WORKSPACE_SCANNING.md](docs/WORKSPACE_SCANNING.md) for OpenClaw workspace precedence scanning.
228
+ See [docs/POLICY_MODEL.md](docs/POLICY_MODEL.md) for the risk and governance decision model.
229
+ See [docs/REPORT_SCHEMA.md](docs/REPORT_SCHEMA.md) for the versioned JSON output contract.
230
+ See [docs/RULES.md](docs/RULES.md) for stable rule IDs and suppression guidance.
231
+ See [docs/ARCHITECTURE_ROADMAP.md](docs/ARCHITECTURE_ROADMAP.md) for the build sequence.
232
+ See [docs/PROJECT_REVIEW.md](docs/PROJECT_REVIEW.md) for the current hardening and launch priorities.
233
+ See [docs/LOCAL_PROJECT_ASSETS.md](docs/LOCAL_PROJECT_ASSETS.md) for nearby local projects that can strengthen ClawGuard.
234
+
235
+ ## Positioning
236
+
237
+ ClawGuard should be 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.
238
+
239
+ ## License
240
+
241
+ MIT
package/SECURITY.md ADDED
@@ -0,0 +1,33 @@
1
+ # Security Policy
2
+
3
+ ClawGuard is a defensive scanner. Please report vulnerabilities privately before opening a public issue.
4
+
5
+ ## Reporting
6
+
7
+ Open a private security advisory on GitHub, or contact the maintainer directly.
8
+
9
+ Please include:
10
+
11
+ - A short description of the issue
12
+ - Reproduction steps
13
+ - Expected impact
14
+ - Any sample skill or config needed to reproduce the issue
15
+
16
+ ## Scope
17
+
18
+ In scope:
19
+
20
+ - Scanner bypasses that miss clearly dangerous skill behavior
21
+ - False negatives for credential theft, destructive shell commands, or remote execution
22
+ - Crashes caused by malformed skill files
23
+ - Incorrect JSON output that could break CI usage
24
+
25
+ Out of scope:
26
+
27
+ - Requests to scan private third-party repositories without permission
28
+ - Social engineering against maintainers or contributors
29
+ - Vulnerabilities in external package managers, AI models, or OpenClaw itself
30
+
31
+ ## Disclosure
32
+
33
+ The goal is coordinated disclosure with a fix or documented mitigation before public discussion.
package/action.yml ADDED
@@ -0,0 +1,72 @@
1
+ name: ClawGuard
2
+ description: Scan OpenClaw-style skills and MCP configs for security and governance risk.
3
+
4
+ inputs:
5
+ target:
6
+ description: Path to scan.
7
+ required: false
8
+ default: "."
9
+ policy:
10
+ description: Policy preset to apply.
11
+ required: false
12
+ default: governed
13
+ fail-on:
14
+ description: Risk level that should fail the workflow.
15
+ required: false
16
+ default: critical
17
+ fail-on-policy:
18
+ description: Whether policy decisions should fail the workflow.
19
+ required: false
20
+ default: "true"
21
+ policy-fail-on:
22
+ description: Policy decision threshold that should fail the workflow.
23
+ required: false
24
+ default: manual_review
25
+ config:
26
+ description: Optional .clawguard.json path.
27
+ required: false
28
+ default: ""
29
+ sarif:
30
+ description: Optional SARIF output path.
31
+ required: false
32
+ default: clawguard.sarif
33
+
34
+ runs:
35
+ using: composite
36
+ steps:
37
+ - uses: actions/setup-node@v4
38
+ with:
39
+ node-version: 20
40
+
41
+ - name: Run ClawGuard
42
+ shell: bash
43
+ env:
44
+ INPUT_TARGET: ${{ inputs.target }}
45
+ INPUT_POLICY: ${{ inputs.policy }}
46
+ INPUT_FAIL_ON: ${{ inputs.fail-on }}
47
+ INPUT_FAIL_ON_POLICY: ${{ inputs.fail-on-policy }}
48
+ INPUT_POLICY_FAIL_ON: ${{ inputs.policy-fail-on }}
49
+ INPUT_CONFIG: ${{ inputs.config }}
50
+ INPUT_SARIF: ${{ inputs.sarif }}
51
+ run: |
52
+ args=(
53
+ scan
54
+ "$INPUT_TARGET"
55
+ --policy "$INPUT_POLICY"
56
+ --fail-on "$INPUT_FAIL_ON"
57
+ --policy-fail-on "$INPUT_POLICY_FAIL_ON"
58
+ )
59
+
60
+ if [ "$INPUT_FAIL_ON_POLICY" = "true" ]; then
61
+ args+=(--fail-on-policy)
62
+ fi
63
+
64
+ if [ -n "$INPUT_CONFIG" ]; then
65
+ args+=(--config "$INPUT_CONFIG")
66
+ fi
67
+
68
+ if [ -n "$INPUT_SARIF" ]; then
69
+ args+=(--sarif "$INPUT_SARIF")
70
+ fi
71
+
72
+ node "$GITHUB_ACTION_PATH/src/cli.js" "${args[@]}"
@@ -0,0 +1,312 @@
1
+ # ClawGuard Architecture
2
+
3
+ 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.
4
+
5
+ ## Mission
6
+
7
+ ClawGuard answers one question before a user trusts a skill or plugin:
8
+
9
+ > What can this thing influence, access, install, or exfiltrate?
10
+
11
+ The product should be small, explainable, and useful in three moments:
12
+
13
+ - Before installing a skill or plugin.
14
+ - After installing into an OpenClaw workspace.
15
+ - During pull requests and publishing workflows.
16
+
17
+ ## Product Surfaces
18
+
19
+ 1. CLI
20
+
21
+ Current surface: `clawguard scan <path>`.
22
+
23
+ Target surface:
24
+
25
+ - `clawguard scan <path>`
26
+ - `clawguard scan-skill <skill-dir>`
27
+ - `clawguard scan-workspace <workspace-dir>`
28
+ - `clawguard scan-mcp <config-path>`
29
+ - `clawguard explain <finding-id>`
30
+ - `clawguard policy check <report.json>`
31
+
32
+ 2. Core library
33
+
34
+ A dependency-free or low-dependency JavaScript API that other surfaces call. The CLI, GitHub Action, web demo, and MCP server should all use the same core scanner.
35
+
36
+ 3. GitHub Action
37
+
38
+ Pull request gate for skill repos, OpenClaw companion repos, and enterprise skill catalogs. It should output CLI text, JSON artifact, and SARIF.
39
+
40
+ 4. Web demo
41
+
42
+ Public demo: upload or paste `SKILL.md`, optionally upload a folder, then get a risk score with evidence and recommended action.
43
+
44
+ 5. MCP server
45
+
46
+ Optional later surface exposing tools like `scan_skill`, `scan_mcp_config`, `explain_finding`, and `policy_decision`.
47
+
48
+ 6. Install gate
49
+
50
+ Optional wrapper or integration pattern around OpenClaw/ClawHub install/update flows. It should scan a downloaded bundle before the user enables it.
51
+
52
+ ## Trust Boundaries
53
+
54
+ ClawGuard must treat every scanned file as hostile input.
55
+
56
+ Security invariants:
57
+
58
+ - Never execute scanned files.
59
+ - Never install dependencies from scanned files.
60
+ - Do not fetch remote code by default.
61
+ - Do not follow symbolic links by default.
62
+ - Enforce size and file count limits.
63
+ - Keep evidence short and bounded.
64
+ - Do not print full secrets.
65
+ - Keep rules deterministic and explainable.
66
+ - Fail closed in CI when configured by policy.
67
+
68
+ ## High-Level Flow
69
+
70
+ ```mermaid
71
+ flowchart TD
72
+ A["Skill folder, workspace, ClawHub metadata, or MCP config"] --> B["Target discovery"]
73
+ B --> C["File safety filters"]
74
+ C --> D["Parsers and normalizers"]
75
+ D --> E["Rule engine"]
76
+ E --> F["Risk scoring"]
77
+ F --> G["Policy engine"]
78
+ G --> H["Reporters"]
79
+ H --> I["CLI text"]
80
+ H --> J["JSON"]
81
+ H --> K["SARIF"]
82
+ H --> L["HTML"]
83
+ H --> M["JSONL audit"]
84
+ ```
85
+
86
+ ## Core Modules
87
+
88
+ Current code can evolve into these modules without a rewrite:
89
+
90
+ - `src/cli.js`: command parsing and terminal output.
91
+ - `src/scanner.js`: orchestration, target walking, file safety limits, and scan result construction.
92
+ - `src/rules.js`: initial static rule pack.
93
+
94
+ Target architecture:
95
+
96
+ - `src/core/scan.js`: main scanner orchestration.
97
+ - `src/core/types.js`: shared contracts for targets, findings, scores, policies, and reports.
98
+ - `src/fs/discovery.js`: safe traversal, symlink behavior, max file size, ignore rules.
99
+ - `src/parsers/skill.js`: `SKILL.md` detection, frontmatter extraction, metadata normalization.
100
+ - `src/parsers/package.js`: `package.json`, script, dependency, and lifecycle analysis.
101
+ - `src/parsers/mcp.js`: MCP and plugin config parsing.
102
+ - `src/parsers/clawhub.js`: ClawHub origin, lockfile, and package metadata parsing.
103
+ - `src/rules/*.js`: rule packs by domain.
104
+ - `src/risk/scoring.js`: severity weights, confidence, caps, and summary.
105
+ - `src/policy/engine.js`: decisions such as allow, warn, manual review, sandbox required, and block.
106
+ - `src/reporters/*.js`: human, JSON, SARIF, HTML, and JSONL output.
107
+ - `src/integrations/*`: GitHub Action, OpenClaw/ClawHub wrappers, MCP server, web demo adapter.
108
+
109
+ ## Data Contracts
110
+
111
+ Scan target:
112
+
113
+ ```js
114
+ {
115
+ kind: "skill" | "workspace" | "mcp-config" | "clawhub-package" | "directory" | "file",
116
+ path: "/absolute/path",
117
+ source: "local" | "clawhub" | "github" | "upload",
118
+ metadata: {}
119
+ }
120
+ ```
121
+
122
+ Finding:
123
+
124
+ ```js
125
+ {
126
+ id: "credential-access",
127
+ title: "References credentials or environment secrets",
128
+ severity: "high",
129
+ confidence: "medium",
130
+ category: "secret-access",
131
+ file: "SKILL.md",
132
+ line: 14,
133
+ evidence: "process.env.TODOIST_API_KEY",
134
+ recommendation: "Declare required env vars and verify least privilege.",
135
+ tags: ["openclaw", "frontmatter-mismatch"]
136
+ }
137
+ ```
138
+
139
+ Risk score:
140
+
141
+ ```js
142
+ {
143
+ score: 72,
144
+ level: "critical",
145
+ findingCounts: { low: 0, medium: 1, high: 2, critical: 1 },
146
+ reasons: ["remote-code-execution", "undeclared-env-access"]
147
+ }
148
+ ```
149
+
150
+ Policy decision:
151
+
152
+ ```js
153
+ {
154
+ decision: "block",
155
+ preset: "enterprise",
156
+ reason: "Critical finding and undeclared network/system access.",
157
+ requiredActions: ["sandbox", "manual-review", "declare-permissions"]
158
+ }
159
+ ```
160
+
161
+ ## Rule Packs
162
+
163
+ Core rule packs:
164
+
165
+ - `core-static`: remote code execution, destructive shell, obfuscation, credential access, data exfiltration.
166
+ - `skill-metadata`: missing name/description/version, undeclared env vars, undeclared binaries, undeclared config reads, install metadata mismatch.
167
+ - `openclaw-permissions`: broad tool categories, high-risk workspace paths, sandbox recommendations, skill precedence warnings.
168
+ - `clawhub-supply-chain`: origin metadata, version drift, unsigned or unknown source, install specs, package risk metadata.
169
+ - `mcp-config`: broad MCP tools, unknown command sources, network/system capabilities, token-heavy env injection.
170
+ - `prompt-injection`: instruction hijacking, policy bypass language, credential disclosure instructions.
171
+
172
+ ## Risk Model
173
+
174
+ Risk should be explainable before it is clever.
175
+
176
+ Base severity:
177
+
178
+ - `info`: noteworthy but not dangerous.
179
+ - `low`: likely safe but worth visibility.
180
+ - `medium`: could surprise the user or expand trust.
181
+ - `high`: can access secrets, files, network, tools, or external systems.
182
+ - `critical`: can execute remote code, destroy data, silently exfiltrate, or bypass controls.
183
+
184
+ Score factors:
185
+
186
+ - Severity weight.
187
+ - Number of unique findings.
188
+ - Confidence.
189
+ - Capability category.
190
+ - Declared versus observed mismatch.
191
+ - Source trust.
192
+ - Whether sandboxing is available or required.
193
+ - Whether the finding is in executable code, frontmatter, docs, or examples.
194
+
195
+ ## Policy Model
196
+
197
+ The policy engine maps scan results into decisions:
198
+
199
+ - `allow`: no action required.
200
+ - `warn`: show risk, allow user to continue.
201
+ - `manual_review`: require human approval.
202
+ - `sandbox_required`: allow only with sandbox or limited tools.
203
+ - `dual_approval`: require two reviewers for enterprise workflows.
204
+ - `block`: do not install or enable.
205
+
206
+ Presets:
207
+
208
+ - `personal`: warn on medium, block critical.
209
+ - `governed`: review medium, sandbox high, block critical.
210
+ - `enterprise`: review medium, dual approval high, block critical and undeclared sensitive access.
211
+
212
+ ## OpenClaw Workspace Model
213
+
214
+ OpenClaw skill precedence matters. A workspace skill can override a managed or bundled skill. ClawGuard should eventually scan and display:
215
+
216
+ - All visible skill locations.
217
+ - Duplicate skill names.
218
+ - Effective winning skill by precedence.
219
+ - Skills enabled by agent allowlists.
220
+ - Skills shipped by plugins.
221
+ - Skills loaded from extra directories.
222
+
223
+ This becomes the foundation for an `openclaw doctor` style companion command:
224
+
225
+ ```bash
226
+ clawguard openclaw scan-workspace ~/.openclaw/workspace
227
+ ```
228
+
229
+ ## ClawHub Model
230
+
231
+ ClawGuard should consume ClawHub metadata when available, but should not rely on it as the only authority.
232
+
233
+ Useful ClawHub signals:
234
+
235
+ - Skill slug, version, tag, changelog, origin, and lockfile state.
236
+ - `metadata.openclaw` runtime requirements.
237
+ - Install specs such as `brew`, `node`, `go`, or `uv`.
238
+ - Package family, trust, capability, compatibility, and source metadata.
239
+ - Registry moderation and report status if exposed by API later.
240
+
241
+ ClawGuard should compare registry declarations with local bundle behavior.
242
+
243
+ ## Reports
244
+
245
+ Every report should include:
246
+
247
+ - Target path and target kind.
248
+ - Source and metadata if available.
249
+ - Files scanned and skipped.
250
+ - Risk score and policy decision.
251
+ - Findings grouped by severity and category.
252
+ - Evidence with file and line.
253
+ - Recommendations.
254
+ - Limitations and scan options.
255
+
256
+ Machine-readable reports should preserve stable finding IDs so suppressions and trend tracking work over time.
257
+
258
+ ## Repository Shape
259
+
260
+ Near-term repo shape:
261
+
262
+ ```text
263
+ clawguard/
264
+ +-- src/
265
+ | +-- cli.js
266
+ | +-- scanner.js
267
+ | +-- rules.js
268
+ | +-- parsers/
269
+ | +-- policy/
270
+ | +-- reporters/
271
+ | +-- integrations/
272
+ +-- test/
273
+ +-- examples/
274
+ +-- docs/
275
+ +-- .github/workflows/
276
+ ```
277
+
278
+ Long-term package shape:
279
+
280
+ ```text
281
+ clawguard/
282
+ +-- packages/
283
+ | +-- core/
284
+ | +-- cli/
285
+ | +-- action/
286
+ | +-- mcp-server/
287
+ | +-- web/
288
+ +-- fixtures/
289
+ +-- docs/
290
+ +-- examples/
291
+ ```
292
+
293
+ Stay single-package until the code is large enough to justify splitting. A clean monolith is better than a premature monorepo.
294
+
295
+ ## Non-Goals
296
+
297
+ - Do not fork OpenClaw.
298
+ - Do not replace ClawHub.
299
+ - Do not claim a clean scan proves safety.
300
+ - Do not execute untrusted code for analysis.
301
+ - Do not build a giant agent framework inside ClawGuard.
302
+ - Do not collect user skill data by default.
303
+
304
+ ## Success Criteria
305
+
306
+ ClawGuard is strong when:
307
+
308
+ - A developer can run it in under one minute.
309
+ - A maintainer can add it to CI without learning OpenClaw internals.
310
+ - A user understands why a skill is risky.
311
+ - A security reviewer can see exact evidence.
312
+ - An OpenClaw contributor sees it as a useful companion, not a competing platform.