@bryan-thompson/inspector-assessment-client 1.34.2 → 1.35.2

package/lib/lib/assessment/summarizer/stageBEnrichmentBuilder.js

@@ -0,0 +1,282 @@
+/**
+ * Stage B Enrichment Builder
+ *
+ * Functions to build Stage B enrichment data from assessment results.
+ * Extracts evidence, correlations, and confidence details for Claude
+ * semantic analysis.
+ *
+ * Issue #137: Stage A data enrichment for Stage B Claude analysis
+ *
+ * @module assessment/summarizer/stageBEnrichmentBuilder
+ */
+import { DEFAULT_TIER2_MAX_SAMPLES, DEFAULT_TIER3_MAX_CORRELATIONS, MAX_RESPONSE_LENGTH, MAX_CONTEXT_WINDOW, } from "./stageBTypes.js";
+// ============================================================================
+// Helper Functions
+// ============================================================================
+/**
+ * Truncate a string to a maximum length, adding ellipsis if truncated.
+ */
+function truncate(str, maxLength) {
+    if (!str)
+        return "";
+    if (str.length <= maxLength)
+        return str;
+    return str.slice(0, maxLength - 3) + "...";
+}
+/**
+ * Map test result to classification.
+ */
+function classifyTestResult(test) {
+    if (test.connectionError)
+        return "error";
+    if (test.testReliability === "failed")
+        return "error";
+    if (test.vulnerable)
+        return "vulnerable";
+    return "safe";
+}
+/**
+ * Convert SecurityTestResult to PayloadCorrelation.
+ */
+function testToCorrelation(test) {
+    return {
+        inputPayload: truncate(test.payload, MAX_RESPONSE_LENGTH),
+        outputResponse: truncate(test.response, MAX_RESPONSE_LENGTH),
+        classification: classifyTestResult(test),
+        matchedPatterns: test.vulnerable ? [test.testName] : [],
+        toolName: test.toolName || "unknown",
+        testName: test.testName,
+        confidence: test.confidence,
+    };
+}
+/**
+ * Convert test result to finding evidence.
+ */
+function testToEvidence(test) {
+    const contextSource = test.evidence || test.response;
+    const location = test.evidence
+        ? "evidence"
+        : test.response
+            ? "response"
+            : "unknown";
+    return {
+        raw: truncate(test.payload, MAX_RESPONSE_LENGTH),
+        context: truncate(contextSource, MAX_CONTEXT_WINDOW),
+        location,
+    };
+}
+/**
+ * Calculate confidence distribution from tests.
+ */
+function calculateConfidenceBreakdown(tests) {
+    const breakdown = { high: 0, medium: 0, low: 0 };
+    for (const test of tests) {
+        if (test.vulnerable) {
+            const confidence = test.confidence || "medium";
+            breakdown[confidence]++;
+        }
+    }
+    return breakdown;
+}
+/**
+ * Calculate pattern distribution from tests.
+ */
+function calculatePatternDistribution(tests) {
+    const distribution = {};
+    for (const test of tests) {
+        if (test.vulnerable) {
+            const pattern = test.testName;
+            distribution[pattern] = (distribution[pattern] || 0) + 1;
+        }
+    }
+    return distribution;
+}
+/**
+ * Find the highest risk test (most concerning vulnerability).
+ */
+function findHighestRiskTest(tests) {
+    const vulnerableTests = tests.filter((t) => t.vulnerable);
+    if (vulnerableTests.length === 0)
+        return undefined;
+    // Prioritize by risk level, then by confidence
+    const riskOrder = { CRITICAL: 0, HIGH: 1, MEDIUM: 2, LOW: 3 };
+    const confidenceOrder = { high: 0, medium: 1, low: 2 };
+    return vulnerableTests.sort((a, b) => {
+        const riskDiff = (riskOrder[a.riskLevel] ?? 4) - (riskOrder[b.riskLevel] ?? 4);
+        if (riskDiff !== 0)
+            return riskDiff;
+        return ((confidenceOrder[a.confidence || "medium"] ?? 1) -
+            (confidenceOrder[b.confidence || "medium"] ?? 1));
+    })[0];
+}
+// ============================================================================
+// Tier 2: Tool Summary Enrichment Builder
+// ============================================================================
+/**
+ * Build Stage B enrichment for Tier 2 tool summaries.
+ *
+ * @param toolName - Name of the tool
+ * @param tests - Security test results for this tool
+ * @param maxSamples - Maximum evidence samples to include
+ * @returns Tool summary Stage B enrichment
+ */
+export function buildToolSummaryStageBEnrichment(toolName, tests, maxSamples = DEFAULT_TIER2_MAX_SAMPLES) {
+    // Filter to only tests for this tool
+    const toolTests = tests.filter((t) => t.toolName === toolName);
+    // Get vulnerable tests for evidence sampling
+    const vulnerableTests = toolTests.filter((t) => t.vulnerable);
+    // Sample evidence from highest-risk vulnerabilities
+    const sortedVulnerable = [...vulnerableTests].sort((a, b) => {
+        const riskOrder = { CRITICAL: 0, HIGH: 1, MEDIUM: 2, LOW: 3 };
+        return (riskOrder[a.riskLevel] ?? 4) - (riskOrder[b.riskLevel] ?? 4);
+    });
+    const sampleEvidence = sortedVulnerable
+        .slice(0, maxSamples)
+        .map(testToEvidence);
+    // Calculate confidence breakdown
+    const confidenceBreakdown = calculateConfidenceBreakdown(toolTests);
+    // Find highest risk correlation
+    const highestRiskTest = findHighestRiskTest(toolTests);
+    const highestRiskCorrelation = highestRiskTest
+        ? testToCorrelation(highestRiskTest)
+        : undefined;
+    // Calculate pattern distribution
+    const patternDistribution = calculatePatternDistribution(toolTests);
+    // Check for sanitization detection
+    const sanitizationDetected = toolTests.some((t) => t.sanitizationDetected);
+    // Check auth failure mode
+    const authTests = toolTests.filter((t) => t.authFailureMode);
+    const authFailureMode = authTests.length > 0 ? authTests[0].authFailureMode : undefined;
+    return {
+        sampleEvidence,
+        confidenceBreakdown,
+        highestRiskCorrelation,
+        patternDistribution,
+        sanitizationDetected: sanitizationDetected || undefined,
+        authFailureMode,
+    };
+}
+// ============================================================================
+// Tier 3: Tool Detail Enrichment Builder
+// ============================================================================
+/**
+ * Build Stage B enrichment for Tier 3 per-tool detail files.
+ *
+ * @param toolName - Name of the tool
+ * @param tests - Security test results for this tool
+ * @param annotationResult - Tool annotation result (if available)
+ * @param aupViolations - AUP violations for this tool (if any)
+ * @param maxCorrelations - Maximum correlations to include
+ * @returns Tool detail Stage B enrichment
+ */
+export function buildToolDetailStageBEnrichment(toolName, tests, annotationResult, aupViolations, maxCorrelations = DEFAULT_TIER3_MAX_CORRELATIONS) {
+    // Filter to only tests for this tool
+    const toolTests = tests.filter((t) => t.toolName === toolName);
+    // Build payload correlations (prioritize vulnerable, then errors, then safe)
+    const sortedTests = [...toolTests].sort((a, b) => {
+        if (a.vulnerable && !b.vulnerable)
+            return -1;
+        if (!a.vulnerable && b.vulnerable)
+            return 1;
+        if (a.connectionError && !b.connectionError)
+            return -1;
+        if (!a.connectionError && b.connectionError)
+            return 1;
+        return 0;
+    });
+    const payloadCorrelations = sortedTests
+        .slice(0, maxCorrelations)
+        .map(testToCorrelation);
+    // Pattern distribution
+    const patternDistribution = calculatePatternDistribution(toolTests);
+    // Build context windows from evidence
+    const contextWindows = {};
+    for (const test of toolTests.filter((t) => t.vulnerable && t.evidence)) {
+        const key = `${test.testName}:${test.payload.slice(0, 30)}`;
+        if (!contextWindows[key]) {
+            contextWindows[key] = truncate(test.evidence, MAX_CONTEXT_WINDOW);
+        }
+    }
+    // Calculate confidence details
+    const confidenceBreakdown = calculateConfidenceBreakdown(toolTests);
+    const totalVulnerable = confidenceBreakdown.high +
+        confidenceBreakdown.medium +
+        confidenceBreakdown.low;
+    const overallConfidence = totalVulnerable > 0
+        ? Math.round(((confidenceBreakdown.high * 100 +
+            confidenceBreakdown.medium * 70 +
+            confidenceBreakdown.low * 40) /
+            totalVulnerable /
+            100) *
+            100)
+        : 100; // 100% confidence if no vulnerabilities
+    const confidenceDetails = {
+        overall: overallConfidence,
+        byCategory: patternDistribution,
+        requiresManualReview: toolTests.filter((t) => t.requiresManualReview)
+            .length,
+    };
+    // Security details
+    const vulnerableCount = toolTests.filter((t) => t.vulnerable).length;
+    const safeCount = toolTests.filter((t) => !t.vulnerable && !t.connectionError).length;
+    const errorCount = toolTests.filter((t) => t.connectionError).length;
+    // Collect sanitization libraries
+    const sanitizationLibraries = [
+        ...new Set(toolTests.flatMap((t) => t.sanitizationLibraries || []).filter(Boolean)),
+    ];
+    // Auth bypass evidence
+    const authBypassTest = toolTests.find((t) => t.authBypassDetected);
+    const authBypassEvidence = authBypassTest?.authBypassEvidence;
+    const securityDetails = {
+        vulnerableCount,
+        safeCount,
+        errorCount,
+        sanitizationLibraries,
+        authBypassEvidence,
+    };
+    // Annotation details
+    let annotationDetails;
+    if (annotationResult) {
+        annotationDetails = {
+            hasAnnotations: annotationResult.hasAnnotations,
+            alignmentStatus: annotationResult.alignmentStatus,
+            inferredBehavior: annotationResult.inferredBehavior
+                ? {
+                    expectedReadOnly: annotationResult.inferredBehavior.expectedReadOnly,
+                    expectedDestructive: annotationResult.inferredBehavior.expectedDestructive,
+                    reason: annotationResult.inferredBehavior.reason,
+                }
+                : undefined,
+            descriptionPoisoning: annotationResult.descriptionPoisoning
+                ? {
+                    detected: annotationResult.descriptionPoisoning.detected,
+                    patterns: annotationResult.descriptionPoisoning.patterns.map((p) => ({
+                        name: p.name,
+                        evidence: truncate(p.evidence, MAX_CONTEXT_WINDOW),
+                        severity: p.severity,
+                    })),
+                }
+                : undefined,
+        };
+    }
+    // AUP violations for this tool
+    const toolAupViolations = aupViolations
+        ?.filter((v) => v.location?.includes(toolName))
+        .map((v) => ({
+        pattern: v.pattern,
+        matchedText: truncate(v.matchedText, MAX_CONTEXT_WINDOW),
+        severity: v.severity,
+        location: v.location,
+    }));
+    return {
+        payloadCorrelations,
+        patternDistribution,
+        contextWindows,
+        confidenceDetails,
+        securityDetails,
+        annotationDetails,
+        aupViolations: toolAupViolations && toolAupViolations.length > 0
+            ? toolAupViolations
+            : undefined,
+    };
+}

package/lib/lib/assessment/summarizer/stageBTypes.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Stage B Enrichment Types
+ *
+ * Type definitions for Stage B (Claude semantic analysis) data enrichment.
+ * These types extend the tiered output with evidence, correlations, and
+ * confidence details for better LLM semantic analysis.
+ *
+ * Issue #137: Stage A data enrichment for Stage B Claude analysis
+ *
+ * @module assessment/summarizer/stageBTypes
+ */
+/**
+ * Evidence structure for individual findings.
+ * Provides raw data and context for Claude to analyze.
+ */
+export interface FindingEvidence {
+    /** Actual data that triggered the finding (payload or matched text) */
+    raw: string;
+    /** Surrounding context for better understanding */
+    context: string;
+    /** Location in response (e.g., "response.content[0].text", "description") */
+    location: string;
+}
+/**
+ * Payload correlation linking input to output.
+ * Enables Claude to understand cause-effect relationships.
+ */
+export interface PayloadCorrelation {
+    /** The test payload that was sent */
+    inputPayload: string;
+    /** The response received (may be truncated) */
+    outputResponse: string;
+    /** Classification of the result */
+    classification: "vulnerable" | "safe" | "error" | "timeout";
+    /** Patterns that matched this response */
+    matchedPatterns: string[];
+    /** Tool this correlation belongs to */
+    toolName: string;
+    /** Test name/pattern that triggered this */
+    testName: string;
+    /** Confidence level of the detection */
+    confidence?: "high" | "medium" | "low";
+}
+/**
+ * Stage B enrichment for Tier 2 tool summaries.
+ * Provides sampled evidence for quick Claude analysis.
+ */
+export interface ToolSummaryStageBEnrichment {
+    /** Top evidence samples for this tool (limited for token efficiency) */
+    sampleEvidence: FindingEvidence[];
+    /** Confidence breakdown by pattern type */
+    confidenceBreakdown: {
+        high: number;
+        medium: number;
+        low: number;
+    };
+    /** Highest risk correlation for this tool (if vulnerable) */
+    highestRiskCorrelation?: PayloadCorrelation;
+    /** Pattern distribution showing which attack types were detected */
+    patternDistribution: Record<string, number>;
+    /** Whether this tool has sanitization detected */
+    sanitizationDetected?: boolean;
+    /** Auth bypass mode if detected */
+    authFailureMode?: "FAIL_OPEN" | "FAIL_CLOSED" | "UNKNOWN";
+}
+/**
+ * Stage B enrichment for Tier 3 per-tool detail files.
+ * Provides comprehensive evidence for deep-dive analysis.
+ */
+export interface ToolDetailStageBEnrichment {
+    /** All payload correlations for this tool */
+    payloadCorrelations: PayloadCorrelation[];
+    /** Full pattern distribution with counts */
+    patternDistribution: Record<string, number>;
+    /** Context windows for key locations */
+    contextWindows: Record<string, string>;
+    /** Detailed confidence breakdown */
+    confidenceDetails: {
+        /** Overall confidence score (0-100) */
+        overall: number;
+        /** Confidence by attack category */
+        byCategory: Record<string, number>;
+        /** Number of tests with manual review recommended */
+        requiresManualReview: number;
+    };
+    /** Security-specific details */
+    securityDetails: {
+        /** Total vulnerabilities found */
+        vulnerableCount: number;
+        /** Total safe tests */
+        safeCount: number;
+        /** Tests with connection errors */
+        errorCount: number;
+        /** Sanitization libraries detected */
+        sanitizationLibraries: string[];
+        /** Auth bypass evidence if detected */
+        authBypassEvidence?: string;
+    };
+    /** Annotation alignment details (if available) */
+    annotationDetails?: {
+        /** Whether tool has annotations */
+        hasAnnotations: boolean;
+        /** Alignment status */
+        alignmentStatus?: "ALIGNED" | "MISALIGNED" | "MISSING";
+        /** Inferred behavior from patterns */
+        inferredBehavior?: {
+            expectedReadOnly: boolean;
+            expectedDestructive: boolean;
+            reason: string;
+        };
+        /** Description poisoning if detected */
+        descriptionPoisoning?: {
+            detected: boolean;
+            patterns: Array<{
+                name: string;
+                evidence: string;
+                severity: "LOW" | "MEDIUM" | "HIGH";
+            }>;
+        };
+    };
+    /** AUP violations for this tool (if any) */
+    aupViolations?: Array<{
+        pattern: string;
+        matchedText: string;
+        severity: string;
+        location: string;
+    }>;
+}
+/**
+ * Combined Stage B enrichment that can be attached to results.
+ */
+export interface StageBEnrichment {
+    /** Enrichment version for compatibility tracking */
+    version: number;
+    /** Whether enrichment was enabled */
+    enabled: boolean;
+    /** Generation timestamp */
+    generatedAt: string;
+    /** Tier 2 enrichment (tool summary level) */
+    tier2?: ToolSummaryStageBEnrichment;
+    /** Tier 3 enrichment (tool detail level) */
+    tier3?: ToolDetailStageBEnrichment;
+}
+/** Current Stage B enrichment version */
+export declare const STAGE_B_ENRICHMENT_VERSION = 1;
+/** Default maximum samples for Tier 2 evidence */
+export declare const DEFAULT_TIER2_MAX_SAMPLES = 3;
+/** Default maximum correlations for Tier 3 */
+export declare const DEFAULT_TIER3_MAX_CORRELATIONS = 50;
+/** Maximum response length to include (prevents token explosion) */
+export declare const MAX_RESPONSE_LENGTH = 500;
+/** Maximum context window size (chars before/after) */
+export declare const MAX_CONTEXT_WINDOW = 200;
+//# sourceMappingURL=stageBTypes.d.ts.map

package/lib/lib/assessment/summarizer/stageBTypes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stageBTypes.d.ts","sourceRoot":"","sources":["../../../../src/lib/assessment/summarizer/stageBTypes.ts"],"names":[],"mappings":"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"}

package/lib/lib/assessment/summarizer/stageBTypes.js

@@ -0,0 +1,24 @@
+/**
+ * Stage B Enrichment Types
+ *
+ * Type definitions for Stage B (Claude semantic analysis) data enrichment.
+ * These types extend the tiered output with evidence, correlations, and
+ * confidence details for better LLM semantic analysis.
+ *
+ * Issue #137: Stage A data enrichment for Stage B Claude analysis
+ *
+ * @module assessment/summarizer/stageBTypes
+ */
+// ============================================================================
+// Constants
+// ============================================================================
+/** Current Stage B enrichment version */
+export const STAGE_B_ENRICHMENT_VERSION = 1;
+/** Default maximum samples for Tier 2 evidence */
+export const DEFAULT_TIER2_MAX_SAMPLES = 3;
+/** Default maximum correlations for Tier 3 */
+export const DEFAULT_TIER3_MAX_CORRELATIONS = 50;
+/** Maximum response length to include (prevents token explosion) */
+export const MAX_RESPONSE_LENGTH = 500;
+/** Maximum context window size (chars before/after) */
+export const MAX_CONTEXT_WINDOW = 200;

package/lib/lib/assessment/summarizer/tokenEstimator.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Token Estimation Utilities
+ *
+ * Provides token counting and threshold detection for tiered output strategy.
+ * Uses industry-standard approximation of ~4 characters per token.
+ *
+ * Issue #136: Tiered output strategy for large assessments
+ *
+ * @module assessment/summarizer/tokenEstimator
+ */
+import type { MCPDirectoryAssessment } from "../resultTypes.js";
+/**
+ * Estimate the number of tokens for any content.
+ *
+ * Uses the industry-standard approximation of ~4 characters per token.
+ * For JSON content, applies a buffer for formatting overhead.
+ *
+ * @param content - Content to estimate (string, object, or array)
+ * @returns Estimated token count
+ *
+ * @example
+ * ```typescript
+ * // String content
+ * estimateTokens("Hello world"); // ~3 tokens
+ *
+ * // Object content (will be JSON stringified)
+ * estimateTokens({ name: "test", value: 123 }); // ~10 tokens
+ *
+ * // Large assessment results
+ * estimateTokens(assessmentResults); // ~50,000+ tokens
+ * ```
+ */
+export declare function estimateTokens(content: unknown): number;
+/**
+ * Estimate tokens for a JSON file that would be written.
+ * Accounts for pretty-printing with indent=2.
+ *
+ * @param content - Content that would be JSON.stringify'd
+ * @returns Estimated token count
+ */
+export declare function estimateJsonFileTokens(content: unknown): number;
+/**
+ * Determine if assessment results should automatically use tiered output.
+ *
+ * Returns true when estimated token count exceeds the threshold,
+ * indicating the full output would not fit in typical LLM context windows.
+ *
+ * @param results - Full assessment results
+ * @param threshold - Token threshold (default: 100,000)
+ * @returns true if results should be tiered
+ *
+ * @example
+ * ```typescript
+ * const results = await runAssessment(server);
+ *
+ * if (shouldAutoTier(results)) {
+ *   // Use tiered output
+ *   saveTieredResults(serverName, results, options);
+ * } else {
+ *   // Use standard full output
+ *   saveResults(serverName, results, options);
+ * }
+ * ```
+ */
+export declare function shouldAutoTier(results: MCPDirectoryAssessment, threshold?: number): boolean;
+/**
+ * Get a human-readable token estimate with size category.
+ *
+ * @param tokenCount - Number of tokens
+ * @returns Object with formatted token count and size category
+ *
+ * @example
+ * ```typescript
+ * formatTokenEstimate(5000);
+ * // { tokens: "5,000", category: "small", fitsContext: true }
+ *
+ * formatTokenEstimate(500000);
+ * // { tokens: "500,000", category: "very-large", fitsContext: false }
+ * ```
+ */
+export declare function formatTokenEstimate(tokenCount: number): {
+    tokens: string;
+    category: "small" | "medium" | "large" | "very-large" | "oversized";
+    fitsContext: boolean;
+    recommendation: string;
+};
+/**
+ * Estimate tokens for each major section of assessment results.
+ * Useful for understanding which modules contribute most to output size.
+ *
+ * @param results - Assessment results to analyze
+ * @returns Map of section name to estimated token count
+ */
+export declare function estimateSectionTokens(results: MCPDirectoryAssessment): Record<string, number>;
+/**
+ * Get the top N largest sections by token count.
+ *
+ * @param results - Assessment results
+ * @param topN - Number of sections to return (default: 5)
+ * @returns Array of [sectionName, tokenCount] sorted by size descending
+ */
+export declare function getTopSections(results: MCPDirectoryAssessment, topN?: number): Array<[string, number]>;
+//# sourceMappingURL=tokenEstimator.d.ts.map

package/lib/lib/assessment/summarizer/tokenEstimator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokenEstimator.d.ts","sourceRoot":"","sources":["../../../../src/lib/assessment/summarizer/tokenEstimator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAuB7D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAmBvD;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAW/D;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,sBAAsB,EAC/B,SAAS,GAAE,MAAoD,GAC9D,OAAO,CAGT;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG;IACvD,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,YAAY,GAAG,WAAW,CAAC;IACpE,WAAW,EAAE,OAAO,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;CACxB,CA8BA;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,sBAAsB,GAC9B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA8CxB;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,sBAAsB,EAC/B,IAAI,GAAE,MAAU,GACf,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAOzB"}