API Reference

Collections

Information about collections

A collection groups different types of objects giving them some context (e.g. a phishing campaign, a malware family, etc.). Thus it usually contains various IOCs (files, URLs, domains, IP addresses), as well as references, and comments, providing even more context.

Object attributes

A Collection object contains the following attributes:

  • alt_names: <list of strings> list of alternative names for the collection. Useful when describing malware families, which are usually known by several names.
  • autogenerated_tags: <list of strings> relevant tags automatically generated from the aggregations.
  • creation_date: <integer> creation date of the collection (UTC timestamp).
  • description: <string> description of the collection.
  • description_html: <string> HTML formatted description of the collection.
  • domains_count: <integer> number of domains in the collection.
  • files_count: <integer> number of files in the collection.
  • ip_addresses_count: <integer> number of IP addresses in the collection.
  • last_modification_date: <integer> date when any of the collection's attributes was last updated (UTC timestamp).
  • link: <string> URL to the source's website.
  • name: <string> name of the collection.
  • recent_activity_relative_change: <float> ratio of change between the last two "recent activity" periods. Note: "recent activity" periods are comprised of 14 days.
  • recent_activity_summary: <list_of_integers> time series representing the activity of the indicators of compromise contained in the collection (2 weeks).
  • references_count: <integer> number of references in the collection.
  • source_region: <string> Suspected source region of the activity described in the Collection. ISO 3166 Alpha2 - code.
  • sponsor_region: <string> Suspected region sponsoring activity described in the Collection. ISO 3166 Alpha2 - code.
  • status: <string> indicates if the collection has attributes pending to be computed again (e.g. top_icon_md5 after making changes). The possible values are PENDING_RECOMPUTE and COMPUTED.
  • tags: <list of strings> collection's tags.
  • targeted_industries: <list of strings> collection's targeted industries.
  • targeted_regions: <list of strings> collection's targeted regions. ISO 3166 Alpha2 - code.
  • tlp: <string> collection's traffic light protocol color.
  • top_icon_md5: <list of strings> MD5 from the 3 most frequent icons among the collection (file's icons, URLs and domain's favicons).
  • urls_count: <integer> number of URLs in the collection.
{
  "data": {
    "attributes": {
      "alt_names": [<string>],
      "autogenerated_tags": [<string>],
      "creation_date": <int:timestamp>,
      "description": <string>,
      "description_html": <string>,
      "domains_count": <int>,
      "files_count": <int>,
      "ip_addresses_count": <int>,
      "last_modification_date": <int:timestamp>,
      "link": <string>,
      "name": <string>,
      "recent_activity_relative_change":<float>,
      "recent_activity_summary":[<int>],
      "references_count": <int>,
    	"source_region":<string>,
    	"sponsor_region":<string>,
      "status": <string>,
      "tags": [<string>],
      "targeted_industries": [<string>],
      "targeted_regions": [<string>],
      "tlp": <string>,
      "top_icon_md5": [<string>],
      "urls_count": <int>,
    },
    "id": <string>,
    "links": {
      "self": "https://virustotal.com/api/v3/collections/<id>"
    },
    "type": "collection"
  }
}

{
  "data": {
    "attributes": {
      "alt_names": [
        "Geodo",
        "Heodo"
      ],
      "autogenerated_tags": [
        "cve-2018-20250",
        "cve-2017-11882",
        "upx",
      ],
      "creation_date": 1612569600,
      "description": "While [i]Emotet[/i] historically was a banking malware organized in a botnet, nowadays Emotet is mostly seen as infrastructure as a service for content delivery. For example, since mid 2018 it is used by Trickbot for installs, which may also lead to ransomware attacks using Ryuk, a combination observed several times against high-profile targets.\r\nIt is always stealing information from victims but what the criminal gang behind it did, was to open up another business channel by selling their infrastructure delivering additional malicious software. From malware analysts it has been classified into epochs depending on command and control, payloads, and delivery solutions which change over time.",
      "description_html": "While <em>Emotet</em> historically was a banking malware organized in a botnet, nowadays Emotet is mostly seen as infrastructure as a service for content delivery. For example, since mid 2018 it is used by Trickbot for installs, which may also lead to ransomware attacks using Ryuk, a combination observed several times against high-profile targets.\r\nIt is always stealing information from victims but what the criminal gang behind it did, was to open up another business channel by selling their infrastructure delivering additional malicious software. From malware analysts it has been classified into epochs depending on command and control, payloads, and delivery solutions which change over time.",
      "domains_count": 0,
      "files_count": 3688,
      "ip_addresses_count": 0,
      "last_modification_date": 1613148085,
      "link": "https://malpedia.caad.fkie.fraunhofer.de/details/win.emotet",
      "name": "Emotet",
      "references_count": 129,
      "recent_activity_relative_change": 0.39,
      "recent_activity_summary": [
        30436,
        26799,
        27709,
        29112,
        26659,
        29997,
        18676,
        35813,
        28992,
        33486,
        24593,
        25648,
        26175,
        29243
      ],
      "source_region":"US",
      "sponsor_region":"US",
      "status": "COMPUTED",
      "tags": [
        "upx"
      ],
      "targeted_industries": ["Finance"],
      "targeted_regions": ["US"],
      "tlp": "WHITE",
      "top_icon_md5": [
        "647ca034cb6c763363b636269047a4c0",
        "da87510c3aabe7851c7c5d0493dbb14a",
        "d2d15e1e362ef2edda7238e165376112"
      ],
      "urls_count": 0
    },
    "id": "malpedia_win_emotet",
    "links": {
      "self": "https://virustotal.com/api/v3/collections/malpedia_win_emotet"
    },
    "type": "collection"
  }
}

Relationships

The collection's relationships allows retrieving the objects contained in the collection as explained in the Relationships section. The available relationships are described below.

RelationshipReturn object type
autogenerated_graphsList of Graphs
commentsList of Comments
domainsList of Domains
filesList of Files
ip_addressesList of IP addresses
ownerA single User
referencesList of References
related_collectionsList of Collections
related_referencesList of References
threat_actorsList of Threat Actors
urlsList of URLs