Skip to main content

Migrating Custom API Code and Enrichment Pipelines to Spectra Intelligence

Security teams and security vendors that call the VirusTotal API directly, in custom scripts, enrichment pipelines, internal tooling, or embedded product features, can now move those calls to Spectra Intelligence by changing only a base URL and an API key. The response schema, field names, and authentication pattern are preserved, saving time and effort when migrating.

SOAR and SIEM platforms ship pre-built VT connectors maintained by platform vendors and reconfigured inside the platform, not through direct API calls. The audience for the VirusTotal Compatible API Suite is different: engineers who write code that calls the VT API directly, and security companies that have embedded VT calls into their own products. For that class of integration, the compatibility layer, a Spectra Intelligence endpoint that accepts VT v3 requests and returns VT v3 responses, reduces migration to just a configuration change.

Integration patterns this covers​

Custom Python scripts using the vt-py SDK​

The official VirusTotal Python client, vt-py, is the most common way engineers write custom VT integrations. Its vt.Client constructor accepts a host parameter that overrides the default base URL. Redirecting a vt-py-based script to the RL VT-compatible endpoint requires one additional constructor argument:

# Before
client = vt.Client(apikey=VT_API_KEY)


# After — one parameter added, all downstream calls unchanged
client = vt.Client(
    apikey=RL_API_KEY,
    host="https://data.reversinglabs.com",
)


# Existing code continues to work without modification
file = client.get_object("/files/{}", sha256)
print(file.last_analysis_stats)   # {'malicious': 14, 'undetected': 58}
caution

The vt-py host= parameter is documented as overridable for testing purposes. Compatibility covers file and URL reputation lookups. SDK features that depend on VT-specific capabilities, retrohunt, file feeds, VT Intelligence search, have no RL equivalent behind this layer.

Direct HTTP calls with requests or other HTTP clients​

Scripts that call the VT v3 API directly via requests or equivalent HTTP libraries typically hardcode the base URL as a constant alongside the API key. Changing those two values is the entire migration:

# Before
VT_BASE = "https://www.virustotal.com/api/v3/"
headers = {"x-apikey": VT_API_KEY}
resp = requests.get(VT_BASE + "files/" + sha256, headers=headers)


# After — two values changed, everything else untouched
RL_BASE = "https://data.reversinglabs.com/api/v3/"
headers = {"x-apikey": RL_API_KEY}
resp = requests.get(RL_BASE + sha256, headers=headers)


# Response parsing is identical
stats = resp.json()["data"]["attributes"]["last_analysis_stats"]
if stats["malicious"] > threshold:
    alert(sha256)
caution

Base URL paths above are sourced from internal product documentation. Confirm exact paths against official RL documentation before deploying.

The API suite​

Two endpoints cover the file and URL reputation lookups that account for the majority of direct VT API usage:

APIEndpointQuery input
File ReportGET /api/v3/files/{hash}MD5, SHA-1, or SHA-256
URL ReportGET /api/v3/urls/{urlid}SHA-1 URL identifier or base64-encoded URL (no padding)

Both use x-apikey header authentication. Base host: https://data.reversinglabs.com.

File Report response fields​

{ "data": { "id": "<SHA-256>", "attributes": {
    "sha256": "...", "sha1": "...", "md5": "...",
    "last_analysis_stats": { "malicious": 14, "undetected": 58 },
    "last_analysis_results": {
      "BitDefender": { "engine_name": "BitDefender",
                       "category": "malicious",
                       "result": "Trojan.GenericKD.71234567" }
    },
    "first_submission_date": 1706745600,
    "last_analysis_date":    1712345678
} } }
Response fieldDescription
sha256 / sha1 / md5All three hashes for the queried sample
last_analysis_stats.maliciousCount of engines returning a malicious verdict
last_analysis_stats.undetectedCount of engines with no detection
last_analysis_results[n].engine_nameName of the scanning engine
last_analysis_results[n].categorymalicious or undetected
last_analysis_results[n].resultThreat name string, or null
first_submission_date / last_analysis_dateUnix epoch seconds

URL Report response fields​

Response fieldDescription
urlHuman-readable URL
last_analysis_statsmalicious / suspicious / harmless / undetected counts
last_analysis_results[n].engine_nameName of the reputation source
last_analysis_results[n].categorymalicious, suspicious, harmless, or undetected
last_analysis_results[n].threat_namesList of threat name strings, or empty
first_submission_date / last_analysis_dateUnix epoch seconds

What does not change across both patterns​

  • Authentication header name (x-apikey)
  • HTTP method (GET for both endpoints)
  • Hash input types (MD5, SHA-1, SHA-256)
  • JSON response field names and nesting structure
  • Timestamp format (Unix epoch seconds)

Bulk workflows​

The v3-compatible endpoints mirror VT v3's single-item GET design. Scripts that loop over a list of hashes calling the VT API sequentially work without modification, and VT v3 itself does not support batch file report lookups, so this is not a regression. For high-volume batch lookup, RL provides a separate bulk endpoint at POST /api/xref/v2/bulk_query/{format} on data.reversinglabs.com, which accepts a JSON body with a list of hashes. This endpoint uses a different request format and response schema from the v3-compatible layer and requires a separate integration path.

Enterprise and security vendor use cases​

Beyond individual enrichment scripts, several other major use cases benefit from the same plug and play compatibility, in which the response schema, field names, and auth header are unchanged.

Incident response and malware triage tooling​

IR teams frequently build and maintain internal hash-vetting tools: scripts or lightweight applications that accept a list of hashes extracted from a memory dump, disk image, or alert queue, query VT for each one, and return a verdict table sorted by malicious count. These tools are rarely documented and often owned by a single analyst. The compatibility layer means an IR team can redirect an existing triage tool to Spectra Intelligence without involving the analyst who originally wrote it, the tool's output logic, threshold checks, and report formatting all continue to work.

Alert enrichment pipelines feeding a TIP or data lake​

Some enterprises build custom enrichment pipelines outside their SOAR platform: a Python service or Lambda function that consumes alert events from a queue, queries VT for each hash or URL, and writes enriched records back to a TIP, data lake, or ticketing system. These pipelines parse specific VT response fields, typically last_analysis_stats.malicious, last_analysis_results per-engine verdicts, and submission timestamps, into an internal schema. Redirecting the upstream query to RL changes the intelligence source without touching the field extraction logic or the downstream write operations.

Security product vendors and MSSPs embedding reputation lookup​

Security ISVs and MSSPs frequently embed third-party file or URL reputation lookups directly into their own products. The customer interacts with the vendor's interface; the VT API call happens in the product backend, not in customer-controlled code. For vendors in this situation, VT's OEM pricing model has historically tied cost to how much reputation data is surfaced to end users: broader result display and customer awareness of the underlying provider increases license cost.

The RL VT-compatible layer applies directly here. A vendor whose product initializes a vt.Client or issues requests.get calls against the VT v3 endpoint can redirect those calls to RL Spectra Intelligence by changing the client constructor or base URL constant in their codebase. The product's output logic, which reads last_analysis_stats and last_analysis_results to generate a verdict display, requires no modification. Data handling also changes: Spectra Intelligence does not share submitted samples with public repositories by default, which removes a common data handling concern when vendors analyze customer-provided files.

Email gateway and file transfer enrichment​

Custom integrations at email gateways and secure file transfer systems often include a step that hashes inbound attachments and queries a reputation service for a quick triage verdict before routing or quarantining. These integrations are commonly implemented as Python scripts or lightweight services calling the VT file report endpoint, parsing last_analysis_stats.malicious against a configured threshold. The compatibility layer allows these integrations to be redirected to Spectra Intelligence without modifying the threshold logic, the quarantine routing, or the logging format.

CI/CD pipeline artifact scanning​

Development and DevSecOps teams sometimes instrument build pipelines to hash build artifacts and query a reputation service before promoting a build or deploying to production. The check is typically a simple requests.get call against the VT file report endpoint, with a pass/fail based on last_analysis_stats.malicious. Redirecting this to Spectra Intelligence, a change to the base URL and API key in the pipeline's environment configuration, gives the same pass/fail behavior backed by RL's complex binary analysis engine, without modifying the pipeline logic itself.

Scope boundary​

The VT Compatible API Suite covers file and URL reputation lookup. It does not replace:

  • Pre-built VT/GTI connector plugins for SOAR, SIEM, or EDR platforms; those are reconfigured inside the platform.
  • VT Intelligence search, retrohunt, YARA LiveHunt, or file feeds; no RL equivalent sits behind this compatibility layer.
  • RL's native Spectra Intelligence API, which provides a richer data model including MITRE ATT&CK mappings, behavioral classification, certificate chain data, and JSON-body bulk query support.

Teams whose VT usage is primarily file and URL reputation lookup, the dominant pattern in custom scripts, IR tooling, enrichment pipelines, and embedded product features, can migrate that surface completely. Teams with heavy VT Intelligence usage should evaluate RL's native Spectra Intelligence APIs directly.

Conclusion​

Custom code that calls the VT API depends on VT's JSON schema, not on VirusTotal as a platform. Because the RL VT Compatible API Suite preserves that schema, the same field names, the same nesting structure, the same x-apikey header, the same epoch-seconds timestamps, the intelligence source behind a lookup can be changed without touching the code that consumes the response. For vt-py users, that is one added constructor parameter. For requests-based scripts, it is two constant values. For security vendors with embedded VT calls in their product, it is a change to a client initialization in their own codebase.

Keep learning​