vt_ip
Analyze an IP address with VirusTotal to retrieve reputation, detection statistics, country, ASN, and network information. Requires a VirusTotal API key.
Instructions
VirusTotal IP analysis: reputation, detection stats, country, ASN, network. Requires VT_API_KEY.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ip | Yes | IP address to analyze |
Implementation Reference
- src/virustotal/index.ts:92-113 (handler)The vtIp function is the core handler for the vt_ip tool. It calls the VirusTotal /ip_addresses/{ip} API endpoint, caches results with a 10-minute TTL, and returns IP reputation, analysis stats, country, ASN, AS owner, and network info.
export async function vtIp(ip: string, apiKey: string): Promise<VtIpResult> { const cacheKey = `vt:ip:${ip}`; const cached = cache.get(cacheKey); if (cached) return cached; const data = await vtFetch(`/ip_addresses/${encodeURIComponent(ip)}`, apiKey); if (!data) throw new Error(`IP ${ip} not found on VirusTotal`); const attrs = data.data?.attributes ?? {}; const result: VtIpResult = { ip, reputation: attrs.reputation ?? 0, analysisStats: attrs.last_analysis_stats ?? { malicious: 0, suspicious: 0, undetected: 0, harmless: 0 }, country: attrs.country, asn: attrs.asn, asOwner: attrs.as_owner, network: attrs.network, }; cache.set(cacheKey, result); return result; } - src/virustotal/index.ts:29-37 (schema)VtIpResult interface defines the output schema for vt_ip: ip, reputation, analysisStats (malicious/suspicious/undetected/harmless counts), country, asn, asOwner, and network.
interface VtIpResult { ip: string; reputation: number; analysisStats: VtAnalysisStats; country?: string; asn?: number; asOwner?: string; network?: string; } - src/protocol/tools.ts:194-204 (registration)Registration of the vt_ip tool as a ToolDef: name 'vt_ip', description, Zod schema (ip: string), and execute handler that extracts API key from config and calls the vtIp function.
const vtIpTool: ToolDef = { name: "vt_ip", description: "VirusTotal IP analysis: reputation, detection stats, country, ASN, network. Requires VT_API_KEY.", schema: { ip: z.string().describe("IP address to analyze"), }, execute: async (args, ctx) => { const key = requireApiKey(ctx.config.vtApiKey, "VirusTotal", "VT_API_KEY"); return json(await vtIp(args.ip as string, key)); }, }; - src/virustotal/index.ts:54-62 (helper)Generic vtFetch helper used by vtIp — rate-limited fetch to the VirusTotal v3 API with JSON parsing and 404 handling.
async function vtFetch(path: string, apiKey: string): Promise<any> { await limiter.acquire(); const res = await fetch(`${VT_BASE}${path}`, { headers: { "x-apikey": apiKey }, }); if (res.status === 404) return null; if (!res.ok) throw new Error(`VirusTotal API error: ${res.status} ${res.statusText}`); return res.json(); } - src/index.ts:37-37 (registration)Tool listing registration: 'vt_ip' is listed under the VirusTotal provider group, requiring VT_API_KEY environment variable.
{ label: "VirusTotal", env: "VT_API_KEY", tools: ["vt_domain", "vt_ip", "vt_subdomains", "vt_url"] },