shodan_host
Retrieve comprehensive host intelligence for an IP address, including open ports, services, vulnerabilities, and geolocation data from Shodan's database.
Instructions
Get Shodan host details for an IP: open ports, services, banners, vulns, OS, ASN, geolocation. Requires SHODAN_API_KEY.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ip | Yes | IP address to look up |
Implementation Reference
- src/shodan/index.ts:58-95 (handler)The handler implementation for the `shodan_host` tool. It fetches host details from the Shodan API using the provided IP and API key, performs data transformation, and includes caching.
export async function shodanHost(ip: string, apiKey: string): Promise<ShodanHostResult> { const cacheKey = `host:${ip}`; const cached = cache.get(cacheKey); if (cached) return cached; await limiter.acquire(); const res = await fetch(`https://api.shodan.io/shodan/host/${encodeURIComponent(ip)}?key=${apiKey}`); if (!res.ok) throw new Error(`Shodan host lookup failed: ${res.status} ${res.statusText}`); const data = await res.json(); const services: ShodanService[] = (data.data ?? []).map((s: any) => ({ port: s.port, transport: s.transport ?? "tcp", product: s.product, version: s.version, cpe: s.cpe, banner: s.data ? String(s.data).slice(0, 500) : undefined, })); const result: ShodanHostResult = { ip: data.ip_str ?? ip, hostnames: data.hostnames ?? [], org: data.org, isp: data.isp, os: data.os, asn: data.asn, country: data.country_name, city: data.city, vulns: data.vulns, ports: data.ports ?? [], services, lastUpdate: data.last_update, tags: data.tags, }; cache.set(cacheKey, result); return result; } - src/shodan/index.ts:18-32 (schema)Interface defining the structure of the result returned by `shodan_host`.
interface ShodanHostResult { ip: string; hostnames: string[]; org?: string; isp?: string; os?: string; asn?: string; country?: string; city?: string; vulns?: string[]; ports: number[]; services: ShodanService[]; lastUpdate?: string; tags?: string[]; } - src/protocol/tools.ts:127-144 (registration)Registration of the `shodan_host` tool definition, including the schema and the execution wrapper.
const shodanHostTool: ToolDef = { name: "shodan_host", description: "Get Shodan host details for an IP: open ports, services, banners, vulns, OS, ASN, geolocation. Requires SHODAN_API_KEY.", schema: { ip: z.string().describe("IP address to look up"), }, execute: async (args, ctx) => { const key = requireApiKey(ctx.config.shodanApiKey, "Shodan", "SHODAN_API_KEY"); return json(await shodanHost(args.ip as string, key)); }, }; 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)"),