Skip to content

w33ts/virustotal-api-skill

virustotal-api

Verified

Comprehensive reference for the VirusTotal API v3, covering authentication, rate limits, endpoint usage, and the critical differences between Free (Public) and Premium (Enterprise) tiers. Use this skill whenever a user asks about VirusTotal, VT API, scanning files or URLs with VirusTotal, threat intelligence lookups, IoC enrichment, YARA hunting, Retrohunt, Livehunt, VT Intelligence search, VT Graph, VT Monitor, VT Feeds, private scanning, malware analysis via VirusTotal, or building integrations with the VirusTotal API. Also trigger when the user mentions "VT", "virustotal", hash lookups, file reputation checks, URL scanning services, sandbox detonation reports, or any workflow involving programmatic interaction with VirusTotal's threat intelligence platform β€” even if they don't say "API" explicitly.

FileKindSize
SKILL.mdexecutableskill md16.4 KB
references/endpoints-enterprise.mdexecutablescript13.8 KB
references/endpoints-free.mdexecutablescript11.2 KB
references/objects-and-relationships.mdexecutablescript13.3 KB

references/objects-and-relationships.md

View on GitHub
# VirusTotal API v3 β€” Objects & Relationships Reference

This reference documents the main API object types, their key attributes, and relationship
mappings. Items marked πŸ”’ require enterprise access.

---

## Table of Contents

1. [Object Structure](#object-structure)
2. [File Object](#file-object)
3. [URL Object](#url-object)
4. [Domain Object](#domain-object)
5. [IP Address Object](#ip-address-object)
6. [Comment Object](#comment-object)
7. [Analysis Object](#analysis-object)
8. [File Behaviour Object](#file-behaviour-object)
9. [Graph Object](#graph-object)
10. [Hunting Objects](#hunting-objects)
11. [Other Objects](#other-objects)
12. [Relationship Access Matrix](#relationship-access-matrix)

---

## Object Structure

Every VT API object follows this pattern:

```json
{
  "type": "<object_type>",
  "id": "<unique_identifier>",
  "links": {
    "self": "https://www.virustotal.com/api/v3/<type>/<id>"
  },
  "attributes": { ... },
  "relationships": { ... }
}
```

Relationships are not included by default. Request them explicitly:
```
GET /api/v3/files/{id}?relationships=contacted_domains,dropped_files
```

Or fetch them separately:
```
GET /api/v3/files/{id}/contacted_domains
```

---

## File Object

**Type:** `file`
**ID:** SHA-256 hash

### Key attributes

| Attribute | Description |
|-----------|-------------|
| `sha256`, `sha1`, `md5` | File hashes |
| `size` | File size in bytes |
| `type_description` | Human-readable file type |
| `type_tag` | Short type tag (e.g., `peexe`, `pdf`, `doc`) |
| `meaningful_name` | Most meaningful filename from submissions |
| `names` | All known filenames |
| `tags` | Auto-generated tags |
| `creation_date` | File creation timestamp |
| `first_submission_date` | When first submitted to VT |
| `last_submission_date` | When last submitted |
| `last_analysis_date` | When last analyzed |
| `last_analysis_stats` | Detection summary counts |
| `last_analysis_results` | Per-engine results |
| `reputation` | Community reputation score |
| `total_votes` | Vote counts (harmless/malicious) |
| `popular_threat_classification` | Categorized threat type |
| `sigma_analysis_stats` | Sigma rule match statistics |
| `sigma_analysis_results` | Sigma rule matches |
| `crowdsourced_yara_results` | YARA rule matches |
| `crowdsourced_ids_results` | IDS (Snort/Suricata) results |
| `sandbox_verdicts` | Sandbox detection verdicts |
| `pe_info` | PE header information (for executables) |
| `elf_info` | ELF header information (for Linux binaries) |
| `macho_info` | Mach-O information (for macOS binaries) |
| `pdf_info` | PDF structure information |
| `androguard` | Android APK analysis |
| `signature_info` | Digital signature details |
| `ssdeep`, `tlsh`, `telfhash` | Fuzzy hashes for similarity matching |
| `detectiteasy` | Detect-It-Easy packer/compiler identification |
| `magic` | File magic string |
| πŸ”’ `exiftool` | ExifTool metadata |
| πŸ”’ `malware_config` | Extracted malware configuration |
| πŸ”’ `office_info` | Office document details |
| πŸ”’ `openxml_info` | OpenXML document details |
| πŸ”’ `rtf_info` | RTF document details |

### File relationships

**Free access:**
- `behaviours` β€” Sandbox behavior reports
- `bundled_files` β€” Files inside archives/bundles
- `collections` β€” VT collections containing this file
- `comments` β€” Community comments
- `contacted_domains` β€” Domains contacted in sandbox
- `contacted_ips` β€” IPs contacted in sandbox
- `contacted_urls` β€” URLs contacted in sandbox
- `dropped_files` β€” Files dropped during execution
- `execution_parents` β€” Files that spawned this file
- `graphs` β€” VT Graph references
- `pe_resource_children` / `pe_resource_parents` β€” PE resource links
- `sigma_analysis` β€” Sigma rule analysis
- `memory_pattern_domains` / `memory_pattern_ips` / `memory_pattern_urls` β€” Memory-extracted IOCs
- `votes` β€” Community votes

**πŸ”’ Enterprise only:**
- `analyses` β€” Submission analyses history
- `carbonblack_children` / `carbonblack_parents` β€” Carbon Black telemetry
- `compressed_parents` β€” Archives containing this file
- `email_attachments` / `email_parents` β€” Email relationships
- `embedded_domains` / `embedded_ips` / `embedded_urls` β€” Statically embedded IOCs
- `itw_domains` / `itw_ips` / `itw_urls` β€” In-the-wild distribution infrastructure
- `overlay_children` / `overlay_parents` β€” PE overlay relationships
- `pcap_children` / `pcap_parents` β€” PCAP relationships
- `related_references` β€” Threat intelligence references
- `related_threat_actors` β€” Associated threat actors
- `screenshots` β€” Sandbox execution screenshots
- `similar_files` β€” Structurally similar files
- `submissions` β€” Submission history with metadata
- `urls_for_embedded_js` β€” URLs hosting embedded JavaScript

---

## URL Object

**Type:** `url`
**ID:** Base64url-encoded URL (no padding)

### Key attributes

| Attribute | Description |
|-----------|-------------|
| `url` | The actual URL string |
| `last_http_response_content_length` | Response size |
| `last_http_response_content_sha256` | SHA-256 of response body |
| `last_http_response_code` | HTTP status code |
| `last_analysis_stats` | Detection summary |
| `last_analysis_results` | Per-engine results |
| `last_analysis_date` | When last analyzed |
| `reputation` | Community reputation score |
| `total_votes` | Vote counts |
| `tags` | Auto-generated tags |
| `categories` | Categorization by various vendors |
| `title` | Page title |
| `html_meta` | HTML meta tags |
| `trackers` | Detected tracking technologies |
| `last_final_url` | URL after redirects |

---

## Domain Object

**Type:** `domain`
**ID:** Domain name string

### Key attributes

| Attribute | Description |
|-----------|-------------|
| `last_analysis_stats` | Detection summary |
| `last_analysis_results` | Per-engine results |
| `registrar` | Domain registrar |
| `creation_date` | Domain registration date |
| `last_dns_records` | Current DNS records |
| `last_https_certificate` | Current SSL certificate |
| `popularity_ranks` | Rankings from various services |
| `categories` | Categorization by vendors |
| `whois` | WHOIS data |
| `reputation` | Community reputation |
| `total_votes` | Vote counts |
| `tags` | Auto-generated tags |

---

## IP Address Object

**Type:** `ip_address`
**ID:** IP address string

### Key attributes

| Attribute | Description |
|-----------|-------------|
| `last_analysis_stats` | Detection summary |
| `last_analysis_results` | Per-engine results |
| `asn` | Autonomous System Number |
| `as_owner` | AS owner name |
| `country` | Country code |
| `continent` | Continent code |
| `network` | CIDR network |
| `regional_internet_registry` | RIR (ARIN, RIPE, etc.) |
| `last_https_certificate` | Current SSL cert |
| `whois` | WHOIS data |
| `reputation` | Community reputation |
| `total_votes` | Vote counts |
| `tags` | Auto-generated tags |

---

## Comment Object

**Type:** `comment`
**ID:** Comment ID string

### Key attributes
- `text` β€” Comment body (supports VT's hashtag and IoC linking syntax)
- `date` β€” Creation timestamp
- `votes` β€” Vote counts on the comment
- `html` β€” Rendered HTML version

### Relationships
- `author` β€” User who wrote the comment

---

## Analysis Object

**Type:** `analysis`
**ID:** Analysis ID (returned by scan/rescan endpoints)

### Key attributes
- `status` β€” `queued`, `in-progress`, or `completed`
- `stats` β€” Detection count summary (when completed)
- `results` β€” Per-engine results (when completed)
- `date` β€” Analysis timestamp

### Relationships
- `item` β€” The file or URL that was analyzed

---

## File Behaviour Object

**Type:** `file_behaviour`

### Key attributes
- `sandbox_name` β€” Name of the sandbox that produced the report
- `analysis_date` β€” When the analysis was performed
- `tags` β€” Behavior tags
- `verdicts` β€” Sandbox verdicts
- `dns_lookups` β€” DNS queries made
- `http_conversations` β€” HTTP request/response pairs
- `ip_traffic` β€” Network traffic to IPs
- `processes_tree` β€” Process execution tree
- `files_dropped` β€” Files created during execution
- `files_copied` β€” Files copied
- `files_opened` / `files_written` / `files_deleted` β€” File system activity
- `registry_keys_opened` / `registry_keys_set` / `registry_keys_deleted` β€” Registry activity
- `mutexes_created` / `mutexes_opened` β€” Synchronization primitives
- `command_executions` β€” Commands executed
- `modules_loaded` β€” DLLs/modules loaded
- `services_created` / `services_started` β€” Windows services
- `permissions_checked` β€” Android permissions
- `sms_sent` β€” SMS messages (Android)

### Relationships
- `file` β€” The analyzed file
- `attack_techniques` β€” MITRE ATT&CK techniques observed

---

## Graph Object

**Type:** `graph`
**ID:** Graph ID string

### Key attributes
- `graph_data` β€” JSON structure of nodes and links
- `label` β€” Graph name
- `owner` β€” Creator user ID

### Relationships
- `comments`, `editors`, `group`, `items`, `owner`, `viewers`

---

## Hunting Objects

### Hunting Ruleset (πŸ”’)
- `type: "hunting_ruleset"`
- Attributes: `name`, `enabled`, `rules` (YARA source), `limit`, `match_object_type`
- Relationships: `owner`, `editors`, `viewers`, `hunting_notification_files`

### Hunting Notification (πŸ”’)
- `type: "hunting_notification"`
- Attributes: `date`, `source_key`, `rule_name`, `tags`

### Retrohunt Job (πŸ”’)
- `type: "retrohunt_job"`
- Attributes: `rules`, `status`, `progress`, `scanned_bytes`, `matching_files`
- Relationships: `matching_files`, `owner`

---

## Other Objects

| Object | Type | Description |
|--------|------|-------------|
| Resolution | `resolution` | DNS resolution record (domain ↔ IP) |
| SSL Certificate | `ssl_certificate` | TLS/SSL certificate details |
| Submission | `submission` | File/URL submission metadata |
| Whois | `whois` | Historical WHOIS records |
| Sigma Rule | `sigma_rule` | Sigma detection rule |
| YARA Rule | `yara_rule` | YARA detection rule |
| YARA Ruleset | `yara_ruleset` | Collection of YARA rules |
| Vote | `vote` | Community vote (malicious/harmless) |
| Operation | `operation` | Async operation status |
| πŸ”’ Private File | `private_file` | Privately scanned file |
| πŸ”’ Private Analysis | `private_analysis` | Private scan result |
| πŸ”’ Activity Log | `activity_log` | Audit log entry |
| πŸ”’ Service Account | `service_account` | Programmatic access account |

---

## Relationship Access Matrix

This matrix shows which relationship types are available at each tier for the four main
object types.

### Legend
- βœ… Free β€” available with public API key
- πŸ”’ Enterprise β€” requires premium API key
- πŸ§‘β€πŸ’» Authenticated β€” requires any API key with appropriate user context

### File relationships
| Relationship | Access |
|-------------|--------|
| behaviours | βœ… |
| bundled_files | βœ… |
| collections | βœ… |
| comments | βœ… |
| contacted_domains | βœ… |
| contacted_ips | βœ… |
| contacted_urls | βœ… |
| dropped_files | βœ… |
| execution_parents | βœ… |
| graphs | βœ… |
| pe_resource_children | βœ… |
| pe_resource_parents | βœ… |
| sigma_analysis | βœ… |
| memory_pattern_domains | βœ… |
| memory_pattern_ips | βœ… |
| memory_pattern_urls | βœ… |
| user_votes | πŸ§‘β€πŸ’» |
| votes | βœ… |
| analyses | πŸ”’ |
| carbonblack_children | πŸ”’ |
| carbonblack_parents | πŸ”’ |
| compressed_parents | πŸ”’ |
| email_attachments | πŸ”’ |
| email_parents | πŸ”’ |
| embedded_domains | πŸ”’ |
| embedded_ips | πŸ”’ |
| embedded_urls | πŸ”’ |
| itw_domains | πŸ”’ |
| itw_ips | πŸ”’ |
| itw_urls | πŸ”’ |
| overlay_children | πŸ”’ |
| overlay_parents | πŸ”’ |
| pcap_children | πŸ”’ |
| pcap_parents | πŸ”’ |
| related_references | πŸ”’ |
| related_threat_actors | πŸ”’ |
| screenshots | πŸ”’ |
| similar_files | πŸ”’ |
| submissions | πŸ”’ |
| urls_for_embedded_js | πŸ”’ |

### Domain relationships
| Relationship | Access |
|-------------|--------|
| collections | βœ… |
| comments | βœ… |
| communicating_files | βœ… |
| graphs | βœ… |
| historical_ssl_certificates | βœ… |
| historical_whois | βœ… |
| immediate_parent | βœ… |
| parent | βœ… |
| referrer_files | βœ… |
| related_comments | βœ… |
| resolutions | βœ… |
| siblings | βœ… |
| subdomains | βœ… |
| user_votes | πŸ§‘β€πŸ’» |
| votes | βœ… |
| caa_records | πŸ”’ |
| cname_records | πŸ”’ |
| downloaded_files | πŸ”’ |
| mx_records | πŸ”’ |
| ns_records | πŸ”’ |
| related_references | πŸ”’ |
| related_threat_actors | πŸ”’ |
| soa_records | πŸ”’ |
| urls | πŸ”’ |

### IP Address relationships
| Relationship | Access |
|-------------|--------|
| collections | βœ… |
| comments | βœ… |
| communicating_files | βœ… |
| graphs | βœ… |
| historical_ssl_certificates | βœ… |
| historical_whois | βœ… |
| related_comments | βœ… |
| referrer_files | βœ… |
| resolutions | βœ… |
| user_votes | πŸ§‘β€πŸ’» |
| votes | βœ… |
| downloaded_files | πŸ”’ |
| related_references | πŸ”’ |
| related_threat_actors | πŸ”’ |
| urls | πŸ”’ |

### URL relationships
| Relationship | Access |
|-------------|--------|
| collections | βœ… |
| comments | βœ… |
| graphs | βœ… |
| last_serving_ip_address | βœ… |
| network_location | βœ… |
| related_comments | βœ… |
| user_votes | πŸ§‘β€πŸ’» |
| votes | βœ… |
| analyses | πŸ”’ |
| communicating_files | πŸ”’ |
| contacted_domains | πŸ”’ |
| contacted_ips | πŸ”’ |
| downloaded_files | πŸ”’ |
| embedded_js_files | πŸ”’ |
| redirecting_urls | πŸ”’ |
| redirects_to | πŸ”’ |
| referrer_files | πŸ”’ |
| referrer_urls | πŸ”’ |
| related_references | πŸ”’ |
| related_threat_actors | πŸ”’ |
| submissions | πŸ”’ |
| urls_related_by_tracker_id | πŸ”’ |
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall