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; }