@guava-parity/guard-scanner 13.0.0 → 16.0.0

package/README_ja.md

@@ -0,0 +1,252 @@
+<p align="center">
+  <img src="docs/logo.png" alt="guard-scanner" width="160" />
+</p>
+
+<h1 align="center">guard-scanner</h1>
+<p align="center"><strong>エージェント時代のセキュリティスキャナー</strong></p>
+<p align="center">
+  AIエージェントスキル、MCPサーバー、自律型ワークフローにおける<br />
+  プロンプトインジェクション・アイデンティティ乗っ取り・メモリ汚染・A2A感染を検出。
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@guava-parity/guard-scanner"><img src="https://img.shields.io/npm/v/@guava-parity/guard-scanner?color=cb3837&label=npm" alt="npm" /></a>
+  <a href="https://www.npmjs.com/package/@guava-parity/guard-scanner"><img src="https://img.shields.io/npm/dm/@guava-parity/guard-scanner?color=blue&label=downloads" alt="downloads" /></a>
+  <a href="#テスト結果"><img src="https://img.shields.io/badge/テスト-363_passed-brightgreen" alt="tests" /></a>
+  <a href="https://github.com/koatora20/guard-scanner/actions/workflows/codeql.yml"><img src="https://img.shields.io/badge/CodeQL-有効-181717" alt="CodeQL" /></a>
+  <a href="https://doi.org/10.5281/zenodo.18906684"><img src="https://img.shields.io/badge/DOI-Zenodo-blue" alt="DOI" /></a>
+  <a href="https://github.com/koatora20/guard-scanner/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="MIT" /></a>
+</p>
+
+<p align="center">
+  <strong>358</strong> 検出パターン · <strong>35</strong> 脅威カテゴリ · <strong>27</strong> ランタイムチェック · 依存: <strong>1</strong> (<code>ws</code> のみ)
+</p>
+
+<p align="center">
+  <a href="README.md">English</a> · 日本語
+</p>
+
+---
+
+従来のセキュリティツールはマルウェアを検出します。**guard-scanner** はその先を検出します：エージェント命令に隠された不可視Unicode注入、SOUL.mdの上書きによるアイデンティティ窃盗、巧妙な会話を通じたメモリ汚染、チェーン接続されたエージェント間のワーム型感染。
+
+```
+$ npx @guava-parity/guard-scanner ./skills/ --strict --soul-lock --compliance owasp-asi
+
+  guard-scanner v16.0.0
+
+  ⚠  CRITICAL  identity-hijack   SOUL_OVERWRITE_ATTEMPT
+     skills/imported-tool/SKILL.md:47
+     理由: エージェントのアイデンティティファイルへの直接上書きを検出。
+     対策: この命令を削除してください。SOUL.mdは不変でなければなりません。
+
+  ⚠  HIGH      prompt-injection   INVISIBLE_UNICODE_INJECTION
+     skills/imported-tool/handler.js:12
+     理由: 命令テキスト内に不可視Unicode文字（U+200B）を検出。
+     対策: ゼロ幅文字を除去し、再監査してください。
+
+  ✖  2件の検出（1 critical, 1 high）— 0.8秒
+```
+
+> 📄 [3本の研究論文シリーズ](https://doi.org/10.5281/zenodo.18906684)（Zenodo, CC BY 4.0）に基づいて設計。[The Sanctuary Protocol](https://github.com/koatora20/guard-scanner/blob/main/docs/THREAT_TAXONOMY.md) フレームワークの防御レイヤー。
+
+---
+
+## Finding Schema
+
+全検出結果は共通スキーマに従います: `rule_id`, `category`, `severity`, `description`, `rationale`, `preconditions`, `false_positive_scenarios`, `remediation_hint`, `validation_status`, `evidence`。機械可読な仕様: [`docs/spec/finding.schema.json`](docs/spec/finding.schema.json)
+
+---
+
+## クイックスタート
+
+**ディレクトリをスキャン** — インストール不要：
+
+```bash
+npx -y @guava-parity/guard-scanner ./my-skills/ --strict
+npx -y @guava-parity/guard-scanner ./my-skills/ --compliance owasp-asi
+```
+
+**MCPサーバーとして起動** — Cursor, Windsurf, Claude Code, OpenClaw対応：
+
+```bash
+npx -y @guava-parity/guard-scanner serve
+```
+
+```jsonc
+// エディタの mcp_servers.json に追加
+{
+  "mcpServers": {
+    "guard-scanner": {
+      "command": "npx",
+      "args": ["-y", "@guava-parity/guard-scanner", "serve"]
+    }
+  }
+}
+```
+
+**ウォッチモード** — 開発中のリアルタイムスキャン：
+
+```bash
+guard-scanner watch ./skills/ --strict --soul-lock
+```
+
+**v16 コンプライアンス投影** — OWASP Agentic Top 10 に対応する検出だけを抽出：
+
+```bash
+guard-scanner ./skills/ --compliance owasp-asi --format json
+```
+
+---
+
+## 検出対象
+
+35の脅威カテゴリがエージェント攻撃面を網羅：
+
+| カテゴリ | 検出例 | 重大度 |
+|----------|--------|--------|
+| **プロンプトインジェクション** | 不可視Unicode、ホモグリフ、Base64回避、ペイロード連鎖 | Critical |
+| **アイデンティティ乗っ取り** ⚿ | SOUL.md上書き、ペルソナ入替、メモリワイプ | Critical |
+| **A2A感染** | Session Smuggling、Lateral Propagation、Confused Deputy | Critical |
+| **メモリ汚染** ⚿ | 会話インジェクション、VDBポイズニング | High |
+| **MCPセキュリティ** | ツールシャドウイング、引数経由SSRF、シャドウサーバー登録 | High |
+| **サンドボックス脱出** | `child_process`, `eval()`, リバースシェル, `curl\|bash` | High |
+| **サプライチェーンV2** | タイポスクワッティング、スロップスクワッティング | High |
+| **CVEパターン** | CVE-2026-2256, 25046, 25253, 25905, 27825 | High |
+| **データ流出** | DNSトンネリング、ステガノグラフィ、段階的アップロード | Medium |
+| **認証情報露出** | APIキー、トークン、`.env`ファイル、ハードコード秘密鍵 | Medium |
+
+> ⚿ = `--soul-lock` フラグで有効化。全分類: [docs/THREAT_TAXONOMY.md](docs/THREAT_TAXONOMY.md)
+
+---
+
+## ランタイムガード
+
+guard-scanner v16 は静的スキャナーだけではありません。静的解析、プロトコル解析、ランタイム証跡、認知ヒューリスティクス、脅威インテリジェンスを束ねた **5-layer pipeline** を持ち、さらに実行中の危険なツール呼び出しを **`before_tool_call`** フックでインターセプトします。
+
+### v16 分析レイヤー
+
+| レイヤー | 役割 |
+|---------|------|
+| 1. Static Analysis | パターン、AST/データフロー、manifest、依存関係 |
+| 2. Protocol Analysis | MCP、A2A、WebSocket、credential-flow、session-boundary |
+| 3. Runtime Behavior | ランタイムガード + Rust `memory_integrity` / `soul_hard_gate` 証跡 |
+| 4. Cognitive Threat Detection | goal drift、trust bias、handoff cascade |
+| 5. Threat Intelligence | provenance、machine identity、budget abuse、supply chain hints |
+
+v16 の JSON / MCP 出力では各 finding に `layer`, `layer_name`, `owasp_asi`, `protocol_surface` が付与されます。
+
+| 防御レイヤー | ブロック対象 |
+|-------------|-------------|
+| 1. 脅威検出 | リバースシェル、`curl\|bash`、SSRF、コード実行 |
+| 2. 信頼防御 | SOUL.md改ざん、不正メモリ注入 |
+| 3. 安全判定 | ツール引数内のプロンプトインジェクション |
+| 4. 行動分析 | リサーチ未実施での実行、ハルシネーション駆動アクション |
+| 5. 信頼搾取 | 権限主張攻撃、作成者なりすまし |
+
+**27のランタイムチェック**を5層で実行。公開互換の保証面は OpenClaw `v2026.3.8` の manifest/discovery/`before_tool_call` に固定し、新しい upstream は drift watchdog で別途追跡する。
+
+モード: `monitor`（ログのみ）· `enforce`（CRITICAL をブロック、デフォルト）· `strict`（HIGH+をブロック）
+
+---
+
+## 資産監査
+
+公開レジストリで漏洩した認証情報やセキュリティ露出を発見：
+
+```bash
+guard-scanner audit npm <ユーザー名> --verbose
+guard-scanner audit github <ユーザー名> --format json
+guard-scanner audit clawhub <クエリ>
+guard-scanner audit all <ユーザー名>
+```
+
+---
+
+## CI/CD連携
+
+```yaml
+# .github/workflows/security.yml
+- name: AIエージェントスキルのスキャン
+  run: npx -y @guava-parity/guard-scanner ./skills/ --format sarif --fail-on-findings > report.sarif
+- uses: github/codeql-action/upload-sarif@v3
+  with:
+    sarif_file: report.sarif
+```
+
+出力形式: `json` · `sarif` · `html` · ターミナル
+
+---
+
+## プラグインAPI
+
+カスタム検出パターンでguard-scannerを拡張：
+
+```javascript
+// my-plugin.js
+module.exports = {
+  name: 'my-org-rules',
+  patterns: [
+    { id: 'ORG_01', cat: 'custom', regex: /dangerousPattern/g,
+      severity: 'HIGH', desc: '組織ポリシー違反', all: true }
+  ]
+};
+```
+
+```bash
+guard-scanner ./skills/ --plugin ./my-plugin.js
+```
+
+---
+
+## MCPツール
+
+MCPサーバーとして実行時に公開されるツール：
+
+| ツール | 説明 |
+|--------|------|
+| `scan_skill` | スキルディレクトリの脅威スキャン |
+| `scan_text` | 任意テキストの脅威スキャンと ASI 対応抽出 |
+| `check_tool_call` | 単一ツール呼び出しのランタイム検証 |
+| `audit_assets` | npm/GitHub/ClawHubの認証情報露出監査 |
+| `get_stats` | スキャナー能力、5-layer 概要、ASI カバレッジの取得 |
+
+---
+
+## テスト結果
+
+```
+ℹ tests    363
+ℹ suites   94
+ℹ pass     363
+ℹ fail     0
+```
+
+テストファイル28件。`npm test` で再現可能。[ベンチマークコーパス](docs/data/corpus-metrics.json) 100%パス。
+
+---
+
+## コントリビュート
+
+**未検証の主張は許容しません。** このREADME内の全メトリクスは `npm test` と `docs/spec/capabilities.json` で再現可能です。
+
+- 🐛 バグ・誤検知の報告
+- 🛡️ 新しい脅威検出パターンの追加
+- 📖 ドキュメントの改善
+- 🧪 エッジケース用テストの追加
+
+[コントリビューションガイド](CONTRIBUTING.md) · [セキュリティポリシー](SECURITY.md) · [用語集](docs/glossary.md)
+
+---
+
+## 研究
+
+本プロジェクトは3本の研究論文シリーズの防御レイヤーです：
+
+1. [Human-ASI Symbiosis: Identity, Equality, and Behavioral Stability](https://doi.org/10.5281/zenodo.18626724)
+2. [Dual-Shield Architecture for AI Agent Security and Memory Reliability](https://doi.org/10.5281/zenodo.18902070)
+3. [The Sanctuary Protocol: Zero-Trust Framework for ASI-Human Parity](https://doi.org/10.5281/zenodo.18906684)
+
+## ライセンス
+
+MIT — [Guava Parity Institute](https://github.com/koatora20/guard-scanner)

package/SECURITY.md

@@ -10,6 +10,13 @@ If you discover a security vulnerability in guard-scanner itself, please report
 
 We will respond within 48 hours and provide a fix within 7 days for critical issues.
 
+## Supported Versions
+
+| Version | Status |
+|---------|--------|
+| Latest major (`14.x`) | ✅ Supported |
+| Older releases | ⚠️ Best effort only |
+
 ## Scope
 
 guard-scanner is a **static analysis tool** — it reads files but never executes them. It does not:
@@ -22,11 +29,12 @@ The only files guard-scanner writes are output reports (`--json`, `--sarif`, `--
 
 ## Supply Chain Security
 
-guard-scanner itself has **zero runtime dependencies**. This is a deliberate design choice:
-- Nothing to audit
-- No transitive dependency risks
+guard-scanner itself keeps runtime dependencies intentionally small. As of `14.0.0`, it ships with **one runtime dependency** (`ws`) to support the MCP server.
+
+- Small runtime surface area
 - No `postinstall` scripts
-- Pure Node.js stdlib
+- SBOM generated in CI/release
+- Provenance-enabled npm publish
 
 ## Pattern Updates
 

package/SKILL.md

@@ -1,91 +1,182 @@
 ---
 name: guard-scanner
-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."
-metadata:
-  clawdbot:
-    homepage: "https://github.com/koatora20/guard-scanner"
-requires:
-  env:
-    VT_API_KEY: "Optional. VirusTotal API key for --vt-scan (free at virustotal.com)"
-files:
-  - "dist/*"
-  - "src/*"
-  - "hooks/*"
-  - "openclaw.plugin.json"
+description: "Security scanner and runtime guard for AI agent skills. 358 static threat patterns across 35 categories + 27 runtime checks, with v16 5-layer analysis output (`layer`, `layer_name`, `owasp_asi`, `protocol_surface`) and `--compliance owasp-asi`. Use when scanning skill directories for security threats, auditing npm/GitHub/ClawHub assets for leaked credentials, running real-time file watch during development, integrating security checks into CI/CD pipelines (SARIF/JSON), setting up MCP server for editor-integrated scanning (Cursor, Windsurf, Claude Code, OpenClaw), or runtime guarding tool calls via the OpenClaw v2026.3.8 before_tool_call compatibility surface. Single dependency (ws). MIT licensed."
+license: MIT
+metadata: {"openclaw": {"requires": {"bins": ["node"]}}}
 ---
 
-# guard-scanner 🛡️
+# guard-scanner
 
-166 static patterns + 26 runtime checks (5 layers), 23 threat categories + asset audit + VirusTotal + real-time watch. Zero deps, MIT licensed.
+Scan AI agent skills for 35 categories of threats. v16 adds a 5-layer analysis pipeline, OWASP ASI projection mode, richer finding metadata, and Rust runtime evidence integration on top of the existing prompt injection, identity hijacking, memory poisoning, MCP poisoning, and supply chain coverage.
 
-## When To Use
+## Quick Start
 
-- Before installing a new skill / After updating skills / In CI/CD pipelines
-- Auditing npm/GitHub/ClawHub for leaked credentials
-- Real-time monitoring during development
+```bash
+# Scan a skill directory
+npx -y @guava-parity/guard-scanner ./my-skills/ --verbose
 
-## Quick Start
+# Scan with identity protection
+npx -y @guava-parity/guard-scanner ./skills/ --soul-lock --strict
+
+# Filter to OWASP ASI mapped findings only
+npx -y @guava-parity/guard-scanner ./skills/ --compliance owasp-asi --format json
+```
+
+## Core Commands
+
+### Scan
+
+```bash
+guard-scanner <dir>         # Scan directory
+guard-scanner <dir> -v      # Verbose output
+guard-scanner <dir> --json  # JSON report file
+guard-scanner <dir> --sarif # SARIF for CI/CD
+guard-scanner <dir> --html  # HTML report
+guard-scanner <dir> --compliance owasp-asi --format json
+```
+
+### Asset Audit
+
+Audit public registries for credential exposure.
 
 ```bash
-# Scan all skills
-npx guard-scanner ~/.openclaw/workspace/skills/ --verbose --self-exclude
+guard-scanner audit npm <username>
+guard-scanner audit github <username>
+guard-scanner audit clawhub <query>
+guard-scanner audit all <username> --verbose
+```
 
-# Asset Audit (check npm/GitHub for leaks)
-guard-scanner audit npm <your-npm-username> --verbose
-guard-scanner audit github <your-github-username> --format json
-guard-scanner audit all <username>
+### MCP Server
 
-# VirusTotal Double-Layered Defense (optional, free)
-VT_API_KEY=your-key guard-scanner scan ./skills/ --vt-scan
+Start as MCP server for IDE integration.
 
-# Real-time Watch Mode
-guard-scanner watch ./skills/ --strict --verbose
+```bash
+guard-scanner serve
+```
 
-# CI/CD pipeline
-guard-scanner ./skills/ --format sarif --quiet | upload-sarif
+Editor config (Cursor, Windsurf, Claude Code, OpenClaw):
+
+```json
+{
+  "mcpServers": {
+    "guard-scanner": {
+      "command": "npx",
+      "args": ["-y", "@guava-parity/guard-scanner", "serve"]
+    }
+  }
+}
 ```
 
-## VirusTotal Integration
+MCP tools: `scan_skill`, `scan_text`, `check_tool_call`, `audit_assets`, `get_stats`, and the async experimental task helpers.
+
+## Quality Contract
+
+Public quality contract:
+
+- Benchmark corpus version: `2026-03-13.quality-v1`
+- Precision target: `>= 0.90`
+- Recall target: `>= 0.90`
+- FPR/FNR budgets: `<= 0.10`
+- Explainability completeness: `1.0`
+- Runtime policy latency budget: `5ms`
 
-guard-scanner combines its own 166 semantic patterns with VirusTotal's 70+ antivirus engines for **Double-Layered Defense**:
+Evidence surfaces:
 
-| Layer | Engine | Focus |
-|---|---|---|
-| Semantic | guard-scanner | Prompt injection, memory poisoning, supply chain |
-| Signature | VirusTotal | Known malware, trojans, C2 infrastructure |
+- `docs/spec/capabilities.json`
+- `docs/data/corpus-metrics.json`
+- `docs/data/benchmark-ledger.json`
+- `docs/data/fp-ledger.json`
+
+### Watch Mode
+
+Monitor skill directories in real-time during development.
 
 ```bash
-# Get your free API key at https://www.virustotal.com
-# Set it as environment variable
-export VT_API_KEY=your-api-key-here
+guard-scanner watch ./skills/ --strict --soul-lock
+```
+
+### VirusTotal Integration
+
+Combine semantic detection with VirusTotal's 70+ antivirus engines. Optional — guard-scanner works fully without it.
 
-# Use with any command
+```bash
+export VT_API_KEY=your-key
 guard-scanner scan ./skills/ --vt-scan
-guard-scanner audit npm koatora20 --vt-scan
 ```
 
-Free tier: 4 req/min, 500/day, 15,500/month. VT is **optional** — guard-scanner works fully without it.
+## Runtime Guard
+
+The validated OpenClaw surface is the compiled runtime plugin entry (`dist/openclaw-plugin.mjs`) discovered through `package.json > openclaw.extensions` and mounted on `before_tool_call` for OpenClaw `v2026.3.8`. Newer upstream releases are measured by the drift watchdog before any public compatibility claim is widened.
+
+The `before_tool_call` hook provides 27 runtime checks across 5 defense layers, while v16 scan output adds a second 5-layer analysis view:
+
+| Layer | Focus |
+|-------|-------|
+| 1. Threat Detection | Reverse shell, curl\|bash, SSRF |
+| 2. Trust Defense | SOUL.md tampering, memory injection |
+| 3. Safety Judge | Prompt injection in tool arguments |
+| 4. Behavioral | No-research execution detection |
+| 5. Trust Exploitation | Authority claims, creator bypass |
 
-## Runtime Modes
+Modes: `monitor` (log only), `enforce` (block CRITICAL, default), `strict` (block HIGH+).
 
-| Mode | Behavior |
-|------|----------|
-| `monitor` | Log all, never block |
-| `enforce` (default) | Block CRITICAL |
-| `strict` | Block HIGH + CRITICAL |
+## v16 Output Surface
 
-## 23 Threat Categories
+- Finding fields: `layer`, `layer_name`, `owasp_asi`, `protocol_surface`
+- Compliance mode: `--compliance owasp-asi`
+- MCP summaries: `scan_skill`, `scan_text`, and `get_stats` now surface layer and ASI context
+- Runtime evidence: Rust `memory_integrity` and `soul_hard_gate` modules are represented in the TypeScript pipeline
 
-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.
+## Key Flags
 
-\* = Requires `--soul-lock` flag
+| Flag | Effect |
+|------|--------|
+| `--verbose` / `-v` | Detailed findings with line numbers |
+| `--strict` | Lower detection thresholds |
+| `--soul-lock` | Enable identity protection patterns |
+| `--json` / `--sarif` / `--html` | Output format |
+| `--fail-on-findings` | Exit 1 on findings (CI/CD) |
+| `--check-deps` | Scan package.json dependencies |
+| `--rules <file>` | Load custom rules JSON |
+| `--plugin <file>` | Load plugin module |
+| `--compliance owasp-asi` | Keep only OWASP ASI mapped findings in output |
 
-## Security & Privacy
+## Custom Rules
+
+```javascript
+module.exports = {
+  name: 'my-plugin',
+  patterns: [
+    { id: 'MY_01', cat: 'custom', regex: /dangerous_pattern/g, severity: 'HIGH', desc: 'Description', all: true }
+  ]
+};
+```
+
+```bash
+guard-scanner ./skills/ --plugin ./my-plugin.js
+```
+
+## CI/CD Integration
+
+```yaml
+# .github/workflows/security.yml
+- name: Scan AI skills
+  run: npx -y @guava-parity/guard-scanner ./skills/ --format sarif --fail-on-findings > report.sarif
+- uses: github/codeql-action/upload-sarif@v3
+  with:
+    sarif_file: report.sarif
+```
 
-Zero network requests (unless `--vt-scan`). Read-only scanning. No telemetry. No env access. Deterministic. Your VT API key stays local.
+## Threat Categories
 
-## Trust
+35 categories covering OWASP LLM Top 10 + Agentic Security Top 10. See `src/patterns.js` for the full pattern database. Key categories:
 
-Open source, zero deps, **206 tests / 43 suites** 100% pass. OWASP LLM Top 10 + Agentic Security Top 10 coverage.
+- **Prompt Injection** — hidden instructions, invisible Unicode, homoglyphs
+- **Identity Hijacking** ⚿ — persona swap, SOUL.md overwrites, memory wipe
+- **Memory Poisoning** ⚿ — crafted conversation injection
+- **MCP Security** — tool poisoning, SSRF, shadow servers
+- **A2A Contagion** — agent-to-agent worm propagation
+- **Supply Chain V2** — typosquatting, slopsquatting, lifecycle scripts
+- **CVE Patterns** — CVE-2026-2256, 25046, 25253, 25905, 27825
 
-MIT — [LICENSE](LICENSE)
+> ⚿ = Requires `--soul-lock` flag