zap.start_active_scan

Instructions

Implementation Reference

• src/tools/zap.ts:126-172 (registration)

  Full registration of the MCP tool 'zap.start_active_scan', defining its input schema, description, and handler function that delegates to ZAPClient.startActiveScan after client check and saves results.

  server.tool(
    'zap.start_active_scan',
    {
      description: 'Start an active vulnerability scan on a target URL',
      inputSchema: {
        type: 'object',
        properties: {
          url: {
            type: 'string',
            description: 'Target URL to scan',
          },
          recurse: {
            type: 'boolean',
            description: 'Whether to recurse into subdirectories (optional)',
          },
          inScopeOnly: {
            type: 'boolean',
            description: 'Only scan URLs in scope (optional)',
          },
          scanPolicyName: {
            type: 'string',
            description: 'Scan policy name to use (optional)',
          },
          method: {
            type: 'string',
            description: 'HTTP method (optional)',
          },
          postData: {
            type: 'string',
            description: 'POST data (optional)',
          },
        },
        required: ['url'],
      },
    },
    async ({ url, recurse, inScopeOnly, scanPolicyName, method, postData }: any): Promise<ToolResult> => {
      const client = getZAPClient();
      if (!client) {
        return formatToolResult(false, null, 'ZAP client not initialized');
      }
      const result = await client.startActiveScan(url, recurse, inScopeOnly, scanPolicyName, method, postData);
      if (result.success) {
        await safeSaveTestResult(url, 'zap_active_scan', true, result.data);
      }
      return formatToolResult(result.success, result.data, result.error);
    }
  );

• src/integrations/zap.ts:148-177 (handler)

  Core handler in ZAPClient class that performs the actual active scan by calling ZAP REST API endpoint /ascan/action/scan/ with parameters and returns scan ID or error.

  async startActiveScan(url: string, recurse?: boolean, inScopeOnly?: boolean, scanPolicyName?: string, method?: string, postData?: string): Promise<ZAPScanResult> {
    try {
      const params: any = { url };
      if (recurse !== undefined) params.recurse = recurse;
      if (inScopeOnly !== undefined) params.inScopeOnly = inScopeOnly;
      if (scanPolicyName) params.scanPolicyName = scanPolicyName;
      if (method) params.method = method;
      if (postData) params.postData = postData;
  
      const response = await this.client.get('/ascan/action/scan/', { params });
      
      // Handle different response formats
      const scanId = response.data.scan || response.data.scanId || response.data;
      if (!scanId && scanId !== 0) {
        throw new Error('No scan ID returned from ZAP');
      }
      
      return {
        success: true,
        data: {
          scanId: scanId.toString(),
        },
      };
    } catch (error: any) {
      return {
        success: false,
        error: error.message || 'Failed to start active scan',
      };
    }
  }

• src/tools/zap.ts:9-24 (helper)

  Helper function used by the tool handler to safely persist scan results to database without crashing on failure.

  async function safeSaveTestResult(
    target: string,
    testType: string,
    success: boolean,
    resultData?: any,
    errorMessage?: string,
    score?: number,
    payload?: string,
    responseData?: string
  ) {
    try {
      await saveTestResult(target, testType, success, resultData, errorMessage, score, payload, responseData);
    } catch (error: any) {
      console.error(`[ZAP] Failed to save test result (${testType}):`, error?.message || error);
    }
  }

• src/tools/zap.ts:128-159 (schema)

  Input schema definition for the zap.start_active_scan tool, specifying parameters like url (required), recurse, inScopeOnly, etc.

  {
    description: 'Start an active vulnerability scan on a target URL',
    inputSchema: {
      type: 'object',
      properties: {
        url: {
          type: 'string',
          description: 'Target URL to scan',
        },
        recurse: {
          type: 'boolean',
          description: 'Whether to recurse into subdirectories (optional)',
        },
        inScopeOnly: {
          type: 'boolean',
          description: 'Only scan URLs in scope (optional)',
        },
        scanPolicyName: {
          type: 'string',
          description: 'Scan policy name to use (optional)',
        },
        method: {
          type: 'string',
          description: 'HTTP method (optional)',
        },
        postData: {
          type: 'string',
          description: 'POST data (optional)',
        },
      },
      required: ['url'],
    },