osint-mcp-server

Instructions

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)"),