MCP Shamash

Instructions

Implementation Reference

• src/scanners/pentest-scanner.ts:17-84 (handler)

  Core handler implementing the pentest_application tool logic: orchestrates Docker-based scans using OWASP ZAP for web vulnerabilities, custom tests for SQL injection, XSS, and security headers.

  async scan(request: ScanRequest): Promise<ScanResult> {
    const scanId = this.generateScanId();
    const startTime = Date.now();
  
    // Validate URL boundaries
    const validation = await this.boundaryEnforcer.validateUrl(request.target);
    if (!validation.allowed) {
      throw new Error(`URL boundary violation: ${validation.reason}`);
    }
  
    console.error(`Starting pentest scan: ${scanId}`);
  
    const allFindings: Finding[] = [];
    const errors: string[] = [];
    let tokenUsage = 0;
  
    // Determine test types to run
    const testTypes = request.tools || this.getDefaultTests(request.profile);
    
    try {
      // Run OWASP ZAP scan
      if (testTypes.includes('zap') || testTypes.includes('web_scan')) {
        const zapResults = await this.runZAP(request.target, testTypes);
        allFindings.push(...zapResults.findings);
        tokenUsage += zapResults.tokenUsage;
      }
  
      // Run specific vulnerability tests
      if (testTypes.includes('sql_injection')) {
        const sqlResults = await this.testSQLInjection(request.target);
        allFindings.push(...sqlResults.findings);
        tokenUsage += sqlResults.tokenUsage;
      }
  
      if (testTypes.includes('xss')) {
        const xssResults = await this.testXSS(request.target);
        allFindings.push(...xssResults.findings);
        tokenUsage += xssResults.tokenUsage;
      }
  
      if (testTypes.includes('security_headers')) {
        const headerResults = await this.testSecurityHeaders(request.target);
        allFindings.push(...headerResults.findings);
        tokenUsage += headerResults.tokenUsage;
      }
  
    } catch (error) {
      const errorMsg = `Pentest 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,
    };
  
    console.error(`Pentest scan completed: ${result.status}, ${allFindings.length} findings`);
    return result;
  }

• src/core/server.ts:464-486 (handler)

  MCP tool call handler for 'pentest_application' that validates input, prepares ScanRequest, and delegates execution to PentestScanner.

  private async handlePentest(args: any): Promise<ScanResult> {
    const { targetUrl, testTypes = [], depth = 'standard' } = args;
  
    // Validate target URL is within project
    const validation = await this.boundaryEnforcer.validateUrl(targetUrl);
    if (!validation.allowed) {
      throw new McpError(ErrorCode.InvalidRequest, validation.reason || 'URL validation failed');
    }
  
    // Perform pentest
    const request: ScanRequest = {
      type: 'application',
      target: targetUrl,
      profile: depth,
      tools: testTypes,
      options: {
        maxTokens: this.tokenManager.getRemainingTokens(),
        maxDuration: 30 * 60 * 1000, // 30 minutes
      },
    };
  
    return await this.pentestScanner.scan(request);
  }

• src/core/server.ts:112-132 (schema)

  Input schema definition for the pentest_application tool, including parameters targetUrl (required), testTypes, and depth.

  {
    name: 'pentest_application',
    description: 'Performs penetration testing on deployed applications',
    inputSchema: {
      type: 'object',
      properties: {
        targetUrl: { type: 'string', description: 'Application URL' },
        testTypes: {
          type: 'array',
          items: { type: 'string' },
          description: 'Types of tests to perform'
        },
        depth: {
          type: 'string',
          enum: ['quick', 'standard', 'thorough'],
          description: 'Testing depth'
        },
      },
      required: ['targetUrl'],
    },
  },

• src/core/server.ts:265-267 (registration)

  Dispatch registration in the CallToolRequestSchema handler switch statement for routing 'pentest_application' calls to the appropriate handler.

  case 'pentest_application':
    result = await this.handlePentest(args);
    break;