@plosson/vt-js

Unofficial TypeScript/Bun client library for the VirusTotal API v3.

This is an independent port of VirusTotal's official Python library vt-py. It is not affiliated with, endorsed by, or sponsored by VirusTotal.

With this library you can interact with the VirusTotal REST API v3 to scan files and URLs, look up information about files, URLs, domains and IPs, run Intelligence searches, iterate collections, and consume real-time feeds.

Differences from vt-py

This is a faithful port, with a few deliberate, idiomatic adaptations:

• Async-only. JavaScript cannot block on a promise, so every operation returns a Promise. There is no synchronous flavor (vt-py's make_sync).
• Method names are camelCase (getObject, scanFilePrivate, toDict). Data attribute names from the API are preserved as-is (e.g. last_analysis_date).
• Iterators are async iterables — use for await ... of.
• Dynamic objects use a Proxy, preserving obj.sha256 access, transparent date coercion (*_date ↔ Date), and change tracking for patchObject.

Installation

bun add @plosson/vt-js
# or
npm install @plosson/vt-js

Usage

import { Client, urlId, FeedType } from "@plosson/vt-js";

const client = new Client(process.env.VT_API_KEY!, { agent: "my-app" });

// Look up a file by hash (SHA-256, SHA-1 or MD5).
const file = await client.getObject("/files/{}", {
  pathArgs: ["275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f"],
});
console.log(file.type, file.id);
console.log(file.last_analysis_date); // a Date instance

// Look up a domain, IP or URL.
await client.getObject("/domains/{}", { pathArgs: ["google.com"] });
await client.getObject("/ip_addresses/{}", { pathArgs: ["8.8.8.8"] });
await client.getObject("/urls/{}", { pathArgs: [urlId("http://www.google.com/")] });

// Iterate a collection (async).
for await (const comment of client.iterator("/files/{}/comments", {
  pathArgs: [file.id!],
  limit: 10,
})) {
  console.log(comment.text);
}

// VT Intelligence search (premium).
for await (const match of client.iterator("/intelligence/search", {
  params: { query: "type:peexe positives:5+" },
  limit: 20,
})) {
  console.log(match.id);
}

// Scan a file or URL.
const analysis = await client.scanFile(Bun.file("./sample.bin"), {
  waitForCompletion: true,
});
console.log(analysis.get("stats"));

// Consume a real-time feed.
for await (const obj of client.feed(FeedType.FILES)) {
  console.log(obj.id);
}

Development

bun install
bun test          # offline tests (live tests skip without VT_API_KEY)
bun run typecheck
bun run build     # emits dist/ (bundled JS + .d.ts)

To run the live integration tests, copy .env.example to .env and set VT_API_KEY.

License

Apache-2.0. See NOTICE for attribution.