shodan_search
Query Shodan to find internet-connected devices and services matching specific criteria. Retrieve host IPs, open ports, banners, and metadata for reconnaissance and attack surface analysis.
Instructions
Search Shodan for hosts matching a query (e.g. 'apache port:443 country:US'). Requires SHODAN_API_KEY.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Shodan search query | |
| page | No | Results page number (default: 1) | |
| facets | No | Facets to include (e.g. 'country,org') |
Implementation Reference
- src/shodan/index.ts:99-122 (handler)The actual implementation of shodanSearch — calls the Shodan API /shodan/host/search endpoint, parses the response into ShodanSearchResult (total, matches, facets).
export async function shodanSearch(query: string, apiKey: string, page = 1, facets?: string): Promise<ShodanSearchResult> { await limiter.acquire(); const params = new URLSearchParams({ key: apiKey, query, page: String(page) }); if (facets) params.set("facets", facets); const res = await fetch(`https://api.shodan.io/shodan/host/search?${params}`); if (!res.ok) throw new Error(`Shodan search failed: ${res.status} ${res.statusText}`); const data = await res.json(); return { total: data.total ?? 0, matches: (data.matches ?? []).map((m: any) => ({ ip_str: m.ip_str, port: m.port, org: m.org, hostnames: m.hostnames ?? [], product: m.product, os: m.os, asn: m.asn, domains: m.domains ?? [], })), facets: data.facets, }; } - src/shodan/index.ts:34-49 (schema)Type definitions for ShodanSearchMatch and ShodanSearchResult — the input/output shapes used by the search handler.
interface ShodanSearchMatch { ip_str: string; port: number; org?: string; hostnames: string[]; product?: string; os?: string; asn?: string; domains: string[]; } interface ShodanSearchResult { total: number; matches: ShodanSearchMatch[]; facets?: Record<string, [string, number][]>; } - src/protocol/tools.ts:139-151 (registration)Tool registration definition for shodan_search — maps the name, description, Zod schema (query, page, facets), and execute handler that calls the shodanSearch function.
const shodanSearchTool: ToolDef = { name: "shodan_search", description: "Search Shodan for hosts matching a query (e.g. 'apache port:443 country:US'). Requires SHODAN_API_KEY.", schema: { query: z.string().describe("Shodan search query"), page: z.number().optional().describe("Results page number (default: 1)"), facets: z.string().optional().describe("Facets to include (e.g. 'country,org')"), }, execute: async (args, ctx) => { const key = requireApiKey(ctx.config.shodanApiKey, "Shodan", "SHODAN_API_KEY"); return json(await shodanSearch(args.query as string, key, args.page as number | undefined, args.facets as string | undefined)); }, }; - src/protocol/tools.ts:11-11 (registration)Import of shodanSearch from the shodan module into the tools registry.
import { shodanHost, shodanSearch, shodanDnsResolve, shodanExploits } from "../shodan/index.js"; - src/protocol/tools.ts:496-496 (registration)The shodanSearchTool is included in the allTools array for export.
shodanSearchTool,