st_dns_history
Retrieve historical DNS records for a domain, including first and last seen dates, values, and organizations. Specify record type (A, AAAA, MX, NS, SOA, TXT).
Instructions
Get historical DNS records for a domain via SecurityTrails. Shows first/last seen dates, values, and organizations. Requires ST_API_KEY.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes | Domain to get DNS history for | |
| type | Yes | DNS record type |
Implementation Reference
- src/securitytrails/index.ts:61-76 (handler)The main handler function for st_dns_history. Calls SecurityTrails API at /history/{domain}/dns/{type}, parses records with first/last seen dates, values, and organizations.
export async function stDnsHistory(domain: string, type: string, apiKey: string): Promise<StDnsHistoryResult> { const validTypes = ["a", "aaaa", "mx", "ns", "soa", "txt"]; const t = type.toLowerCase(); if (!validTypes.includes(t)) throw new Error(`Invalid DNS type: ${type}. Valid: ${validTypes.join(", ")}`); const data = await stFetch(`/history/${encodeURIComponent(domain)}/dns/${t}`, apiKey); const records: StDnsHistoryRecord[] = (data.records ?? []).map((r: any) => ({ values: (r.values ?? []).map((v: any) => v.ip ?? v.host ?? v.value ?? String(v)), type: r.type ?? t, firstSeen: r.first_seen ?? "", lastSeen: r.last_seen ?? "", organizations: r.organizations, })); return { domain, type: t, records, total: records.length }; } - src/securitytrails/index.ts:15-28 (schema)Type definitions for DNS history records and result structure.
interface StDnsHistoryRecord { values: string[]; type: string; firstSeen: string; lastSeen: string; organizations?: string[]; } interface StDnsHistoryResult { domain: string; type: string; records: StDnsHistoryRecord[]; total: number; } - src/protocol/tools.ts:247-258 (registration)Tool registration definition for st_dns_history. Registers the tool with name, description, Zod schema (domain + type enum), and execute handler that calls stDnsHistory.
const stDnsHistoryTool: ToolDef = { name: "st_dns_history", description: "Get historical DNS records for a domain via SecurityTrails. Shows first/last seen dates, values, and organizations. Requires ST_API_KEY.", schema: { domain: z.string().describe("Domain to get DNS history for"), type: z.enum(["a", "aaaa", "mx", "ns", "soa", "txt"]).describe("DNS record type"), }, execute: async (args, ctx) => { const key = requireApiKey(ctx.config.stApiKey, "SecurityTrails", "ST_API_KEY"); return json(await stDnsHistory(args.domain as string, args.type as string, key)); }, }; - src/index.ts:38-38 (registration)Tool listing in the main index, showing st_dns_history as a SecurityTrails tool requiring ST_API_KEY.
{ label: "SecurityTrails", env: "ST_API_KEY", tools: ["st_subdomains", "st_dns_history", "st_whois"] }, - src/securitytrails/index.ts:42-49 (helper)Helper function stFetch used by stDnsHistory to make authenticated HTTP requests to the SecurityTrails API with rate limiting.
async function stFetch(path: string, apiKey: string): Promise<any> { await limiter.acquire(); const res = await fetch(`${ST_BASE}${path}`, { headers: { APIKEY: apiKey, Accept: "application/json" }, }); if (!res.ok) throw new Error(`SecurityTrails API error: ${res.status} ${res.statusText}`); return res.json(); }