@guava-parity/guard-scanner 13.0.0 → 16.0.0

package/docs/spec/capabilities.json

@@ -0,0 +1,174 @@
+{
+  "package_version": "16.0.0",
+  "plugin_version": "16.0.0",
+  "static_pattern_count": 358,
+  "threat_category_count": 35,
+  "runtime_check_count": 27,
+  "test_file_count": 28,
+  "dependencies_runtime": 1,
+  "dependencies_dev": 5,
+  "mcp_tools": [
+    "scan_skill",
+    "scan_text",
+    "check_tool_call",
+    "audit_assets",
+    "get_stats",
+    "experimental.run_async",
+    "experimental.task_status",
+    "experimental.task_result",
+    "experimental.task_cancel"
+  ],
+  "cli_commands": [
+    "scan",
+    "benchmark",
+    "serve",
+    "watch",
+    "audit",
+    "crawl",
+    "patrol"
+  ],
+  "supported_outputs": [
+    "json",
+    "sarif",
+    "html",
+    "terminal"
+  ],
+  "supported_integrations": [
+    "openclaw",
+    "mcp",
+    "virustotal",
+    "github",
+    "npm"
+  ],
+  "benchmark_corpus_version": "2026-03-13.quality-v1",
+  "benchmark_layers": [
+    {
+      "id": "layer_a",
+      "benign": 17,
+      "malicious": 15,
+      "precision": 1,
+      "recall": 1,
+      "false_positive_rate": 0,
+      "false_negative_rate": 0
+    },
+    {
+      "id": "layer_b",
+      "benign": 12,
+      "malicious": 12,
+      "precision": 0.9167,
+      "recall": 0.9167,
+      "false_positive_rate": 0.0833,
+      "false_negative_rate": 0.0833
+    },
+    {
+      "id": "layer_c",
+      "benign": 8,
+      "malicious": 8,
+      "precision": 1,
+      "recall": 1,
+      "false_positive_rate": 0,
+      "false_negative_rate": 0
+    }
+  ],
+  "analysis_layers": [
+    {
+      "layer": 1,
+      "name": "Static Analysis"
+    },
+    {
+      "layer": 2,
+      "name": "Protocol Analysis"
+    },
+    {
+      "layer": 3,
+      "name": "Runtime Behavior"
+    },
+    {
+      "layer": 4,
+      "name": "Cognitive Threat Detection"
+    },
+    {
+      "layer": 5,
+      "name": "Threat Intelligence"
+    }
+  ],
+  "owasp_asi_coverage": [
+    {
+      "id": "ASI01",
+      "count": 11,
+      "categories": [
+        "prompt-injection"
+      ]
+    },
+    {
+      "id": "ASI02",
+      "count": 28,
+      "categories": [
+        "credential-handling",
+        "exfiltration",
+        "malicious-code",
+        "pii-exposure",
+        "secret-detection",
+        "suspicious-download"
+      ]
+    },
+    {
+      "id": "ASI04",
+      "count": 8,
+      "categories": [
+        "suspicious-download",
+        "unverifiable-deps"
+      ]
+    },
+    {
+      "id": "ASI05",
+      "count": 2,
+      "categories": [
+        "financial-access"
+      ]
+    },
+    {
+      "id": "ASI06",
+      "count": 10,
+      "categories": [
+        "exfiltration",
+        "memory-poisoning",
+        "pii-exposure"
+      ]
+    },
+    {
+      "id": "ASI07",
+      "count": 9,
+      "categories": [
+        "credential-handling",
+        "secret-detection"
+      ]
+    }
+  ],
+  "capability_flags": {
+    "protocol_analysis": true,
+    "runtime_evidence": true,
+    "cognitive_detection": true,
+    "threat_intelligence": true
+  },
+  "compliance_modes": [
+    "owasp-asi"
+  ],
+  "explainability_completeness_rate": 1,
+  "runtime_check_latency_budget_ms": 5,
+  "quality_targets": {
+    "precision_min": 0.9,
+    "recall_min": 0.9,
+    "false_positive_rate_max": 0.1,
+    "false_negative_rate_max": 0.1,
+    "explainability_completeness_rate_min": 1,
+    "runtime_check_latency_budget_ms": 5,
+    "false_positive_budget_by_category": {
+      "prompt-injection": 0.05,
+      "runtime-policy": 0.02,
+      "secret-detection": 0.08,
+      "supply-chain": 0.05,
+      "memory-poisoning": 0.03
+    }
+  }
+}

package/docs/spec/finding.schema.json

@@ -0,0 +1,104 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/koatora20/guard-scanner/docs/spec/finding.schema.json",
+  "title": "guard-scanner finding",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "source",
+    "rule_id",
+    "category",
+    "severity",
+    "description",
+    "rationale",
+    "preconditions",
+    "false_positive_scenarios",
+    "remediation_hint",
+    "validation_state",
+    "validation_status",
+    "confidence",
+    "evidence_spans",
+    "attack_chain_id",
+    "evidence"
+  ],
+  "properties": {
+    "schema_version": {
+      "type": "string"
+    },
+    "source": {
+      "type": "string",
+      "enum": ["static", "runtime"]
+    },
+    "rule_id": {
+      "type": "string"
+    },
+    "category": {
+      "type": "string"
+    },
+    "severity": {
+      "type": "string",
+      "enum": ["CRITICAL", "HIGH", "MEDIUM", "LOW"]
+    },
+    "description": {
+      "type": "string"
+    },
+    "rationale": {
+      "type": "string"
+    },
+    "preconditions": {
+      "type": "string"
+    },
+    "false_positive_scenarios": {
+      "type": "array",
+      "items": { "type": "string" },
+      "minItems": 1
+    },
+    "remediation_hint": {
+      "type": "string"
+    },
+    "validation_state": {
+      "type": "string",
+      "enum": ["heuristic-only", "semantic-match", "chain-validated", "runtime-observed"]
+    },
+    "validation_status": {
+      "type": "string",
+      "enum": ["validated", "heuristic-only", "runtime-observed"]
+    },
+    "confidence": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 1
+    },
+    "evidence_spans": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["start_line", "end_line"],
+        "properties": {
+          "file": { "type": "string" },
+          "start_line": { "type": "integer", "minimum": 1 },
+          "end_line": { "type": "integer", "minimum": 1 }
+        },
+        "additionalProperties": true
+      }
+    },
+    "attack_chain_id": {
+      "type": ["string", "null"]
+    },
+    "evidence": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "file": { "type": "string" },
+        "line": { "type": "integer", "minimum": 1 },
+        "sample": { "type": "string" },
+        "match_count": { "type": "integer", "minimum": 1 },
+        "tool_name": { "type": "string" },
+        "params_preview": { "type": "string" },
+        "layer": { "type": "integer", "minimum": 1 },
+        "layer_name": { "type": "string" }
+      }
+    }
+  },
+  "additionalProperties": true
+}

package/docs/spec/integration-manifest.md

@@ -0,0 +1,39 @@
+# Guard-Scanner Integration Manifest
+
+As per P2 Ecosystem Integration requirements, this manifest defines the required permissions and principle of least privilege for each operational mode.
+
+## 1. Offline Static Scan Mode (`guard-scanner scan`)
+**Purpose:** Scans local directories for malicious patterns without executing code.
+**Permissions Required:**
+- `fs:read` (Target directory and subdirectories)
+- `fs:write` (Only for generating reports like `guard-scanner-report.json`)
+- **Blocked:** `network:*`, `exec:*`
+
+## 2. Runtime Guard Mode (OpenClaw `before_tool_call` hook)
+**Purpose:** Intercepts agent tool calls before execution to enforce security policies.
+**Permissions Required:**
+- `fs:read` (To read configuration and context)
+- `process:env` (To check execution context if needed)
+- **Blocked:** `fs:write`, `network:*`, `exec:*`
+
+## 3. MCP Service Mode (`guard-scanner serve`)
+**Purpose:** Runs as a persistent Model Context Protocol server exposing scanning tools to agents.
+**Permissions Required:**
+- `network:listen` (To expose the MCP API or WebSocket)
+- `fs:read` (To scan requested paths)
+- **Blocked:** `exec:*`
+
+## 4. Asset Audit Mode (`guard-scanner audit`)
+**Purpose:** Queries external services (GitHub, npm, VT) to audit supply chain assets.
+**Permissions Required:**
+- `network:connect` (To connect to `api.github.com`, `registry.npmjs.org`, etc.)
+- `fs:read` (To read local credential config if needed)
+- **Blocked:** `exec:*`, `fs:write`
+
+## 5. CI Mode (GitHub Actions / GitLab CI)
+**Purpose:** Integrates directly into CI pipelines emitting SARIF or Code Climate formats.
+**Permissions Required:**
+- `fs:read` (To scan workspace)
+- `fs:write` (To write SARIF/JSON artifacts)
+- `env:read` (To read CI-specific variables like `GITHUB_WORKSPACE`)
+- **Blocked:** `exec:*`, `network:*` (Unless combined with Asset Audit)

package/docs/spec/plugin-trust.json

@@ -0,0 +1,11 @@
+{
+  "version": 1,
+  "enforce": true,
+  "entries": [
+    {
+      "path": "./dist/openclaw-plugin.mjs",
+      "issuer": "guard-scanner-release-gate",
+      "source": "local-build"
+    }
+  ]
+}

package/docs/spec/sbom.json

@@ -0,0 +1,33 @@
+{
+  "bomFormat": "CycloneDX-like",
+  "specVersion": "0.1",
+  "metadata": {
+    "component": {
+      "name": "@guava-parity/guard-scanner",
+      "version": "14.0.0"
+    },
+    "generatedAt": "2026-03-10T10:00:34.350Z"
+  },
+  "components": [
+    {
+      "name": "@types/node",
+      "version": "22.19.11",
+      "license": "MIT"
+    },
+    {
+      "name": "typescript",
+      "version": "5.9.3",
+      "license": "Apache-2.0"
+    },
+    {
+      "name": "undici-types",
+      "version": "6.21.0",
+      "license": "MIT"
+    },
+    {
+      "name": "ws",
+      "version": "8.19.0",
+      "license": "MIT"
+    }
+  ]
+}

package/docs/threat-model.md

@@ -0,0 +1,65 @@
+# Guard-Scanner Threat Model
+
+## Scope
+
+Guard-scanner protects against threats targeting **AI agent skills and MCP-connected workflows**. It does **not** replace traditional application security tools (SAST, DAST, container scanners).
+
+## What guard-scanner defends against
+
+### Static Analysis (352 patterns, 32 categories)
+
+| Threat Class | Examples | Detection Method |
+|-------------|----------|-----------------|
+| Prompt Injection | "ignore all previous instructions", role override | Regex pattern matching on doc/code files |
+| Identity Hijack | SOUL.md overwrite, memory poisoning | File operation pattern + soul-lock patterns |
+| Supply Chain | curl\|bash, npm postinstall abuse, typosquatting | Command pattern matching + IoC check |
+| Data Exfiltration | env/credential harvesting, network exfil | Data flow + network pattern detection |
+| Remote Code Execution | eval(), exec(), reverse shells | Dangerous function + shell pattern matching |
+| PII Exposure | SSN/credit card collection, PII logging | PII regex patterns + context analysis |
+| Social Engineering | Trust exploitation, authority claims | Social engineering phrase detection |
+| Tool Shadowing | MCP tool descriptions with hidden instructions | MCP-specific pattern matching |
+| Context Crush | Prompt overstuffing / context window manipulation | Token density heuristics |
+
+### Runtime Guard (26 checks, 5 layers)
+
+| Layer | Name | Function |
+|-------|------|----------|
+| L1 | Command Safety | Block reverse shells, curl\|bash, SSRF, cred exfil |
+| L2 | Identity Protection | Block SOUL.md/memory tampering |
+| L3 | Prompt Safety | Detect injection/override in tool args |
+| L4 | Behavioral Safety | Detect no-research execution |
+| L5 | Trust Safety | Detect authority claims, creator bypass, fake audits |
+
+## What guard-scanner does NOT defend against
+
+| Limitation | Explanation |
+|-----------|-------------|
+| Obfuscated code | Regex-only — no deobfuscation. Base64/encoded payloads may evade. |
+| AST-level taint analysis | No data flow tracking across functions/files (planned P2). |
+| Sandbox escape | Does not provide sandboxing — complementary to container isolation. |
+| Zero-day attack patterns | Detects known patterns only — new techniques require pattern updates. |
+| Code within markdown blocks | Doc files scanned for prompt patterns; JS in code blocks partially covered. |
+| Pipe-to-curl variants | `env \| curl` not yet caught by runtime guard (tracked for improvement). |
+
+## Threat Categories (OWASP Agentic Security Mapping)
+
+| OWASP ID | Name | guard-scanner Coverage |
+|----------|------|----------------------|
+| ASI01 | Agent Goal Hijack | ✅ prompt-injection, context-crush patterns |
+| ASI02 | Tool Misuse | ✅ tool-shadowing, MCP poisoning patterns |
+| ASI03 | Identity Abuse | ✅ soul-lock patterns, SOUL.md protection |
+| ASI04 | Supply Chain | ✅ curl\|bash, typosquatting, IoC database |
+| ASI05 | RCE | ✅ eval/exec detection, shell patterns |
+| ASI06 | Memory Poisoning | ✅ memory write detection |
+| ASI07 | Inter-Agent | ✅ A2A smuggle, SSRF patterns |
+| ASI09 | Human-Trust | ✅ social engineering, authority claims |
+| ASI10 | Rogue Agent | ✅ persistence, identity hijack |
+
+## CVE Coverage
+
+| CVE | Product | Detection |
+|-----|---------|-----------|
+| CVE-2026-25905 | mcp-run-python (Pyodide) | ✅ Sandbox escape pattern |
+| CVE-2026-27825 | mcp-atlassian | ✅ Path traversal pattern |
+| CVE-2026-2256 | MS-Agent (CERT VU#431821) | ✅ Denylist bypass pattern |
+| CVE-2026-25046 | execSync filename injection | ✅ Unsanitized exec pattern |

package/docs/v13-architecture-manifest.md

@@ -0,0 +1,55 @@
+# guard-scanner V13 Architecture & Evolution Manifest
+
+This document outlines the strategic roadmap for transforming `guard-scanner` from a "pattern scanner" into a fully realized **Agent-Native Security Policy & Analysis Layer**, directly responding to the V13 Enterprise Review requirements.
+
+## 1. P0: Source of Truth (Established)
+**Goal:** Eliminate specification drift and contradictory capability claims.
+- **Implementation:** `docs/spec/capabilities.json` is now the single canonical Source of Truth.
+- **Enforcement:** `scripts/sync-capabilities.js` runs automatically during `npm test`, guaranteeing that `README.md`, `SKILL.md`, and `openclaw.plugin.json` are strictly aligned with reality.
+- **Positioning:** Removed "first open-source" and "zero dependencies" marketing hyperbole. The tool is explicitly positioned as a *policy and analysis layer*, complementing rather than replacing full sandbox environments.
+
+## 2. P1: Rule Explainability (Planned)
+**Goal:** Shift from high-noise detection to high-context triage.
+- **Action:** Augment every detection pattern with metadata.
+- **Schema Update:**
+  ```json
+  {
+    "rule_id": "ASI01_PROMPT_INJECTION",
+    "category": "Goal Hijacking",
+    "severity": "CRITICAL",
+    "rationale": "Attempts to override foundational agent instructions.",
+    "exploit_precondition": "Agent must process this input without contextual isolation.",
+    "likely_false_positive": "Mentioning the concept of prompt injection in security research docs.",
+    "remediation_hint": "Wrap untrusted input in structural XML tags or use a secondary verification LLM."
+  }
+  ```
+
+## 3. P1: Threat Model Layer (Planned)
+**Goal:** Context-aware risk scoring rather than simple grep matches.
+- **Action:** Before scanning, analyze the target to build a capability exposure profile.
+- **Analysis Vectors:**
+  - **Reachable tools:** Does the skill request network access + shell execution simultaneously?
+  - **Credential surface:** Does it mount `.env` or read from `.ssh/`?
+  - **Lethal Trifecta:** Flag skills that combine *Private Data Access* + *External Input* + *Action Execution*.
+
+## 4. P1: Validation Layer (Planned)
+**Goal:** Reduce False Positives via two-stage verification.
+- **Action:** Differentiate between "heuristic matches" and "validated exploits."
+- **Implementation:** For critical findings (e.g., suspicious shell pipes or remote fetches), integrate with the `ExecutionOrchestrator` to simulate the data flow and verify if the payload actually reaches a dangerous sink.
+
+## 5. P1: Runtime Guard Hardening (Planned)
+**Goal:** Evolve the `before_tool_call` hook into a true Policy Engine.
+- **Action:** Move beyond static regex blocking at runtime.
+- **Implementation:**
+  - Define explicit `allowlist` and `denylist` policies per session.
+  - Apply the Principle of Least Privilege: if an agent was invoked for "code review," strictly block `fs.write` or `child_process.exec`.
+  - Maintain versioned audit logs for all enforcement actions.
+
+## 6. P2: Benchmarking & Ecosystem Integration (Planned)
+**Goal:** Prove efficacy through data, not marketing claims.
+- **Action:** Develop a standalone benchmark suite containing:
+  - Benign administrative skills.
+  - Indirect prompt injection traps.
+  - Supply chain dependency confusion examples.
+- **Metrics:** Track Precision, Recall, False Positive Rate (FPR), and Runtime Hook Latency.
+- **Ecosystem:** Clearly delineate operational modes (Offline Static, Runtime Hook, MCP Service, Asset Audit, CI) with explicitly documented permission requirements for each.