MCP Shamash

Instructions

Implementation Reference

• src/core/server.ts:393-441 (handler)

  Primary MCP tool handler for 'scan_project'. Validates input, enforces boundaries, supports incremental scanning, applies false positive filtering, and delegates core scanning to ProjectScanner.scan()

  private async handleProjectScan(args: any): Promise<ScanResult> {
    const { path, profile = 'standard', tools, incremental = false } = args;
  
    // Validate project boundaries
    const validation = await this.boundaryEnforcer.validatePath(path);
    if (!validation.allowed) {
      throw new McpError(ErrorCode.InvalidRequest, validation.reason || 'Path validation failed');
    }
  
    // Perform scan
    const request: ScanRequest = {
      type: 'project',
      target: path,
      profile,
      tools,
      options: {
        maxTokens: this.tokenManager.getRemainingTokens(),
        incremental,
      },
    };
  
    // Use incremental scanner if requested
    if (incremental && this.incrementalScanner) {
      const result = await this.incrementalScanner.scan(request);
      
      // Apply false positive filtering
      if (this.falsePositiveFilter) {
        const filterResults = await this.falsePositiveFilter.filterFindings(result.findings);
        result.findings = filterResults.filter(r => !r.filtered).map(r => r.finding);
        
        // Add filter stats to result
        const filterStats = this.falsePositiveFilter.getStatistics(filterResults);
        console.error(`Filtered ${filterStats.filtered} false positives (${filterStats.filterRate.toFixed(1)}%)`);
      }
      
      return result;
    }
  
    // Regular scan
    const result = await this.projectScanner.scan(request);
    
    // Apply false positive filtering
    if (this.falsePositiveFilter) {
      const filterResults = await this.falsePositiveFilter.filterFindings(result.findings);
      result.findings = filterResults.filter(r => !r.filtered).map(r => r.finding);
    }
    
    return result;
  }

• src/scanners/project-scanner.ts:30-115 (handler)

  Core implementation of project scanning logic. Orchestrates multiple security tools (Semgrep, Trivy, Gitleaks, Checkov, etc.), supports caching, parallel execution, and aggregates findings from all scanners.

  async scan(request: ScanRequest): Promise<ScanResult> {
    const scanId = this.generateScanId();
    const startTime = Date.now();
  
    // Validate boundaries
    const validation = await this.boundaryEnforcer.validatePath(request.target);
    if (!validation.allowed) {
      throw new Error(`Boundary violation: ${validation.reason}`);
    }
  
    // Determine which tools to run
    const tools = request.tools || this.getDefaultTools(request.profile);
    
    // Check cache first
    const cachedResult = await this.cache.get('project', request.target, tools, request.profile);
    if (cachedResult) {
      console.error(`Cache hit for project scan: ${scanId}`);
      // Update scan ID and timing for the cached result
      cachedResult.scanId = scanId;
      cachedResult.scanTimeMs = Date.now() - startTime;
      return cachedResult;
    }
  
    console.error(`Starting project scan: ${scanId} with tools: ${tools.join(', ')}`);
  
    const allFindings: Finding[] = [];
    const errors: string[] = [];
    let tokenUsage = 0;
  
    // Determine execution strategy
    const useParallel = request.options?.parallel !== false && tools.length > 1;
    
    if (useParallel) {
      // Run scanners in parallel
      const scanResults = await this.runScannersInParallel(request.target, tools);
      
      // Aggregate results
      for (const result of scanResults.results) {
        if (result.status === 'success' && result.result) {
          allFindings.push(...result.result.findings);
          tokenUsage += result.result.tokenUsage;
        } else if (result.status === 'error') {
          const errorMsg = `${result.id} failed: ${result.error?.message}`;
          console.error(errorMsg);
          errors.push(errorMsg);
        }
      }
    } else {
      // Run scanners sequentially
      for (const tool of tools) {
        try {
          console.error(`Running ${tool} scanner...`);
          
          const scanResult = await this.runSingleScanner(tool, request.target);
          allFindings.push(...scanResult.findings);
          tokenUsage += scanResult.tokenUsage;
          
        } catch (error) {
          const errorMsg = `${tool} failed: ${error instanceof Error ? error.message : 'Unknown error'}`;
          console.error(errorMsg);
          errors.push(errorMsg);
        }
      }
    }
  
    // Calculate summary
    const summary = this.calculateSummary(allFindings);
  
    const result: ScanResult = {
      scanId,
      status: errors.length === 0 ? 'success' : (allFindings.length > 0 ? 'partial' : 'failed'),
      summary,
      findings: allFindings,
      tokenUsage,
      scanTimeMs: Date.now() - startTime,
      errors: errors.length > 0 ? errors : undefined,
    };
  
    // Cache successful results
    if (result.status === 'success') {
      await this.cache.set('project', request.target, tools, result, request.profile);
    }
  
    console.error(`Project scan completed: ${result.status}, ${allFindings.length} findings`);
    return result;
  }

• src/core/server.ts:74-97 (schema)

  Tool registration and input schema definition for 'scan_project' in the MCP tools list returned by ListToolsRequestHandler.

  {
    name: 'scan_project',
    description: 'Performs comprehensive security scan on project directory',
    inputSchema: {
      type: 'object',
      properties: {
        path: { type: 'string', description: 'Project path to scan' },
        profile: { 
          type: 'string', 
          enum: ['quick', 'standard', 'thorough'],
          description: 'Scan profile'
        },
        tools: {
          type: 'array',
          items: { type: 'string' },
          description: 'Specific tools to use'
        },
        incremental: {
          type: 'boolean',
          description: 'Use incremental scanning if available'
        },
      },
      required: ['path'],
    },

• src/core/server.ts:256-259 (registration)

  Tool dispatch registration in the central CallToolRequestHandler switch statement.

  switch (name) {
    case 'scan_project':
      result = await this.handleProjectScan(args);
      break;

• src/scanners/project-scanner.ts:816-839 (helper)

  Helper function that dispatches to individual scanner implementations (Semgrep, Trivy, Gitleaks, etc.) based on tool name.

  private async runSingleScanner(tool: string, targetPath: string): Promise<{ findings: Finding[]; tokenUsage: number }> {
    switch (tool) {
      case 'semgrep':
        return await this.runSemgrep(targetPath);
      case 'trivy':
        return await this.runTrivy(targetPath);
      case 'gitleaks':
        return await this.runGitleaks(targetPath);
      case 'checkov':
        return await this.runCheckov(targetPath);
      case 'nuclei':
        return await this.runNuclei(targetPath);
      case 'bandit':
        return await this.runBandit(targetPath);
      case 'grype':
        return await this.runGrype(targetPath);
      case 'custom_rules':
        return await this.runCustomRules(targetPath);
      case 'owasp_dependency_check':
        return await this.runOwaspDependencyCheck(targetPath);
      default:
        throw new Error(`Unknown scanner tool: ${tool}`);
    }
  }