vt_url
Scan URLs with VirusTotal to detect malicious, suspicious, or harmless content through comprehensive security analysis.
Instructions
Submit a URL to VirusTotal for scanning and get analysis results (malicious/suspicious/harmless). Requires VT_API_KEY.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | URL to scan |
Implementation Reference
- src/virustotal/index.ts:127-159 (handler)Implementation of the vtUrl function which submits a URL to VirusTotal for analysis and attempts to fetch the analysis results.
export async function vtUrl(url: string, apiKey: string): Promise<VtUrlResult> { // Submit URL for analysis await limiter.acquire(); const submitRes = await fetch(`${VT_BASE}/urls`, { method: "POST", headers: { "x-apikey": apiKey, "Content-Type": "application/x-www-form-urlencoded" }, body: `url=${encodeURIComponent(url)}`, }); if (!submitRes.ok) throw new Error(`VirusTotal URL submit failed: ${submitRes.status}`); const submitData = await submitRes.json(); const analysisId = submitData.data?.id; if (!analysisId) { return { url, status: "submitted", analysisId: undefined }; } // Try to get analysis results (may not be ready yet) try { const analysisData = await vtFetch(`/analyses/${analysisId}`, apiKey); if (analysisData?.data?.attributes?.status === "completed") { return { url, analysisId, analysisStats: analysisData.data.attributes.stats, status: "completed", }; } return { url, analysisId, status: analysisData?.data?.attributes?.status ?? "queued" }; } catch { return { url, analysisId, status: "queued" }; } } - src/virustotal/index.ts:45-50 (schema)TypeScript interface defining the result structure for vtUrl analysis.
interface VtUrlResult { url: string; analysisId?: string; analysisStats?: VtAnalysisStats; status: string; } - src/protocol/tools.ts:219-229 (registration)Registration of the vt_url tool, defining its metadata and the execution logic calling vtUrl.
const vtUrlTool: ToolDef = { name: "vt_url", description: "Submit a URL to VirusTotal for scanning and get analysis results (malicious/suspicious/harmless). Requires VT_API_KEY.", schema: { url: z.string().describe("URL to scan"), }, execute: async (args, ctx) => { const key = requireApiKey(ctx.config.vtApiKey, "VirusTotal", "VT_API_KEY"); return json(await vtUrl(args.url as string, key)); }, };