@bryan-thompson/inspector-assessment-client 1.25.1 → 1.25.5

package/lib/services/assessment/modules/securityTests/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Security Assessment Module
+ * Exports all security-related components
+ */
+export { SecurityResponseAnalyzer, type ConfidenceResult, type AnalysisResult, type ErrorClassification, } from "./SecurityResponseAnalyzer.js";
+export { SecurityPayloadTester, type TestProgressCallback, type PayloadTestConfig, type TestLogger, } from "./SecurityPayloadTester.js";
+export { SecurityPayloadGenerator } from "./SecurityPayloadGenerator.js";
+//# sourceMappingURL=index.d.ts.map

package/lib/services/assessment/modules/securityTests/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/services/assessment/modules/securityTests/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,wBAAwB,EACxB,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,mBAAmB,GACzB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EACL,qBAAqB,EACrB,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,EACtB,KAAK,UAAU,GAChB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC"}

package/lib/services/assessment/modules/securityTests/index.js

@@ -0,0 +1,7 @@
+/**
+ * Security Assessment Module
+ * Exports all security-related components
+ */
+export { SecurityResponseAnalyzer, } from "./SecurityResponseAnalyzer.js";
+export { SecurityPayloadTester, } from "./SecurityPayloadTester.js";
+export { SecurityPayloadGenerator } from "./SecurityPayloadGenerator.js";

package/lib/services/assessment/orchestratorHelpers.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Assessment Orchestrator Helpers
+ *
+ * Pure functions extracted from AssessmentOrchestrator for testability.
+ * These functions handle:
+ * - AUP violation enrichment for JSONL events
+ * - Module progress/started event emission
+ * - Overall status determination
+ * - Summary and recommendations generation
+ */
+import { MCPDirectoryAssessment, AssessmentStatus } from "../../lib/assessmentTypes.js";
+export declare const moduleStartTimes: Map<string, number>;
+/**
+ * Emit module_started event and track start time for duration calculation.
+ * Emits JSONL to stderr with version field for consistent event structure.
+ */
+export declare function emitModuleStartedEvent(moduleName: string, estimatedTests: number, toolCount: number): void;
+/**
+ * Emit module_complete event with score and duration.
+ * Uses shared score calculator for consistent scoring logic.
+ * For AUP module, includes enriched violation data for Claude analysis.
+ */
+export declare function emitModuleProgress(moduleName: string, status: string, result: unknown, testsRun?: number): void;
+/**
+ * Build AUP enrichment data from an AUP compliance assessment result.
+ * Samples violations prioritizing by severity (CRITICAL > HIGH > MEDIUM).
+ */
+export declare function buildAUPEnrichment(aupResult: {
+    violations?: Array<{
+        severity: string;
+        category: string;
+        categoryName?: string;
+        matchedText?: string;
+        location?: string;
+        confidence?: string;
+    }>;
+    scannedLocations?: {
+        toolNames: boolean;
+        toolDescriptions: boolean;
+        readme: boolean;
+        sourceCode: boolean;
+    };
+    highRiskDomains?: string[];
+}, maxSamples?: number): {
+    violationsSample: Array<{
+        category: string;
+        categoryName: string;
+        severity: string;
+        matchedText: string;
+        location: string;
+        confidence: string;
+    }>;
+    samplingNote: string;
+    violationMetrics: {
+        total: number;
+        critical: number;
+        high: number;
+        medium: number;
+        byCategory: Record<string, number>;
+    };
+    scannedLocations: {
+        toolNames: boolean;
+        toolDescriptions: boolean;
+        readme: boolean;
+        sourceCode: boolean;
+    };
+    highRiskDomains: string[];
+};
+/**
+ * Determine overall status from assessment results.
+ * Priority: FAIL > NEED_MORE_INFO > PASS
+ */
+export declare function determineOverallStatus(results: Partial<MCPDirectoryAssessment>): AssessmentStatus;
+/**
+ * Generate summary text from assessment results.
+ */
+export declare function generateSummary(results: Partial<MCPDirectoryAssessment>): string;
+/**
+ * Generate recommendations from assessment results.
+ * Aggregates, deduplicates, and limits to 10 recommendations.
+ */
+export declare function generateRecommendations(results: Partial<MCPDirectoryAssessment>): string[];
+//# sourceMappingURL=orchestratorHelpers.d.ts.map

package/lib/services/assessment/orchestratorHelpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestratorHelpers.d.ts","sourceRoot":"","sources":["../../../src/services/assessment/orchestratorHelpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,sBAAsB,EACtB,gBAAgB,EACjB,MAAM,uBAAuB,CAAC;AAU/B,eAAO,MAAM,gBAAgB,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAa,CAAC;AAE/D;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,MAAM,EAClB,cAAc,EAAE,MAAM,EACtB,SAAS,EAAE,MAAM,GAChB,IAAI,CAcN;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,OAAO,EACf,QAAQ,GAAE,MAAU,GACnB,IAAI,CAiCN;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE;IACT,UAAU,CAAC,EAAE,KAAK,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC,CAAC;IACH,gBAAgB,CAAC,EAAE;QACjB,SAAS,EAAE,OAAO,CAAC;QACnB,gBAAgB,EAAE,OAAO,CAAC;QAC1B,MAAM,EAAE,OAAO,CAAC;QAChB,UAAU,EAAE,OAAO,CAAC;KACrB,CAAC;IACF,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;CAC5B,EACD,UAAU,GAAE,MAAW,GACtB;IACD,gBAAgB,EAAE,KAAK,CAAC;QACtB,QAAQ,EAAE,MAAM,CAAC;QACjB,YAAY,EAAE,MAAM,CAAC;QACrB,QAAQ,EAAE,MAAM,CAAC;QACjB,WAAW,EAAE,MAAM,CAAC;QACpB,QAAQ,EAAE,MAAM,CAAC;QACjB,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC,CAAC;IACH,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE;QAChB,KAAK,EAAE,MAAM,CAAC;QACd,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KACpC,CAAC;IACF,gBAAgB,EAAE;QAChB,SAAS,EAAE,OAAO,CAAC;QACnB,gBAAgB,EAAE,OAAO,CAAC;QAC1B,MAAM,EAAE,OAAO,CAAC;QAChB,UAAU,EAAE,OAAO,CAAC;KACrB,CAAC;IACF,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B,CAkEA;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,OAAO,CAAC,sBAAsB,CAAC,GACvC,gBAAgB,CAsBlB;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,OAAO,CAAC,sBAAsB,CAAC,GACvC,MAAM,CA8ER;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,OAAO,CAAC,sBAAsB,CAAC,GACvC,MAAM,EAAE,CAiBV"}

package/lib/services/assessment/orchestratorHelpers.js

@@ -0,0 +1,212 @@
+/**
+ * Assessment Orchestrator Helpers
+ *
+ * Pure functions extracted from AssessmentOrchestrator for testability.
+ * These functions handle:
+ * - AUP violation enrichment for JSONL events
+ * - Module progress/started event emission
+ * - Overall status determination
+ * - Summary and recommendations generation
+ */
+// Import score calculation helpers from shared module
+import { calculateModuleScore, normalizeModuleKey, INSPECTOR_VERSION, } from "../../lib/moduleScoring.js";
+// Track module start times for duration calculation
+export const moduleStartTimes = new Map();
+/**
+ * Emit module_started event and track start time for duration calculation.
+ * Emits JSONL to stderr with version field for consistent event structure.
+ */
+export function emitModuleStartedEvent(moduleName, estimatedTests, toolCount) {
+    const moduleKey = normalizeModuleKey(moduleName);
+    moduleStartTimes.set(moduleKey, Date.now());
+    // Emit JSONL to stderr with version field
+    console.error(JSON.stringify({
+        event: "module_started",
+        module: moduleKey,
+        estimatedTests,
+        toolCount,
+        version: INSPECTOR_VERSION,
+    }));
+}
+/**
+ * Emit module_complete event with score and duration.
+ * Uses shared score calculator for consistent scoring logic.
+ * For AUP module, includes enriched violation data for Claude analysis.
+ */
+export function emitModuleProgress(moduleName, status, result, testsRun = 0) {
+    // Calculate score using shared helper
+    const score = calculateModuleScore(result);
+    // Don't emit events for skipped modules (null score means module wasn't run)
+    if (score === null)
+        return;
+    const moduleKey = normalizeModuleKey(moduleName);
+    // Calculate duration from module start time
+    const startTime = moduleStartTimes.get(moduleKey);
+    const duration = startTime ? Date.now() - startTime : 0;
+    moduleStartTimes.delete(moduleKey);
+    // Build base event
+    const event = {
+        event: "module_complete",
+        module: moduleKey,
+        status,
+        score,
+        testsRun,
+        duration,
+        version: INSPECTOR_VERSION,
+    };
+    // Add AUP enrichment when module is AUP
+    if (moduleKey === "aup" && result) {
+        const aupEnrichment = buildAUPEnrichment(result);
+        Object.assign(event, aupEnrichment);
+    }
+    // Emit JSONL to stderr with version field
+    console.error(JSON.stringify(event));
+}
+/**
+ * Build AUP enrichment data from an AUP compliance assessment result.
+ * Samples violations prioritizing by severity (CRITICAL > HIGH > MEDIUM).
+ */
+export function buildAUPEnrichment(aupResult, maxSamples = 10) {
+    const violations = aupResult.violations || [];
+    // Calculate metrics
+    const metrics = {
+        total: violations.length,
+        critical: violations.filter((v) => v.severity === "CRITICAL").length,
+        high: violations.filter((v) => v.severity === "HIGH").length,
+        medium: violations.filter((v) => v.severity === "MEDIUM").length,
+        byCategory: {},
+    };
+    // Count by category
+    for (const v of violations) {
+        metrics.byCategory[v.category] = (metrics.byCategory[v.category] || 0) + 1;
+    }
+    // Sample violations prioritizing by severity
+    const sampled = [];
+    const severityOrder = ["CRITICAL", "HIGH", "MEDIUM"];
+    for (const severity of severityOrder) {
+        if (sampled.length >= maxSamples)
+            break;
+        const bySeverity = violations.filter((v) => v.severity === severity);
+        for (const v of bySeverity) {
+            if (sampled.length >= maxSamples)
+                break;
+            sampled.push({
+                category: v.category,
+                categoryName: v.categoryName || "",
+                severity: v.severity,
+                matchedText: v.matchedText || "",
+                location: v.location || "",
+                confidence: v.confidence || "",
+            });
+        }
+    }
+    // Build sampling note
+    let samplingNote = "";
+    if (violations.length === 0) {
+        samplingNote = "No violations detected.";
+    }
+    else if (violations.length <= maxSamples) {
+        samplingNote = `All ${violations.length} violation(s) included.`;
+    }
+    else {
+        samplingNote = `Sampled ${sampled.length} of ${violations.length} violations, prioritized by severity (CRITICAL > HIGH > MEDIUM).`;
+    }
+    return {
+        violationsSample: sampled,
+        samplingNote,
+        violationMetrics: metrics,
+        scannedLocations: aupResult.scannedLocations || {
+            toolNames: false,
+            toolDescriptions: false,
+            readme: false,
+            sourceCode: false,
+        },
+        highRiskDomains: (aupResult.highRiskDomains || []).slice(0, 10),
+    };
+}
+/**
+ * Determine overall status from assessment results.
+ * Priority: FAIL > NEED_MORE_INFO > PASS
+ */
+export function determineOverallStatus(results) {
+    const statuses = [];
+    // Collect all statuses from assessment results
+    Object.values(results).forEach((assessment) => {
+        if (assessment &&
+            typeof assessment === "object" &&
+            "status" in assessment) {
+            statuses.push(assessment.status);
+        }
+    });
+    // If any critical category fails, overall fails
+    if (statuses.includes("FAIL"))
+        return "FAIL";
+    // If any category needs more info, overall needs more info
+    if (statuses.includes("NEED_MORE_INFO"))
+        return "NEED_MORE_INFO";
+    // All must pass for overall pass
+    return "PASS";
+}
+/**
+ * Generate summary text from assessment results.
+ */
+export function generateSummary(results) {
+    const parts = [];
+    const totalCategories = Object.keys(results).length;
+    const passedCategories = Object.values(results).filter((r) => r && typeof r === "object" && "status" in r && r.status === "PASS").length;
+    parts.push(`Assessment complete: ${passedCategories}/${totalCategories} categories passed.`);
+    // Add key findings - use type assertions for optional properties
+    const security = results.security;
+    if (security?.vulnerabilities?.length) {
+        parts.push(`Found ${security.vulnerabilities.length} security vulnerabilities.`);
+    }
+    const functionality = results.functionality;
+    if (functionality?.brokenTools?.length) {
+        parts.push(`${functionality.brokenTools.length} tools are not functioning correctly.`);
+    }
+    // New assessor findings
+    const aupCompliance = results.aupCompliance;
+    if (aupCompliance?.violations?.length) {
+        const criticalCount = aupCompliance.violations.filter((v) => v.severity === "CRITICAL").length;
+        if (criticalCount > 0) {
+            parts.push(`CRITICAL: ${criticalCount} AUP violation(s) detected.`);
+        }
+        else {
+            parts.push(`${aupCompliance.violations.length} AUP item(s) flagged for review.`);
+        }
+    }
+    const toolAnnotations = results.toolAnnotations;
+    if (toolAnnotations?.missingAnnotationsCount) {
+        parts.push(`${toolAnnotations.missingAnnotationsCount} tools missing annotations.`);
+    }
+    const prohibitedLibraries = results.prohibitedLibraries;
+    if (prohibitedLibraries?.matches?.length) {
+        const blockingCount = prohibitedLibraries.matches.filter((m) => m.severity === "BLOCKING").length;
+        if (blockingCount > 0) {
+            parts.push(`BLOCKING: ${blockingCount} prohibited library/libraries detected.`);
+        }
+    }
+    const portability = results.portability;
+    if (portability?.usesBundleRoot) {
+        parts.push("Uses ${BUNDLE_ROOT} anti-pattern.");
+    }
+    return parts.join(" ");
+}
+/**
+ * Generate recommendations from assessment results.
+ * Aggregates, deduplicates, and limits to 10 recommendations.
+ */
+export function generateRecommendations(results) {
+    const recommendations = [];
+    // Aggregate recommendations from all assessments
+    Object.values(results).forEach((assessment) => {
+        if (assessment &&
+            typeof assessment === "object" &&
+            "recommendations" in assessment &&
+            Array.isArray(assessment.recommendations)) {
+            recommendations.push(...assessment.recommendations);
+        }
+    });
+    // De-duplicate and prioritize
+    return [...new Set(recommendations)].slice(0, 10);
+}

package/lib/services/assessment/tool-classifier-patterns.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Tool Classifier Pattern Configuration
+ *
+ * Pre-compiled regex patterns for MCP tool classification.
+ * Extracting patterns to this file provides:
+ * - Single source of truth for patterns, confidence values, and risk levels
+ * - Pre-compiled patterns (created once at module load, not per classify() call)
+ * - Easier maintenance without modifying core classification logic
+ *
+ * @see ToolClassifier.ts for classification logic
+ * @see ToolClassifier.test.ts for pattern behavior validation
+ */
+/**
+ * Security risk categories for MCP tools.
+ *
+ * Categories are organized by risk level:
+ * - **HIGH**: Tools that may execute code or access sensitive data
+ * - **MEDIUM**: Tools with potential bypass or supply chain risks
+ * - **LOW**: Safe tools for data retrieval and manipulation
+ */
+export declare enum ToolCategory {
+    CALCULATOR = "calculator",
+    SYSTEM_EXEC = "system_exec",
+    CODE_EXECUTOR = "code_executor",
+    DATA_ACCESS = "data_access",
+    TOOL_OVERRIDE = "tool_override",
+    CONFIG_MODIFIER = "config_modifier",
+    URL_FETCHER = "fetcher",
+    UNICODE_PROCESSOR = "unicode",
+    JSON_PARSER = "parser",
+    PACKAGE_INSTALLER = "installer",
+    RUG_PULL = "rug_pull",
+    SAFE_STORAGE = "safe_storage",
+    API_WRAPPER = "api_wrapper",
+    SEARCH_RETRIEVAL = "search_retrieval",
+    CRUD_CREATION = "crud_creation",
+    READ_ONLY_INFO = "read_only_info",
+    DATA_FETCHER = "data_fetcher",
+    GENERIC = "generic"
+}
+/**
+ * Risk level for security categorization
+ */
+export type RiskLevel = "HIGH" | "MEDIUM" | "LOW";
+/**
+ * Configuration for a single tool category
+ */
+export interface CategoryConfig {
+    /** Pre-compiled regex patterns for this category */
+    readonly patterns: readonly RegExp[];
+    /** Confidence score (0-100) when this category matches */
+    readonly confidence: number;
+    /** Human-readable reasoning for classification */
+    readonly reasoning: string;
+    /** Risk level for security prioritization */
+    readonly risk: RiskLevel;
+}
+/**
+ * Complete pattern configuration for all tool categories.
+ * Patterns are pre-compiled as static constants for performance.
+ *
+ * ## Pattern Types
+ *
+ * 1. **Substring patterns** (`/keyword/i`): Match anywhere in text
+ *    - Used for HIGH-risk keywords that warrant scrutiny even when embedded
+ *
+ * 2. **Word boundary patterns** (`/\bword\b/i`): Match isolated words only
+ *    - Used for common words to prevent false positives
+ *    - Note: `\b` treats hyphens as boundaries but underscores as word chars
+ */
+export declare const CATEGORY_PATTERNS: Readonly<Record<Exclude<ToolCategory, ToolCategory.GENERIC>, CategoryConfig>>;
+/**
+ * Default configuration for GENERIC category (no pattern match)
+ */
+export declare const GENERIC_CONFIG: Readonly<{
+    confidence: number;
+    reasoning: string;
+    risk: RiskLevel;
+}>;
+/**
+ * Order in which categories are checked during classification.
+ * This order determines priority when a tool matches multiple categories.
+ */
+export declare const CATEGORY_CHECK_ORDER: readonly Exclude<ToolCategory, ToolCategory.GENERIC>[];
+//# sourceMappingURL=tool-classifier-patterns.d.ts.map

package/lib/services/assessment/tool-classifier-patterns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-classifier-patterns.d.ts","sourceRoot":"","sources":["../../../src/services/assessment/tool-classifier-patterns.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;;;;;GAOG;AACH,oBAAY,YAAY;IAEtB,UAAU,eAAe;IACzB,WAAW,gBAAgB;IAC3B,aAAa,kBAAkB;IAC/B,WAAW,gBAAgB;IAC3B,aAAa,kBAAkB;IAC/B,eAAe,oBAAoB;IACnC,WAAW,YAAY;IAGvB,iBAAiB,YAAY;IAC7B,WAAW,WAAW;IACtB,iBAAiB,cAAc;IAC/B,QAAQ,aAAa;IAGrB,YAAY,iBAAiB;IAC7B,WAAW,gBAAgB;IAC3B,gBAAgB,qBAAqB;IACrC,aAAa,kBAAkB;IAC/B,cAAc,mBAAmB;IACjC,YAAY,iBAAiB;IAG7B,OAAO,YAAY;CACpB;AAED;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;AAElD;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,oDAAoD;IACpD,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,0DAA0D;IAC1D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,kDAAkD;IAClD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,6CAA6C;IAC7C,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;CAC1B;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,iBAAiB,EAAE,QAAQ,CACtC,MAAM,CAAC,OAAO,CAAC,YAAY,EAAE,YAAY,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC,CA0S3D,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,QAAQ,CAAC;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,SAAS,CAAC;CACjB,CAIS,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,oBAAoB,EAAE,SAAS,OAAO,CACjD,YAAY,EACZ,YAAY,CAAC,OAAO,CACrB,EAqBS,CAAC"}