threat_intel_get_file_relationships
Extract network IOCs and file relationships from a file hash to pivot from malware samples to domains, IPs, and related files.
Instructions
Get relationships for a file hash from VirusTotal (network IOCs and related files).
This tool extracts relationship data from a file's VirusTotal analysis, revealing network infrastructure (domains, IPs, URLs) contacted by the file, as well as related files. This is essential for pivoting from files to network indicators and building comprehensive threat intelligence profiles.
Available relationship types:
contacted_domains: Domains contacted during execution
contacted_ips: IP addresses contacted during execution
contacted_urls: URLs contacted during execution
similar_files: Files with similar characteristics
execution_parents: Files that executed this file
bundled_files: Files bundled/dropped by this file
compressed_parents: Archives containing this file
overlay_parents: Parent files with overlays
What this tool provides:
Network infrastructure IOCs (domains, IPs, URLs)
File lineage and relationships
Dropped/bundled files
Similar malware samples
Execution chain information
Common Use Cases:
Extract network IOCs from malware samples
Build threat intelligence from file analysis
Pivot from files to domains/IPs for blocking
Identify related malware families
Map malware infrastructure and campaigns
Enrich incident response with related indicators
Args: hash_value: The file hash (MD5, SHA1, or SHA256) to query. relationship_type: The type of relationship to retrieve (e.g., 'contacted_domains').
Returns: JSON string containing: - relationships: Array of related objects with full details (up to 100) - count: Number of relationships found
Examples: hash_value="275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f", relationship_type="contacted_domains"
hash_value="44d88612fea8a8f36de82e1278abb02f",
relationship_type="contacted_ips"Notes: - Requires a valid VirusTotal API key (PURPLEMCP_VT_API_KEY environment variable) - Returns up to 100 relationships (the API maximum) - Not all files have all relationship types - Relationship data comes from sandbox execution - Private API keys have access to more relationship types - When a hash or relationship is not found, returns a structured JSON response with found=false - IMPORTANT: Do NOT call this tool repeatedly with the same parameters. It returns the same data each time, not additional results.
Raises: ThreatIntelligenceClientError: If there's an error communicating with the API. RuntimeError: If the API key is not configured.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| hash_value | Yes | ||
| relationship_type | Yes |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |