scan_network_range
Scan a network range in CIDR notation to discover internet-connected devices and gather cybersecurity intelligence using Shodan's database.
Instructions
Scan a network range (CIDR notation) for devices
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cidr | Yes | Network range in CIDR notation (e.g., 192.168.1.0/24) | |
| max_items | No | Maximum number of items to include in results (default: 5) | |
| fields | No | List of fields to include in the results (e.g., ['ip_str', 'ports', 'location.country_name']) |
Implementation Reference
- src/index.ts:1376-1418 (handler)MCP CallToolRequestSchema handler case for 'scan_network_range' that validates input parameters (cidr required), calls shodanClient.scanNetworkRange, handles 401 unauthorized responses from Shodan paid API, and returns JSON-formatted results or errors.case "scan_network_range": { const cidr = String(request.params.arguments?.cidr); if (!cidr) { throw new McpError( ErrorCode.InvalidParams, "CIDR notation is required" ); } const maxItems = Number(request.params.arguments?.max_items) || 5; const fields = Array.isArray(request.params.arguments?.fields) ? request.params.arguments?.fields.map(String) : undefined; try { const scanResults = await shodanClient.scanNetworkRange(cidr, maxItems, fields); // Check if we got an error response from the scan method if (scanResults.error && scanResults.status === 401) { return { content: [{ type: "text", text: JSON.stringify(scanResults, null, 2) }] }; } return { content: [{ type: "text", text: JSON.stringify(scanResults, null, 2) }] }; } catch (error) { if (error instanceof McpError) { throw error; } throw new McpError( ErrorCode.InternalError, `Error scanning network range: ${(error as Error).message}` ); } }
- src/index.ts:189-213 (helper)Core implementation in ShodanClient class that translates CIDR to Shodan 'net:' query, performs API search, samples/truncates results using sampleResponse, filters fields if specified, and handles API errors including requirement for paid Shodan membership.async scanNetworkRange(cidr: string, maxItems: number = 5, selectedFields?: string[]): Promise<any> { try { // Convert CIDR to Shodan search query format const query = `net:${cidr}`; const response = await this.axiosInstance.get("/shodan/host/search", { params: { query } }); return this.sampleResponse(response.data, maxItems, selectedFields); } catch (error: unknown) { if (axios.isAxiosError(error)) { if (error.response?.status === 401) { return { error: "Unauthorized: The Shodan search API requires a paid membership. Your API key does not have access to this endpoint.", message: "The network scanning functionality requires a Shodan membership subscription with API access. Please upgrade your Shodan plan to use this feature.", status: 401 }; } throw new McpError( ErrorCode.InternalError, `Shodan API error: ${error.response?.data?.error || error.message}` ); } throw error; } }
- src/index.ts:946-966 (schema)Zod/JSON schema definition for tool inputs: requires 'cidr' string, optional 'max_items' number for result limiting, optional 'fields' array for response filtering.inputSchema: { type: "object", properties: { cidr: { type: "string", description: "Network range in CIDR notation (e.g., 192.168.1.0/24)" }, max_items: { type: "number", description: "Maximum number of items to include in results (default: 5)" }, fields: { type: "array", items: { type: "string" }, description: "List of fields to include in the results (e.g., ['ip_str', 'ports', 'location.country_name'])" } }, required: ["cidr"] }
- src/index.ts:943-967 (registration)Tool registration entry in ListToolsRequestSchema handler's tools array, defining name, description, and complete inputSchema for client discovery.{ name: "scan_network_range", description: "Scan a network range (CIDR notation) for devices", inputSchema: { type: "object", properties: { cidr: { type: "string", description: "Network range in CIDR notation (e.g., 192.168.1.0/24)" }, max_items: { type: "number", description: "Maximum number of items to include in results (default: 5)" }, fields: { type: "array", items: { type: "string" }, description: "List of fields to include in the results (e.g., ['ip_str', 'ports', 'location.country_name'])" } }, required: ["cidr"] } },