virus_total_ex v0.1.0 VirusTotal

Documentation for VirusTotal.

Full API documentation can be found on the official site

As a note, this wrapper will convert HTTP-200 responses with a response_code of 0 to errors. Apparently VT considers to be HTTP 200 to be a valid status code for "not found". How silly.

Example usage:

iex> client = VirusTotal.Client.new(my_api_key)
iex> {:ok, report} = VirusTotal.file_report(client, "7bf5623f0a10dfa148a35bebd899b7758612f1693d2a9910f716cf15a921a76a")
{:ok, %{"ITW_urls" => ["https://chiru.no/u/rensenware.exe"], ...}}

Link to this section Summary

Functions

Deletes a scheduled file rescan task. The file rescan api allows you to schedule periodic scans of a file, this API call tells VirusTotal to stop rescanning a file that you have previously enqueued for recurrent scanning.

Retrieves a report on a given domain (including the information recorded by VirusTotal's passive DNS infrastructure).

VirusTotal runs a distributed setup of Cuckoo sandbox machines that execute the files they receive. Execution is attempted only once, upon first submission to VirusTotal, and only Portable Executables under 10MB in size are ran. The execution of files is a best effort process, hence, there are no guarantees about a report being generated for a given file in the dataset.

This API offers a programmatic access to the clustering section of VirusTotal Intelligence

Downloads a file from VirusTotal's store

Files that are successfully executed may communicate with certain network resources, all this communication is recorded in a network traffic dump (pcap file). This API allows you to retrieve the network traffic dump generated during the file's execution.

Retrieves a concluded file scan report for a given file.

Retrieves a report on a given IP address (including the information recorded by VirusTotal's Passive DNS infrastructure).

Retrieves all notifications created by VirusTotal's hunting functionality

Allows you to rescan files present in VirusTotal's file store without having to resubmit them

Retrieves a report for a given URL

Allows you to submit URLs to be scanned by VirusTotal

Link to this section Functions

Link to this function

delete_rescan(client, resource)

Deletes a scheduled file rescan task. The file rescan api allows you to schedule periodic scans of a file, this API call tells VirusTotal to stop rescanning a file that you have previously enqueued for recurrent scanning.

Link to this function

domain_report(client, domain)

Retrieves a report on a given domain (including the information recorded by VirusTotal's passive DNS infrastructure).

Link to this function

file_behaviour(client, hash)

VirusTotal runs a distributed setup of Cuckoo sandbox machines that execute the files they receive. Execution is attempted only once, upon first submission to VirusTotal, and only Portable Executables under 10MB in size are ran. The execution of files is a best effort process, hence, there are no guarantees about a report being generated for a given file in the dataset.

Link to this function

file_clusters(client, date)

This API offers a programmatic access to the clustering section of VirusTotal Intelligence

Valid params:

  • :date: A specific day for which we want to access the clustering details, example: 2013-09-10.
Link to this function

file_download(client, hash)

Downloads a file from VirusTotal's store

iex> file_download(client, "7bf5623f0a10dfa148a35bebd899b7758612f1693d2a9910f716cf15a921a76a")
{:ok, <<77, 90, 144, ...>>}
Link to this function

file_network_traffic(client, hash)

Files that are successfully executed may communicate with certain network resources, all this communication is recorded in a network traffic dump (pcap file). This API allows you to retrieve the network traffic dump generated during the file's execution.

Link to this function

file_report(client, hash, params \\ [allinfo: 1])

Retrieves a concluded file scan report for a given file.

Valid parameters:

  • :allinfo: if this is specified and set to 1, the call will return additional info. This is turned ON by default

    iex> file_report(client, "7bf5623f0a10dfa148a35bebd899b7758612f1693d2a9910f716cf15a921a76a") {:ok, %{"ITW_urls" => ["https://chiru.no/u/rensenware.exe"]}}

Link to this function

file_search(client, query, params \\ %{})

Valid params:

  • :offset: The offset value returned by a previously issued identical query, allows you to paginate over the results. If not specified the first 300 matching files sorted according to last submission date to VirusTotal in a descending fashion will be returned.
Link to this function

get_comments(client, resource, params \\ [])

Link to this function

ip_report(client, ip)

Retrieves a report on a given IP address (including the information recorded by VirusTotal's Passive DNS infrastructure).

iex> ip_report(client, "8.8.8.8")
{:ok, %{"asn" => ...}}
Link to this function

notifications(client)

Retrieves all notifications created by VirusTotal's hunting functionality

Link to this function

put_comment(client, resource, comment)

Link to this function

rescan_file(client, resource, params \\ [])

Allows you to rescan files present in VirusTotal's file store without having to resubmit them

iex> rescan_file(client, some_hash)
{:ok, %{"scan_id" => "something"}}

Valid parameters:

  • :date: Date in %Y%m%d%H%M%S format (example: 20120725170000) in which the rescan should be performed. If not specified the rescan will be performed immediately.
  • :period: Periodicity (in days) with which the file should be rescanned. If this argument is provided the file will be rescanned periodically every period days, if not, the rescan is performed once and not repeated again.
  • :repeat: Used in conjunction with period to specify the number of times the file should be rescanned. If this argument is provided the file will be rescanned the given amount of times in coherence with the chosen periodicity, if not, the file will be rescanned indefinitely.
  • :notify_url: A URL to which a POST notification should be sent when the rescan finishes.
  • :notify_changes_only: Used in conjunction with notify_url. Indicates if POST notifications should only be sent if the scan results differ from the previous one.
Link to this function

url_report(client, url)

Retrieves a report for a given URL

iex> url_report(client, "https://yuruyuri.com/")
{:ok, %{"positives" => 0, ...}}
Link to this function

url_scan(client, url)

Allows you to submit URLs to be scanned by VirusTotal

iex> url_scan(client, "https://yuruyuri.com")
{:ok, %{"scan_id" => ...}}