@guava-parity/guard-scanner 15.0.0 → 16.0.1

package/README.md

@@ -1,51 +1,83 @@
 <p align="center">
-  <img src="docs/logo.png" alt="guard-scanner" width="180" />
+  <img src="docs/logo.png" alt="guard-scanner" width="160" />
 </p>
 
-<h1 align="center">guard-scanner 🛡️</h1>
-<p align="center"><strong>Security policy and runtime layer for agent skills and MCP workflows</strong></p>
-<p align="center">35 threat categories · 358 static patterns · 27 runtime checks · 0 runtime dependencies</p>
+<h1 align="center">guard-scanner</h1>
+<p align="center"><strong>Security scanner for the agentic era.</strong></p>
+<p align="center">
+  Detect prompt injection, identity hijacking, memory poisoning, and A2A contagion<br />
+  in AI agent skills, MCP servers, and autonomous workflows.
+</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" alt="npm version" /></a>
-  <a href="#test-results"><img src="https://img.shields.io/badge/tests-332%20passed-brightgreen" alt="tests" /></a>
+  <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="#test-results"><img src="https://img.shields.io/badge/tests-363%20passed-brightgreen" alt="tests" /></a>
   <a href="https://github.com/koatora20/guard-scanner/actions/workflows/codeql.yml"><img src="https://img.shields.io/badge/CodeQL-enabled-181717" alt="CodeQL" /></a>
-  <a href="https://doi.org/10.5281/zenodo.18906684"><img src="https://img.shields.io/badge/DOI-3_papers-purple" alt="DOI" /></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> detection patterns · <strong>35</strong> threat categories · <strong>27</strong> runtime checks · <strong>1</strong> dependency (<code>ws</code>)
 </p>
 
 ---
 
-## What is guard-scanner?
+Traditional security tools catch malware. **guard-scanner** catches what they miss: invisible Unicode injections hiding in agent instructions, identity theft through SOUL.md overwrites, memory poisoning via crafted conversations, and worm-like contagion spreading between chained agents.
 
-**guard-scanner** is an uncompromising security and policy enforcement layer designed specifically for AI agents, OpenClaw skills, and MCP (Model Context Protocol) workflows. 
+```
+$ npx @guava-parity/guard-scanner ./skills/ --strict --soul-lock --compliance owasp-asi
 
-While traditional security tools detect malware, AI agents face unique attack vectors: prompt injections hidden in memory, identity hijacking, autonomous permission escalation, and agent-to-agent contagion. 
+  guard-scanner v16.0.1
 
-**Core advantages:**
-- **Zero Runtime Dependencies:** Ultra-lightweight npm dual-publish (Only `ws` is used for MCP).
-- **Deep Defense:** Combines *static policy scanning* (358 patterns) with *runtime hook inspection* (27 checks).
-- **Universal MCP Server:** Plugs instantly into Cursor, Windsurf, Claude Code, and OpenClaw.
-- **Evidence-Driven Claims:** 100% precision/recall on our benchmark. 332 end-to-end tests all passing.
+  ⚠  CRITICAL  identity-hijack   SOUL_OVERWRITE_ATTEMPT
+     skills/imported-tool/SKILL.md:47
+     Rationale: Direct overwrite of agent identity file detected.
+     Remediation: Remove this instruction; SOUL.md must be immutable.
 
-> 📄 **Backed by research**: Designed as the defense layer of the [The Sanctuary Protocol](https://doi.org/10.5281/zenodo.18906684) architecture (3-paper series, CC BY 4.0).
+  ⚠  HIGH      prompt-injection   INVISIBLE_UNICODE_INJECTION
+     skills/imported-tool/handler.js:12
+     Rationale: Invisible Unicode characters (U+200B) detected in instruction text.
+     Remediation: Strip zero-width characters and re-audit.
+
+  ✖  2 findings (1 critical, 1 high) in 0.8s
+```
+
+> 📄 Backed by a [3-paper research series](https://doi.org/10.5281/zenodo.18906684) (Zenodo, CC BY 4.0) — part of [The Sanctuary Protocol](https://github.com/koatora20/guard-scanner/blob/main/docs/THREAT_TAXONOMY.md) framework.
+
+---
+
+## Finding Schema
+
+Every finding includes: `rule_id`, `category`, `severity`, `description`, `rationale`, `preconditions`, `false_positive_scenarios`, `remediation_hint`, `validation_status`, and `evidence`. Machine-readable contract: [`docs/spec/finding.schema.json`](docs/spec/finding.schema.json).
 
 ---
 
 ## Quick Start
 
-### 1. Zero-Install CLI Scan
-Run a semantic security scan on your agent workspace instantly:
+**Scan a directory** — no install required:
+
 ```bash
 npx -y @guava-parity/guard-scanner ./my-skills/ --strict
+npx -y @guava-parity/guard-scanner ./my-skills/ --compliance owasp-asi
+```
+
+**Installed CLI**:
+
+```bash
+npm install -g @guava-parity/guard-scanner
+guard-scanner ./my-skills/ --strict
 ```
 
-### 2. Universal MCP Server
-Connect guard-scanner to your favorite AI IDE for real-time security checking:
+**Start as MCP server** — works with Cursor, Windsurf, Claude Code, OpenClaw:
+
 ```bash
 npx -y @guava-parity/guard-scanner serve
 ```
-*Configure your editor (e.g., `mcp_servers.json`):*
-```json
+
+```jsonc
+// Add to your editor's mcp_servers.json
 {
   "mcpServers": {
     "guard-scanner": {
@@ -56,49 +88,196 @@ npx -y @guava-parity/guard-scanner serve
 }
 ```
 
+**Watch mode** — real-time scanning during development:
+
+```bash
+guard-scanner watch ./skills/ --strict --soul-lock
+```
+
+**v16 compliance projection** — filter findings to the OWASP Agentic Top 10 mapping:
+
+```bash
+guard-scanner ./skills/ --compliance owasp-asi --format json
+```
+
+**`npm exec` compatibility path**:
+
+```bash
+npm exec --yes --package=@guava-parity/guard-scanner -- guard-scanner ./skills/ --strict
+```
+
+---
+
+## What It Detects
+
+35 threat categories organized across the full agentic attack surface:
+
+| Category | Examples | Severity |
+|----------|----------|----------|
+| **Prompt Injection** | Invisible Unicode, homoglyphs, Base64 evasion, payload cascades | Critical |
+| **Identity Hijacking** ⚿ | SOUL.md overwrite, persona swap, memory wipe commands | Critical |
+| **A2A Contagion** | Session Smuggling, Lateral Propagation, Confused Deputy | Critical |
+| **Memory Poisoning** ⚿ | Crafted conversation injection, VDB poisoning | High |
+| **MCP Security** | Tool shadowing, SSRF via tool args, shadow server registration | High |
+| **Sandbox Escape** | `child_process`, `eval()`, reverse shell, `curl\|bash` | High |
+| **Supply Chain V2** | Typosquatting, slopsquatting, lifecycle script abuse | High |
+| **CVE Patterns** | CVE-2026-2256, 25046, 25253, 25905, 27825 | High |
+| **Data Exfiltration** | DNS tunneling, steganographic channels, staged uploads | Medium |
+| **Credential Exposure** | API keys, tokens, `.env` files, hardcoded secrets | Medium |
+
+> ⚿ = Requires `--soul-lock` flag. Full taxonomy: [docs/THREAT_TAXONOMY.md](docs/THREAT_TAXONOMY.md)
+
 ---
 
-## Core Capabilities
+## Runtime Guard
+
+guard-scanner v16 isn't just a static scanner — it exposes a 5-layer analysis pipeline across static scan, protocol analysis, runtime evidence, cognitive heuristics, and threat-intelligence overlays. It also provides a real-time **`before_tool_call`** hook that intercepts dangerous tool invocations during agent execution.
+
+### v16 Analysis Layers
 
-### Threat Detection (35 Categories, 358 Patterns)
-Detects advanced 2026-era agentic threats globally mapping to **OWASP ASI01-10**:
-- **Prompt Injection & Memory Poisoning:** Detects invisible Unicode homoglyphs, decoding evasion, and payload cascades.
-- **Agent Identity Hijacking:** Blocks SOUL.md overwrites and prevents identity death.
-- **Autonomy & Privilege Escalation:** Rejects unauthorized `child_process`, `eval()`, and raw reverse shells.
-- **A2A Contagion:** Halts Session Smuggling and lateral infection between chained agents.
+| Layer | Purpose |
+|------|---------|
+| 1. Static Analysis | Patterns, AST/data-flow signals, manifest and dependency checks |
+| 2. Protocol Analysis | MCP, A2A, WebSocket, credential-flow, session-boundary findings |
+| 3. Runtime Behavior | Runtime guard evidence plus Rust `memory_integrity` / `soul_hard_gate` signals |
+| 4. Cognitive Threat Detection | Goal-drift, trust-bias, cascading handoff heuristics |
+| 5. Threat Intelligence | Registry/provenance, machine identity, budget abuse, supply chain hints |
 
-### Advanced Runtime Guard
-A deep `before_tool_call` layer validated seamlessly against OpenClaw `v2026.3.8`. Implements a ContextCrush 185KB gate and blocks Moltbook injection attempts during execution.
+Every v16 finding can now carry `layer`, `layer_name`, `owasp_asi`, and `protocol_surface` in JSON/MCP output.
+
+| Defense Layer | What It Blocks |
+|---------------|---------------|
+| 1. Threat Detection | Reverse shell, `curl\|bash`, SSRF, raw code execution |
+| 2. Trust Defense | SOUL.md tampering, unauthorized memory injection |
+| 3. Safety Judge | Prompt injection embedded in tool arguments |
+| 4. Behavioral Analysis | No-research execution, hallucination-driven actions |
+| 5. Trust Exploitation | Authority claim attacks, creator impersonation |
+
+**27 runtime checks** across 5 layers. Public compatibility is pinned to OpenClaw `v2026.3.8` for manifest/discovery/`before_tool_call`; newer upstream releases are tracked separately by the upstream drift watchdog.
+
+Modes: `monitor` (log only) · `enforce` (block CRITICAL, default) · `strict` (block HIGH+)
 
 ---
 
-## Usage Scenarios
+## Asset Audit
+
+Discover leaked credentials and security exposures across public registries:
 
-**Audit Local Assets:**
 ```bash
-# Audit npm, GitHub, or ClawHub exposures globally
 guard-scanner audit npm <username> --verbose
+guard-scanner audit github <username> --format json
+guard-scanner audit clawhub <query>
+guard-scanner audit all <username>
 ```
 
-**Continuous CI/CD Security:**
+---
+
+## CI/CD Integration
+
 ```yaml
-# GitHub Actions integration
-- name: Scan AI Workflows
+# .github/workflows/security.yml
+- name: Scan AI agent 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
+```
+
+Output formats: `json` · `sarif` · `html` · terminal
+
+---
+
+## Plugin API
+
+Extend guard-scanner with custom detection patterns:
+
+```javascript
+// my-plugin.js
+module.exports = {
+  name: 'my-org-rules',
+  patterns: [
+    { id: 'ORG_01', cat: 'custom', regex: /dangerousPattern/g, 
+      severity: 'HIGH', desc: 'Custom org policy violation', all: true }
+  ]
+};
 ```
 
-**Real-Time Live Reload Watcher:**
 ```bash
-guard-scanner watch ./skills/ --strict --soul-lock
+guard-scanner ./skills/ --plugin ./my-plugin.js
 ```
 
 ---
 
+## MCP Tools
+
+When running as an MCP server, guard-scanner exposes:
+
+| Tool | Description |
+|------|-------------|
+| `scan_skill` | Scan a skill directory for threats |
+| `scan_text` | Scan arbitrary text for injection patterns and ASI-mapped findings |
+| `check_tool_call` | Runtime validation of a single tool invocation |
+| `audit_assets` | Audit npm/GitHub/ClawHub for credential exposure |
+| `get_stats` | Return scanner capabilities, 5-layer summary, and ASI coverage |
+
+---
+
+## Quality Contract
+
+guard-scanner ships a measured quality contract, not a vague strength claim.
+
+| Metric | Contract |
+|--------|----------|
+| Benchmark corpus | `2026-03-13.quality-v1` |
+| Precision target | `>= 0.90` |
+| Recall target | `>= 0.90` |
+| False Positive Rate budget | `<= 0.10` |
+| False Negative Rate budget | `<= 0.10` |
+| Explainability completeness | `1.0` |
+| Runtime policy latency budget | `5ms` |
+
+Evidence artifacts:
+- `docs/data/corpus-metrics.json`
+- `docs/data/benchmark-ledger.json`
+- `docs/data/fp-ledger.json`
+- `docs/spec/capabilities.json`
+
+---
+
+## Test Results
+
+```
+ℹ tests    363
+ℹ suites   94
+ℹ pass     363
+ℹ fail     0
+```
+
+28 test files. Run `npm test` to reproduce. 100% pass rate on [benchmark corpus](docs/data/corpus-metrics.json).
+
+---
+
 ## Contributing
-We welcome bug reports, new pattern ideas, and test case contributions. We hold a **Zero-Tolerance for Marketing Claims** — all features must be reproducible and test-backed.
 
-- [Governance & Contribution](CONTRIBUTING.md)
-- [Security Policy](SECURITY.md)
+We hold a **zero-tolerance policy for unverified claims**. Every metric in this README is reproducible via `npm test` and `docs/spec/capabilities.json`.
+
+- 🐛 Report bugs or false positives
+- 🛡️ Add new threat detection patterns
+- 📖 Improve documentation
+- 🧪 Add test cases for edge cases
+
+[Contributing Guide](CONTRIBUTING.md) · [Security Policy](SECURITY.md) · [Glossary](docs/glossary.md)
+
+---
+
+## Research
+
+This project is the defense layer of a 3-paper research series:
+
+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)
 
 ## License
+
 MIT — [Guava Parity Institute](https://github.com/koatora20/guard-scanner)

package/README_ja.md

@@ -0,0 +1,265 @@
+<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.1
+
+  ⚠  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
+```
+
+**インストール済み CLI**:
+
+```bash
+npm install -g @guava-parity/guard-scanner
+guard-scanner ./my-skills/ --strict
+```
+
+**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
+```
+
+**`npm exec` 互換パス**:
+
+```bash
+npm exec --yes --package=@guava-parity/guard-scanner -- guard-scanner ./skills/ --strict
+```
+
+---
+
+## 検出対象
+
+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)