search_iot_devices
Identify and locate IoT devices globally by specifying device type, country, and result limit using Shodan API for cybersecurity research and threat intelligence.
Instructions
Search for specific types of IoT devices
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| country | No | Optional country code to limit search (e.g., 'US', 'DE') | |
| device_type | Yes | Type of IoT device to search for (e.g., 'webcam', 'router', 'smart tv') | |
| max_items | No | Maximum number of items to include in results (default: 5) |
Implementation Reference
- src/index.ts:276-329 (handler)Core handler function in ShodanClient that performs the IoT device search using Shodan API, builds query, processes results, and handles errors.async searchIotDevices(deviceType: string, country?: string, maxItems: number = 5): Promise<any> { try { // Build query based on device type and optional country let query = `"${deviceType}"`; if (country) { query += ` country:${country}`; } const response = await this.axiosInstance.get("/shodan/host/search", { params: { query } }); const results = this.sampleResponse(response.data, maxItems); // Extract relevant IoT device information if (results.matches && results.matches.length > 0) { const devices = results.matches.map((match: any) => { return { ip: match.ip_str, port: match.port, organization: match.org, location: match.location, hostnames: match.hostnames, product: match.product, version: match.version, timestamp: match.timestamp }; }); return { total_found: results.total, sample_size: devices.length, devices: devices }; } return { total_found: 0, devices: [] }; } 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 IoT device search 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:1459-1501 (registration)MCP server handler registration for 'search_iot_devices' tool in the CallToolRequestSchema switch statement, validates params and calls the core handler.case "search_iot_devices": { const deviceType = String(request.params.arguments?.device_type); if (!deviceType) { throw new McpError( ErrorCode.InvalidParams, "Device type is required" ); } const country = request.params.arguments?.country ? String(request.params.arguments.country) : undefined; const maxItems = Number(request.params.arguments?.max_items) || 5; try { const iotDevices = await shodanClient.searchIotDevices(deviceType, country, maxItems); // Check if we got an error response from the IoT devices search method if (iotDevices.error && iotDevices.status === 401) { return { content: [{ type: "text", text: JSON.stringify(iotDevices, null, 2) }] }; } return { content: [{ type: "text", text: JSON.stringify(iotDevices, null, 2) }] }; } catch (error) { if (error instanceof McpError) { throw error; } throw new McpError( ErrorCode.InternalError, `Error searching for IoT devices: ${(error as Error).message}` ); } }
- src/index.ts:983-1002 (schema)Tool schema definition including input schema for validation, listed in ListToolsRequestSchema response.name: "search_iot_devices", description: "Search for specific types of IoT devices", inputSchema: { type: "object", properties: { device_type: { type: "string", description: "Type of IoT device to search for (e.g., 'webcam', 'router', 'smart tv')" }, country: { type: "string", description: "Optional country code to limit search (e.g., 'US', 'DE')" }, max_items: { type: "number", description: "Maximum number of items to include in results (default: 5)" } }, required: ["device_type"] }