@bryan-thompson/inspector-assessment-cli 1.26.5 → 1.26.7

package/build/lib/assessment-runner/source-loader.js

@@ -0,0 +1,139 @@
+/**
+ * Source File Loading
+ *
+ * Handles recursive source file discovery with gitignore support.
+ *
+ * @module cli/lib/assessment-runner/source-loader
+ */
+import * as fs from "fs";
+import * as path from "path";
+/** Maximum file size (in characters) to include in source code analysis */
+const MAX_SOURCE_FILE_SIZE = 100_000;
+/**
+ * Load optional files from source code path
+ *
+ * @param sourcePath - Path to source code directory
+ * @returns Object containing loaded source files
+ */
+export function loadSourceFiles(sourcePath) {
+    const result = {};
+    // Search for README in source directory and parent directories (up to 3 levels)
+    // This handles cases where --source points to a subdirectory but README is at repo root
+    const readmePaths = ["README.md", "readme.md", "Readme.md"];
+    let readmeFound = false;
+    // First try the source directory itself
+    for (const readmePath of readmePaths) {
+        const fullPath = path.join(sourcePath, readmePath);
+        if (fs.existsSync(fullPath)) {
+            result.readmeContent = fs.readFileSync(fullPath, "utf-8");
+            readmeFound = true;
+            break;
+        }
+    }
+    // If not found, search parent directories (up to 3 levels)
+    if (!readmeFound) {
+        let currentDir = sourcePath;
+        for (let i = 0; i < 3; i++) {
+            const parentDir = path.dirname(currentDir);
+            if (parentDir === currentDir)
+                break; // Reached filesystem root
+            for (const readmePath of readmePaths) {
+                const fullPath = path.join(parentDir, readmePath);
+                if (fs.existsSync(fullPath)) {
+                    result.readmeContent = fs.readFileSync(fullPath, "utf-8");
+                    readmeFound = true;
+                    break;
+                }
+            }
+            if (readmeFound)
+                break;
+            currentDir = parentDir;
+        }
+    }
+    const packagePath = path.join(sourcePath, "package.json");
+    if (fs.existsSync(packagePath)) {
+        result.packageJson = JSON.parse(fs.readFileSync(packagePath, "utf-8"));
+    }
+    const manifestPath = path.join(sourcePath, "manifest.json");
+    if (fs.existsSync(manifestPath)) {
+        result.manifestRaw = fs.readFileSync(manifestPath, "utf-8");
+        try {
+            result.manifestJson = JSON.parse(result.manifestRaw);
+        }
+        catch {
+            console.warn("[Assessment] Failed to parse manifest.json");
+        }
+    }
+    result.sourceCodeFiles = new Map();
+    // Include config files for portability analysis
+    const sourceExtensions = [
+        ".ts",
+        ".js",
+        ".py",
+        ".go",
+        ".rs",
+        ".json",
+        ".sh",
+        ".yaml",
+        ".yml",
+    ];
+    // Parse .gitignore patterns
+    const gitignorePatterns = [];
+    const gitignorePath = path.join(sourcePath, ".gitignore");
+    if (fs.existsSync(gitignorePath)) {
+        const gitignoreContent = fs.readFileSync(gitignorePath, "utf-8");
+        for (const line of gitignoreContent.split("\n")) {
+            const trimmed = line.trim();
+            if (!trimmed || trimmed.startsWith("#"))
+                continue;
+            // Convert gitignore pattern to regex
+            const pattern = trimmed
+                .replace(/\./g, "\\.")
+                .replace(/\*\*/g, ".*")
+                .replace(/\*/g, "[^/]*")
+                .replace(/\?/g, ".");
+            try {
+                gitignorePatterns.push(new RegExp(pattern));
+            }
+            catch {
+                // Skip invalid patterns
+            }
+        }
+    }
+    const isGitignored = (relativePath) => {
+        return gitignorePatterns.some((pattern) => pattern.test(relativePath));
+    };
+    const loadSourceDir = (dir, prefix = "") => {
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.name.startsWith(".") || entry.name === "node_modules")
+                continue;
+            const fullPath = path.join(dir, entry.name);
+            const relativePath = prefix ? `${prefix}/${entry.name}` : entry.name;
+            // Skip gitignored files
+            if (isGitignored(relativePath))
+                continue;
+            if (entry.isDirectory()) {
+                loadSourceDir(fullPath, relativePath);
+            }
+            else if (sourceExtensions.some((ext) => entry.name.endsWith(ext))) {
+                try {
+                    const content = fs.readFileSync(fullPath, "utf-8");
+                    if (content.length < MAX_SOURCE_FILE_SIZE) {
+                        result.sourceCodeFiles.set(relativePath, content);
+                    }
+                }
+                catch {
+                    // Skip unreadable files
+                }
+            }
+        }
+    };
+    try {
+        loadSourceDir(sourcePath);
+    }
+    catch (e) {
+        console.warn("[Assessment] Could not load source files:", e);
+    }
+    return result;
+}

package/build/lib/assessment-runner/tool-wrapper.js

@@ -0,0 +1,40 @@
+/**
+ * Tool Call Wrapper
+ *
+ * Creates a wrapper around MCP client.callTool() for assessment context.
+ *
+ * @module cli/lib/assessment-runner/tool-wrapper
+ */
+/**
+ * Create callTool wrapper for assessment context
+ *
+ * @param client - Connected MCP client
+ * @returns Wrapped callTool function
+ */
+export function createCallToolWrapper(client) {
+    return async (name, params) => {
+        try {
+            const response = await client.callTool({
+                name,
+                arguments: params,
+            });
+            return {
+                content: response.content,
+                isError: response.isError || false,
+                structuredContent: response
+                    .structuredContent,
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    };
+}

package/build/lib/assessment-runner/types.js

@@ -0,0 +1,8 @@
+/**
+ * Assessment Runner Types
+ *
+ * Shared type definitions for the assessment-runner module.
+ *
+ * @module cli/lib/assessment-runner/types
+ */
+export {};

package/build/lib/assessment-runner.js

@@ -0,0 +1,12 @@
+/**
+ * Assessment Runner Module (Facade)
+ *
+ * This file provides backward-compatible exports by re-exporting from the
+ * modular assessment-runner/ directory structure.
+ *
+ * Refactored as part of Issue #94.
+ *
+ * @module cli/lib/assessment-runner
+ */
+// Re-export all public APIs from the modular structure
+export * from "./assessment-runner/index.js";

package/build/lib/cli-parser.js

@@ -0,0 +1,419 @@
+/**
+ * CLI Parser Module
+ *
+ * Handles command-line argument parsing, validation, and help text for
+ * the mcp-assess-full CLI tool.
+ *
+ * Extracted from assess-full.ts as part of Issue #90 modularization.
+ *
+ * @module cli/lib/cli-parser
+ */
+import { ASSESSMENT_CATEGORY_METADATA, } from "../../../client/lib/lib/assessmentTypes.js";
+import { ASSESSMENT_PROFILES, isValidProfileName, getProfileHelpText, } from "../profiles.js";
+// ============================================================================
+// Constants
+// ============================================================================
+// Valid module names derived from ASSESSMENT_CATEGORY_METADATA
+const VALID_MODULE_NAMES = Object.keys(ASSESSMENT_CATEGORY_METADATA);
+// ============================================================================
+// Validation Functions
+// ============================================================================
+/**
+ * Validate module names from CLI input
+ *
+ * @param input - Comma-separated module names
+ * @param flagName - Flag name for error messages (e.g., "--skip-modules")
+ * @returns Array of validated module names, or empty array if invalid
+ */
+export function validateModuleNames(input, flagName) {
+    const names = input
+        .split(",")
+        .map((n) => n.trim())
+        .filter(Boolean);
+    const invalid = names.filter((n) => !VALID_MODULE_NAMES.includes(n));
+    if (invalid.length > 0) {
+        console.error(`Error: Invalid module name(s) for ${flagName}: ${invalid.join(", ")}`);
+        console.error(`Valid modules: ${VALID_MODULE_NAMES.join(", ")}`);
+        setTimeout(() => process.exit(1), 10);
+        return [];
+    }
+    return names;
+}
+/**
+ * Validate parsed options for consistency and requirements
+ *
+ * @param options - Partial assessment options to validate
+ * @returns Validation result with any errors
+ */
+export function validateArgs(options) {
+    const errors = [];
+    // Server name is required
+    if (!options.serverName) {
+        errors.push("--server is required");
+    }
+    // Validate mutual exclusivity of --profile, --skip-modules, and --only-modules
+    if (options.profile &&
+        (options.skipModules?.length || options.onlyModules?.length)) {
+        errors.push("--profile cannot be used with --skip-modules or --only-modules");
+    }
+    if (options.skipModules?.length && options.onlyModules?.length) {
+        errors.push("--skip-modules and --only-modules are mutually exclusive");
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+    };
+}
+// ============================================================================
+// Argument Parsing
+// ============================================================================
+/**
+ * Parse command-line arguments
+ *
+ * @param argv - Command-line arguments (defaults to process.argv.slice(2))
+ * @returns Parsed assessment options
+ */
+export function parseArgs(argv) {
+    const args = argv ?? process.argv.slice(2);
+    const options = {};
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (!arg)
+            continue;
+        switch (arg) {
+            case "--server":
+            case "-s":
+                options.serverName = args[++i];
+                break;
+            case "--config":
+            case "-c":
+                options.serverConfigPath = args[++i];
+                break;
+            case "--output":
+            case "-o":
+                options.outputPath = args[++i];
+                break;
+            case "--source":
+                options.sourceCodePath = args[++i];
+                break;
+            case "--pattern-config":
+            case "-p":
+                options.patternConfigPath = args[++i];
+                break;
+            case "--performance-config":
+                options.performanceConfigPath = args[++i];
+                break;
+            case "--claude-enabled":
+                options.claudeEnabled = true;
+                break;
+            case "--claude-http":
+                // Enable Claude Bridge with HTTP transport (connects to mcp-auditor)
+                options.claudeEnabled = true;
+                options.claudeHttp = true;
+                break;
+            case "--mcp-auditor-url": {
+                const urlValue = args[++i];
+                if (!urlValue || urlValue.startsWith("-")) {
+                    console.error("Error: --mcp-auditor-url requires a URL argument");
+                    setTimeout(() => process.exit(1), 10);
+                    options.helpRequested = true;
+                    return options;
+                }
+                try {
+                    new URL(urlValue); // Validate URL format
+                    options.mcpAuditorUrl = urlValue;
+                }
+                catch {
+                    console.error(`Error: Invalid URL for --mcp-auditor-url: ${urlValue}`);
+                    console.error("  Expected format: http://hostname:port or https://hostname:port");
+                    setTimeout(() => process.exit(1), 10);
+                    options.helpRequested = true;
+                    return options;
+                }
+                break;
+            }
+            case "--full":
+                options.fullAssessment = true;
+                break;
+            case "--verbose":
+            case "-v":
+                options.verbose = true;
+                options.logLevel = "debug";
+                break;
+            case "--silent":
+                options.logLevel = "silent";
+                break;
+            case "--log-level": {
+                const levelValue = args[++i];
+                const validLevels = [
+                    "silent",
+                    "error",
+                    "warn",
+                    "info",
+                    "debug",
+                ];
+                if (!validLevels.includes(levelValue)) {
+                    console.error(`Invalid log level: ${levelValue}. Valid options: ${validLevels.join(", ")}`);
+                    setTimeout(() => process.exit(1), 10);
+                    options.helpRequested = true;
+                    return options;
+                }
+                options.logLevel = levelValue;
+                break;
+            }
+            case "--json":
+                options.jsonOnly = true;
+                break;
+            case "--format":
+            case "-f": {
+                const formatValue = args[++i];
+                if (formatValue !== "json" && formatValue !== "markdown") {
+                    console.error(`Invalid format: ${formatValue}. Valid options: json, markdown`);
+                    setTimeout(() => process.exit(1), 10);
+                    options.helpRequested = true;
+                    return options;
+                }
+                options.format = formatValue;
+                break;
+            }
+            case "--include-policy":
+                options.includePolicy = true;
+                break;
+            case "--preflight":
+                options.preflightOnly = true;
+                break;
+            case "--compare":
+                options.comparePath = args[++i];
+                break;
+            case "--diff-only":
+                options.diffOnly = true;
+                break;
+            case "--resume":
+                options.resume = true;
+                break;
+            case "--no-resume":
+                options.noResume = true;
+                break;
+            case "--temporal-invocations":
+                options.temporalInvocations = parseInt(args[++i], 10);
+                break;
+            case "--skip-temporal":
+                options.skipTemporal = true;
+                break;
+            case "--profile": {
+                const profileValue = args[++i];
+                if (!profileValue) {
+                    console.error("Error: --profile requires a profile name");
+                    console.error(`Valid profiles: ${Object.keys(ASSESSMENT_PROFILES).join(", ")}`);
+                    setTimeout(() => process.exit(1), 10);
+                    options.helpRequested = true;
+                    return options;
+                }
+                if (!isValidProfileName(profileValue)) {
+                    console.error(`Error: Invalid profile name: ${profileValue}`);
+                    console.error(`Valid profiles: ${Object.keys(ASSESSMENT_PROFILES).join(", ")}`);
+                    setTimeout(() => process.exit(1), 10);
+                    options.helpRequested = true;
+                    return options;
+                }
+                options.profile = profileValue;
+                break;
+            }
+            case "--skip-modules": {
+                const skipValue = args[++i];
+                if (!skipValue) {
+                    console.error("Error: --skip-modules requires a comma-separated list");
+                    setTimeout(() => process.exit(1), 10);
+                    options.helpRequested = true;
+                    return options;
+                }
+                options.skipModules = validateModuleNames(skipValue, "--skip-modules");
+                if (options.skipModules.length === 0 && skipValue) {
+                    options.helpRequested = true;
+                    return options;
+                }
+                break;
+            }
+            case "--only-modules": {
+                const onlyValue = args[++i];
+                if (!onlyValue) {
+                    console.error("Error: --only-modules requires a comma-separated list");
+                    setTimeout(() => process.exit(1), 10);
+                    options.helpRequested = true;
+                    return options;
+                }
+                options.onlyModules = validateModuleNames(onlyValue, "--only-modules");
+                if (options.onlyModules.length === 0 && onlyValue) {
+                    options.helpRequested = true;
+                    return options;
+                }
+                break;
+            }
+            case "--help":
+            case "-h":
+                printHelp();
+                options.helpRequested = true;
+                return options;
+            default:
+                if (!arg.startsWith("-")) {
+                    if (!options.serverName) {
+                        options.serverName = arg;
+                    }
+                }
+                else {
+                    console.error(`Unknown argument: ${arg}`);
+                    printHelp();
+                    setTimeout(() => process.exit(1), 10);
+                    options.helpRequested = true;
+                    return options;
+                }
+        }
+    }
+    // Validate mutual exclusivity of --profile, --skip-modules, and --only-modules
+    if (options.profile &&
+        (options.skipModules?.length || options.onlyModules?.length)) {
+        console.error("Error: --profile cannot be used with --skip-modules or --only-modules");
+        setTimeout(() => process.exit(1), 10);
+        options.helpRequested = true;
+        return options;
+    }
+    if (options.skipModules?.length && options.onlyModules?.length) {
+        console.error("Error: --skip-modules and --only-modules are mutually exclusive");
+        setTimeout(() => process.exit(1), 10);
+        options.helpRequested = true;
+        return options;
+    }
+    if (!options.serverName) {
+        console.error("Error: --server is required");
+        printHelp();
+        setTimeout(() => process.exit(1), 10);
+        options.helpRequested = true;
+        return options;
+    }
+    // Environment variable fallbacks (matches run-security-assessment.ts behavior)
+    // INSPECTOR_CLAUDE=true enables Claude with HTTP transport
+    if (process.env.INSPECTOR_CLAUDE === "true" && !options.claudeEnabled) {
+        options.claudeEnabled = true;
+        options.claudeHttp = true; // HTTP transport when enabled via env var
+    }
+    // INSPECTOR_MCP_AUDITOR_URL overrides default URL (only if not set via CLI)
+    if (process.env.INSPECTOR_MCP_AUDITOR_URL && !options.mcpAuditorUrl) {
+        const envUrl = process.env.INSPECTOR_MCP_AUDITOR_URL;
+        try {
+            new URL(envUrl);
+            options.mcpAuditorUrl = envUrl;
+        }
+        catch {
+            console.warn(`Warning: Invalid INSPECTOR_MCP_AUDITOR_URL: ${envUrl}, using default`);
+        }
+    }
+    return options;
+}
+// ============================================================================
+// Help Text
+// ============================================================================
+/**
+ * Print help message to console
+ */
+export function printHelp() {
+    console.log(`
+Usage: mcp-assess-full [options] [server-name]
+
+Run comprehensive MCP server assessment with 16 assessor modules organized in 4 tiers.
+
+Options:
+  --server, -s <name>    Server name (required, or pass as first positional arg)
+  --config, -c <path>    Path to server config JSON
+  --output, -o <path>    Output path (default: /tmp/inspector-full-assessment-<server>.<ext>)
+  --source <path>        Source code path for deep analysis (AUP, portability, etc.)
+  --pattern-config, -p <path>  Path to custom annotation pattern JSON
+  --performance-config <path>  Path to performance tuning JSON (batch sizes, timeouts, etc.)
+  --format, -f <type>    Output format: json (default) or markdown
+  --include-policy       Include policy compliance mapping in report (30 requirements)
+  --preflight            Run quick validation only (tools exist, manifest valid, server responds)
+  --compare <path>       Compare current assessment against baseline JSON file
+  --diff-only            Output only the comparison diff (requires --compare)
+  --resume               Resume from previous interrupted assessment
+  --no-resume            Force fresh start, clear any existing state
+  --claude-enabled       Enable Claude Code integration (CLI transport: requires 'claude' binary)
+  --claude-http          Enable Claude Code via HTTP transport (connects to mcp-auditor proxy)
+  --mcp-auditor-url <url>  mcp-auditor URL for HTTP transport (default: http://localhost:8085)
+  --full                 Enable all assessment modules (default)
+  --profile <name>       Use predefined module profile (quick, security, compliance, full)
+  --temporal-invocations <n>  Number of invocations per tool for rug pull detection (default: 25)
+  --skip-temporal        Skip temporal/rug pull testing (faster assessment)
+  --skip-modules <list>  Skip specific modules (comma-separated)
+  --only-modules <list>  Run only specific modules (comma-separated)
+  --json                 Output only JSON path (no console summary)
+  --verbose, -v          Enable verbose logging (same as --log-level debug)
+  --silent               Suppress all diagnostic logging
+  --log-level <level>    Set log level: silent, error, warn, info (default), debug
+                         Also supports LOG_LEVEL environment variable
+  --help, -h             Show this help message
+
+Environment Variables:
+  INSPECTOR_CLAUDE=true         Enable Claude with HTTP transport (same as --claude-http)
+  INSPECTOR_MCP_AUDITOR_URL     Override default mcp-auditor URL (default: http://localhost:8085)
+  LOG_LEVEL                     Set log level (overridden by --log-level flag)
+
+${getProfileHelpText()}
+Module Selection:
+  --profile, --skip-modules, and --only-modules are mutually exclusive.
+  Use --profile for common assessment scenarios.
+  Use --skip-modules for custom runs by disabling expensive modules.
+  Use --only-modules to focus on specific areas (e.g., tool annotation PRs).
+
+  Valid module names (new naming):
+    functionality, security, errorHandling, protocolCompliance, aupCompliance,
+    toolAnnotations, prohibitedLibraries, manifestValidation, authentication,
+    temporal, resources, prompts, crossCapability, developerExperience,
+    portability, externalAPIScanner
+
+  Legacy module names (deprecated, will map to new names):
+    documentation -> developerExperience
+    usability -> developerExperience
+    mcpSpecCompliance -> protocolCompliance
+    protocolConformance -> protocolCompliance
+
+Module Tiers (16 total):
+  Tier 1 - Core Security (Always Run):
+    • Functionality      - Tests all tools work correctly
+    • Security           - Prompt injection & vulnerability testing
+    • Error Handling     - Validates error responses
+    • Protocol Compliance - MCP protocol + JSON-RPC validation
+    • AUP Compliance     - Acceptable Use Policy checks
+    • Temporal           - Rug pull/temporal behavior change detection
+
+  Tier 2 - Compliance (MCP Directory):
+    • Tool Annotations   - readOnlyHint/destructiveHint validation
+    • Prohibited Libs    - Dependency security checks
+    • Manifest           - MCPB manifest.json validation
+    • Authentication     - OAuth/auth evaluation
+
+  Tier 3 - Capability-Based (Conditional):
+    • Resources          - Resource capability assessment
+    • Prompts            - Prompt capability assessment
+    • Cross-Capability   - Chained vulnerability detection
+
+  Tier 4 - Extended (Optional):
+    • Developer Experience - Documentation + usability assessment
+    • Portability        - Cross-platform compatibility
+    • External API       - External service detection
+
+Examples:
+  # Profile-based (recommended):
+  mcp-assess-full my-server --profile quick         # CI/CD fast check (~30s)
+  mcp-assess-full my-server --profile security      # Security audit (~2-3min)
+  mcp-assess-full my-server --profile compliance    # Directory submission (~5min)
+  mcp-assess-full my-server --profile full          # Comprehensive audit (~10-15min)
+
+  # Custom module selection:
+  mcp-assess-full my-server --skip-modules temporal,resources  # Skip expensive modules
+  mcp-assess-full my-server --only-modules functionality,toolAnnotations  # Annotation PR review
+
+  # Advanced options:
+  mcp-assess-full --server my-server --source ./my-server --output ./results.json
+  mcp-assess-full --server my-server --format markdown --include-policy
+  mcp-assess-full --server my-server --compare ./baseline.json --diff-only
+  `);
+}