censys_host_details

Instructions

Implementation Reference

• src/censys/index.ts:101-124 (handler)

  The core handler function `censysHostDetails` that fetches detailed Censys host info for a single IP address via the Censys API v2 `/hosts/{ip}` endpoint.

  export async function censysHostDetails(ip: string, auth: CensysAuth): Promise<CensysHost> {
    const data = await censysFetch("GET", `/hosts/${encodeURIComponent(ip)}`, auth);
    const h = data.result ?? {};
  
    return {
      ip: h.ip ?? ip,
      services: (h.services ?? []).map((s: any) => ({
        port: s.port,
        serviceName: s.service_name ?? s.extended_service_name ?? "",
        transportProtocol: s.transport_protocol ?? "TCP",
        certificate: s.tls?.certificates?.leaf_data?.fingerprint,
      })),
      location: h.location
        ? { country: h.location.country, city: h.location.city, province: h.location.province }
        : undefined,
      autonomousSystem: h.autonomous_system
        ? { asn: h.autonomous_system.asn, name: h.autonomous_system.name, bgpPrefix: h.autonomous_system.bgp_prefix }
        : undefined,
      lastUpdatedAt: h.last_updated_at,
      operatingSystem: h.operating_system
        ? { product: h.operating_system.product, version: h.operating_system.version }
        : undefined,
    };
  }

• src/protocol/tools.ts:290-301 (schema)

  Tool definition including schema (zod validation for `ip` string) and execute wrapper registered under name `censys_host_details`.

  const censysHostDetailsTool: ToolDef = {
    name: "censys_host_details",
    description: "Get detailed Censys host information for a single IP: all services, certificates, OS, location, ASN. Requires CENSYS_API_ID + CENSYS_API_SECRET.",
    schema: {
      ip: z.string().describe("IP address to look up"),
    },
    execute: async (args, ctx) => {
      const id = requireApiKey(ctx.config.censysApiId, "Censys", "CENSYS_API_ID");
      const secret = requireApiKey(ctx.config.censysApiSecret, "Censys", "CENSYS_API_SECRET");
      return json(await censysHostDetails(args.ip as string, { id, secret }));
    },
  };

• src/protocol/tools.ts:509-511 (registration)

  Registration of `censysHostDetailsTool` in the `allTools` array alongside other Censys tools.

  censysHostsTool,
  censysHostDetailsTool,
  censysCertificatesTool,

• src/censys/index.ts:50-65 (helper)

  Helper function `censysFetch` used by the handler to make authenticated API calls to Censys.

  async function censysFetch(method: string, path: string, auth: CensysAuth, body?: any): Promise<any> {
    await limiter.acquire();
    const opts: RequestInit = {
      method,
      headers: {
        Authorization: authHeader(auth),
        Accept: "application/json",
        ...(body ? { "Content-Type": "application/json" } : {}),
      },
      ...(body ? { body: JSON.stringify(body) } : {}),
    };
  
    const res = await fetch(`${CENSYS_BASE}${path}`, opts);
    if (!res.ok) throw new Error(`Censys API error: ${res.status} ${res.statusText}`);
    return res.json();
  }

• src/censys/index.ts:46-48 (helper)

  Helper function `authHeader` that generates the Basic auth header for Censys API authentication.

  function authHeader(auth: CensysAuth): string {
    return "Basic " + btoa(`${auth.id}:${auth.secret}`);
  }