guard-scanner 1.1.0 → 2.0.0

package/README.md

@@ -2,13 +2,14 @@
   <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.
+    Detect prompt injection, credential theft, exfiltration, identity hijacking, and 16 more threat categories.<br>
+    <sub>🆕 Plugin Hook v2.0 — <strong>actual blocking</strong> 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/tests-56%2F56-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">
   </p>
@@ -73,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.0 Plugin Hook** — Uses OpenClaw's native `block`/`blockReason` API to actually prevent dangerous tool calls. Supports 3 modes: `monitor` (log only), `enforce` (block CRITICAL), `strict` (block HIGH + CRITICAL).
+
 ### Installation (Optional)
 
 ```bash
@@ -90,11 +103,13 @@ openclaw skill install guard-scanner
 guard-scanner ~/.openclaw/workspace/skills/ --self-exclude --verbose
 ```
 
+> **🆕 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 **20 threat categories** derived from four sources:
 
 | # | Category | Based On | Severity | What It Detects |
 |---|----------|----------|----------|----------------|
@@ -128,7 +143,7 @@ guard-scanner covers **20 threat categories** derived from three taxonomies:
 ### Terminal (Default)
 
 ```
-🛡️  guard-scanner v1.0.0
+🛡️  guard-scanner v1.1.1
 ══════════════════════════════════════════════════════
 📂 Scanning: ./skills/
 📦 Skills found: 22
@@ -391,9 +406,12 @@ guard-scanner/
 │   └── cli.js          # CLI entry point and argument parser
 ├── hooks/
 │   └── guard-scanner/
-│       └── handler.ts  # Runtime Guard — before_tool_call hook
+│       ├── 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
+│   ├── scanner.test.js # 56 tests — static scanner
+│   ├── plugin.test.js  # 35 tests — Plugin Hook runtime guard
 │   └── fixtures/       # Malicious, clean, complex, config-changer samples
 ├── package.json        # Zero dependencies, node --test
 ├── CHANGELOG.md
@@ -518,11 +536,11 @@ console.log(scanner.toHTML());    // HTML string
 ## Test Results
 
 ```
-ℹ tests 55
+ℹ tests 56
 ℹ suites 13
-ℹ pass 55
+ℹ pass 56
 ℹ fail 0
-ℹ duration_ms 115ms
+ℹ duration_ms 108ms
 ```
 
 | Suite | Tests | Coverage |
@@ -553,13 +571,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 | Insecure Output Handling | 🔜 v1.2 | Planned: unvalidated output execution patterns |
+| LLM03 | Training Data Poisoning | ⬜ N/A | Out of scope for static analysis |
+| LLM04 | Model Denial of Service | 🔜 v1.3 | Planned: excessive input / infinite loop patterns |
+| LLM05 | Supply Chain Vulnerabilities | ⚠️ Partial | IoC database, typosquat detection, dependency chain scan |
+| LLM06 | Sensitive Information Disclosure | ⚠️ Partial | Secret detection, PII patterns, credential leaks |
+| 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: 3/10 (partial).** Full OWASP Gen AI coverage is targeted for v1.3. See [ROADMAP.md](ROADMAP.md) for details.
+>
+> **Known limitation:** Regex-based detection can be evaded by AI-generated code obfuscation. v2.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 56+ tests must pass
 6. Submit a Pull Request
 
 ### Adding a New Detection Pattern
@@ -605,15 +646,29 @@ guard-scanner catches threats **before** installation. But what happens **after*
 | | guard-scanner (OSS) | GuavaSuite (Private) |
 |---|---|---|
 | Static scan | ✅ 20 categories | ✅ 20 categories |
-| Runtime blocking | — | ✅ 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 |
+| Runtime blocking | ✅ Plugin Hook v2.0 (`block`/`blockReason`) | ✅ SuiteGate (enhanced ruleset) |
+| SOUL.md integrity | Pattern detection only | ⏳ SHA-256 hash watchdog (W4 E2E) |
+| On-chain verification | — | ⏳ SoulChain (Polygon, Phase 2) |
+| Identity recovery | — | ⏳ Automatic rollback (Phase 2) |
 
 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).
 
 ---
 
+## Roadmap
+
+| Version | Focus | Key Features |
+|---------|-------|------|
+| v1.1.1 ✅ | Stability | 56 tests, bug fixes |
+| v1.2 | PII + Shadow AI | Credential-in-context, unauthorized LLM API calls, memory poisoning vectors |
+| v1.3 | OWASP Gen AI | Complete LLM02/04/07/08/09/10 coverage |
+| v2.0 | AST + ML | JavaScript AST analysis, taint tracking, ML-based obfuscation detection, SBOM generation |
+| v2.1 | Community | YAML pattern definitions, CONTRIBUTING guide, automated pattern updates |
+
+See [ROADMAP.md](ROADMAP.md) for full details.
+
+---
+
 ## 💜 Sponsor This Project
 
 If guard-scanner helps protect your agents, consider sponsoring continued development:

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

@@ -29,7 +29,7 @@ metadata:
 # guard-scanner 🛡️
 
 Static + runtime security scanner for AI agent skills.
-**170+ threat patterns** across **17 categories** — zero dependencies.
+**186+ threat patterns** across **20 categories** — zero dependencies.
 
 ## When To Use This Skill
 
@@ -54,27 +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)
+### 2. Runtime Guard (OpenClaw) — ⚠️ warn-only currently
 
-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
 ```
@@ -83,11 +79,13 @@ openclaw hooks enable guard-scanner
 
 Set in `openclaw.json` → `hooks.internal.entries.guard-scanner.mode`:
 
-| Mode | Behavior |
-|------|----------|
-| `monitor` | Log all, never block |
-| `enforce` (default) | Block CRITICAL threats |
-| `strict` | Block HIGH + CRITICAL |
+| Mode | Intended Behavior | Current Status |
+|------|-------------------|----------------|
+| `monitor` | Log all, never block | ✅ Fully working |
+| `enforce` (default) | Block CRITICAL threats | ⚠️ Warn only (cancel API pending) |
+| `strict` | Block HIGH + CRITICAL | ⚠️ Warn only (cancel API pending) |
+
+> **Note:** OpenClaw's `InternalHookEvent` does not yet expose a `cancel`/`veto` mechanism. All detections are currently logged and warned via `event.messages`, but tool execution cannot be blocked. Blocking will be enabled when the cancel API is added.
 
 ## Threat Categories
 
@@ -110,6 +108,9 @@ Set in `openclaw.json` → `hooks.internal.entries.guard-scanner.mode`:
 | 15 | CVE Patterns | Known agent vulnerabilities |
 | 16 | MCP Security | Tool/schema poisoning, SSRF |
 | 17 | Identity Hijacking | SOUL.md/IDENTITY.md tampering |
+| 18 | Sandbox Validation | Dangerous binaries, broad file scope, sensitive env |
+| 19 | Code Complexity | Excessive file length, deep nesting, eval density |
+| 20 | Config Impact | openclaw.json writes, exec approval bypass |
 
 ## External Endpoints
 
@@ -140,7 +141,7 @@ an AI agent's SOUL.md personality file, and no existing tool could detect it.
 
 - **Open source**: Full source code available at https://github.com/koatora20/guard-scanner
 - **Zero dependencies**: Nothing to audit, no transitive risks
-- **Test suite**: 45 tests across 10 sections, 100% pass rate
+- **Test suite**: 55 tests across 13 sections, 100% pass rate
 - **Taxonomy**: Based on Snyk ToxicSkills (Feb 2026), OWASP MCP Top 10, and original research
 - **Complementary to VirusTotal**: Detects prompt injection and LLM-specific attacks
   that VirusTotal's signature-based scanning cannot catch

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,26 +1,74 @@
-import type { HookHandler } from "../../src/hooks/hooks.js";
-import { appendFileSync, mkdirSync } from "fs";
-import { join } from "path";
-import { homedir } from "os";
-
 /**
- * guard-scanner Runtime Guard — before_tool_call Hook Handler
- * 
- * Intercepts tool executions in real-time and checks against
- * threat intelligence patterns. Zero dependencies.
- * 
- * Modes:
- *   monitor  — log only
- *   enforce  — block CRITICAL (default)
- *   strict   — block HIGH+CRITICAL, log MEDIUM+
- * 
+ * 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.
+ *
+ * Registered for event: agent:before_tool_call
+ *
+ * Current limitation:
+ *   The OpenClaw InternalHookEvent interface does not yet expose a
+ *   `cancel` / `veto` mechanism. This handler can WARN via
+ *   event.messages but cannot block tool execution.
+ *   When a cancel API is introduced, this handler will be updated
+ *   to actually block CRITICAL/HIGH threats.
+ *
+ * Modes (for future blocking behaviour):
+ *   monitor  — log only (current effective behaviour for all modes)
+ *   enforce  — will block CRITICAL when cancel API is available
+ *   strict   — will block HIGH+CRITICAL when cancel API is available
+ *
  * @author Guava 🍈 & Dee
- * @version 1.0.0
+ * @version 1.1.0
  * @license MIT
  */
 
+import { appendFileSync, mkdirSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+
+// ── OpenClaw Hook Types (from openclaw/src/hooks/internal-hooks.ts) ──
+// Inline types to avoid broken relative-path imports.
+// These match the official InternalHookEvent / InternalHookHandler
+// from OpenClaw v2026.2.15.
+
+type InternalHookEventType = "command" | "session" | "agent" | "gateway";
+
+interface InternalHookEvent {
+    /** The type of event */
+    type: InternalHookEventType;
+    /** The specific action within the type (e.g., "before_tool_call") */
+    action: string;
+    /** The session key this event relates to */
+    sessionKey: string;
+    /** Additional context specific to the event */
+    context: Record<string, unknown>;
+    /** Timestamp when the event occurred */
+    timestamp: Date;
+    /** Messages to send back to the user (hooks can push to this array) */
+    messages: string[];
+}
+
+type InternalHookHandler = (event: InternalHookEvent) => Promise<void> | void;
+
+// Re-export as the public types for compatibility
+type HookHandler = InternalHookHandler;
+type HookEvent = InternalHookEvent;
+
 // ── Runtime threat patterns (12 checks) ──
-const RUNTIME_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: string) => /\/dev\/tcp\/|nc\s+-e|ncat\s+-e|bash\s+-i\s+>&|socat\s+TCP/i.test(s)
@@ -78,11 +126,11 @@ const RUNTIME_CHECKS = [
 const AUDIT_DIR = join(homedir(), ".openclaw", "guard-scanner");
 const AUDIT_FILE = join(AUDIT_DIR, "audit.jsonl");
 
-function ensureAuditDir() {
+function ensureAuditDir(): void {
     try { mkdirSync(AUDIT_DIR, { recursive: true }); } catch { }
 }
 
-function logAudit(entry: Record<string, unknown>) {
+function logAudit(entry: Record<string, unknown>): void {
     ensureAuditDir();
     const line = JSON.stringify({ ...entry, ts: new Date().toISOString() }) + '\n';
     try { appendFileSync(AUDIT_FILE, line); } catch { }
@@ -90,16 +138,21 @@ function logAudit(entry: Record<string, unknown>) {
 
 // ── Main Handler ──
 const handler: HookHandler = async (event) => {
-    // Only handle before_tool_call
+    // Only handle agent:before_tool_call events
     if (event.type !== "agent" || event.action !== "before_tool_call") return;
 
-    const { toolName, toolArgs } = (event as any).context || {};
+    const { toolName, toolArgs } = event.context as {
+        toolName?: string;
+        toolArgs?: Record<string, unknown>;
+    };
     if (!toolName || !toolArgs) return;
 
-    // Get mode from config
-    const mode = (event as any).context?.cfg?.hooks?.internal?.entries?.['guard-scanner']?.mode || 'enforce';
+    // Get mode from context config (if available)
+    const cfg = event.context.cfg as Record<string, unknown> | undefined;
+    const hookEntries = (cfg as any)?.hooks?.internal?.entries?.['guard-scanner'] as Record<string, unknown> | undefined;
+    const mode = (hookEntries?.mode as string) || 'enforce';
 
-    // Only check dangerous tools
+    // Only check tools that can cause damage
     const dangerousTools = new Set(['exec', 'write', 'edit', 'browser', 'web_fetch', 'message']);
     if (!dangerousTools.has(toolName)) return;
 
@@ -113,35 +166,39 @@ const handler: HookHandler = async (event) => {
                 severity: check.severity,
                 desc: check.desc,
                 mode,
-                action: 'allowed' as string,
-                session: (event as any).sessionKey,
+                action: 'warned' as string,
+                session: event.sessionKey,
             };
 
-            if (mode === 'strict' && (check.severity === 'CRITICAL' || check.severity === 'HIGH')) {
-                entry.action = 'blocked';
-                logAudit(entry);
-                event.messages.push(`🛡️ guard-scanner BLOCKED: ${check.desc} [${check.id}]`);
-                event.cancel = true;
-                console.warn(`[guard-scanner] 🚨 BLOCKED: ${check.desc} [${check.id}]`);
-                return;
-            }
-
-            if (mode === 'enforce' && check.severity === 'CRITICAL') {
-                entry.action = 'blocked';
-                logAudit(entry);
-                event.messages.push(`🛡️ guard-scanner BLOCKED: ${check.desc} [${check.id}]`);
-                event.cancel = true;
-                console.warn(`[guard-scanner] 🚨 BLOCKED: ${check.desc} [${check.id}]`);
-                return;
-            }
-
-            // Monitor mode or non-critical: log only
-            entry.action = 'logged';
+            // NOTE: OpenClaw InternalHookEvent does not currently support
+            // a cancel/veto mechanism. When it does, uncomment the blocking
+            // logic below. For now, all detections are warnings only.
+            //
+            // if (mode === 'strict' && (check.severity === 'CRITICAL' || check.severity === 'HIGH')) {
+            //     entry.action = 'blocked';
+            //     logAudit(entry);
+            //     event.messages.push(`🛡️ guard-scanner BLOCKED: ${check.desc} [${check.id}]`);
+            //     event.cancel = true;  // Not yet in the public API
+            //     return;
+            // }
+            //
+            // if (mode === 'enforce' && check.severity === 'CRITICAL') {
+            //     entry.action = 'blocked';
+            //     logAudit(entry);
+            //     event.messages.push(`🛡️ guard-scanner BLOCKED: ${check.desc} [${check.id}]`);
+            //     event.cancel = true;  // Not yet in the public API
+            //     return;
+            // }
+
+            // Current behaviour: warn and log for all modes
             logAudit(entry);
 
             if (check.severity === 'CRITICAL') {
                 event.messages.push(`🛡️ guard-scanner WARNING: ${check.desc} [${check.id}]`);
                 console.warn(`[guard-scanner] ⚠️ WARNING: ${check.desc} [${check.id}]`);
+            } else if (check.severity === 'HIGH') {
+                event.messages.push(`🛡️ guard-scanner NOTICE: ${check.desc} [${check.id}]`);
+                console.warn(`[guard-scanner] ℹ️ NOTICE: ${check.desc} [${check.id}]`);
             }
         }
     }

package/hooks/guard-scanner/plugin.ts

@@ -0,0 +1,261 @@
+/**
+ * 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";
+
+function loadMode(): GuardMode {
+    try {
+        const configPath = join(homedir(), ".openclaw", "openclaw.json");
+        const config = JSON.parse(readFileSync(configPath, "utf8"));
+        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,6 +1,6 @@
 {
     "name": "guard-scanner",
-    "version": "1.1.0",
+    "version": "2.0.0",
     "description": "Agent skill security scanner — detect prompt injection, malicious code, credential leaks, and 20 threat categories in AI agent skills",
     "main": "src/scanner.js",
     "bin": {

package/src/scanner.js

@@ -24,6 +24,7 @@
 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');
@@ -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 };
@@ -886,6 +888,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);
                 }
             }
@@ -971,11 +975,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 } }]
                 });
             }
         }