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}`); } }