censys_hosts
Search Censys for hosts matching specific criteria to identify IP addresses, services, ports, location data, and ASN information for reconnaissance and attack surface mapping.
Instructions
Search Censys for hosts matching a query. Returns IPs, services, ports, location, ASN. Requires CENSYS_API_ID + CENSYS_API_SECRET.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Censys search query | |
| per_page | No | Results per page (max 100, default: 25) |
Implementation Reference
- src/censys/index.ts:69-97 (handler)The handler function that executes the censys_hosts tool logic by calling the Censys API.
export async function censysHosts(query: string, auth: CensysAuth, perPage = 25): Promise<CensysHostsResult> { const data = await censysFetch("POST", "/hosts/search", auth, { q: query, per_page: Math.min(perPage, 100), }); const result = data.result ?? {}; const hosts: CensysHost[] = (result.hits ?? []).map((h: any) => ({ ip: h.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.certificate, })), 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, })); return { total: result.total ?? 0, hosts, query }; } - src/censys/index.ts:23-27 (schema)Schema/Interface defining the structure of the Censys host search result.
interface CensysHostsResult { total: number; hosts: CensysHost[]; query: string; } - src/protocol/tools.ts:276-287 (registration)Registration of the 'censys_hosts' tool definition in the protocol tools file.
const censysHostsTool: ToolDef = { name: "censys_hosts", description: "Search Censys for hosts matching a query. Returns IPs, services, ports, location, ASN. Requires CENSYS_API_ID + CENSYS_API_SECRET.", schema: { query: z.string().describe("Censys search query"), per_page: z.number().optional().describe("Results per page (max 100, default: 25)"), }, 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 censysHosts(args.query as string, { id, secret }, args.per_page as number | undefined)); },