shodan_search
Search Shodan's database of internet-connected devices to find detailed information about services, vulnerabilities, and geographic distribution using advanced search filters.
Instructions
Search Shodan's database of internet-connected devices. Returns detailed information about matching devices including services, vulnerabilities, and geographic distribution. Supports advanced search filters and returns country-based statistics.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| max_results | No | Maximum results to return. | |
| query | Yes | Search query for Shodan. |
Implementation Reference
- src/index.ts:421-483 (handler)Handler for the 'shodan_search' tool. Parses arguments using ShodanSearchArgsSchema, queries Shodan API endpoint '/shodan/host/search', formats results with search summary, country facets, and detailed match information (IP, org, location, services, etc.), and returns formatted JSON text content.case "shodan_search": { const parsedSearchArgs = ShodanSearchArgsSchema.safeParse(args); if (!parsedSearchArgs.success) { throw new Error("Invalid search arguments"); } const result: SearchResponse = await queryShodan("/shodan/host/search", { query: parsedSearchArgs.data.query, limit: parsedSearchArgs.data.max_results, }); // Format the response in a user-friendly way const formattedResult = { "Search Summary": { "Query": parsedSearchArgs.data.query, "Total Results": result.total, "Results Returned": result.matches.length }, "Country Distribution": result.facets?.country?.map(country => ({ "Country": country.value, "Count": country.count, "Percentage": `${((country.count / result.total) * 100).toFixed(2)}%` })) || [], "Matches": result.matches.map(match => ({ "Basic Information": { "IP Address": match.ip_str, "Organization": match.org, "ISP": match.isp, "ASN": match.asn, "Last Update": match.timestamp }, "Location": { "Country": match.location.country_name, "City": match.location.city || "Unknown", "Region": match.location.region_code || "Unknown", "Coordinates": `${match.location.latitude}, ${match.location.longitude}` }, "Service Details": { "Port": match.port, "Transport": match.transport, "Product": match.product || "Unknown", "Version": match.version || "Unknown", "CPE": match.cpe || [] }, "Web Information": match.http ? { "Server": match.http.server, "Title": match.http.title, "Robots.txt": match.http.robots ? "Present" : "Not found", "Sitemap": match.http.sitemap ? "Present" : "Not found" } : "No HTTP information", "Hostnames": match.hostnames, "Domains": match.domains })) }; return { content: [ { type: "text", text: JSON.stringify(formattedResult, null, 2), }, ], }; }
- src/index.ts:150-157 (schema)Zod schema for shodan_search input: 'query' (required string) and 'max_results' (optional number, default 10).const ShodanSearchArgsSchema = z.object({ query: z.string().describe("Search query for Shodan."), max_results: z .number() .optional() .default(10) .describe("Maximum results to return."), });
- src/index.ts:321-325 (registration)Tool registration entry in the tools list for ListToolsRequestHandler, specifying name, description, and input schema derived from ShodanSearchArgsSchema.{ name: "shodan_search", description: "Search Shodan's database of internet-connected devices. Returns detailed information about matching devices including services, vulnerabilities, and geographic distribution. Supports advanced search filters and returns country-based statistics.", inputSchema: zodToJsonSchema(ShodanSearchArgsSchema), },