censys_certificates

Instructions

Implementation Reference

• src/protocol/tools.ts:303-315 (registration)

  ToolDef registration for 'censys_certificates' with schema (query, per_page) and execute handler that calls the censysCertificates function with API credentials.

  const censysCertificatesTool: ToolDef = {
    name: "censys_certificates",
    description: "Search Censys certificate database. Returns certificate fingerprints, subjects, issuers, validity, and SANs. Requires CENSYS_API_ID + CENSYS_API_SECRET.",
    schema: {
      query: z.string().describe("Certificate search query (e.g. 'parsed.names: example.com')"),
      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 censysCertificates(args.query as string, { id, secret }, args.per_page as number | undefined));
    },
  };

• src/censys/index.ts:128-149 (handler)

  Main handler for censys_certificates — calls Censys API v2 POST /certificates/search, maps results to CensysCert objects with fingerprint, subject, issuer, validity, and names.

  export async function censysCertificates(query: string, auth: CensysAuth, perPage = 25): Promise<CensysCertsResult> {
    const data = await censysFetch("POST", "/certificates/search", auth, {
      q: query,
      per_page: Math.min(perPage, 100),
    });
  
    const result = data.result ?? {};
    const certificates: CensysCert[] = (result.hits ?? []).map((c: any) => ({
      fingerprint: c.fingerprint_sha256 ?? c.fingerprint ?? "",
      subject: c.parsed?.subject
        ? { commonName: c.parsed.subject.common_name?.[0], organization: c.parsed.subject.organization?.[0] }
        : undefined,
      issuer: c.parsed?.issuer
        ? { commonName: c.parsed.issuer.common_name?.[0], organization: c.parsed.issuer.organization?.[0] }
        : undefined,
      validityStart: c.parsed?.validity?.start,
      validityEnd: c.parsed?.validity?.end,
      names: c.names ?? c.parsed?.names ?? [],
    }));
  
    return { total: result.total ?? 0, certificates, query };
  }

• src/censys/index.ts:29-42 (schema)

  Type definitions for certificate search results (CensysCert and CensysCertsResult).

  interface CensysCert {
    fingerprint: string;
    subject?: { commonName?: string; organization?: string };
    issuer?: { commonName?: string; organization?: string };
    validityStart?: string;
    validityEnd?: string;
    names: string[];
  }
  
  interface CensysCertsResult {
    total: number;
    certificates: CensysCert[];
    query: string;
  }

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

  Generic HTTP helper for Censys API calls — handles auth headers, rate limiting, and JSON parsing.

  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/protocol/tools.ts:511-511 (registration)

  Tool included in the exported list of all tool definitions.

  censysCertificatesTool,