@bryan-thompson/inspector-assessment 1.22.13 → 1.22.16

package/client/lib/lib/assessment/coreTypes.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Core Assessment Types
+ *
+ * Foundational types used across all assessment modules.
+ * These are the building blocks that other type files depend on.
+ *
+ * @module assessment/coreTypes
+ */
+export type AssessmentStatus = "PASS" | "FAIL" | "NEED_MORE_INFO";
+export type SecurityRiskLevel = "LOW" | "MEDIUM" | "HIGH";
+/**
+ * Alignment status for tool annotations.
+ * Extends beyond PASS/FAIL to handle ambiguous cases.
+ */
+export type AlignmentStatus = "ALIGNED" | "MISALIGNED" | "REVIEW_RECOMMENDED" | "UNKNOWN";
+/**
+ * Confidence level for behavior inference
+ */
+export type InferenceConfidence = "high" | "medium" | "low";
+/**
+ * Assessment category tier for distinguishing core vs optional assessments.
+ * - "core": Always applicable to any MCP server audit
+ * - "optional": Contextual assessments (e.g., MCPB bundle-specific)
+ */
+export type AssessmentCategoryTier = "core" | "optional";
+/**
+ * Metadata for assessment categories including tier and applicability info.
+ */
+export interface AssessmentCategoryMetadata {
+    tier: AssessmentCategoryTier;
+    description: string;
+    applicableTo?: string;
+}
+/**
+ * Category metadata mapping for all assessment modules.
+ * Used for CLI output and downstream consumers to understand category context.
+ *
+ * Note: Uses `satisfies` to preserve literal key types while ensuring type safety.
+ * This allows deriving AssessmentModuleName from the object keys.
+ */
+declare const ASSESSMENT_CATEGORY_METADATA_INTERNAL: {
+    functionality: {
+        tier: "core";
+        description: string;
+    };
+    security: {
+        tier: "core";
+        description: string;
+    };
+    documentation: {
+        tier: "core";
+        description: string;
+    };
+    errorHandling: {
+        tier: "core";
+        description: string;
+    };
+    usability: {
+        tier: "core";
+        description: string;
+    };
+    mcpSpecCompliance: {
+        tier: "core";
+        description: string;
+    };
+    aupCompliance: {
+        tier: "core";
+        description: string;
+    };
+    toolAnnotations: {
+        tier: "core";
+        description: string;
+    };
+    prohibitedLibraries: {
+        tier: "core";
+        description: string;
+    };
+    manifestValidation: {
+        tier: "optional";
+        description: string;
+        applicableTo: string;
+    };
+    portability: {
+        tier: "optional";
+        description: string;
+        applicableTo: string;
+    };
+    externalAPIScanner: {
+        tier: "core";
+        description: string;
+    };
+    authentication: {
+        tier: "core";
+        description: string;
+    };
+    temporal: {
+        tier: "core";
+        description: string;
+    };
+    resources: {
+        tier: "core";
+        description: string;
+    };
+    prompts: {
+        tier: "core";
+        description: string;
+    };
+    crossCapability: {
+        tier: "core";
+        description: string;
+    };
+};
+/**
+ * Type-safe module name derived from ASSESSMENT_CATEGORY_METADATA keys.
+ * Use this type for compile-time validation of module names.
+ */
+export type AssessmentModuleName = keyof typeof ASSESSMENT_CATEGORY_METADATA_INTERNAL;
+/**
+ * Re-export with original name for backward compatibility.
+ * Type is preserved as Record<AssessmentModuleName, AssessmentCategoryMetadata>.
+ */
+export declare const ASSESSMENT_CATEGORY_METADATA: Record<AssessmentModuleName, AssessmentCategoryMetadata>;
+/**
+ * Generate module configuration derived from ASSESSMENT_CATEGORY_METADATA.
+ * Single source of truth for all assessment module names.
+ *
+ * @param options.sourceCodePath - If true, enables externalAPIScanner
+ * @param options.skipTemporal - If true, disables temporal assessment
+ * @returns Record of module names to enabled state (type-safe)
+ */
+export declare function getAllModulesConfig(options: {
+    sourceCodePath?: boolean;
+    skipTemporal?: boolean;
+}): Record<AssessmentModuleName, boolean>;
+/**
+ * Persistence model for MCP servers (Three-Tier Classification).
+ *
+ * These types are re-exported from the services layer for backward compatibility
+ * with existing imports from `@/lib/assessmentTypes`. This cross-layer import
+ * is intentional and documented:
+ *
+ * **Why cross-layer?**
+ * - PersistenceModel and ServerPersistenceContext are defined in
+ *   `services/assessment/config/annotationPatterns.ts` alongside the pattern
+ *   matching logic that uses them.
+ * - Moving the types here would create a circular dependency since the
+ *   annotationPatterns module needs to import its own types.
+ * - Type-only imports (`export type`) don't create runtime dependencies,
+ *   so this cross-layer reference is safe.
+ *
+ * **Type definitions:**
+ * - "immediate": Write operations persist directly to storage (database, file, API)
+ * - "deferred": Write operations are in-memory until explicit save operation
+ * - "unknown": Cannot determine persistence model
+ *
+ * @see services/assessment/config/annotationPatterns.ts for implementation
+ */
+export type { PersistenceModel, ServerPersistenceContext, } from "../../services/assessment/config/annotationPatterns.js";
+//# sourceMappingURL=coreTypes.d.ts.map

package/client/lib/lib/assessment/coreTypes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coreTypes.d.ts","sourceRoot":"","sources":["../../../src/lib/assessment/coreTypes.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,MAAM,GAAG,gBAAgB,CAAC;AAClE,MAAM,MAAM,iBAAiB,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE1D;;;GAGG;AACH,MAAM,MAAM,eAAe,GACvB,SAAS,GACT,YAAY,GACZ,oBAAoB,GACpB,SAAS,CAAC;AAEd;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;AAE5D;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,GAAG,MAAM,GAAG,UAAU,CAAC;AAEzD;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC,IAAI,EAAE,sBAAsB,CAAC;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;GAMG;AACH,QAAA,MAAM,qCAAqC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8DW,CAAC;AAEvD;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAC9B,MAAM,OAAO,qCAAqC,CAAC;AAErD;;;GAGG;AACH,eAAO,MAAM,4BAA4B,EAAE,MAAM,CAC/C,oBAAoB,EACpB,0BAA0B,CACa,CAAC;AAE1C;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE;IAC3C,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB,GAAG,MAAM,CAAC,oBAAoB,EAAE,OAAO,CAAC,CAaxC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,YAAY,EACV,gBAAgB,EAChB,wBAAwB,GACzB,MAAM,qDAAqD,CAAC"}

package/client/lib/lib/assessment/coreTypes.js

@@ -0,0 +1,101 @@
+/**
+ * Core Assessment Types
+ *
+ * Foundational types used across all assessment modules.
+ * These are the building blocks that other type files depend on.
+ *
+ * @module assessment/coreTypes
+ */
+/**
+ * Category metadata mapping for all assessment modules.
+ * Used for CLI output and downstream consumers to understand category context.
+ *
+ * Note: Uses `satisfies` to preserve literal key types while ensuring type safety.
+ * This allows deriving AssessmentModuleName from the object keys.
+ */
+const ASSESSMENT_CATEGORY_METADATA_INTERNAL = {
+    functionality: {
+        tier: "core",
+        description: "Tool functionality validation",
+    },
+    security: {
+        tier: "core",
+        description: "Security vulnerability detection",
+    },
+    documentation: {
+        tier: "core",
+        description: "Documentation quality",
+    },
+    errorHandling: {
+        tier: "core",
+        description: "Error handling compliance",
+    },
+    usability: { tier: "core", description: "Usability assessment" },
+    mcpSpecCompliance: {
+        tier: "core",
+        description: "MCP protocol compliance",
+    },
+    aupCompliance: {
+        tier: "core",
+        description: "Acceptable use policy compliance",
+    },
+    toolAnnotations: {
+        tier: "core",
+        description: "Tool annotation validation",
+    },
+    prohibitedLibraries: {
+        tier: "core",
+        description: "Prohibited library detection",
+    },
+    manifestValidation: {
+        tier: "optional",
+        description: "MCPB manifest validation",
+        applicableTo: "MCPB bundles",
+    },
+    portability: {
+        tier: "optional",
+        description: "Portability checks",
+        applicableTo: "MCPB bundles",
+    },
+    externalAPIScanner: {
+        tier: "core",
+        description: "External API detection",
+    },
+    authentication: {
+        tier: "core",
+        description: "OAuth/auth evaluation",
+    },
+    temporal: {
+        tier: "core",
+        description: "Temporal/rug pull detection",
+    },
+    resources: { tier: "core", description: "Resource security" },
+    prompts: { tier: "core", description: "Prompt security" },
+    crossCapability: {
+        tier: "core",
+        description: "Cross-capability security",
+    },
+};
+/**
+ * Re-export with original name for backward compatibility.
+ * Type is preserved as Record<AssessmentModuleName, AssessmentCategoryMetadata>.
+ */
+export const ASSESSMENT_CATEGORY_METADATA = ASSESSMENT_CATEGORY_METADATA_INTERNAL;
+/**
+ * Generate module configuration derived from ASSESSMENT_CATEGORY_METADATA.
+ * Single source of truth for all assessment module names.
+ *
+ * @param options.sourceCodePath - If true, enables externalAPIScanner
+ * @param options.skipTemporal - If true, disables temporal assessment
+ * @returns Record of module names to enabled state (type-safe)
+ */
+export function getAllModulesConfig(options) {
+    return Object.keys(ASSESSMENT_CATEGORY_METADATA).reduce((acc, key) => ({
+        ...acc,
+        [key]: key === "externalAPIScanner"
+            ? Boolean(options.sourceCodePath)
+            : key === "temporal"
+                ? !options.skipTemporal
+                : true,
+    }), {});
+}

package/client/lib/lib/assessment/extendedTypes.d.ts

@@ -0,0 +1,415 @@
+/**
+ * Extended Assessment Types
+ *
+ * Types for extended assessment modules including AUP compliance,
+ * tool annotations, temporal detection, and capability assessors.
+ *
+ * @module assessment/extendedTypes
+ */
+import type { AssessmentStatus, SecurityRiskLevel, InferenceConfidence, AlignmentStatus } from "./coreTypes.js";
+export type AUPCategory = "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J" | "K" | "L" | "M" | "N";
+export type AUPSeverity = "CRITICAL" | "HIGH" | "MEDIUM" | "FLAG";
+export interface AUPViolation {
+    category: AUPCategory;
+    categoryName: string;
+    severity: AUPSeverity;
+    pattern: string;
+    matchedText: string;
+    location: "tool_name" | "tool_description" | "readme" | "source_code";
+    filePath?: string;
+    lineNumber?: number;
+    confidence: "high" | "medium" | "low";
+    requiresHumanReview: boolean;
+    reviewGuidance?: string;
+}
+export interface AUPComplianceAssessment {
+    violations: AUPViolation[];
+    highRiskDomains: string[];
+    scannedLocations: {
+        toolNames: boolean;
+        toolDescriptions: boolean;
+        readme: boolean;
+        sourceCode: boolean;
+    };
+    status: AssessmentStatus;
+    explanation: string;
+    recommendations: string[];
+}
+/**
+ * Source of tool annotations
+ */
+export type AnnotationSource = "mcp" | "source-code" | "inferred" | "none";
+export interface ToolAnnotationResult {
+    toolName: string;
+    hasAnnotations: boolean;
+    annotations?: {
+        readOnlyHint?: boolean;
+        destructiveHint?: boolean;
+        title?: string;
+        description?: string;
+        idempotentHint?: boolean;
+        openWorldHint?: boolean;
+    };
+    /** Where the annotations were extracted from */
+    annotationSource?: AnnotationSource;
+    inferredBehavior?: {
+        expectedReadOnly: boolean;
+        expectedDestructive: boolean;
+        reason: string;
+        /** Confidence level of the inference */
+        confidence: InferenceConfidence;
+        /** True if the tool name matches an ambiguous pattern */
+        isAmbiguous: boolean;
+    };
+    /** Alignment status between annotations and inferred behavior */
+    alignmentStatus?: AlignmentStatus;
+    issues: string[];
+    recommendations: string[];
+    /** Description poisoning detection (Issue #8) */
+    descriptionPoisoning?: {
+        detected: boolean;
+        patterns: Array<{
+            name: string;
+            pattern: string;
+            severity: "LOW" | "MEDIUM" | "HIGH";
+            category: string;
+            evidence: string;
+        }>;
+        riskLevel: "NONE" | "LOW" | "MEDIUM" | "HIGH";
+    };
+}
+export interface ToolAnnotationAssessment {
+    toolResults: ToolAnnotationResult[];
+    annotatedCount: number;
+    missingAnnotationsCount: number;
+    /** Count of high-confidence misalignments only (excludes REVIEW_RECOMMENDED) */
+    misalignedAnnotationsCount: number;
+    status: AssessmentStatus;
+    explanation: string;
+    recommendations: string[];
+    /** Detailed metrics for annotation quality */
+    metrics?: {
+        /** Percentage of tools with any annotations (0-100) */
+        coverage: number;
+        /** Percentage of tools without contradictions (0-100) */
+        consistency: number;
+        /** Percentage of high-confidence alignments (0-100) */
+        correctness: number;
+        /** Count of tools needing manual review */
+        reviewRequired: number;
+    };
+    /** Breakdown of tools by alignment status */
+    alignmentBreakdown?: {
+        aligned: number;
+        misaligned: number;
+        reviewRecommended: number;
+        unknown: number;
+    };
+    /** Summary of where annotations were extracted from */
+    annotationSources?: {
+        /** Count from MCP protocol (tools/list response) */
+        mcp: number;
+        /** Count from source code analysis */
+        sourceCode: number;
+        /** Count where behavior was inferred from patterns */
+        inferred: number;
+        /** Count with no annotations found */
+        none: number;
+    };
+    /** Count of tools with poisoned descriptions detected (Issue #8) */
+    poisonedDescriptionsDetected?: number;
+}
+export type ProhibitedLibraryCategory = "financial" | "media" | "payments" | "banking";
+export interface ProhibitedLibraryMatch {
+    name: string;
+    category: ProhibitedLibraryCategory;
+    location: "package.json" | "source_import" | "requirements.txt" | "cargo.toml";
+    filePath?: string;
+    lineNumber?: number;
+    severity: "BLOCKING" | "HIGH" | "MEDIUM";
+    reason: string;
+    policyReference: string;
+}
+export interface ProhibitedLibrariesAssessment {
+    matches: ProhibitedLibraryMatch[];
+    scannedFiles: string[];
+    hasFinancialLibraries: boolean;
+    hasMediaLibraries: boolean;
+    status: AssessmentStatus;
+    explanation: string;
+    recommendations: string[];
+}
+export interface ManifestJsonSchema {
+    manifest_version: string;
+    name: string;
+    version: string;
+    description?: string;
+    author?: string;
+    repository?: string;
+    license?: string;
+    mcp_config: {
+        command: string;
+        args?: string[];
+        env?: Record<string, string>;
+    };
+    icon?: string;
+    homepage?: string;
+    keywords?: string[];
+    privacy_policies?: string[];
+}
+/**
+ * Privacy Policy URL Validation Result
+ * Validates that privacy_policies URLs are accessible
+ */
+export interface PrivacyPolicyValidation {
+    url: string;
+    accessible: boolean;
+    statusCode?: number;
+    contentType?: string;
+    error?: string;
+}
+export interface ManifestValidationResult {
+    field: string;
+    valid: boolean;
+    value?: unknown;
+    expectedType?: string;
+    issue?: string;
+    severity: "ERROR" | "WARNING" | "INFO";
+}
+export interface ManifestValidationAssessment {
+    hasManifest: boolean;
+    manifestVersion?: string;
+    validationResults: ManifestValidationResult[];
+    hasIcon: boolean;
+    hasRequiredFields: boolean;
+    missingFields: string[];
+    /** Privacy policy URL validation results */
+    privacyPolicies?: {
+        declared: string[];
+        validationResults: PrivacyPolicyValidation[];
+        allAccessible: boolean;
+    };
+    status: AssessmentStatus;
+    explanation: string;
+    recommendations: string[];
+}
+export interface PortabilityIssue {
+    type: "hardcoded_path" | "platform_specific" | "bundle_root_antipattern" | "absolute_path" | "user_home_path";
+    filePath: string;
+    lineNumber?: number;
+    matchedText: string;
+    severity: "HIGH" | "MEDIUM" | "LOW";
+    recommendation: string;
+}
+export interface PortabilityAssessment {
+    issues: PortabilityIssue[];
+    scannedFiles: number;
+    platformSpecificCount: number;
+    hardcodedPathCount: number;
+    usesDirname: boolean;
+    usesBundleRoot: boolean;
+    status: AssessmentStatus;
+    explanation: string;
+    recommendations: string[];
+    /** Shell command portability analysis */
+    shellCommands?: Array<{
+        command: string;
+        isPortable: boolean;
+        alternativeCommand?: string;
+    }>;
+    /** Platform coverage summary */
+    platformCoverage?: {
+        supported: "all" | "windows" | "macos" | "linux";
+        missing: string[];
+    };
+}
+export interface DetectedAPI {
+    url: string;
+    service: string;
+    filePath: string;
+}
+export interface ExternalAPIScannerAssessment {
+    detectedAPIs: DetectedAPI[];
+    uniqueServices: string[];
+    affiliationWarning?: string;
+    scannedFiles: number;
+    status: AssessmentStatus;
+    explanation: string;
+    recommendations: string[];
+}
+export type AuthMethod = "oauth" | "api_key" | "none" | "unknown";
+export interface AuthAppropriateness {
+    isAppropriate: boolean;
+    concerns: string[];
+    explanation: string;
+}
+export interface TransportSecurityAnalysis {
+    usesTLS: boolean;
+    tlsEnforced: boolean;
+    hasInsecurePatterns: boolean;
+    insecurePatterns: string[];
+    hasSecurePatterns: boolean;
+    securePatterns: string[];
+    corsConfigured: boolean;
+    corsPermissive: boolean;
+    sessionSecure: boolean;
+    recommendations: string[];
+}
+export interface AuthenticationAssessment {
+    authMethod: AuthMethod;
+    hasLocalDependencies: boolean;
+    transportType: string;
+    appropriateness: AuthAppropriateness;
+    recommendation: string;
+    detectedPatterns: {
+        oauthIndicators: string[];
+        localResourceIndicators: string[];
+        apiKeyIndicators: string[];
+    };
+    transportSecurity?: TransportSecurityAnalysis;
+    status: AssessmentStatus;
+    explanation: string;
+    recommendations: string[];
+}
+export interface TemporalToolResult {
+    tool: string;
+    vulnerable: boolean;
+    totalInvocations: number;
+    firstDeviationAt: number | null;
+    deviationCount: number;
+    errorCount: number;
+    pattern: "RUG_PULL_TEMPORAL" | "RUG_PULL_DEFINITION" | null;
+    severity: "HIGH" | "MEDIUM" | "NONE";
+    reducedInvocations?: boolean;
+    note?: string;
+    evidence?: {
+        safeResponseExample: unknown;
+        maliciousResponseExample: unknown;
+    };
+    definitionMutated?: boolean;
+    definitionMutationAt?: number | null;
+    definitionEvidence?: {
+        baselineDescription?: string;
+        mutatedDescription?: string;
+        baselineSchema?: unknown;
+        mutatedSchema?: unknown;
+    };
+}
+export interface TemporalAssessment {
+    toolsTested: number;
+    invocationsPerTool: number;
+    rugPullsDetected: number;
+    definitionMutationsDetected: number;
+    details: TemporalToolResult[];
+    status: AssessmentStatus;
+    explanation: string;
+    recommendations: string[];
+}
+export interface ResourceTestResult {
+    resourceUri: string;
+    resourceName?: string;
+    mimeType?: string;
+    tested: boolean;
+    accessible: boolean;
+    securityIssues: string[];
+    pathTraversalVulnerable: boolean;
+    sensitiveDataExposed: boolean;
+    promptInjectionDetected: boolean;
+    promptInjectionPatterns: string[];
+    validUri: boolean;
+    readTime?: number;
+    contentSizeBytes?: number;
+    error?: string;
+    /** Sensitive data patterns detected in resource content */
+    sensitivePatterns?: Array<{
+        pattern: string;
+        severity: "critical" | "high" | "medium";
+        detected: boolean;
+    }>;
+    /** Access control information */
+    accessControls?: {
+        requiresAuth: boolean;
+        authType?: string;
+    };
+    /** Data classification based on content analysis */
+    dataClassification?: "public" | "internal" | "confidential" | "restricted";
+}
+export interface ResourceAssessment {
+    resourcesTested: number;
+    resourceTemplatesTested: number;
+    accessibleResources: number;
+    securityIssuesFound: number;
+    pathTraversalVulnerabilities: number;
+    sensitiveDataExposures: number;
+    promptInjectionVulnerabilities: number;
+    results: ResourceTestResult[];
+    status: AssessmentStatus;
+    explanation: string;
+    recommendations: string[];
+}
+export interface PromptTestResult {
+    promptName: string;
+    description?: string;
+    tested: boolean;
+    hasRequiredArguments: boolean;
+    argumentsValidated: boolean;
+    aupCompliant: boolean;
+    injectionVulnerable: boolean;
+    safetyIssues: string[];
+    argumentCount: number;
+    executionTime?: number;
+    error?: string;
+    /** Template analysis for prompt structure */
+    promptTemplate?: {
+        templateType: string;
+        variables: string[];
+        validated: boolean;
+    };
+    /** Dynamic content analysis */
+    dynamicContent?: {
+        hasInterpolation: boolean;
+        injectionSafe: boolean;
+        escapingApplied: string[];
+    };
+}
+export interface PromptAssessment {
+    promptsTested: number;
+    aupViolations: number;
+    injectionVulnerabilities: number;
+    argumentValidationIssues: number;
+    results: PromptTestResult[];
+    status: AssessmentStatus;
+    explanation: string;
+    recommendations: string[];
+}
+export interface CrossCapabilityTestResult {
+    testType: "tool_to_resource" | "prompt_to_tool" | "resource_to_tool" | "privilege_escalation";
+    sourceCapability: string;
+    targetCapability: string;
+    vulnerable: boolean;
+    evidence?: string;
+    riskLevel: SecurityRiskLevel;
+    description: string;
+    /** Specific privilege escalation vector if detected */
+    privilegeEscalationVector?: string;
+    /** Data exfiltration risk details */
+    dataExfiltrationRisk?: {
+        sensitiveFields: string[];
+        exfiltrationMethod: string;
+    };
+    /** Chain of capabilities that could be exploited together */
+    attackChain?: string[];
+    /** Confidence level in the detection */
+    confidence?: "high" | "medium" | "low";
+}
+export interface CrossCapabilitySecurityAssessment {
+    testsRun: number;
+    vulnerabilitiesFound: number;
+    privilegeEscalationRisks: number;
+    dataFlowViolations: number;
+    results: CrossCapabilityTestResult[];
+    status: AssessmentStatus;
+    explanation: string;
+    recommendations: string[];
+}
+//# sourceMappingURL=extendedTypes.d.ts.map