@guava-parity/guard-scanner 13.0.0 → 16.0.0

package/dist/types.cjs

@@ -0,0 +1,18 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/types.ts
+var types_exports = {};
+module.exports = __toCommonJS(types_exports);

package/dist/types.d.mts

@@ -0,0 +1,215 @@
+type Severity = "LOW" | "MEDIUM" | "HIGH" | "CRITICAL";
+type GuardMode = "monitor" | "enforce" | "strict";
+type RuntimeAction = "blocked" | "warned";
+interface EvidenceSpan {
+    file?: string;
+    start_line: number;
+    end_line: number;
+}
+interface FindingEvidence {
+    file?: string;
+    line?: number | null;
+    sample?: string;
+    match_count?: number;
+    tool_name?: string;
+    params_preview?: string;
+    layer?: number;
+    layer_name?: string;
+    owasp_asi?: string[];
+    protocol_surface?: string[];
+}
+interface Finding {
+    schema_version?: string;
+    source?: "static" | "runtime";
+    id: string;
+    rule_id?: string;
+    cat?: string;
+    category: string;
+    severity: Severity;
+    desc?: string;
+    description: string;
+    file?: string;
+    line?: number | null;
+    matchCount?: number;
+    sample?: string;
+    rationale: string;
+    preconditions: string;
+    remediation_hint: string;
+    false_positive_scenarios: string[];
+    validation_state: string;
+    validation_status: string;
+    confidence: number;
+    attack_chain_id: string | null;
+    evidence: FindingEvidence;
+    evidence_spans: EvidenceSpan[];
+    layer?: number;
+    layer_name?: string;
+    owasp_asi?: string[];
+    protocol_surface?: string[];
+    action?: RuntimeAction;
+}
+interface SkillFindingResult {
+    skill: string;
+    risk: number;
+    verdict: string;
+    findings: Finding[];
+}
+interface ThresholdBand {
+    suspicious: number;
+    malicious: number;
+}
+interface ScanStats {
+    scanned: number;
+    clean: number;
+    low: number;
+    suspicious: number;
+    malicious: number;
+}
+interface Recommendation {
+    skill: string;
+    actions: string[];
+}
+interface ScanReport {
+    schema_version: string;
+    timestamp: string;
+    scanner: string;
+    finding_schema_version: string;
+    mode: "normal" | "strict";
+    compliance_mode?: "owasp-asi" | null;
+    stats: ScanStats;
+    thresholds: ThresholdBand;
+    findings: SkillFindingResult[];
+    recommendations: Recommendation[];
+    layer_summary?: Array<Record<string, unknown>>;
+    owasp_asi_coverage?: Array<Record<string, unknown>>;
+    threat_model?: Record<string, unknown>;
+    iocVersion: string;
+}
+interface TextScanResult {
+    safe: boolean;
+    risk: number;
+    detections: Finding[];
+}
+interface ScannerOptions {
+    verbose?: boolean;
+    selfExclude?: boolean;
+    strict?: boolean;
+    summaryOnly?: boolean;
+    quiet?: boolean;
+    checkDeps?: boolean;
+    soulLock?: boolean;
+    plugins?: string[];
+    rulesFile?: string;
+    compliance?: "owasp-asi";
+}
+interface CustomRule {
+    id: string;
+    cat: string;
+    regex: RegExp;
+    severity: Severity;
+    desc: string;
+    codeOnly?: boolean;
+    docOnly?: boolean;
+    all?: boolean;
+    soulLock?: boolean;
+}
+interface PluginConfig {
+    mode?: GuardMode;
+    auditLog?: boolean;
+    customRules?: string;
+}
+interface RuntimeDecision {
+    blocked: boolean;
+    blockReason: string | null;
+    detections: Finding[];
+    mode: GuardMode;
+    toolName?: string;
+    matchedPolicyId?: string | null;
+    policyRationale?: string | null;
+    riskAmplificationReasons?: string[];
+    remediationSuggestion?: string | null;
+    policyDecision?: RuntimePolicyDecision | null;
+}
+interface McpRequest {
+    method: string;
+    params?: Record<string, unknown>;
+    id?: string | number | null;
+}
+interface SarifReport {
+    version: string;
+    $schema?: string;
+    runs: Array<Record<string, unknown>>;
+}
+interface CapabilityMetrics {
+    static_pattern_count: number;
+    runtime_check_count?: number;
+    threat_category_count: number;
+    runtime_layer_count?: number;
+    runtime_layers?: number;
+    benchmark_corpus_version?: string;
+    explainability_completeness_rate?: number;
+    runtime_check_latency_budget_ms?: number;
+    quality_targets?: QualityTargets;
+    [key: string]: unknown;
+}
+interface RuntimeCheckStats {
+    total: number;
+    byLayer: Record<number, number>;
+    bySeverity: Partial<Record<Severity, number>>;
+}
+interface QualityTargets {
+    precision_min: number;
+    recall_min: number;
+    false_positive_rate_max: number;
+    false_negative_rate_max: number;
+    explainability_completeness_rate_min: number;
+    runtime_check_latency_budget_ms: number;
+    false_positive_budget_by_category: Record<string, number>;
+}
+interface RuntimePolicyContract {
+    id?: string;
+    allowed_tools?: string[];
+    blocked_tools?: string[];
+    max_network_scope?: "none" | "internal-only" | "external-ok";
+    secret_bearing_context?: boolean;
+    memory_write_permission?: boolean;
+}
+interface RuntimePolicyDecision {
+    action: "allow" | "block";
+    reason: string;
+    policyId: string;
+    amplificationReasons: string[];
+    remediationSuggestion: string;
+}
+interface ThreatModel {
+    timestamp: string;
+    surface: Record<string, boolean>;
+    summary: string;
+    owasp_asi?: string[];
+    layer_summary?: Array<Record<string, unknown>>;
+    protocol_surfaces?: string[];
+}
+interface GuardScannerInstance {
+    verbose: boolean;
+    strict: boolean;
+    summaryOnly: boolean;
+    quiet: boolean;
+    checkDeps: boolean;
+    soulLock: boolean;
+    thresholds: ThresholdBand;
+    findings: SkillFindingResult[];
+    stats: ScanStats;
+    scanText(text: string): TextScanResult;
+    scanDirectory(dir: string): SkillFindingResult[];
+    scanTarget(targetPath: string): ScanReport;
+    toJSON(): ScanReport;
+    toSARIF(scanDir: string): SarifReport;
+    toHTML(): string;
+    generateThreatModel(findings: Finding[]): ThreatModel;
+}
+interface GuardScannerConstructor {
+    new (options?: ScannerOptions): GuardScannerInstance;
+}
+type ScanResult = SkillFindingResult;
+
+export type { CapabilityMetrics, CustomRule, EvidenceSpan, Finding, FindingEvidence, GuardMode, GuardScannerConstructor, GuardScannerInstance, McpRequest, PluginConfig, QualityTargets, Recommendation, RuntimeAction, RuntimeCheckStats, RuntimeDecision, RuntimePolicyContract, RuntimePolicyDecision, SarifReport, ScanReport, ScanResult, ScanStats, ScannerOptions, Severity, SkillFindingResult, TextScanResult, ThreatModel, ThresholdBand };

package/dist/types.d.ts

@@ -0,0 +1,215 @@
+type Severity = "LOW" | "MEDIUM" | "HIGH" | "CRITICAL";
+type GuardMode = "monitor" | "enforce" | "strict";
+type RuntimeAction = "blocked" | "warned";
+interface EvidenceSpan {
+    file?: string;
+    start_line: number;
+    end_line: number;
+}
+interface FindingEvidence {
+    file?: string;
+    line?: number | null;
+    sample?: string;
+    match_count?: number;
+    tool_name?: string;
+    params_preview?: string;
+    layer?: number;
+    layer_name?: string;
+    owasp_asi?: string[];
+    protocol_surface?: string[];
+}
+interface Finding {
+    schema_version?: string;
+    source?: "static" | "runtime";
+    id: string;
+    rule_id?: string;
+    cat?: string;
+    category: string;
+    severity: Severity;
+    desc?: string;
+    description: string;
+    file?: string;
+    line?: number | null;
+    matchCount?: number;
+    sample?: string;
+    rationale: string;
+    preconditions: string;
+    remediation_hint: string;
+    false_positive_scenarios: string[];
+    validation_state: string;
+    validation_status: string;
+    confidence: number;
+    attack_chain_id: string | null;
+    evidence: FindingEvidence;
+    evidence_spans: EvidenceSpan[];
+    layer?: number;
+    layer_name?: string;
+    owasp_asi?: string[];
+    protocol_surface?: string[];
+    action?: RuntimeAction;
+}
+interface SkillFindingResult {
+    skill: string;
+    risk: number;
+    verdict: string;
+    findings: Finding[];
+}
+interface ThresholdBand {
+    suspicious: number;
+    malicious: number;
+}
+interface ScanStats {
+    scanned: number;
+    clean: number;
+    low: number;
+    suspicious: number;
+    malicious: number;
+}
+interface Recommendation {
+    skill: string;
+    actions: string[];
+}
+interface ScanReport {
+    schema_version: string;
+    timestamp: string;
+    scanner: string;
+    finding_schema_version: string;
+    mode: "normal" | "strict";
+    compliance_mode?: "owasp-asi" | null;
+    stats: ScanStats;
+    thresholds: ThresholdBand;
+    findings: SkillFindingResult[];
+    recommendations: Recommendation[];
+    layer_summary?: Array<Record<string, unknown>>;
+    owasp_asi_coverage?: Array<Record<string, unknown>>;
+    threat_model?: Record<string, unknown>;
+    iocVersion: string;
+}
+interface TextScanResult {
+    safe: boolean;
+    risk: number;
+    detections: Finding[];
+}
+interface ScannerOptions {
+    verbose?: boolean;
+    selfExclude?: boolean;
+    strict?: boolean;
+    summaryOnly?: boolean;
+    quiet?: boolean;
+    checkDeps?: boolean;
+    soulLock?: boolean;
+    plugins?: string[];
+    rulesFile?: string;
+    compliance?: "owasp-asi";
+}
+interface CustomRule {
+    id: string;
+    cat: string;
+    regex: RegExp;
+    severity: Severity;
+    desc: string;
+    codeOnly?: boolean;
+    docOnly?: boolean;
+    all?: boolean;
+    soulLock?: boolean;
+}
+interface PluginConfig {
+    mode?: GuardMode;
+    auditLog?: boolean;
+    customRules?: string;
+}
+interface RuntimeDecision {
+    blocked: boolean;
+    blockReason: string | null;
+    detections: Finding[];
+    mode: GuardMode;
+    toolName?: string;
+    matchedPolicyId?: string | null;
+    policyRationale?: string | null;
+    riskAmplificationReasons?: string[];
+    remediationSuggestion?: string | null;
+    policyDecision?: RuntimePolicyDecision | null;
+}
+interface McpRequest {
+    method: string;
+    params?: Record<string, unknown>;
+    id?: string | number | null;
+}
+interface SarifReport {
+    version: string;
+    $schema?: string;
+    runs: Array<Record<string, unknown>>;
+}
+interface CapabilityMetrics {
+    static_pattern_count: number;
+    runtime_check_count?: number;
+    threat_category_count: number;
+    runtime_layer_count?: number;
+    runtime_layers?: number;
+    benchmark_corpus_version?: string;
+    explainability_completeness_rate?: number;
+    runtime_check_latency_budget_ms?: number;
+    quality_targets?: QualityTargets;
+    [key: string]: unknown;
+}
+interface RuntimeCheckStats {
+    total: number;
+    byLayer: Record<number, number>;
+    bySeverity: Partial<Record<Severity, number>>;
+}
+interface QualityTargets {
+    precision_min: number;
+    recall_min: number;
+    false_positive_rate_max: number;
+    false_negative_rate_max: number;
+    explainability_completeness_rate_min: number;
+    runtime_check_latency_budget_ms: number;
+    false_positive_budget_by_category: Record<string, number>;
+}
+interface RuntimePolicyContract {
+    id?: string;
+    allowed_tools?: string[];
+    blocked_tools?: string[];
+    max_network_scope?: "none" | "internal-only" | "external-ok";
+    secret_bearing_context?: boolean;
+    memory_write_permission?: boolean;
+}
+interface RuntimePolicyDecision {
+    action: "allow" | "block";
+    reason: string;
+    policyId: string;
+    amplificationReasons: string[];
+    remediationSuggestion: string;
+}
+interface ThreatModel {
+    timestamp: string;
+    surface: Record<string, boolean>;
+    summary: string;
+    owasp_asi?: string[];
+    layer_summary?: Array<Record<string, unknown>>;
+    protocol_surfaces?: string[];
+}
+interface GuardScannerInstance {
+    verbose: boolean;
+    strict: boolean;
+    summaryOnly: boolean;
+    quiet: boolean;
+    checkDeps: boolean;
+    soulLock: boolean;
+    thresholds: ThresholdBand;
+    findings: SkillFindingResult[];
+    stats: ScanStats;
+    scanText(text: string): TextScanResult;
+    scanDirectory(dir: string): SkillFindingResult[];
+    scanTarget(targetPath: string): ScanReport;
+    toJSON(): ScanReport;
+    toSARIF(scanDir: string): SarifReport;
+    toHTML(): string;
+    generateThreatModel(findings: Finding[]): ThreatModel;
+}
+interface GuardScannerConstructor {
+    new (options?: ScannerOptions): GuardScannerInstance;
+}
+type ScanResult = SkillFindingResult;
+
+export type { CapabilityMetrics, CustomRule, EvidenceSpan, Finding, FindingEvidence, GuardMode, GuardScannerConstructor, GuardScannerInstance, McpRequest, PluginConfig, QualityTargets, Recommendation, RuntimeAction, RuntimeCheckStats, RuntimeDecision, RuntimePolicyContract, RuntimePolicyDecision, SarifReport, ScanReport, ScanResult, ScanStats, ScannerOptions, Severity, SkillFindingResult, TextScanResult, ThreatModel, ThresholdBand };

package/dist/types.mjs

@@ -0,0 +1 @@
+import { createRequire as __createRequire } from "node:module"; const require = __createRequire(import.meta.url);

package/docs/EVIDENCE_DRIVEN.md

@@ -0,0 +1,182 @@
+# Evidence-Driven Metrics
+
+guard-scanner uses a **single source of truth (SSoT)** architecture for all public metrics. This ensures that numbers in README, documentation, and tests are always in sync with the implementation.
+
+## Architecture
+
+```
+┌─────────────────────────────────────┐
+│ Source Code (patterns.js, etc.)    │
+└──────────────┬──────────────────────┘
+               │
+               ▼
+┌─────────────────────────────────────┐
+│ generate-capabilities.js           │
+│ Generates: docs/spec/capabilities.json
+└──────────────┬──────────────────────┘
+               │
+               ▼
+┌─────────────────────────────────────┐
+│ capabilities.json (SSoT)            │
+│ - static_pattern_count: 352         │
+│ - threat_category_count: 32         │
+│ - runtime_check_count: 26           │
+│ - mcp_tools: [...]                  │
+└──────┬───────────────────────┬──────┘
+       │                       │
+       ▼                       ▼
+┌──────────────┐      ┌────────────────┐
+│ generate-    │      │ verify-        │
+│ readme-      │      │ capabilities.js│
+│ metrics.js   │      │ (CI check)     │
+└──────┬───────┘      └────────────────┘
+       │
+       ▼
+┌─────────────────────────────────────┐
+│ README.md                           │
+│ (Auto-updated metrics)              │
+└─────────────────────────────────────┘
+```
+
+## Scripts
+
+### 1. `generate-capabilities.js`
+
+**Purpose:** Generate `docs/spec/capabilities.json` from source code.
+
+**Runs:**
+- Counts patterns from `src/patterns.js`
+- Counts runtime checks from `src/runtime-guard.js`
+- Lists MCP tools from `src/mcp-server.js`
+- Reads versions from `package.json` and `openclaw.plugin.json`
+
+**Usage:**
+```bash
+node scripts/generate-capabilities.js
+```
+
+**Output:** `docs/spec/capabilities.json`
+
+### 2. `generate-readme-metrics.js`
+
+**Purpose:** Inject metrics from `capabilities.json` into `README.md`.
+
+**Updates:**
+- Header metrics line (categories, patterns, checks)
+- Dependency badge
+- Capability table entries
+- MCP tool descriptions
+
+**Usage:**
+```bash
+# Update README
+node scripts/generate-readme-metrics.js
+
+# CI mode: fail if drift detected
+node scripts/generate-readme-metrics.js --check
+```
+
+### 3. `generate-readme-stats.js`
+
+**Purpose:** Inject test counts from `npm test` output into README.
+
+**Updates:**
+- Test badge: `tests-336%20passed`
+- Test results block
+
+**Usage:**
+```bash
+# Update README
+node scripts/generate-readme-stats.js
+
+# CI mode: fail if drift detected
+node scripts/generate-readme-stats.js --check
+```
+
+### 4. `verify-capabilities.js`
+
+**Purpose:** Verify all documentation matches `capabilities.json`.
+
+**Checks:**
+- README.md metrics
+- README_ja.md metrics
+- SKILL.md metrics
+- package.json version
+- openclaw.plugin.json version
+- Test file count
+
+**Usage:**
+```bash
+node scripts/verify-capabilities.js
+# Exits 1 if any drift detected
+```
+
+## CI Integration
+
+The CI workflow enforces zero-tolerance for drift:
+
+```yaml
+# .github/workflows/ci.yml
+- name: Generate capabilities manifest
+  run: node scripts/generate-capabilities.js
+
+- name: Check README metrics drift
+  run: |
+    node scripts/generate-readme-metrics.js --check
+    node scripts/generate-readme-stats.js --check
+
+- name: Verify all capability claims
+  run: node scripts/verify-capabilities.js
+```
+
+## Local Development
+
+**Sync all README metrics:**
+```bash
+npm run sync:readme
+```
+
+This runs:
+1. `generate-capabilities.js` (update SSoT)
+2. `generate-readme-metrics.js` (update metrics)
+3. `generate-readme-stats.js` (update test counts)
+
+## Adding New Metrics
+
+1. **Add to source code:** Update `patterns.js`, `runtime-guard.js`, etc.
+2. **Update generator:** Edit `generate-capabilities.js` to extract new metric
+3. **Update README generator:** Edit `generate-readme-metrics.js` to inject into README
+4. **Update verifier:** Edit `verify-capabilities.js` to check for drift
+5. **Run sync:** `npm run sync:readme`
+6. **Commit changes:** Include updated `capabilities.json` and `README.md`
+
+## Philosophy
+
+**Why evidence-driven?**
+
+- **Trust:** Users can verify claims match implementation
+- **Marketing-first avoidance:** Numbers come from code, not marketing
+- **Drift prevention:** CI blocks PRs with mismatched numbers
+- **Single source of truth:** One canonical source (`capabilities.json`)
+- **Audit trail:** All changes go through generators
+
+**Zero tolerance for hardcoded numbers in public docs.**
+
+## MCP Integration
+
+The `get_stats` MCP tool reads from `capabilities.json`:
+
+```javascript
+function handleGetStats() {
+    const runtimeStats = getCheckStats();
+    return successResult(
+        `🛡️ guard-scanner v${VERSION}\n\n` +
+        `Static Analysis:\n` +
+        `  • ${STATIC_SUMMARY}\n` +  // from capabilities.json
+        `  • ${runtimeStats.total} checks across ${Object.keys(runtimeStats.byLayer).length} layers\n` +
+        // ...
+    );
+}
+```
+
+This ensures MCP clients always get accurate, up-to-date metrics.