VirusTotal Integration Guide

Overview

The VirusTotal integration allows your NINA workflows to interact with the VirusTotal threat intelligence platform to analyze files, URLs, domains, and IP addresses for malware and security threats. VirusTotal aggregates data from multiple antivirus engines and security services to provide comprehensive threat analysis, making it an essential tool for security operations and incident response workflows.

Status

Supported resources and operations:

• IP Address: Get Report, Get Relationships, Get Comments, Add Comment
• Domain: Get Report, Rescan, Get Relationships, Get Comments, Add Comment
• URL: Analyze, Get Report, Rescan, Get Relationships, Get Comments, Add Comment
• File: Upload File, Get Report, Rescan, Get Relationships, Get Comments, Add Comment

Advanced features:

• Multi-Engine Analysis: Results from 70+ antivirus engines and security services
• Relationship Intelligence: Discover related files, domains, IPs, and URLs
• Community Comments: Access and contribute to community intelligence
• Historical Analysis: Retrieve existing reports without triggering new scans
• Rescan Capability: Request fresh analysis for domains, URLs, and files

Credential Configuration

Authentication Method

API Key

Field	Description	Example
API Key	Your VirusTotal API key	a1b2c3d4e5f6...
Base URL	VirusTotal API base URL (optional)	Leave empty for default v3

Note:

• Recommended: Leave the Base URL field empty to automatically use the v3 API endpoint (https://www.virustotal.com/api/v3)
• Custom URLs: You can specify a custom endpoint if needed
• Automatic v2 to v3 Migration: If you have existing credentials with the old v2 URL (/vtapi/v2), the integration will automatically migrate them to the v3 API (/api/v3) when validated

How to Get Your VirusTotal API Key

1. Create a VirusTotal Account: Go to VirusTotal and sign up for an account (free or premium)
2. Access Your Profile: Click on your username in the top-right corner
3. Navigate to API Key: Select API Key from the dropdown menu
4. Copy Your API Key: Copy the displayed API key

API Tiers:

• Free/Public API: 4 requests per minute, limited features
• Premium API: Higher rate limits, advanced features, and bulk operations

Creating a VirusTotal Credential

1. Navigate to the Credentials section in NINA
2. Click Add New Credential
3. Fill in:
   • Integration Service: "VirusTotal"
   • Auth Type: "API Key"
   • API Key: Your VirusTotal API key
   • Base URL: (Optional) Leave empty for default v3 API, or specify custom endpoint
4. Click Save

Supported Resources and Operations

IP Address

Operation	Name	Description
getReport	Get IP Report	Retrieve threat intelligence report for an IP address
getRelationships	Get Relationships	Retrieve objects related to an IP (resolutions, communicating_files, downloaded_files, referrer_files, urls)
getComments	Get Comments	Retrieve community comments for an IP address
addComment	Add Comment	Add a comment to an IP address

Domain

Operation	Name	Description
getReport	Get Domain Report	Retrieve threat intelligence report for a domain
rescan	Rescan Domain	Request a rescan/reanalysis of a domain
getRelationships	Get Relationships	Retrieve objects related to a domain (resolutions, subdomains, siblings, communicating_files, downloaded_files, referrer_files, urls)
getComments	Get Comments	Retrieve community comments for a domain
addComment	Add Comment	Add a comment to a domain

URL

Operation	Name	Description
analyze	Analyze URL	Submit a URL for analysis
getReport	Get URL Report	Retrieve analysis report for a URL
rescan	Rescan URL	Request a rescan/reanalysis of a URL
getRelationships	Get Relationships	Retrieve objects related to a URL (contacted_domains, contacted_ips, downloaded_files, redirects_to)
getComments	Get Comments	Retrieve community comments for a URL
addComment	Add Comment	Add a comment to a URL

File

Operation	Name	Description
uploadFile	Upload File	Upload a file for malware analysis
getReport	Get File Report	Retrieve analysis report for a file by hash (MD5, SHA1, or SHA256)
rescan	Rescan File	Request a rescan/reanalysis of an existing file
getRelationships	Get Relationships	Retrieve objects related to a file (contacted_domains, contacted_ips, contacted_urls, embedded_domains, embedded_ips)
getComments	Get Comments	Retrieve community comments for a file
addComment	Add Comment	Add a comment to a file

Examples

Get IP Address Report

{
  "integration_service": "virustotal",
  "resource": "ip",
  "operation": "getReport",
  "ip": "8.8.8.8"
}

Get IP Relationships (Communicating Files)

{
  "integration_service": "virustotal",
  "resource": "ip",
  "operation": "getRelationships",
  "ip": "203.0.113.45",
  "relationship": "communicating_files",
  "limit": 20
}

Add Comment to IP

{
  "integration_service": "virustotal",
  "resource": "ip",
  "operation": "addComment",
  "ip": "203.0.113.45",
  "comment": "Known C2 server associated with APT29 campaign. Blocked at firewall."
}

Get Domain Report

{
  "integration_service": "virustotal",
  "resource": "domain",
  "operation": "getReport",
  "domain": "example.com"
}

Rescan Domain

{
  "integration_service": "virustotal",
  "resource": "domain",
  "operation": "rescan",
  "domain": "suspicious-site.com"
}

Get Domain Relationships (Subdomains)

{
  "integration_service": "virustotal",
  "resource": "domain",
  "operation": "getRelationships",
  "domain": "example.com",
  "relationship": "subdomains",
  "limit": 50
}

Analyze URL

{
  "integration_service": "virustotal",
  "resource": "url",
  "operation": "analyze",
  "url": "https://example.com/suspicious-page"
}

Get URL Report

{
  "integration_service": "virustotal",
  "resource": "url",
  "operation": "getReport",
  "urlId": "aHR0cHM6Ly9leGFtcGxlLmNvbS9zdXNwaWNpb3VzLXBhZ2U="
}

Note: urlId can be either the base64 encoded URL or the analysis ID returned from the analyze operation.

Rescan URL

{
  "integration_service": "virustotal",
  "resource": "url",
  "operation": "rescan",
  "urlId": "aHR0cHM6Ly9leGFtcGxlLmNvbS9zdXNwaWNpb3VzLXBhZ2U="
}

Get URL Relationships (Contacted Domains)

{
  "integration_service": "virustotal",
  "resource": "url",
  "operation": "getRelationships",
  "urlId": "aHR0cHM6Ly9leGFtcGxlLmNvbS9zdXNwaWNpb3VzLXBhZ2U=",
  "relationship": "contacted_domains",
  "limit": 30
}

Upload File for Analysis

{
  "integration_service": "virustotal",
  "resource": "file",
  "operation": "uploadFile",
  "fileContent": "UEsDBBQAAAAIAG9h...",
  "filename": "suspicious.exe"
}

Note: fileContent should be base64 encoded file content.

Get File Report by Hash

{
  "integration_service": "virustotal",
  "resource": "file",
  "operation": "getReport",
  "hash": "44d88612fea8a8f36de82e1278abb02f"
}

Supported Hash Types: MD5, SHA1, or SHA256

Rescan File

{
  "integration_service": "virustotal",
  "resource": "file",
  "operation": "rescan",
  "hash": "44d88612fea8a8f36de82e1278abb02f"
}

Get File Relationships (Contacted IPs)

{
  "integration_service": "virustotal",
  "resource": "file",
  "operation": "getRelationships",
  "hash": "44d88612fea8a8f36de82e1278abb02f",
  "relationship": "contacted_ips",
  "limit": 25
}

Get Comments for File

{
  "integration_service": "virustotal",
  "resource": "file",
  "operation": "getComments",
  "hash": "44d88612fea8a8f36de82e1278abb02f",
  "limit": 10
}

Add Comment to File

{
  "integration_service": "virustotal",
  "resource": "file",
  "operation": "addComment",
  "hash": "44d88612fea8a8f36de82e1278abb02f",
  "comment": "Confirmed ransomware. Sample analyzed in sandbox environment. Encrypts files and demands Bitcoin payment."
}

Relationship Types

IP Address Relationships

• resolutions: Domain resolutions for the IP
• communicating_files: Files that communicate with the IP
• downloaded_files: Files downloaded from the IP
• referrer_files: Files that contain the IP
• urls: URLs hosted on the IP

Domain Relationships

• resolutions: IP resolutions for the domain
• subdomains: Subdomains of the domain
• siblings: Sibling domains
• communicating_files: Files that communicate with the domain
• downloaded_files: Files downloaded from the domain
• referrer_files: Files that reference the domain
• urls: URLs associated with the domain

URL Relationships

• contacted_domains: Domains contacted by the URL
• contacted_ips: IP addresses contacted by the URL
• downloaded_files: Files downloaded when accessing the URL
• redirects_to: URLs the original URL redirects to

File Relationships

• contacted_domains: Domains the file contacts
• contacted_ips: IP addresses the file contacts
• contacted_urls: URLs the file contacts
• embedded_domains: Domains embedded in the file
• embedded_ips: IP addresses embedded in the file

Response Structure

Report Objects

VirusTotal reports typically include:

• Attributes: Object metadata (reputation, stats, last_analysis_date, etc.)
• Last Analysis Stats: Detection counts by category (malicious, suspicious, clean, undetected)
• Last Analysis Results: Individual engine verdicts
• Reputation Score: Community reputation score (positive to negative)
• Tags: Community-applied tags
• Categories: Content categorization from various sources

Detection Statistics

{
  "last_analysis_stats": {
    "harmless": 65,
    "malicious": 5,
    "suspicious": 2,
    "undetected": 8,
    "timeout": 0
  }
}

Scan Results

Each antivirus engine provides:

• Engine Name: Name of the security engine
• Category: Detection category (malicious, suspicious, clean, undetected)
• Result: Detection name or null if clean
• Method: Detection method used
• Engine Update: Engine database version date

Best Practices

1. Check Existing Reports First: Use getReport operations before triggering rescans to avoid unnecessary API quota consumption.

2. Respect Rate Limits: Free API keys are limited to 4 requests per minute. Implement proper rate limiting and error handling.

3. Use Hash Lookups: For files, check by hash before uploading to avoid duplicate submissions and save quota.

4. Leverage Relationships: Use relationship operations to discover connected infrastructure and expand threat intelligence.

5. Add Context with Comments: Contribute to the community by adding informative comments about analyzed threats.

6. Monitor Reputation Scores: Use reputation scores as initial indicators, but review detailed analysis results for accuracy.

7. Handle Async Analysis: URL and file analysis may take time to complete. Implement polling or webhook mechanisms for results.

8. Validate Input: Ensure IPs, domains, URLs, and hashes are properly formatted before submission.

9. Base64 Encode URLs: When using URL IDs, ensure URLs are properly base64 encoded without padding.

10. Upgrade for Production: Consider premium API tiers for production environments with higher volume and advanced features.

Troubleshooting

Issue	Resolution
401 Unauthorized	Verify API key is correct and active; check if key has expired
403 Forbidden	Ensure operation is available for your API tier (some features require premium)
404 Not Found	Verify the resource (hash, domain, IP, URL) exists in VirusTotal database
429 Too Many Requests	Rate limit exceeded; implement backoff strategy and reduce request frequency
Analysis not ready	URL/file analysis is still processing; wait and retry after a few minutes
Invalid hash format	Ensure hash is valid MD5 (32 chars), SHA1 (40 chars), or SHA256 (64 chars)
URL encoding issues	Ensure URL is properly base64 encoded for urlId parameters
File too large	Free API has file size limits (32MB); upgrade to premium for larger files
No relationships found	Resource may have no related objects or limited visibility on your API tier

Workflow Context

This integration is particularly useful for:

• Automated Threat Analysis: Automatically analyze suspicious files, URLs, domains, and IPs from emails, logs, or security alerts
• Incident Response: Enrich security incidents with VirusTotal intelligence during investigation workflows
• IOC Enrichment: Enhance indicators of compromise (IOCs) with reputation data and detection statistics
• Threat Hunting: Discover related infrastructure and malware families through relationship analysis
• Phishing Detection: Analyze suspicious URLs and domains from reported phishing emails
• Malware Analysis: Upload suspicious files for multi-engine analysis and behavioral insights
• Security Orchestration: Integrate VirusTotal checks into SOAR workflows for automated decision-making
• Intelligence Sharing: Contribute findings back to the community through comments

Security Considerations

1. Protect API Keys: Store API keys securely; never commit to version control or expose in logs.
2. Data Privacy: Files and URLs submitted to VirusTotal become part of their dataset and may be shared with researchers.
3. Sensitive Files: Avoid uploading proprietary or confidential files to VirusTotal; use private scanning services if needed.
4. False Positives: Not all detections indicate malware; review results carefully before taking action.
5. Premium Features: For sensitive operations, consider premium API with private scanning capabilities.
6. Rate Limiting: Implement proper rate limiting to avoid service disruption and API key suspension.

Additional Resources

• VirusTotal API Documentation
• VirusTotal API v3 Migration Guide
• Understanding VirusTotal Scores
• VirusTotal Premium Plans