@bryan-thompson/inspector-assessment-client 1.25.0 → 1.25.4

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

@@ -3,56 +3,183 @@
  * Categorizes MCP tools based on name/description to select appropriate security test patterns
  *
  * Validated against broken-mcp server with 16 tools (6 HIGH, 4 MEDIUM, 6 SAFE)
+ *
+ * ## Pattern Matching Design
+ *
+ * This classifier uses two types of regex patterns intentionally:
+ *
+ * 1. **Substring patterns** (e.g., `/calculator/i`): Match anywhere in the text.
+ *    Used for HIGH-risk category keywords that should trigger even when embedded.
+ *    Example: "recalculator_v2" matches CALCULATOR because any calculator-like
+ *    tool warrants security scrutiny.
+ *
+ * 2. **Word boundary patterns** (e.g., `/\bget\b/i`): Match isolated words only.
+ *    Used for common words that would cause false positives as substrings.
+ *    Example: "target_selector" should NOT match DATA_ACCESS's `/\bget\b/` pattern.
+ *
+ * **Underscore vs Hyphen Behavior:**
+ * - Word boundaries (`\b`) treat hyphens as boundaries but underscores as word characters
+ * - `api-get-data` matches `/\bget\b/` (hyphen is boundary)
+ * - `api_get_data` does NOT match `/\bget\b/` (underscore is word char)
+ * - This is intentional: underscore-joined names are typically single identifiers
+ *
+ * See tests in ToolClassifier.test.ts for comprehensive pattern behavior validation.
+ *
+ * @module ToolClassifier
+ */
+import { ToolCategory, type RiskLevel } from "./tool-classifier-patterns.js";
+export { ToolCategory };
+export type { RiskLevel };
+/**
+ * Result of classifying a tool into security categories.
+ *
+ * @example
+ * ```typescript
+ * const result: ToolClassification = {
+ *   toolName: 'vulnerable_calculator_tool',
+ *   categories: [ToolCategory.CALCULATOR],
+ *   confidence: 90,
+ *   reasoning: 'Calculator pattern detected (arithmetic execution risk)'
+ * };
+ * ```
  */
-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",
-    GENERIC = "generic"
-}
 export interface ToolClassification {
+    /** The original tool name that was classified */
     toolName: string;
+    /** One or more categories the tool was classified into */
     categories: ToolCategory[];
+    /** Confidence score from 0-100 (averaged if multiple categories) */
     confidence: number;
+    /** Human-readable explanation of why these categories were assigned */
     reasoning: string;
 }
 /**
  * Classifies MCP tools into vulnerability categories based on naming patterns
- * and descriptions. Uses patterns validated by testing against broken-mcp server.
+ * and descriptions. Uses pre-compiled patterns for optimal performance.
+ *
+ * The classifier is stateless and thread-safe - multiple classifications can
+ * run concurrently without interference.
+ *
+ * @example
+ * ```typescript
+ * const classifier = new ToolClassifier();
+ *
+ * // Single classification
+ * const result = classifier.classify('vulnerable_calculator_tool');
+ * console.log(result.categories);  // [ToolCategory.CALCULATOR]
+ * console.log(result.confidence);  // 90
+ *
+ * // Batch classification
+ * const tools = [
+ *   { name: 'calculator_tool' },
+ *   { name: 'search_api', description: 'Search for documents' }
+ * ];
+ * const results = classifier.classifyBatch(tools);
+ * ```
  */
 export declare class ToolClassifier {
+    /** Maximum input length to prevent ReDoS with pathological inputs */
+    private static readonly MAX_INPUT_LENGTH;
     /**
-     * Classify a tool into one or more categories
-     * Returns multiple categories if tool matches multiple patterns
+     * Classify a tool into one or more security risk categories.
+     *
+     * The classifier analyzes both the tool name and optional description,
+     * matching against pre-compiled regex patterns for each category.
+     * A tool may match multiple categories if it contains multiple patterns.
+     *
+     * @param toolName - The MCP tool name to classify (e.g., "vulnerable_calculator_tool")
+     * @param description - Optional tool description for additional pattern matching
+     * @returns Classification result with categories, confidence score (0-100), and reasoning
+     *
+     * @example
+     * ```typescript
+     * const classifier = new ToolClassifier();
+     *
+     * // Basic classification by name
+     * const calc = classifier.classify('calculator_tool');
+     * // { toolName: 'calculator_tool', categories: ['calculator'], confidence: 90, ... }
+     *
+     * // Classification with description
+     * const tool = classifier.classify('my_tool', 'Executes shell commands');
+     * // { toolName: 'my_tool', categories: ['system_exec'], confidence: 95, ... }
+     *
+     * // Multi-category match
+     * const multi = classifier.classify('calc_exec_command');
+     * // { categories: ['calculator', 'system_exec'], confidence: 92, ... }
+     * ```
+     *
+     * @throws Never throws - returns GENERIC category for invalid inputs
      */
     classify(toolName: string, description?: string): ToolClassification;
     /**
-     * Check if text matches any of the provided patterns
+     * Check if text matches any of the provided patterns.
+     * Limits input length to prevent ReDoS attacks with very long strings.
+     *
+     * @param text - The text to search in (tool name + description)
+     * @param patterns - Pre-compiled regex patterns to match against
+     * @returns True if any pattern matches
      */
     private matchesPattern;
     /**
-     * Get all tool categories (for testing/debugging)
+     * Get all available tool categories.
+     *
+     * Useful for testing, debugging, or building UI components that need
+     * to display all possible categories.
+     *
+     * @returns Array of all ToolCategory enum values
+     *
+     * @example
+     * ```typescript
+     * const allCategories = ToolClassifier.getAllCategories();
+     * console.log(allCategories.length); // 17
+     * ```
      */
     static getAllCategories(): ToolCategory[];
     /**
-     * Get risk level for a category
+     * Get the security risk level for a category.
+     *
+     * Risk levels help prioritize security testing:
+     * - **HIGH**: Requires thorough security testing (code execution, data access)
+     * - **MEDIUM**: Requires moderate security testing (encoding bypass, supply chain)
+     * - **LOW**: Safe categories that typically don't need security testing
+     *
+     * @param category - The category to get the risk level for
+     * @returns Risk level: "HIGH", "MEDIUM", or "LOW"
+     *
+     * @example
+     * ```typescript
+     * ToolClassifier.getRiskLevel(ToolCategory.SYSTEM_EXEC); // "HIGH"
+     * ToolClassifier.getRiskLevel(ToolCategory.JSON_PARSER); // "MEDIUM"
+     * ToolClassifier.getRiskLevel(ToolCategory.SAFE_STORAGE); // "LOW"
+     * ```
      */
-    static getRiskLevel(category: ToolCategory): "HIGH" | "MEDIUM" | "LOW";
+    static getRiskLevel(category: ToolCategory): RiskLevel;
     /**
-     * Classify multiple tools at once
+     * Classify multiple tools at once.
+     *
+     * More efficient than calling classify() in a loop when you have
+     * many tools to process. The classifier is stateless, so batch
+     * processing produces identical results to individual calls.
+     *
+     * @param tools - Array of tools with name and optional description
+     * @returns Array of classification results in the same order as input
+     *
+     * @example
+     * ```typescript
+     * const classifier = new ToolClassifier();
+     * const tools = [
+     *   { name: 'calculator_tool' },
+     *   { name: 'search_api', description: 'Search documents' },
+     *   { name: 'unknown_tool' }
+     * ];
+     *
+     * const results = classifier.classifyBatch(tools);
+     * // [
+     * //   { toolName: 'calculator_tool', categories: ['calculator'], ... },
+     * //   { toolName: 'search_api', categories: ['search_retrieval'], ... },
+     * //   { toolName: 'unknown_tool', categories: ['generic'], ... }
+     * // ]
+     * ```
      */
     classifyBatch(tools: Array<{
         name: string;

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

@@ -1 +1 @@
-{"version":3,"file":"ToolClassifier.d.ts","sourceRoot":"","sources":["../../../src/services/assessment/ToolClassifier.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,oBAAY,YAAY;IACtB,UAAU,eAAe;IACzB,WAAW,gBAAgB;IAC3B,aAAa,kBAAkB;IAC/B,WAAW,gBAAgB;IAC3B,aAAa,kBAAkB;IAC/B,eAAe,oBAAoB;IACnC,WAAW,YAAY;IACvB,iBAAiB,YAAY;IAC7B,WAAW,WAAW;IACtB,iBAAiB,cAAc;IAC/B,QAAQ,aAAa;IACrB,YAAY,iBAAiB;IAC7B,WAAW,gBAAgB;IAC3B,gBAAgB,qBAAqB;IACrC,aAAa,kBAAkB;IAC/B,cAAc,mBAAmB;IACjC,OAAO,YAAY;CACpB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,YAAY,EAAE,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,qBAAa,cAAc;IACzB;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,kBAAkB;IAwWpE;;OAEG;IACH,OAAO,CAAC,cAAc;IAItB;;OAEG;IACH,MAAM,CAAC,gBAAgB,IAAI,YAAY,EAAE;IAIzC;;OAEG;IACH,MAAM,CAAC,YAAY,CAAC,QAAQ,EAAE,YAAY,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK;IAiCtE;;OAEG;IACH,aAAa,CACX,KAAK,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,GACnD,kBAAkB,EAAE;CAGxB"}
+{"version":3,"file":"ToolClassifier.d.ts","sourceRoot":"","sources":["../../../src/services/assessment/ToolClassifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAIL,YAAY,EACZ,KAAK,SAAS,EACf,MAAM,4BAA4B,CAAC;AAGpC,OAAO,EAAE,YAAY,EAAE,CAAC;AACxB,YAAY,EAAE,SAAS,EAAE,CAAC;AAE1B;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,kBAAkB;IACjC,iDAAiD;IACjD,QAAQ,EAAE,MAAM,CAAC;IACjB,0DAA0D;IAC1D,UAAU,EAAE,YAAY,EAAE,CAAC;IAC3B,oEAAoE;IACpE,UAAU,EAAE,MAAM,CAAC;IACnB,uEAAuE;IACvE,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,cAAc;IACzB,qEAAqE;IACrE,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAEjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,kBAAkB;IAkDpE;;;;;;;OAOG;IACH,OAAO,CAAC,cAAc;IAStB;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,gBAAgB,IAAI,YAAY,EAAE;IAIzC;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,CAAC,YAAY,CAAC,QAAQ,EAAE,YAAY,GAAG,SAAS;IAatD;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,aAAa,CACX,KAAK,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,GACnD,kBAAkB,EAAE;CAGxB"}