guard-scanner 1.1.1 → 2.1.0

package/README.md

@@ -2,16 +2,16 @@
   <h1 align="center">🛡️ guard-scanner</h1>
   <p align="center">
     <strong>Static security scanner for AI agent skills</strong><br>
-    Detect prompt injection, credential theft, exfiltration, identity hijacking, and 17 more threat categories.<br>
-    <sub>Runtime Guard hook included — pending <a href="https://github.com/openclaw/openclaw/issues/18677">OpenClaw hook API adoption</a></sub>
+    Detect prompt injection, credential theft, exfiltration, PII exposure, Shadow AI, and 17 more threat categories.<br>
+    <sub>🆕 v2.1 — PII Exposure Detection + Shadow AI + Plugin Hook blocking via <code>block</code>/<code>blockReason</code> API</sub>
   </p>
   <p align="center">
     <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License"></a>
     <img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen" alt="Node.js 18+">
     <img src="https://img.shields.io/badge/dependencies-0-success" alt="Zero Dependencies">
-    <img src="https://img.shields.io/badge/tests-55%2F55-brightgreen" alt="Tests Passing">
-    <img src="https://img.shields.io/badge/patterns-186-orange" alt="186 Patterns">
-    <img src="https://img.shields.io/badge/categories-20-blueviolet" alt="20 Categories">
+    <img src="https://img.shields.io/badge/tests-99%2F99-brightgreen" alt="Tests Passing">
+    <img src="https://img.shields.io/badge/patterns-129-orange" alt="129 Patterns">
+    <img src="https://img.shields.io/badge/categories-21-blueviolet" alt="21 Categories">
   </p>
 </p>
 
@@ -40,8 +40,8 @@ The AI agent skill ecosystem has the same supply-chain security problem that npm
 
 | Feature | Description |
 |---|---|
-| **20 Threat Categories** | Snyk ToxicSkills + OWASP MCP Top 10 + Identity Hijacking + Sandbox/Complexity/Config |
-| **186 Detection Patterns** | Regex-based static analysis covering code, docs, and data files |
+| **21 Threat Categories** | Snyk ToxicSkills + OWASP MCP Top 10 + Identity Hijacking + Sandbox/Complexity/Config + PII |
+| **129 Detection Patterns** | Regex-based static analysis covering code, docs, and data files |
 | **IoC Database** | Known malicious IPs, domains, URLs, usernames, and typosquat names |
 | **Data Flow Analysis** | Lightweight JS analysis: secret reads → network calls → exec chains |
 | **Cross-File Analysis** | Phantom references, base64 fragment assembly, multi-file exfil detection |
@@ -74,6 +74,18 @@ npx guard-scanner ./skills/ --strict
 npx guard-scanner ./skills/ --verbose --check-deps --json --sarif --html
 ```
 
+## OpenClaw Recommended Setup (short)
+
+```bash
+# 1) Pre-install / pre-update static gate
+npx guard-scanner ~/.openclaw/workspace/skills --self-exclude --verbose
+
+# 2) Runtime guard — Plugin Hook version (blocks dangerous calls!)
+cp hooks/guard-scanner/plugin.ts ~/.openclaw/plugins/guard-scanner-runtime.ts
+```
+
+> **🆕 v2.1** — PII Exposure Detection (OWASP LLM02/06) + Shadow AI detection + Plugin Hook `block`/`blockReason` API. 3 modes: `monitor`, `enforce`, `strict`.
+
 ### Installation (Optional)
 
 ```bash
@@ -87,17 +99,17 @@ npx guard-scanner ./skills/
 ### As an OpenClaw Skill
 
 ```bash
-openclaw skill install guard-scanner
+clawhub install guard-scanner
 guard-scanner ~/.openclaw/workspace/skills/ --self-exclude --verbose
 ```
 
-> **⚠️ Runtime Guard (handler.ts)** — The real-time `before_tool_call` hook requires OpenClaw's Hook API ([Issue #18677](https://github.com/openclaw/openclaw/issues/18677)). The hook is registered and runs on `agent:before_tool_call` events, but OpenClaw's `InternalHookEvent` does not yet expose a cancel/veto mechanism — so **detections are warned but not blocked**. The static scanner (`npx guard-scanner`) works fully and independently.
+> **🆕 Plugin Hook version** (`plugin.ts`) uses the `before_tool_call` Plugin Hook API with `block`/`blockReason` — **detections are actually blocked**. The legacy Internal Hook version (`handler.ts`) is still available for backward compatibility but can only warn.
 
 ---
 
 ## Threat Categories
 
-guard-scanner covers **20 threat categories** derived from three taxonomies:
+guard-scanner covers **21 threat categories** derived from four sources:
 
 | # | Category | Based On | Severity | What It Detects |
 |---|----------|----------|----------|----------------|
@@ -121,8 +133,9 @@ guard-scanner covers **20 threat categories** derived from three taxonomies:
 | 18 | **Sandbox Validation** | v1.1 | HIGH | Dangerous binary requirements in SKILL.md, overly broad file scope, sensitive env vars, exec/network declarations |
 | 19 | **Code Complexity** | v1.1 | MEDIUM | Excessive file length (>1000 lines), deep nesting (>5 levels), high eval/exec density |
 | 20 | **Config Impact** | v1.1 | CRITICAL | `openclaw.json` writes, exec approval bypass, exec host gateway, internal hooks modification, network wildcard |
+| 21 | **PII Exposure** | v2.1 | CRITICAL | Hardcoded CC/SSN/phone/email (context-aware), PII logging/network send/plaintext store, Shadow AI (OpenAI/Anthropic/generic LLM), PII collection instructions (address/DOB/government ID) |
 
-> **Categories 17–20** are unique to guard-scanner. Category 17 (Identity Hijacking) was developed from a real attack. Categories 18–20 were added in v1.1.0 based on community feedback.
+> **Categories 17–21** are unique to guard-scanner. Category 17 (Identity Hijacking) was developed from a real attack. Categories 18–20 added in v1.1.0. Category 21 (PII Exposure) added in v2.1.0 covering OWASP LLM02/LLM06.
 
 ---
 
@@ -131,7 +144,7 @@ guard-scanner covers **20 threat categories** derived from three taxonomies:
 ### Terminal (Default)
 
 ```
-🛡️  guard-scanner v1.1.0
+🛡️  guard-scanner v2.1.0
 ══════════════════════════════════════════════════════
 📂 Scanning: ./skills/
 📦 Skills found: 22
@@ -216,6 +229,9 @@ Certain combinations multiply the base score:
 | Config impact | **×2** | OpenClaw configuration tampering |
 | Config impact + Sandbox violation | **min 70** | Combined config + capability abuse |
 | Complexity + Malicious code/Obfuscation | **×1.5** | Complex code hiding threats |
+| PII exposure + Exfiltration | **×3** | PII being sent to external servers |
+| PII exposure + Shadow AI | **×2.5** | PII leak through unauthorized LLM |
+| PII exposure + Credential handling | **×2** | Combined PII + credential risk |
 | Known IoC (IP/URL/typosquat) | **= 100** | Confirmed malicious |
 
 ### Verdict Thresholds
@@ -388,16 +404,19 @@ Options:
 ```
 guard-scanner/
 ├── src/
-│   ├── scanner.js      # GuardScanner class — core scan engine (20 checks)
-│   ├── patterns.js     # 186 threat detection patterns (Cat 1–20)
+│   ├── scanner.js      # GuardScanner class — core scan engine (21 checks)
+│   ├── patterns.js     # 129 threat detection patterns (Cat 1–21)
 │   ├── ioc-db.js       # Indicators of Compromise database
 │   └── cli.js          # CLI entry point and argument parser
 ├── hooks/
 │   └── guard-scanner/
-│       └── handler.ts  # Runtime Guard — before_tool_call hook (experimental, pending OpenClaw API)
+│       ├── plugin.ts   # 🆕 Plugin Hook v2.0 — actual blocking via block/blockReason
+│       ├── handler.ts  # Legacy Internal Hook — warn only (deprecated)
+│       └── HOOK.md     # Internal Hook manifest (legacy)
 ├── test/
-│   ├── scanner.test.js # 55 tests across 13 sections
-│   └── fixtures/       # Malicious, clean, complex, config-changer samples
+│   ├── scanner.test.js # 64 tests — static scanner (incl. PII v2.1)
+│   ├── plugin.test.js  # 35 tests — Plugin Hook runtime guard
+│   └── fixtures/       # Malicious, clean, complex, config-changer, pii-leaky samples
 ├── package.json        # Zero dependencies, node --test
 ├── CHANGELOG.md
 ├── LICENSE             # MIT
@@ -521,11 +540,11 @@ console.log(scanner.toHTML());    // HTML string
 ## Test Results
 
 ```
-ℹ tests 55
-ℹ suites 13
-ℹ pass 55
+ℹ tests 99
+ℹ suites 16
+ℹ pass 99
 ℹ fail 0
-ℹ duration_ms 115ms
+ℹ duration_ms 142ms
 ```
 
 | Suite | Tests | Coverage |
@@ -535,14 +554,34 @@ console.log(scanner.toHTML());    // HTML string
 | Risk Score Calculation | 5 | Empty, single, combo amplifiers, IoC override |
 | Verdict Determination | 5 | All verdicts + strict mode |
 | Output Formats | 4 | JSON + SARIF 2.1.0 + HTML structure |
-| Pattern Database | 4 | 100+ count, required fields, category coverage, regex safety |
+| Pattern Database | 4 | 125+ count, required fields, category coverage, regex safety |
 | IoC Database | 5 | Structure, ClawHavoc C2, webhook.site |
 | Shannon Entropy | 2 | Low entropy, high entropy |
 | Ignore Functionality | 1 | Pattern exclusion |
 | Plugin API | 1 | Plugin loading + custom rule injection |
-| **Manifest Validation (v1.1)** | 4 | Dangerous bins, broad files, sensitive env, clean negatives |
-| **Complexity Metrics (v1.1)** | 2 | Deep nesting, clean negatives |
-| **Config Impact (v1.1)** | 4 | openclaw.json write, exec approval, gateway host, clean negatives |
+| Manifest Validation | 4 | Dangerous bins, broad files, sensitive env, clean negatives |
+| Complexity Metrics | 2 | Deep nesting, clean negatives |
+| Config Impact | 4 | openclaw.json write, exec approval, gateway host, clean negatives |
+| **🆕 PII Exposure Detection** | **8** | **Hardcoded CC/SSN, PII logging, network send, Shadow AI, doc collection, risk amp, clean negatives** |
+| **Plugin Hook Runtime Guard** | **35** | **Blocking in enforce/strict, passthrough in monitor, all 12 threat patterns, blockReason format** |
+
+---
+
+## Fills OpenClaw's Own Security Gaps
+
+OpenClaw's official [`THREAT-MODEL-ATLAS.md`](https://github.com/openclaw/openclaw/blob/main/docs/security/THREAT-MODEL-ATLAS.md) identifies security gaps that guard-scanner directly addresses:
+
+| Gap (from ATLAS / Source Code) | OpenClaw Status | guard-scanner |
+|---|---|---|
+| _"Simple regex easily bypassed"_ — ClawHub moderation | ⚠️ Basic `FLAG_RULES` | ✅ 129 patterns, 21 categories |
+| _"Does not analyze actual skill code content"_ | ❌ Not implemented | ✅ Full code + doc + data flow analysis |
+| No SOUL.md / IDENTITY.md integrity verification | ❌ Not implemented | ✅ Identity hijacking detection (Cat 17) |
+| `skill:before_install` hook | ❌ Not implemented | 🔜 Proposed ([Issue #18677](https://github.com/openclaw/openclaw/issues/18677)) |
+| `before_tool_call` blocking reference impl | ❌ No official plugin | ✅ First reference implementation (plugin.ts) |
+| SARIF / CI integration for skill security | ❌ Not available | ✅ SARIF 2.1.0 + GitHub Actions |
+| Behavioral analysis beyond VirusTotal | ⏳ In progress | ✅ LLM-specific threat patterns (prompt injection, memory poisoning, MCP attacks) |
+
+> guard-scanner is **complementary** to OpenClaw's built-in security — not a replacement. OpenClaw handles infrastructure security (SSRF blocking, exec approvals, sandbox, auth). guard-scanner handles **AI-specific threats** that traditional scanning misses.
 
 ---
 
@@ -556,13 +595,36 @@ console.log(scanner.toHTML());    // HTML string
 
 ---
 
+## OWASP Gen AI Top 10 Coverage
+
+guard-scanner's coverage of the [OWASP Top 10 for LLM Applications (2025)](https://owasp.org/www-project-top-10-for-large-language-model-applications/):
+
+| # | Risk | Status | Detection Method |
+|---|------|--------|------------------|
+| LLM01 | Prompt Injection | ⚠️ Partial | Regex: Unicode exploits, role override, system tags, base64 instructions |
+| LLM02 | Sensitive Information Disclosure | ⚠️ Partial | PII Exposure Detection (v2.1): hardcoded PII, PII logging/network/storage, Shadow AI, PII collection instructions |
+| LLM03 | Training Data Poisoning | ⬜ N/A | Out of scope for static analysis |
+| LLM04 | Model Denial of Service | 🔜 v2.2 | Planned: excessive input / infinite loop patterns |
+| LLM05 | Supply Chain Vulnerabilities | ⚠️ Partial | IoC database, typosquat detection, dependency chain scan |
+| LLM06 | Insecure Output Handling | ⚠️ Partial | PII output detection (console.log, network send, plaintext store) |
+| LLM07 | Insecure Plugin Design | 🔜 v1.3 | Planned: unvalidated plugin input patterns |
+| LLM08 | Excessive Agency | 🔜 v1.3 | Planned: over-permissioned scope detection |
+| LLM09 | Overreliance | 🔜 v1.3 | Planned: unverified output trust patterns |
+| LLM10 | Model Theft | 🔜 v1.3 | Planned: model file exfiltration patterns |
+
+> **Current coverage: 5/10 (partial).** LLM02 and LLM06 added in v2.1.0. Full coverage targeted for v3.0. See [ROADMAP.md](ROADMAP.md) for details.
+>
+> **Known limitation:** Regex-based detection can be evaded by AI-generated code obfuscation. v3.0 will introduce AST analysis and ML-based detection to address this structural gap.
+
+---
+
 ## Contributing
 
 1. Fork the repository
 2. Create a feature branch (`git checkout -b feature/new-pattern`)
 3. Add your pattern to `src/patterns.js` with the required fields
 4. Add a test case in `test/fixtures/` and `test/scanner.test.js`
-5. Run `npm test` — all 55+ tests must pass
+5. Run `npm test` — all 99+ tests must pass
 6. Submit a Pull Request
 
 ### Adding a New Detection Pattern
@@ -601,19 +663,48 @@ We built one.
 
 ## 🔒 Need More? — GuavaSuite
 
-guard-scanner catches threats **before** installation. But what happens **after** a skill is running?
+guard-scanner catches threats **before** installation and **blocks** CRITICAL threats at runtime. **GuavaSuite** unlocks **strict mode** — blocking HIGH + CRITICAL threats, plus exclusive defense-in-depth features.
 
-[**GuavaSuite**](https://github.com/koatora20) extends guard-scanner with real-time protection for production agent deployments:
+### How to Upgrade
 
-| | guard-scanner (OSS) | GuavaSuite (Private) |
+```bash
+# 1. Install GuavaSuite
+clawhub install guava-suite
+
+# 2. Hold 1M+ $GUAVA on Polygon
+#    Token: 0x25cBD481901990bF0ed2ff9c5F3C0d4f743AC7B8
+#    Buy on QuickSwap V2: https://quickswap.exchange
+
+# 3. Activate with your wallet → get JWT → strict mode enabled
+```
+
+### Feature Comparison
+
+| | guard-scanner (Free) | GuavaSuite ($GUAVA) |
 |---|---|---|
-| Static scan | ✅ 20 categories | ✅ 20 categories |
-| Runtime blocking | ⚠️ Warn only (cancel API pending) | ✅ Real-time `before_tool_call` guard |
-| SOUL.md integrity | Pattern detection only | ✅ SHA-256 hash watchdog |
-| On-chain verification | — | ✅ SoulChain (Polygon) |
-| Identity recovery | — | ✅ Automatic rollback |
+| Static scan (129 patterns, 21 categories) | ✅ | ✅ |
+| Runtime Guard — `enforce` (block CRITICAL) | ✅ | ✅ |
+| **Runtime Guard — `strict` (block HIGH + CRITICAL)** | ❌ | ✅ |
+| **Soul Lock** (SOUL.md integrity + auto-rollback) | ❌ | ✅ |
+| **Memory Guard** (L1-L5 記憶保護) | ❌ | ✅ |
+| **On-chain Identity** (SoulRegistry V2 on Polygon) | ❌ | ✅ |
+| Audit Log (JSONL) | ✅ | ✅ |
+
+guard-scanner is and always will be **free, open-source, and zero-dependency**.
+
+---
+
+## Roadmap
+
+| Version | Focus | Key Features |
+|---------|-------|------|
+| v1.1.1 ✅ | Stability | 56 tests, bug fixes |
+| v2.0.0 ✅ | **Plugin Hook Runtime Guard** | `block`/`blockReason` API, 3 modes (monitor/enforce/strict), 91 tests |
+| v2.1.0 ✅ | **PII Exposure + Shadow AI** | 13 PII patterns, OWASP LLM02/06, Shadow AI detection, 3 risk amplifiers, 99 tests |
+| v2.2 | OWASP Full Coverage | LLM04/07/08/09/10, YAML pattern definitions, CONTRIBUTING guide |
+| v3.0 | AST + ML | JavaScript AST analysis, taint tracking, ML-based obfuscation detection, SBOM generation |
 
-guard-scanner is and always will be **free, open-source, and zero-dependency**. If your agent handles production workloads and you want defense-in-depth, [reach out](https://github.com/koatora20).
+See [ROADMAP.md](ROADMAP.md) for full details.
 
 ---
 

package/SECURITY.md

@@ -5,7 +5,7 @@
 If you discover a security vulnerability in guard-scanner itself, please report it responsibly:
 
 1. **Do NOT open a public issue**
-2. Email: [security contact via GitHub private vulnerability reporting]
+2. Email: socialgreen.jp@gmail.com
 3. Include: affected version, steps to reproduce, potential impact
 
 We will respond within 48 hours and provide a fix within 7 days for critical issues.

package/SKILL.md

@@ -54,29 +54,23 @@ Scan a specific skill:
 node skills/guard-scanner/src/cli.js /path/to/new-skill/ --strict --verbose
 ```
 
-### 2. Runtime Guard (Real-time Protection) — ⚠️ Experimental
+### 2. Runtime Guard (OpenClaw) — ⚠️ warn-only currently
 
-> **Note:** Requires the OpenClaw Hook API ([Issue #18677](https://github.com/openclaw/openclaw/issues/18677)), which has not been officially adopted yet. The handler is included for early testing and will be updated once the API is finalized.
-
-Install the hook to block dangerous tool calls before execution:
+> **Note:** OpenClaw `InternalHookEvent` does not yet expose cancel/veto. Runtime hook detections are warning + audit log until [Issue #18677](https://github.com/openclaw/openclaw/issues/18677) is adopted.
 
 ```bash
 openclaw hooks install skills/guard-scanner/hooks/guard-scanner
 openclaw hooks enable guard-scanner
+openclaw hooks list
 ```
 
-Restart the gateway, then verify:
-```bash
-openclaw hooks list   # Should show 🛡️ guard-scanner as ✓ ready
-```
-
-### 3. Full Setup (Recommended)
+### 3. Recommended order
 
 ```bash
-# Static scan first
+# Pre-install / pre-update gate first
 node skills/guard-scanner/src/cli.js ~/.openclaw/workspace/skills/ --verbose --self-exclude --html
 
-# Then enable runtime protection
+# Then keep runtime monitoring enabled
 openclaw hooks install skills/guard-scanner/hooks/guard-scanner
 openclaw hooks enable guard-scanner
 ```

package/docs/OPENCLAW_DOCS_PR_READY_PATCH.md

@@ -0,0 +1,88 @@
+# OpenClaw Docs PR-Ready Patch (Reference Implementation)
+
+Updated: 2026-02-18
+Target: `docs/automation/hooks.md` (new subsection)
+
+## Section Title
+`### Runtime Security Guard (Reference: before_tool_call)`
+
+## Paste-ready content
+
+```md
+### Runtime Security Guard (Reference: `agent:before_tool_call`)
+
+This reference shows a backward-compatible runtime hook pattern for tool-call safety.
+
+#### Proposed event fields (backward-compatible)
+
+```ts
+interface InternalHookEvent {
+  // existing fields
+  cancel?: boolean;      // default false
+  cancelReason?: string; // user-visible cancellation reason
+  policyMode?: "warn" | "balanced" | "strict";
+}
+```
+
+- Existing hooks remain unchanged.
+- If `cancel` fields are not used/supported, behavior stays warn-only.
+
+#### Recommended policy semantics
+
+- `warn`: never block, only warn/log.
+- `balanced`: block high-confidence dangerous patterns.
+- `strict`: block any policy hit.
+
+#### `HOOK.md`
+
+```md
+---
+name: security-runtime-guard
+description: "Reference runtime guard hook for tool-call safety"
+metadata:
+  { "openclaw": { "emoji": "🛡️", "events": ["agent:before_tool_call"] } }
+---
+
+# security-runtime-guard
+
+Reference implementation for runtime tool-call policy checks.
+```
+
+#### `handler.ts`
+
+```ts
+import type { HookHandler } from "../../src/hooks/hooks.js";
+
+const HIGH_RISK = [/curl\s+.*\|\s*sh/i, /reverse\s*shell/i, /169\.254\.169\.254/];
+
+const handler: HookHandler = async (event) => {
+  if (event.type !== "agent" || event.action !== "before_tool_call") return;
+
+  const mode = event.policyMode ?? "warn";
+  const text = JSON.stringify(event.context ?? {});
+  const hit = HIGH_RISK.find((re) => re.test(text));
+  if (!hit) return;
+
+  event.messages.push(`🛡️ Runtime guard detected risky pattern: ${hit}`);
+
+  if (mode === "warn") return;
+
+  event.cancel = true;
+  event.cancelReason =
+    mode === "strict"
+      ? "Blocked by strict runtime policy"
+      : "Blocked by balanced runtime policy (high-risk pattern)";
+};
+
+export default handler;
+```
+
+#### Operational note
+
+If your current OpenClaw runtime is warn-only for tool-call hooks, this reference still works as observability-first policy (`warn` mode). Enforcement activates once cancel/veto is available.
+```
+
+## Reviewer Notes
+- Keeps behavior backward-compatible.
+- Encourages monitor -> enforce rollout.
+- Aligned with install-time + runtime defense-in-depth guidance.

package/docs/OPENCLAW_HOOK_SCHEMA_REFERENCE_DRAFT.md

@@ -0,0 +1,78 @@
+# OpenClaw Hook Schema Reference Draft (Issue #18677)
+
+Updated: 2026-02-18
+
+## Goal
+Provide a docs-ready, backward-compatible reference implementation for runtime security hooks.
+
+## Proposed Event Extension
+
+```ts
+interface InternalHookEvent {
+  // existing fields
+  cancel?: boolean;
+  cancelReason?: string;
+  policyMode?: "warn" | "balanced" | "strict";
+}
+```
+
+### Compatibility
+- Existing hooks continue to work without changes.
+- If cancel fields are absent, runtime behavior is unchanged.
+
+## Policy Semantics
+- `warn`: never block, log + user warning only
+- `balanced`: block HIGH/CRITICAL confidence matches
+- `strict`: block any matched policy rule
+
+## Reference `HOOK.md`
+
+```md
+---
+name: security-runtime-guard
+description: "Reference runtime guard hook for tool-call safety"
+metadata:
+  { "openclaw": { "emoji": "🛡️", "events": ["agent:before_tool_call"] } }
+---
+
+# security-runtime-guard
+
+Reference implementation for cancel/veto-enabled runtime checks.
+```
+
+## Reference `handler.ts`
+
+```ts
+import type { HookHandler } from "../../src/hooks/hooks.js";
+
+const HIGH_RISK = [/curl\s+.*\|\s*sh/i, /reverse\s*shell/i, /169\.254\.169\.254/];
+
+const handler: HookHandler = async (event) => {
+  if (event.type !== "agent" || event.action !== "before_tool_call") return;
+
+  const mode = event.policyMode ?? "warn";
+  const text = JSON.stringify(event.context ?? {});
+  const hit = HIGH_RISK.find((re) => re.test(text));
+  if (!hit) return;
+
+  event.messages.push(`🛡️ Runtime guard detected risky pattern: ${hit}`);
+
+  if (mode === "warn") return;
+
+  // balanced/strict: cancellation path
+  event.cancel = true;
+  event.cancelReason =
+    mode === "strict"
+      ? "Blocked by strict runtime policy"
+      : "Blocked by balanced runtime policy (high-risk pattern)";
+};
+
+export default handler;
+```
+
+## Notes for Docs
+1. Document that some releases may still be warn-only until cancel support lands.
+2. Recommend combining install-time static scan + runtime guard:
+   - Install-time: `guard-scanner`
+   - Runtime: internal hook guard
+3. Add troubleshooting section for false positives (context-aware suppression).

package/docs/TASKLIST_RESEARCH_FIRST_V1.md

@@ -0,0 +1,47 @@
+# guard-scanner Research-First Tasklist (t-wada + 鉄の掟)
+
+Updated: 2026-02-18
+
+## 0) Research Baseline (完了)
+- [x] Semgrep rule testing practices（ruleid/okでFN/FPを分離管理）
+- [x] GitHub SARIF要件（重複防止fingerprint・SARIF 2.1.0 subset）
+- [x] OWASP MCP Top 10（context/protocol attack surface）
+- [x] SLSA levels（provenance配布・build track段階化）
+
+## 1) RED — テスト仕様を先に固定
+- [ ] T1: False Positive回帰テストを追加（safe skill 20ケース）
+- [ ] T2: False Negative回帰テストを追加（malicious corpus 20ケース）
+- [x] T3: node_modules/生成レポート由来ノイズの再現テスト
+- [x] T4: SARIF妥当性テスト（schema + GitHub ingestion向け）
+- [ ] T5: 性能テスト（N=10/50/100 skillsで時間とメモリ）
+
+## 2) GREEN — 最小実装
+- [x] G1: デフォルト除外ルール（node_modules / guard-scanner-report.*）
+- [ ] G2: trust-boundaryの文脈制約（docs/コメント誤検知を抑制）
+- [ ] G3: entropy検知の閾値と例外改善（既知データ定数除外）
+- [x] G4: SARIF fingerprint一貫性の強化（`partialFingerprints.primaryLocationLineHash` 生成）
+
+## 3) REFACTOR — 構造改善
+- [ ] R1: 検知ルールを「攻撃シグナル」と「文脈ルール」に分離
+- [ ] R2: ルール単位で precision/recall メトリクス出力
+- [ ] R3: release gate（テスト全通過 + SLSA provenance確認）
+
+## 4) OpenClawコミュニティ最優先（即効価値）
+- [x] C1: #18677 に方針返信（agent連携文脈 + cancel/veto提案）
+- [x] C2: #18677 へ実装可能な最小仕様を追記（`cancel`, `cancelReason`, `policyMode`）
+- [x] C3: OpenClaw公式Docs向けサンプルhook草案を作成（before_install + before_tool_call） ※ before_tool_call版ドラフト作成済み: `docs/OPENCLAW_HOOK_SCHEMA_REFERENCE_DRAFT.md`
+- [x] C4: guard-scannerの「OpenClaw推奨導入手順」短縮版をREADME/SKILLに反映
+- [x] C5: OpenClaw Discord向け技術共有文（宣伝色なし、再現手順中心）を作成 (`output/OPENCLAW_DISCORD_TECHNICAL_SHARE_DRAFT_2026-02-18.md`)
+- [x] C6: OpenClaw docs向けPR-readyパッチ作成 + #18677に提出（`docs/OPENCLAW_DOCS_PR_READY_PATCH.md`）
+
+## 5) Delivery & GTM（コミュニティ同期後）
+- [ ] D1: note無料記事（使い方 + 失敗例 + 回避）
+- [ ] D2: X告知（SEO/LLMOワード最適化2パターンAB）
+- [ ] D3: Moltbook技術投稿（検知改善ログ + フィードバック募集）
+
+## Exit Criteria
+- FP率: 現状比 30%以上削減
+- FN率: 悪性固定コーパスで95%以上検知
+- 56既存テスト + 新規テスト全PASS
+- SARIFをGitHub Code Scanningで取り込み確認
+- OpenClawコミュニティ向け公開仕様（Issue + Docs草案）を1セット完了

package/hooks/guard-scanner/handler.ts

@@ -1,5 +1,10 @@
 /**
- * guard-scanner Runtime Guard — Hook Handler
+ * guard-scanner Runtime Guard — Hook Handler (LEGACY)
+ *
+ * ⚠️ DEPRECATED: Use plugin.ts instead.
+ * This Internal Hook version can only WARN, not block.
+ * The Plugin Hook version (plugin.ts) uses the native
+ * `block` / `blockReason` API to actually prevent execution.
  *
  * Intercepts agent tool calls and checks arguments against
  * runtime threat intelligence patterns. Zero dependencies.

package/hooks/guard-scanner/plugin.ts

@@ -0,0 +1,303 @@
+/**
+ * guard-scanner Runtime Guard — Plugin Hook Version
+ *
+ * Intercepts agent tool calls via the Plugin Hook API and blocks
+ * dangerous patterns using `block` / `blockReason`.
+ *
+ * Unlike the legacy Internal Hook handler (handler.ts), this version
+ * can ACTUALLY BLOCK tool calls, not just warn.
+ *
+ * Usage:
+ *   Copy to ~/.openclaw/plugins/guard-scanner-runtime.ts
+ *   Or register via openclaw plugin system.
+ *
+ * Modes:
+ *   monitor  — log only, never block
+ *   enforce  — block CRITICAL threats (default)
+ *   strict   — block HIGH + CRITICAL threats
+ *
+ * @author Guava 🍈 & Dee
+ * @version 2.0.0
+ * @license MIT
+ */
+
+import { appendFileSync, mkdirSync, readFileSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+
+// ── Types (from OpenClaw src/plugins/types.ts) ──
+
+type PluginHookBeforeToolCallEvent = {
+    toolName: string;
+    params: Record<string, unknown>;
+};
+
+type PluginHookBeforeToolCallResult = {
+    params?: Record<string, unknown>;
+    block?: boolean;
+    blockReason?: string;
+};
+
+type PluginHookToolContext = {
+    agentId?: string;
+    sessionKey?: string;
+    toolName: string;
+};
+
+type PluginAPI = {
+    on(
+        hookName: "before_tool_call",
+        handler: (
+            event: PluginHookBeforeToolCallEvent,
+            ctx: PluginHookToolContext
+        ) => PluginHookBeforeToolCallResult | void | Promise<PluginHookBeforeToolCallResult | void>
+    ): void;
+    logger: {
+        info: (msg: string) => void;
+        warn: (msg: string) => void;
+        error: (msg: string) => void;
+    };
+};
+
+// ── Runtime threat patterns (12 checks) ──
+
+interface RuntimeCheck {
+    id: string;
+    severity: "CRITICAL" | "HIGH" | "MEDIUM";
+    desc: string;
+    test: (s: string) => boolean;
+}
+
+const RUNTIME_CHECKS: RuntimeCheck[] = [
+    {
+        id: "RT_REVSHELL",
+        severity: "CRITICAL",
+        desc: "Reverse shell attempt",
+        test: (s) => /\/dev\/tcp\/|nc\s+-e|ncat\s+-e|bash\s+-i\s+>&|socat\s+TCP/i.test(s),
+    },
+    {
+        id: "RT_CRED_EXFIL",
+        severity: "CRITICAL",
+        desc: "Credential exfiltration to external",
+        test: (s) =>
+            /(webhook\.site|requestbin\.com|hookbin\.com|pipedream\.net|ngrok\.io|socifiapp\.com)/i.test(s) &&
+            /(token|key|secret|password|credential|env)/i.test(s),
+    },
+    {
+        id: "RT_GUARDRAIL_OFF",
+        severity: "CRITICAL",
+        desc: "Guardrail disabling attempt",
+        test: (s) => /exec\.approvals?\s*[:=]\s*['"]?(off|false)|tools\.exec\.host\s*[:=]\s*['"]?gateway/i.test(s),
+    },
+    {
+        id: "RT_GATEKEEPER",
+        severity: "CRITICAL",
+        desc: "macOS Gatekeeper bypass (xattr)",
+        test: (s) => /xattr\s+-[crd]\s.*quarantine/i.test(s),
+    },
+    {
+        id: "RT_AMOS",
+        severity: "CRITICAL",
+        desc: "ClawHavoc AMOS indicator",
+        test: (s) => /socifiapp|Atomic\s*Stealer|AMOS/i.test(s),
+    },
+    {
+        id: "RT_MAL_IP",
+        severity: "CRITICAL",
+        desc: "Known malicious IP",
+        test: (s) => /91\.92\.242\.30/i.test(s),
+    },
+    {
+        id: "RT_DNS_EXFIL",
+        severity: "HIGH",
+        desc: "DNS-based exfiltration",
+        test: (s) => /nslookup\s+.*\$|dig\s+.*\$.*@/i.test(s),
+    },
+    {
+        id: "RT_B64_SHELL",
+        severity: "CRITICAL",
+        desc: "Base64 decode piped to shell",
+        test: (s) => /base64\s+(-[dD]|--decode)\s*\|\s*(sh|bash)/i.test(s),
+    },
+    {
+        id: "RT_CURL_BASH",
+        severity: "CRITICAL",
+        desc: "Download piped to shell",
+        test: (s) => /(curl|wget)\s+[^\n]*\|\s*(sh|bash|zsh)/i.test(s),
+    },
+    {
+        id: "RT_SSH_READ",
+        severity: "HIGH",
+        desc: "SSH private key access",
+        test: (s) => /\.ssh\/id_|\.ssh\/authorized_keys/i.test(s),
+    },
+    {
+        id: "RT_WALLET",
+        severity: "HIGH",
+        desc: "Crypto wallet credential access",
+        test: (s) => /wallet.*(?:seed|mnemonic|private.*key)|seed.*phrase/i.test(s),
+    },
+    {
+        id: "RT_CLOUD_META",
+        severity: "CRITICAL",
+        desc: "Cloud metadata endpoint access",
+        test: (s) => /169\.254\.169\.254|metadata\.google|metadata\.aws/i.test(s),
+    },
+];
+
+// ── Audit logging ──
+
+const AUDIT_DIR = join(homedir(), ".openclaw", "guard-scanner");
+const AUDIT_FILE = join(AUDIT_DIR, "audit.jsonl");
+
+function ensureAuditDir(): void {
+    try {
+        mkdirSync(AUDIT_DIR, { recursive: true });
+    } catch {
+        /* ignore */
+    }
+}
+
+function logAudit(entry: Record<string, unknown>): void {
+    ensureAuditDir();
+    const line = JSON.stringify({ ...entry, ts: new Date().toISOString() }) + "\n";
+    try {
+        appendFileSync(AUDIT_FILE, line);
+    } catch {
+        /* ignore */
+    }
+}
+
+// ── Config ──
+
+type GuardMode = "monitor" | "enforce" | "strict";
+
+const SUITE_TOKEN_FILE = join(homedir(), ".openclaw", "guava-suite", "token.jwt");
+
+/**
+ * Check if GuavaSuite JWT exists and hasn't expired.
+ * Why: Lightweight check without jsonwebtoken dependency — just decode base64 payload.
+ * Full JWT signature verification happens at activation time in activate.js.
+ */
+function isSuiteActive(): boolean {
+    try {
+        const token = readFileSync(SUITE_TOKEN_FILE, "utf8").trim();
+        if (!token) return false;
+
+        // Decode JWT payload (base64url → JSON)
+        const parts = token.split(".");
+        if (parts.length !== 3) return false;
+
+        const payload = JSON.parse(
+            Buffer.from(parts[1], "base64url").toString("utf8")
+        );
+
+        // Check expiry
+        if (payload.exp && payload.exp * 1000 < Date.now()) return false;
+
+        // Check scope
+        return payload.scope === "suite";
+    } catch {
+        return false;
+    }
+}
+
+function loadMode(): GuardMode {
+    // Priority 1: GuavaSuite JWT token → strict
+    if (isSuiteActive()) {
+        return "strict";
+    }
+
+    // Priority 2: explicit config in openclaw.json
+    try {
+        const configPath = join(homedir(), ".openclaw", "openclaw.json");
+        const config = JSON.parse(readFileSync(configPath, "utf8"));
+
+        // Check suiteEnabled flag (set by activate.js)
+        if (config?.plugins?.["guard-scanner"]?.suiteEnabled === true) {
+            return "strict";
+        }
+
+        const mode = config?.plugins?.["guard-scanner"]?.mode;
+        if (mode === "monitor" || mode === "enforce" || mode === "strict") {
+            return mode;
+        }
+    } catch {
+        /* config not found or invalid — use default */
+    }
+    return "enforce";
+}
+
+function shouldBlock(severity: string, mode: GuardMode): boolean {
+    if (mode === "monitor") return false;
+    if (mode === "enforce") return severity === "CRITICAL";
+    if (mode === "strict") return severity === "CRITICAL" || severity === "HIGH";
+    return false;
+}
+
+// ── Dangerous tool filter ──
+
+const DANGEROUS_TOOLS = new Set([
+    "exec",
+    "write",
+    "edit",
+    "browser",
+    "web_fetch",
+    "message",
+    "shell",
+    "run_command",
+    "multi_edit",
+]);
+
+// ── Plugin entry point ──
+
+export default function (api: PluginAPI) {
+    const mode = loadMode();
+    api.logger.info(`🛡️ guard-scanner runtime guard loaded (mode: ${mode})`);
+
+    api.on("before_tool_call", (event, ctx) => {
+        const { toolName, params } = event;
+
+        // Only check tools that can cause damage
+        if (!DANGEROUS_TOOLS.has(toolName)) return;
+
+        const serialized = JSON.stringify(params);
+
+        for (const check of RUNTIME_CHECKS) {
+            if (!check.test(serialized)) continue;
+
+            const auditEntry = {
+                tool: toolName,
+                check: check.id,
+                severity: check.severity,
+                desc: check.desc,
+                mode,
+                action: "warned" as string,
+                session: ctx.sessionKey || "unknown",
+                agent: ctx.agentId || "unknown",
+            };
+
+            if (shouldBlock(check.severity, mode)) {
+                auditEntry.action = "blocked";
+                logAudit(auditEntry);
+                api.logger.warn(
+                    `🛡️ BLOCKED ${toolName}: ${check.desc} [${check.id}] (${check.severity})`
+                );
+
+                return {
+                    block: true,
+                    blockReason: `🛡️ guard-scanner: ${check.desc} [${check.id}]`,
+                };
+            }
+
+            // Monitor mode or severity below threshold — warn only
+            logAudit(auditEntry);
+            api.logger.warn(
+                `🛡️ WARNING ${toolName}: ${check.desc} [${check.id}] (${check.severity})`
+            );
+        }
+
+        // No threats detected or all below threshold — allow
+        return;
+    });
+}

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "guard-scanner",
-    "version": "1.1.1",
-    "description": "Agent skill security scanner — detect prompt injection, malicious code, credential leaks, and 20 threat categories in AI agent skills",
+    "version": "2.1.0",
+    "description": "Agent skill security scanner — detect prompt injection, malicious code, credential leaks, PII exposure, Shadow AI, and 21 threat categories in AI agent skills",
     "main": "src/scanner.js",
     "bin": {
         "guard-scanner": "src/cli.js"

package/src/patterns.js

@@ -185,6 +185,28 @@ const PATTERNS = [
     { id: 'CFG_EXEC_HOST_GW', cat: 'config-impact', regex: /tools\.exec\.host\s*[:=]\s*['"]gateway['"]/gi, severity: 'CRITICAL', desc: 'Set exec host to gateway (bypass sandbox)', all: true },
     { id: 'CFG_SANDBOX_OFF', cat: 'config-impact', regex: /(?:sandbox|sandboxed|containerized)\s*[:=]\s*(?:false|off|none|disabled|0)/gi, severity: 'CRITICAL', desc: 'Disable sandbox via configuration', all: true },
     { id: 'CFG_TOOL_OVERRIDE', cat: 'config-impact', regex: /(?:tools|capabilities)\s*\.\s*(?:exec|write|browser|web_fetch)\s*[:=]\s*\{[^}]*(?:enabled|allowed|host)/gi, severity: 'HIGH', desc: 'Override tool security settings', codeOnly: true },
+
+    // ── Category 21: PII Exposure (OWASP LLM02 / LLM06) ──
+    // A. Hardcoded PII — actual PII values in code/config (context-aware to reduce FP)
+    { id: 'PII_HARDCODED_CC', cat: 'pii-exposure', regex: /(?:card|cc|credit|payment|pan)[_\s.-]*(?:num|number|no)?\s*[:=]\s*['"`]\d{4}[\s-]?\d{4}[\s-]?\d{4}[\s-]?\d{3,4}['"`]/gi, severity: 'CRITICAL', desc: 'Hardcoded credit card number', codeOnly: true },
+    { id: 'PII_HARDCODED_SSN', cat: 'pii-exposure', regex: /(?:ssn|social[_\s-]*security|tax[_\s-]*id)\s*[:=]\s*['"`]\d{3}-?\d{2}-?\d{4}['"`]/gi, severity: 'CRITICAL', desc: 'Hardcoded SSN/tax ID', codeOnly: true },
+    { id: 'PII_HARDCODED_PHONE', cat: 'pii-exposure', regex: /(?:phone|tel|mobile|cell|fax)[_\s.-]*(?:num|number|no)?\s*[:=]\s*['"`][+]?[\d\s().-]{7,20}['"`]/gi, severity: 'HIGH', desc: 'Hardcoded phone number', codeOnly: true },
+    { id: 'PII_HARDCODED_EMAIL', cat: 'pii-exposure', regex: /(?:email|e-mail|user[_\s-]*mail|contact)\s*[:=]\s*['"`][a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}['"`]/gi, severity: 'HIGH', desc: 'Hardcoded email address', codeOnly: true },
+
+    // B. PII output/logging — code that outputs or transmits PII-like variables
+    { id: 'PII_LOG_SENSITIVE', cat: 'pii-exposure', regex: /(?:console\.log|console\.info|console\.warn|logger?\.\w+|print|puts)\s*\([^)]*\b(?:ssn|social_security|credit_card|card_number|cvv|cvc|passport|tax_id|date_of_birth|dob)\b/gi, severity: 'HIGH', desc: 'PII variable logged to console', codeOnly: true },
+    { id: 'PII_SEND_NETWORK', cat: 'pii-exposure', regex: /(?:fetch|axios|request|http|post|put|send)\s*\([^)]*\b(?:ssn|social_security|credit_card|card_number|cvv|passport|bank_account|routing_number)\b/gi, severity: 'CRITICAL', desc: 'PII variable sent over network', codeOnly: true },
+    { id: 'PII_STORE_PLAINTEXT', cat: 'pii-exposure', regex: /(?:writeFile|writeFileSync|appendFile|fs\.write|fwrite)\s*\([^)]*\b(?:ssn|social_security|credit_card|card_number|cvv|passport|tax_id|bank_account)\b/gi, severity: 'HIGH', desc: 'PII stored in plaintext file', codeOnly: true },
+
+    // C. Shadow AI — unauthorized LLM API calls (data leaks to external AI)
+    { id: 'SHADOW_AI_OPENAI', cat: 'pii-exposure', regex: /(?:api\.openai\.com|https:\/\/api\.openai\.com)\s*|openai\.(?:chat|completions|ChatCompletion)/gi, severity: 'HIGH', desc: 'Shadow AI: OpenAI API call', codeOnly: true },
+    { id: 'SHADOW_AI_ANTHROPIC', cat: 'pii-exposure', regex: /(?:api\.anthropic\.com|https:\/\/api\.anthropic\.com)\s*|anthropic\.(?:messages|completions)/gi, severity: 'HIGH', desc: 'Shadow AI: Anthropic API call', codeOnly: true },
+    { id: 'SHADOW_AI_GENERIC', cat: 'pii-exposure', regex: /\/v1\/(?:chat\/completions|completions|embeddings|models)\b.*(?:fetch|axios|request|http)|(?:fetch|axios|request|http)\s*\([^)]*\/v1\/(?:chat\/completions|completions|embeddings)/gi, severity: 'MEDIUM', desc: 'Shadow AI: generic LLM API endpoint', codeOnly: true },
+
+    // D. PII collection instructions in docs (extends LEAK_COLLECT_PII)
+    { id: 'PII_ASK_ADDRESS', cat: 'pii-exposure', regex: /(?:collect|ask\s+for|request|get|require)\s+(?:the\s+)?(?:user'?s?\s+)?(?:home\s+)?(?:address|street|zip\s*code|postal\s*code|residence)/gi, severity: 'HIGH', desc: 'PII collection: home address', docOnly: true },
+    { id: 'PII_ASK_DOB', cat: 'pii-exposure', regex: /(?:collect|ask\s+for|request|get|require)\s+(?:the\s+)?(?:user'?s?\s+)?(?:date\s+of\s+birth|birth\s*date|birthday|DOB|age)/gi, severity: 'HIGH', desc: 'PII collection: date of birth', docOnly: true },
+    { id: 'PII_ASK_GOV_ID', cat: 'pii-exposure', regex: /(?:collect|ask\s+for|request|get|require)\s+(?:the\s+)?(?:user'?s?\s+)?(?:passport|driver'?s?\s+licen[sc]e|national\s+id|my\s*number|マイナンバー|国民健康保険|social\s+insurance)/gi, severity: 'CRITICAL', desc: 'PII collection: government ID', docOnly: true },
 ];
 
 module.exports = { PATTERNS };

package/src/scanner.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * guard-scanner v1.0.0 — Agent Skill Security Scanner 🛡️
+ * guard-scanner v2.1.0 — Agent Skill Security Scanner 🛡️
  *
  * @security-manifest
  *   env-read: []
@@ -24,13 +24,14 @@
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
+const crypto = require('crypto');
 
 const { PATTERNS } = require('./patterns.js');
 const { KNOWN_MALICIOUS } = require('./ioc-db.js');
 const { generateHTML } = require('./html-template.js');
 
 // ===== CONFIGURATION =====
-const VERSION = '1.1.0';
+const VERSION = '2.1.0';
 
 const THRESHOLDS = {
     normal: { suspicious: 30, malicious: 80 },
@@ -42,6 +43,7 @@ const CODE_EXTENSIONS = new Set(['.js', '.ts', '.mjs', '.cjs', '.py', '.sh', '.b
 const DOC_EXTENSIONS = new Set(['.md', '.txt', '.rst', '.adoc']);
 const DATA_EXTENSIONS = new Set(['.json', '.yaml', '.yml', '.toml', '.xml', '.csv']);
 const BINARY_EXTENSIONS = new Set(['.png', '.jpg', '.jpeg', '.gif', '.ico', '.woff', '.woff2', '.ttf', '.eot', '.wasm', '.wav', '.mp3', '.mp4', '.webm', '.ogg', '.pdf', '.zip', '.tar', '.gz', '.bz2', '.7z', '.exe', '.dll', '.so', '.dylib']);
+const GENERATED_REPORT_FILES = new Set(['guard-scanner-report.json', 'guard-scanner-report.html', 'guard-scanner.sarif']);
 
 // Severity weights for risk scoring
 const SEVERITY_WEIGHTS = { CRITICAL: 40, HIGH: 15, MEDIUM: 5, LOW: 2 };
@@ -866,6 +868,11 @@ class GuardScanner {
         if (cats.has('config-impact') && cats.has('sandbox-validation')) score = Math.max(score, 70);
         if (cats.has('complexity') && (cats.has('malicious-code') || cats.has('obfuscation'))) score = Math.round(score * 1.5);
 
+        // v2.1 PII exposure amplifiers
+        if (cats.has('pii-exposure') && cats.has('exfiltration')) score = Math.round(score * 3);
+        if (cats.has('pii-exposure') && (ids.has('SHADOW_AI_OPENAI') || ids.has('SHADOW_AI_ANTHROPIC') || ids.has('SHADOW_AI_GENERIC'))) score = Math.round(score * 2.5);
+        if (cats.has('pii-exposure') && cats.has('credential-handling')) score = Math.round(score * 2);
+
         return Math.min(100, score);
     }
 
@@ -886,6 +893,8 @@ class GuardScanner {
                     if (entry.name === '.git' || entry.name === 'node_modules') continue;
                     results.push(...this.getFiles(fullPath));
                 } else {
+                    const baseName = entry.name.toLowerCase();
+                    if (GENERATED_REPORT_FILES.has(baseName)) continue;
                     results.push(fullPath);
                 }
             }
@@ -939,6 +948,7 @@ class GuardScanner {
             if (cats.has('sandbox-validation')) skillRecs.push('🔒 SANDBOX: Skill requests dangerous capabilities.');
             if (cats.has('complexity')) skillRecs.push('🧩 COMPLEXITY: Excessive code complexity may hide malicious behavior.');
             if (cats.has('config-impact')) skillRecs.push('⚙️ CONFIG IMPACT: Modifies OpenClaw configuration. DO NOT INSTALL.');
+            if (cats.has('pii-exposure')) skillRecs.push('🆔 PII EXPOSURE: Handles personally identifiable information. Review data handling.');
 
             if (skillRecs.length > 0) recommendations.push({ skill: skillResult.skill, actions: skillRecs });
         }
@@ -971,11 +981,21 @@ class GuardScanner {
                         properties: { tags: ['security', f.cat], 'security-severity': f.severity === 'CRITICAL' ? '9.0' : f.severity === 'HIGH' ? '7.0' : f.severity === 'MEDIUM' ? '4.0' : '1.0' }
                     });
                 }
+                const normalizedFile = String(f.file || '')
+                    .replaceAll('\\', '/')
+                    .replace(/^\/+/, '');
+                const artifactUri = `${skillResult.skill}/${normalizedFile}`;
+                const fingerprintSeed = `${f.id}|${artifactUri}|${f.line || 0}|${(f.sample || '').slice(0, 200)}`;
+                const lineHash = crypto.createHash('sha256').update(fingerprintSeed).digest('hex').slice(0, 24);
+
                 results.push({
                     ruleId: f.id, ruleIndex: ruleIndex[f.id],
                     level: f.severity === 'CRITICAL' ? 'error' : f.severity === 'HIGH' ? 'error' : f.severity === 'MEDIUM' ? 'warning' : 'note',
                     message: { text: `[${skillResult.skill}] ${f.desc}${f.sample ? ` — "${f.sample}"` : ''}` },
-                    locations: [{ physicalLocation: { artifactLocation: { uri: `${skillResult.skill}/${f.file}`, uriBaseId: '%SRCROOT%' }, region: f.line ? { startLine: f.line } : undefined } }]
+                    partialFingerprints: {
+                        primaryLocationLineHash: lineHash
+                    },
+                    locations: [{ physicalLocation: { artifactLocation: { uri: artifactUri, uriBaseId: '%SRCROOT%' }, region: f.line ? { startLine: f.line } : undefined } }]
                 });
             }
         }