zap.start_spider

Instructions

Implementation Reference

• src/tools/zap.ts:86-96 (handler)

  MCP tool handler for 'zap.start_spider': initializes ZAP client, starts spider scan via client.startSpider(), saves test result if successful, and formats the tool result.

  async ({ url, maxChildren, recurse, contextName }: any): Promise<ToolResult> => {
    const client = getZAPClient();
    if (!client) {
      return formatToolResult(false, null, 'ZAP client not initialized');
    }
    const result = await client.startSpider(url, maxChildren, recurse, contextName);
    if (result.success) {
      await safeSaveTestResult(url, 'zap_spider', true, result.data);
    }
    return formatToolResult(result.success, result.data, result.error);
  }

• src/tools/zap.ts:63-84 (schema)

  Input schema for 'zap.start_spider' tool: requires 'url', optional 'maxChildren', 'recurse', 'contextName'.

  inputSchema: {
    type: 'object',
    properties: {
      url: {
        type: 'string',
        description: 'Target URL to spider',
      },
      maxChildren: {
        type: 'number',
        description: 'Maximum number of children to crawl (optional)',
      },
      recurse: {
        type: 'boolean',
        description: 'Whether to recurse into subdirectories (optional)',
      },
      contextName: {
        type: 'string',
        description: 'Context name to use (optional)',
      },
    },
    required: ['url'],
  },

• src/tools/zap.ts:59-97 (registration)

  Registers the 'zap.start_spider' tool on the MCP server within registerZAPTools function.

  server.tool(
    'zap.start_spider',
    {
      description: 'Start a spider (crawler) scan on a target URL',
      inputSchema: {
        type: 'object',
        properties: {
          url: {
            type: 'string',
            description: 'Target URL to spider',
          },
          maxChildren: {
            type: 'number',
            description: 'Maximum number of children to crawl (optional)',
          },
          recurse: {
            type: 'boolean',
            description: 'Whether to recurse into subdirectories (optional)',
          },
          contextName: {
            type: 'string',
            description: 'Context name to use (optional)',
          },
        },
        required: ['url'],
      },
    },
    async ({ url, maxChildren, recurse, contextName }: any): Promise<ToolResult> => {
      const client = getZAPClient();
      if (!client) {
        return formatToolResult(false, null, 'ZAP client not initialized');
      }
      const result = await client.startSpider(url, maxChildren, recurse, contextName);
      if (result.success) {
        await safeSaveTestResult(url, 'zap_spider', true, result.data);
      }
      return formatToolResult(result.success, result.data, result.error);
    }
  );

• src/integrations/zap.ts:92-119 (helper)

  ZAPClient.startSpider method: core implementation that calls ZAP REST API /spider/action/scan/ to start the spider scan and returns scan ID.

  async startSpider(url: string, maxChildren?: number, recurse?: boolean, contextName?: string): Promise<ZAPScanResult> {
    try {
      const params: any = { url };
      if (maxChildren) params.maxChildren = maxChildren;
      if (recurse !== undefined) params.recurse = recurse;
      if (contextName) params.contextName = contextName;
  
      const response = await this.client.get('/spider/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 spider scan',
      };
    }
  }

• src/index.ts:49-49 (registration)

  Top-level call to registerZAPTools(server) which includes registration of 'zap.start_spider'.

  registerZAPTools(server);