censys_certificates

Search Censys certificate database to find SSL/TLS certificate details including fingerprints, subjects, issuers, validity periods, and SANs for security analysis.

Instructions

Search Censys certificate database. Returns certificate fingerprints, subjects, issuers, validity, and SANs. Requires CENSYS_API_ID + CENSYS_API_SECRET.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`query`	Yes	Certificate search query (e.g. 'parsed.names: example.com')
`per_page`	No	Results per page (max 100, default: 25)

Implementation Reference

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

Implementation of the censysCertificates function which queries the Censys API for certificates.

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

Registration of the censys_certificates tool in the protocol layer, invoking the censysCertificates function.

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:29-42 (schema)

Type definitions for certificate search results (CensysCert, 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;
}

osint-mcp-server