Package Documentation
Storm Package: synapse-virustotal
The following Commands are available from this package. This documentation is generated for version 4.18.0 of the package.
Storm Commands
This package implements the following Storm Commands.
virustotal.commfiles
Get communicating files data for an ip/domain from VirusTotal.
This command takes inet:ipv4 or inet:fqdn nodes as input and queries either the
/api/v3/ip_addresses/{ip}/communicating_files or /api/v3/domains/{domain}/communicating_files
endpoint to retrieve files that were communicated with.
The results of the query are used to create file:bytes with their .seen property set
to the first/last submission times to VirusTotal, and a 'refs' light edge to the
inbound node. If the inbound node was an inet:ipv4, an inet:flow node will also
be created.
Examples:
// Get files communicating with an inet:ipv4
inet:ipv4=66.150.14.115 | virustotal.commfiles
// Get files communicating with an inet:ipv4 and yield the file:bytes nodes created
inet:ipv4=66.150.14.115 | virustotal.commfiles --yield
// Get 200 files communicating with an inet:fqdn and yield the file:bytes nodes created
inet:fqdn=google.com | virustotal.commfiles --yield --size 200
Usage: virustotal.commfiles [options]
Options:
--help : Display the command usage.
--debug : Show verbose debug output.
--yield : Yield the newly created nodes.
--asof <asof> : This argument is deprecated and no longer has any effect.
--size <size> : Limit the number of results ingested to the given size (per-node).
virustotal.dlfiles
Get downloaded files data for an ip/domain from VirusTotal.
This command takes inet:ipv4, inet:fqdn or inet:url nodes as input and queries the
/api/v3/{type}/{id}/downloaded_files endpoint to retrieve files that were downloaded.
The results of the query are used to create file:bytes nodes with their .seen property
set to the first/last VirusTotal submission times.
In addition, inet:urlfile nodes will be created to link the inbound node to the
resulting file:bytes node. For inet:ipv4 and inet:fqdn nodes, a url formatted as
'unk://{node.repr()}' will be used in the inet:urlfile.
Examples:
// Get files downloaded from an inet:ipv4
inet:ipv4=66.150.14.115 | virustotal.dlfiles
// Get files downloaded from an inet:ipv4 and yield the file:bytes nodes created
inet:ipv4=66.150.14.115 | virustotal.dlfiles --yield
// Get 200 files downloaded from an inet:fqdn and yield the file:bytes nodes created
inet:fqdn=google.com | virustotal.dlfiles --yield --size 200
Usage: virustotal.dlfiles [options]
Options:
--help : Display the command usage.
--debug : Show verbose debug output.
--yield : Yield the newly created nodes.
--asof <asof> : This argument is deprecated and no longer has any effect.
--size <size> : Limit the number of results ingested to the given size (per-node).
virustotal.domain.relationships
Get domain relationships data from VirusTotal.
This command takes an inet:fqdn node as input and queries the specified
/api/v3/domains/{id}/{relationship} endpoints to retrieve related objects.
Currently supported relationships are:
comments
communicating_files
downloaded_files
historical_ssl_certificates
historical_whois
referrer_files
resolutions
siblings
subdomains
urls
Examples:
// Resolutions for 10 inet:fqdn nodes
inet:fqdn | limit 10 | virustotal.domain.relationships resolutions
// Get 200 communicating files for an inet:fqdn node and yield the results
inet:fqdn#myfqdn |
virustotal.domain.relationships communicating_files --size 200 --yield
// Get 10 each of historical_ssl_certificates and historical_whois records
inet:fqdn#myfqdn |
virustotal.domain.relationships historical_ssl_certificates historical_whois --size 10
Usage: virustotal.domain.relationships [options] <relationships>
Options:
--help : Display the command usage.
--debug : Show verbose debug output.
--yield : Yield the newly created nodes.
--asof <asof> : This argument is deprecated and no longer has any effect.
--size <size> : Limit the number of results ingested to the given size for each relationship (per-node).
--all : Retrieve all supported relationships.
Arguments:
[<relationships> ...] : The relationships to query.
virustotal.enrich
Get report data from VirusTotal.
This command takes nodes as input and retrieves the corresponding object
from the VirusTotal API to add additional information about the domain, file,
IP address, or URL the node represents.
Examples:
// Get report data for a Domain
inet:fqdn=vertex.link | virustotal.enrich
// Get report data for a hash:md5 node and yield the file:bytes node created
hash:md5=dc57fd4585f8b48ff9fb7ce53bda6309 | virustotal.enrich --yield
Usage: virustotal.enrich [options]
Options:
--help : Display the command usage.
--debug : Show verbose debug output.
--yield : Yield the result node for the corresponding report.
--asof <asof> : This argument is deprecated and no longer has any effect.
virustotal.file.behavior
Get file behavior data from VirusTotal.
This command takes file:bytes, hash:md5, hash:sha1, or hash:sha256 nodes as
input and queries the /api/v3/files/{id}/behaviours endpoint to retrieve
information about sandbox execution of the file.
Examples:
// Get behavior data for 10 file:bytes nodes
file:bytes | limit 10 | virustotal.file.behavior
// Get behavior data for a hash:md5 node and yield the file:bytes node created
hash:md5=dc57fd4585f8b48ff9fb7ce53bda6309 | virustotal.file.behavior --yield
Usage: virustotal.file.behavior [options]
Options:
--help : Display the command usage.
--debug : Show verbose debug output.
--yield : Yield the file:bytes node for the file behavior report.
--asof <asof> : This argument is deprecated and no longer has any effect.
--size <size> : Limit the number of results ingested to the given size (per-node).
virustotal.file.download
Download files from VirusTotal.
This command takes file:bytes, hash:md5, hash:sha1, or hash:sha256 nodes as
input and queries the /api/v3/files/{id}/download endpoint to download
the file if it is not already present.
Examples:
// Download a file from a hash:md5 and yield the file:bytes node created
hash:md5=dc57fd4585f8b48ff9fb7ce53bda6309 | virustotal.file.download --yield
Usage: virustotal.file.download [options]
Options:
--help : Display the command usage.
--debug : Show verbose debug output.
--yield : Yield the newly created nodes.
--asof <asof> : This argument is deprecated and no longer has any effect.
virustotal.file.itwurls
Get "in the wild" URL data from VirusTotal.
This command takes file:bytes, hash:md5, hash:sha1, or hash:sha256 nodes as
input and queries the /api/v3/files/{id}/itw_urls endpoint to retrieve "in the
wild" URLs from where the file has been downloaded.
The results of the query are used to create inet:url nodes, with their .seen
property set to the first/last submission times to VirusTotal.
An inet:urlfile node will also be created linking the inet:url to the file:bytes
node for the file that was seen. If the sha256 hash of the last HTTP response is
not available and the inbound node did not have a sha256 hash, a file:bytes node
will be created with a guid of the form $lib.guid(virustotal.itwurls, {hash}).
When a last HTTP response is available, an inet:urlfile node will also be created.
Examples:
// Get in the wild URLs for 10 file:bytes nodes
file:bytes | limit 10 | virustotal.file.itwurls
// Get in the wild URLs and pivot to inet:urlfiles
file:bytes#myfile | virustotal.file.itwurls --yield | -> inet:urlfile
// Get in the wild URLs for a hash:md5 node and yield the inet:url nodes created
hash:md5=c5117ac5232ed7980d1672b820ac1a8d | virustotal.file.itwurls --yield
// Get 200 in the wild URLs for a hash:md5 node
hash:md5=c5117ac5232ed7980d1672b820ac1a8d | virustotal.file.itwurls --size 200
Usage: virustotal.file.itwurls [options]
Options:
--help : Display the command usage.
--debug : Show verbose debug output.
--yield : Yield the newly created nodes.
--asof <asof> : This argument is deprecated and no longer has any effect.
--size <size> : Limit the number of results ingested to the given size (per-node).
virustotal.file.relationships
Get file relationships data from VirusTotal.
This command takes a file:bytes, hash:md5, hash:sha1, or hash:sha256 nodes
as input and queries the specified /api/v3/files/{id}/{relationship} endpoints
to retrieve related objects. For hash:md5, hash:sha1, or hash:sha256 nodes,
the /api/v3/files/{id} endpoint will first be queried to populate the file:bytes
node for the hash.
Currently supported relationships are:
bundled_files
ciphered_parents
comments
compressed_parents
contacted_domains
contacted_ips
contacted_urls
dropped_files
embedded_domains
embedded_ips
embedded_urls
execution_parents
email_parents
itw_urls
overlay_children
overlay_parents
similar_files
submissions
Examples:
// Get in the wild URLs for 10 file:bytes nodes
file:bytes | limit 10 | virustotal.file.relationships itw_urls
// Get 200 similar files for a file:bytes node and yield the results
file:bytes#myfile |
virustotal.file.relationships similar_files --size 200 --yield
// Get 10 each of bundled files, dropped files, and email_parents
file:bytes#myfile |
virustotal.file.relationships bundled_files dropped_files email_parents --size 10
Usage: virustotal.file.relationships [options] <relationships>
Options:
--help : Display the command usage.
--debug : Show verbose debug output.
--yield : Yield the newly created nodes.
--asof <asof> : This argument is deprecated and no longer has any effect.
--size <size> : Limit the number of results ingested to the given size for each relationship (per-node).
--all : Retrieve all supported relationships.
Arguments:
[<relationships> ...] : The relationships to query.
virustotal.file.report
Get file report data from VirusTotal.
This command takes file:bytes, hash:md5, hash:sha1, or hash:sha256 nodes as
input and queries the /api/v3/files/{id} endpoint to retrieve information about
the file.
NOTE: If Synapse-FileParser >= 4.2.1 is available, this command will also download
and populate any crowdsourced YARA rulesets containing rules which matched the
file.
Examples:
// Get report data for 10 file:bytes nodes
file:bytes | limit 10 | virustotal.file.report
// Get report data for a hash:md5 node and yield the file:bytes node created
hash:md5=dc57fd4585f8b48ff9fb7ce53bda6309 | virustotal.file.report --yield
Usage: virustotal.file.report [options]
Options:
--help : Display the command usage.
--debug : Show verbose debug output.
--yield : Yield the file:bytes node for the file report.
--asof <asof> : This argument is deprecated and no longer has any effect.
virustotal.file.search
Query the VirusTotal file search API.
Pass a query to the /api/v3/intelligence/search endpoint and ingest the resulting
file reports. For further documentation on VT file searches, see
https://support.virustotal.com/hc/en-us/articles/360001387057-VirusTotal-Intelligence-Introduction
NOTE - This command will also create an it:exec:query node to represent the
query syntax and link resulting nodes to it via -(found)> edges.
Examples:
// Search for files with a size of 1024 bytes
virustotal.file.search 'size:1024'
// Search for files with imphash 7fa974366048f9c551ef45714595665e limited to
// 200 results and yield the file:bytes nodes created
virustotal.file.search imphash:7fa974366048f9c551ef45714595665e --yield ---size 200
// Search for files with a size of 1024 bytes, also download the file bytes for matches
virustotal.file.search 'size:1024' --download
Usage: virustotal.file.search [options] <search>
Options:
--help : Display the command usage.
--debug : Show verbose debug output.
--yield : Yield the newly created nodes.
--asof <asof> : This argument is deprecated and no longer has any effect.
--size <size> : Limit the number of results ingested to the given size (per-node).
--download : Download file bytes if not already present.
Arguments:
<search> : Query to pass to the VT search API.
virustotal.info
Get information about the VirusTotal API key in use.
This command queries the /api/v3/users/{api_key} endpoint to get information
about the permissions and current quota status for the VirusTotal api key in use.
Usage: virustotal.info [options]
Options:
--help : Display the command usage.
--debug : Show verbose debug output.
virustotal.ip.relationships
Get IP address relationships data from VirusTotal.
This command takes an inet:ipv4 node as input and queries the specified
/api/v3/ip_addresses/{id}/{relationship} endpoints to retrieve related objects.
Currently supported relationships are:
comments
communicating_files
downloaded_files
historical_ssl_certificates
historical_whois
referrer_files
resolutions
urls
Examples:
// Resolutions for 10 inet:ipv4 nodes
inet:ipv4 | limit 10 | virustotal.ip.relationships resolutions
// Get 200 communicating files for an inet:ipv4 node and yield the results
inet:ipv4#myip |
virustotal.ip.relationships communicating_files --size 200 --yield
// Get 10 each of historical_ssl_certificates and historical_whois records
inet:ipv4#myip |
virustotal.ip.relationships historical_ssl_certificates historical_whois --size 10
Usage: virustotal.ip.relationships [options] <relationships>
Options:
--help : Display the command usage.
--debug : Show verbose debug output.
--yield : Yield the newly created nodes.
--asof <asof> : This argument is deprecated and no longer has any effect.
--size <size> : Limit the number of results ingested to the given size for each relationship (per-node).
--all : Retrieve all supported relationships.
Arguments:
[<relationships> ...] : The relationships to query.
virustotal.livehunt.files
Get livehunt notifications and their associated files from VirusTotal.
This command queries the /api/v3/intelligence/hunting_notification_files
endpoint (with an optional filter parameter) to retrieve hunting notifications
and their associated files.
The results of the query are used to create it:app:yara:match nodes
with the it:app:yara:rule from the hunting ruleset and the
file:bytes node which matched the rule. meta:ruleset nodes will
also be created for each hunting ruleset, with 'has' light edges to the
it:app:yara:rule nodes they contain.
This command will not delete notifications from VirusTotal after they are
retrieved unless the --delete argument is used.
Additional information about filters that can be provided to the --filter
argument can be found in the VirusTotal hunting notifications documentation
at https://developers.virustotal.com/reference/list-hunting-notifications
and https://developers.virustotal.com/reference/hunting_notification_files
NOTE: This command requires Synapse-FileParser >= 4.2.1 in order to parse
livehunt rulesets.
Examples:
// Get 20 livehunt notifications and yield the it:app:yara:match
// nodes created.
virustotal.livehunt.files --yield --size 20
// Get 20 livehunt notifications and delete them from VirusTotal
// after ingesting.
virustotal.livehunt.files --size 20 --delete
// Get livehunt notifications matching a filter.
virustotal.livehunt.files --filter "date:2021-07-21+ date:2021-07-23-"
Usage: virustotal.livehunt.files [options]
Options:
--help : Display the command usage.
--filter <filter> : Filter string to use when retrieving notifications.
--delete : Delete remote notifications after ingesting.
--debug : Show verbose debug output.
--yield : Yield the newly created nodes.
--size <size> : Limit the number of results ingested to the given size (per-node).
virustotal.livehunt.notifications.delete
Delete a livehunt notifications from VirusTotal.
This command takes it:app:yara:match nodes as input and deletes the
associated notifications from VirusTotal.
Examples:
// Delete notifications related to a specific it:app:yara:rule.
it:app:yara:rule:name=myrule -> it:app:yara:match | virustotal.livehunt.notifications.delete
// Delete notifications related to a specific ruleset.
meta:ruleset:_virustotal:hunting:ruleset:id={ruleset}
-(has)> it:app:yara:rule -> it:app:yara:match | virustotal.livehunt.notifications.delete
// Delete all notifications which have been ingested.
yield $lib.lift.byNodeData(virustotal:livehunt:notifications) | virustotal.livehunt.notifications.delete
// Delete a single notification by ID.
$noteid = "mynoteid"
$lib.import(virustotal).delLivehuntNotification($noteid)
Usage: virustotal.livehunt.notifications.delete [options]
Options:
--help : Display the command usage.
--debug : Show verbose debug output.
virustotal.pdns
Get DNS resolution data for an ip/domain from VirusTotal.
This command takes inet:ipv4 or inet:fqdn nodes as input and queries either the
/api/v3/ip_addresses/{ip}/resolutions or /api/v3/domains/{domain}/resolutions endpoint to
retrieve DNS resolutions related to the node.
The results of the query are used to create inet:dns:a nodes, with their .seen
property set to the first/last submission times to VirusTotal.
Examples:
# Get DNS resolutions for an inet:ipv4 node
inet:ipv4=66.150.14.115 | virustotal.pdns
# Get DNS resolutions for an inet:ipv4 node and yield the inet:dns:a nodes created
inet:ipv4=66.150.14.115 | virustotal.pdns --yield
# Get 200 DNS resolutions for an inet:fqdn node and yield the inet:dns:a nodes created
inet:fqdn=google.com | virustotal.pdns --yield --size 200
Usage: virustotal.pdns [options]
Options:
--help : Display the command usage.
--debug : Show verbose debug output.
--yield : Yield the newly created nodes.
--asof <asof> : This argument is deprecated and no longer has any effect.
--size <size> : Limit the number of results ingested to the given size (per-node).
virustotal.search
Query the VirusTotal search API.
Pass a query to the /api/v3/search endpoint and ingest the results.
This endpoint searches any of the following:
A file hash - Returns a File object.
A URL - Returns a URL object.
A domain - Returns a Domain object.
A IP address - Returns an IP address object.
Comments by tags - Returns a list of Comment objects with the specified tag.
NOTE - This command will also create an it:exec:query node to represent the
query syntax and link resulting nodes to it via -(found)> edges.
Examples:
// Search for an IP
virustotal.search 74.125.225.229
// Search for a domain and yield the nodes created, limited to 200 results
virustotal.search google.com --yield ---size 200
// Search by MD5 hash and download the file bytes for matches
virustotal.search bea0a6f069bd547db685698bc9f9d25a --download
Usage: virustotal.search [options] <search>
Options:
--help : Display the command usage.
--debug : Show verbose debug output.
--yield : Yield the newly created nodes.
--asof <asof> : This argument is deprecated and no longer has any effect.
--size <size> : Limit the number of results ingested to the given size (per-node).
--download : Download file bytes if not already present.
Arguments:
<search> : Query to pass to the VT search API.
virustotal.setup.apikey
Set the VirusTotal API key.
Usage: virustotal.setup.apikey [options] <apikey>
Options:
--help : Display the command usage.
--self : Set the key as a user variable. If not used, the key is set globally.
Arguments:
<apikey> : The VirusTotal API key string.
virustotal.setup.tagdns
Set the tag to use for connections to IPs that were resolved from DNS.
The default tag is "code.capa.net.dns" if not specified.
Note: This command is deprecated and will be removed in v5.0.0.
Usage: virustotal.setup.tagdns [options] <tagname>
Options:
--help : Display the command usage.
Arguments:
<tagname> : The tag to use.
virustotal.setup.tagip
Set the tag to use for connections to IPs that were not resolved from DNS.
The default tag is "code.capa.net.ip" if not specified.
Note: This command is deprecated and will be removed in v5.0.0.
Usage: virustotal.setup.tagip [options] <tagname>
Options:
--help : Display the command usage.
Arguments:
<tagname> : The tag to use.
virustotal.setup.tagprefix
Set the tag prefix used when recording VirusTotal tags.
The default tag prefix is "rep.vt" if not specified.
Any tags provided by a VirusTotal API will be added within the given namespace.
For example, the VirusTotal tag "foo" would result in "#rep.vt.foo". Any
characters incompatible with tag names are replaced with "_".
Usage: virustotal.setup.tagprefix [options] <tagname>
Options:
--help : Display the command usage.
Arguments:
<tagname> : The tag prefix to use.
virustotal.ssl.history
Get historical SSL certificate data from VirusTotal.
This command takes inet:ipv4 or inet:fqdn nodes as input and queries
either the /api/v3/ip_addresses/{ip}/historical_ssl_certificates or
/api/v3/domains/{domain}/historical_ssl_certificates endpoint to
retrieve historical SSL certificates related to the node.
The results of the query are used to create crypto:x509:cert nodes. For
inet:ipv4 queries, inet:ssl:cert nodes will also be created.
Examples:
// Search by inbound node
inet:ipv4=1.2.3.4 | virustotal.ssl.history
// Output created crypto:x509:cert nodes
inet:fqdn=foo.com | virustotal.ssl.history --yield
Usage: virustotal.ssl.history [options]
Options:
--help : Display the command usage.
--debug : Show verbose debug output.
--yield : Yield the newly created nodes.
--asof <asof> : This argument is deprecated and no longer has any effect.
--size <size> : Limit the number of results ingested to the given size (per-node).
virustotal.url.relationships
Get URL relationships data from VirusTotal.
This command takes an inet:url node as input and queries the specified
/api/v3/urls/{id}/{relationship} endpoints to retrieve related objects.
Currently supported relationships are:
comments
downloaded_files
last_serving_ip_address
referrer_files
Examples:
// Get 200 communicating files for an inet:url node and yield the results
inet:url#myurl |
virustotal.url.relationships communicating_files --size 200 --yield
// Get 10 each of contacted_domains and contacted_ips
inet:url#myurl |
virustotal.url.relationships contacted_domains contacted_ips --size 10
Usage: virustotal.url.relationships [options] <relationships>
Options:
--help : Display the command usage.
--debug : Show verbose debug output.
--yield : Yield the newly created nodes.
--asof <asof> : This argument is deprecated and no longer has any effect.
--size <size> : Limit the number of results ingested to the given size for each relationship (per-node).
--all : Retrieve all supported relationships.
Arguments:
[<relationships> ...] : The relationships to query.
virustotal.urls
Get URLs data for an ip/domain from VirusTotal.
This command takes inet:ipv4 or inet:fqdn nodes as input and queries either the
/api/v3/ip_addresses/{ip}/urls or /api/v3/domains/{domain}/urls endpoint to
retrieve URLs related to the node.
The results of the query are used to create inet:url nodes, with their .seen
property set to the first/last submission times to VirusTotal.
Examples:
// Get URLs related to an inet:ipv4 node
inet:ipv4=66.150.14.115 | virustotal.urls
// Get URLs related to an inet:ipv4 node and yield the inet:url nodes created
inet:ipv4=66.150.14.115 | virustotal.urls --yield
// Get 200 URLs related to an inet:fqdn node and yield the inet:urls nodes created
inet:fqdn=google.com | virustotal.urls --yield --size 200
Usage: virustotal.urls [options]
Options:
--help : Display the command usage.
--debug : Show verbose debug output.
--yield : Yield the newly created nodes.
--asof <asof> : This argument is deprecated and no longer has any effect.
--size <size> : Limit the number of results ingested to the given size (per-node).
virustotal.whois.history
Get historical WHOIS records from VirusTotal.
This command takes inet:ipv4 or inet:fqdn nodes as input and queries
either the /api/v3/ip_addresses/{ip}/historical_whois or
/api/v3/domains/{domain}/historical_whois endpoint to retrieve historical WHOIS
records related to the node.
The results of the query are used to create inet:whois:rec or inet:whois:iprec
nodes depending on the type of input node.
Examples:
// Search by inbound node
inet:ipv4=1.2.3.4 | virustotal.whois.history
// Output created inet:whois:rec nodes
inet:fqdn=foo.com | virustotal.whois.history --yield
Usage: virustotal.whois.history [options]
Options:
--help : Display the command usage.
--debug : Show verbose debug output.
--yield : Yield the newly created nodes.
--asof <asof> : This argument is deprecated and no longer has any effect.
--size <size> : Limit the number of results ingested to the given size (per-node).
Storm Modules
This package does not export any Storm APIs.