search_iot_devices
Find specific types of internet-connected IoT devices like webcams or routers using Shodan's cybersecurity research data. Filter by country and limit results for threat intelligence analysis.
Instructions
Search for specific types of IoT devices
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| device_type | Yes | Type of IoT device to search for (e.g., 'webcam', 'router', 'smart tv') | |
| country | No | Optional country code to limit search (e.g., 'US', 'DE') | |
| max_items | No | Maximum number of items to include in results (default: 5) |
Implementation Reference
- src/index.ts:1459-1501 (handler)MCP CallTool handler for 'search_iot_devices' that extracts parameters, calls ShodanClient.searchIotDevices method, handles errors, and returns JSON-formatted results.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:276-329 (helper)ShodanClient.searchIotDevices method: constructs Shodan search query for IoT devices, fetches data from Shodan API, samples results, extracts relevant fields, and handles API 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:982-1002 (schema)Tool schema definition including input schema for 'search_iot_devices' registered in ListTools handler.{ 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"] }
- src/index.ts:982-1002 (registration)Registration of 'search_iot_devices' tool in the ListToolsRequestSchema response, defining name, description, and input schema.{ 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"] }