shodan_search
Search internet-connected devices in Shodan's database to identify services, vulnerabilities, and geographic distribution using advanced 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 |
|---|---|---|---|
| query | Yes | Search query for Shodan. | |
| max_results | No | Maximum results to return. |
Implementation Reference
- src/index.ts:421-483 (handler)Implements the shodan_search tool handler: parses input arguments, queries the Shodan host/search API, formats the search results including summary, country distribution, and detailed matches with IP info, location, services, and web details.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 defining input for shodan_search: query string and optional max_results (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)Registers the shodan_search tool in the MCP server's tool list with name, description, and converted JSON schema.{ 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), },