virustotal: Access Virustotal API

Description

Access virustotal API. See https://www.virustotal.com/. Details about results of calls to the API can be found at https://docs.virustotal.com/reference.

You will need credentials to use this application. If you haven't already, get the API Key at https://www.virustotal.com/.

Author(s)

Gaurav Sood

See Also

Useful links:

• https://github.com/themains/virustotal

• Report bugs at https://github.com/themains/virustotal/issues

Add comments on Files and URLs

Description

Add comments on files and URLs. For instance, flagging false positives, adding details about malware, instructions for cleaning malware, etc.

Usage

add_comments(hash = NULL, comment = NULL, ...)

Arguments

Value

data.frame with 2 columns: response_code, verbose_msg

• If the hash is incorrect or a duplicate comment is posted, response_code will be 0

• If the hash is incorrect, verbose_msg will be 'Invalid resource'

• If a duplicate comment is posted, verbose_msg will be 'Duplicate comment'

• If a comment is posted successfully, response_code will be 1 and verbose_msg will be 'Your comment was successfully posted'

References

https://docs.virustotal.com/reference

See Also

set_key for setting the API key

Examples

## Not run: 

# Before calling the function, set the API key using set_key('api_key_here')
  
add_comments(hash='99017f6eebbac24f351415dd410d522d', comment="This is great.")



## End(Not run)

Get Domain Report

Description

Retrieves comprehensive analysis report for a given domain, including WHOIS information, DNS resolutions, detected URLs, and threat intelligence data.

Usage

domain_report(domain = NULL, ...)

Arguments

Value

list containing domain analysis results including WHOIS data, DNS resolutions, detected URLs, categories, and threat intelligence

References

https://docs.virustotal.com/reference

See Also

set_key for setting the API key

Examples

## Not run: 

# Before calling the function, set the API key using set_key('api_key_here')
   
domain_report("google.com")
domain_report("example.com")

## End(Not run)

Download a file from VirusTotal

Description

Download a file from VirusTotal

Usage

download_file(hash = NULL, output_path = NULL, ...)

Arguments

Value

Raw file content or saves file to specified path

References

https://docs.virustotal.com/reference

See Also

set_key for setting the API key

Examples

## Not run: 

# Before calling the function, set the API key using set_key('api_key_here')

download_file(hash='99017f6eebbac24f351415dd410d522d', 
              output_path='/tmp/downloaded_file')

## End(Not run)

Get File Scan Report

Description

Get File Scan Report

Usage

file_report(hash = NULL, ...)

Arguments

Value

list containing file analysis results including antivirus scans, file metadata, and threat detection information

References

https://docs.virustotal.com/reference

See Also

set_key for setting the API key

Examples

## Not run: 

# Before calling the function, set the API key using set_key('api_key_here')

file_report(hash='99017f6eebbac24f351415dd410d522d')

## End(Not run)

Retrieve comments for an Internet domain

Description

Retrieve comments for an Internet domain

Usage

get_domain_comments(domain = NULL, limit = limit, cursor = cursor, ...)

Arguments

Value

named list with the following possible items: `BitDefender category`, undetected_referrer_samples, whois_timestamp, detected_downloaded_samples, detected_referrer_samples, `Webutation domain info`, `Alexa category`, undetected_downloaded_samples, resolutions, detected_communicating_samples, `Opera domain info`, `TrendMicro category`, categories, domain_siblings, `BitDefender domain info`, whois, `Alexa domain info`, response_code, verbose_msg, `Websense ThreatSeeker category`, subdomains, `WOT domain info`, detected_urls, `Alexa rank`, undetected_communicating_samples, `Dr.Web category`, pcaps

References

https://docs.virustotal.com/reference

See Also

set_key for setting the API key

Examples

## Not run: 

# Before calling the function, set the API key using set_key('api_key_here')
   
get_domain_comments("http://www.google.com")
get_domain_comments("http://www.goodsfwrfw.com") # Domain not found

## End(Not run)

Retrieve information about an Internet domain

Description

Retrieve information about an Internet domain

Usage

get_domain_info(domain = NULL, limit = NULL, cursor = NULL, ...)

Arguments

Value

named list

References

https://docs.virustotal.com/reference

See Also

set_key for setting the API key

Examples

## Not run: 

# Before calling the function, set the API key using set_key('api_key_here')
   
get_domain_info("http://www.google.com")
get_domain_info("http://www.goodsfwrfw.com") # Domain not found

## End(Not run)

Retrieve related objects to an Internet domain

Description

Retrieve related objects to an Internet domain

Usage

get_domain_relationship(
  domain = NULL,
  relationship = "subdomains",
  limit = NULL,
  cursor = NULL,
  ...
)

Arguments

Value

named list

References

https://docs.virustotal.com/reference

See Also

set_key for setting the API key

Examples

## Not run: 

# Before calling the function, set the API key using set_key('api_key_here')
   
get_domain_relationship("https://www.google.com")
get_domain_relationship("https://www.goodsfwrfw.com") # Domain not found

## End(Not run)

Retrieve votes for an Internet domain

Description

Retrieve votes for an Internet domain

Usage

get_domain_votes(domain = NULL, limit = NULL, cursor = NULL, ...)

Arguments

Value

named list

References

https://docs.virustotal.com/reference

See Also

set_key for setting the API key

Examples

## Not run: 

# Before calling the function, set the API key using set_key('api_key_here')
   
get_domain_votes("http://www.google.com")
get_domain_votes("http://www.goodsfwrfw.com") # Domain not found

## End(Not run)

Retrieve comments for a file

Description

Retrieve comments for a file

Usage

get_file_comments(hash = NULL, limit = NULL, cursor = NULL, ...)

Arguments

Value

list containing file comments

References

https://docs.virustotal.com/reference

See Also

set_key for setting the API key

Examples

## Not run: 

# Before calling the function, set the API key using set_key('api_key_here')

get_file_comments(hash='99017f6eebbac24f351415dd410d522d')

## End(Not run)

Get download URL for a file

Description

Get download URL for a file

Usage

get_file_download_url(hash = NULL, ...)

Arguments

Value

list containing download URL and metadata

References

https://docs.virustotal.com/reference

See Also

set_key for setting the API key

Examples

## Not run: 

# Before calling the function, set the API key using set_key('api_key_here')

get_file_download_url(hash='99017f6eebbac24f351415dd410d522d')

## End(Not run)

Retrieve relationships for a file

Description

Retrieve relationships for a file

Usage

get_file_relationships(
  hash = NULL,
  relationship = NULL,
  limit = NULL,
  cursor = NULL,
  ...
)

Arguments

Value

list containing file relationships

References

https://docs.virustotal.com/reference

See Also

set_key for setting the API key

Examples

## Not run: 

# Before calling the function, set the API key using set_key('api_key_here')

get_file_relationships(hash='99017f6eebbac24f351415dd410d522d', 
                       relationship='contacted_domains')

## End(Not run)

Get file upload URL for large files

Description

Get a special URL for uploading files larger than 32MB to VirusTotal for analysis.

Usage

get_file_upload_url(...)

Arguments

Value

list containing upload URL and other metadata

References

https://docs.virustotal.com/reference

See Also

set_key for setting the API key, scan_file for regular file uploads

Examples

## Not run: 

# Before calling the function, set the API key using set_key('api_key_here')

get_file_upload_url()

## End(Not run)

Retrieve votes for a file

Description

Retrieve votes for a file

Usage

get_file_votes(hash = NULL, limit = NULL, cursor = NULL, ...)

Arguments

Value

list containing file votes

References

https://docs.virustotal.com/reference

See Also

set_key for setting the API key

Examples

## Not run: 

# Before calling the function, set the API key using set_key('api_key_here')

get_file_votes(hash='99017f6eebbac24f351415dd410d522d')

## End(Not run)

Retrieve comments for an IP address

Description

Retrieve comments for an IP address

Usage

get_ip_comments(ip = NULL, limit = NULL, cursor = NULL, ...)

Arguments

Value

named list

References

https://docs.virustotal.com/reference

See Also

set_key for setting the API key

Examples

## Not run: 

# Before calling the function, set the API key using set_key('api_key_here')
   
get_ip_comments("64.233.160.0")

## End(Not run)

Retrieve information about an IP address

Description

Retrieves report on a given domain, including passive DNS, urls detected by at least one url scanner. Gives category of the domain from bitdefender.

Usage

get_ip_info(ip = NULL, limit = NULL, cursor = NULL, ...)

Arguments

Value

named list

References

https://docs.virustotal.com/reference

See Also

set_key for setting the API key

Examples

## Not run: 

# Before calling the function, set the API key using set_key('api_key_here')
   
get_ip_info("64.233.160.0")

## End(Not run)

Retrieve votes for an IP address

Description

Retrieve votes for an IP address

Usage

get_ip_votes(ip = NULL, limit = NULL, cursor = NULL, ...)

Arguments

Value

named list

References

https://docs.virustotal.com/reference

See Also

set_key for setting the API key

Examples

## Not run: 

# Before calling the function, set the API key using set_key('api_key_here')
   
get_ip_votes("64.233.160.0")

## End(Not run)

Retrieve comments for a URL

Description

Retrieve comments for a URL

Usage

get_url_comments(url_id = NULL, limit = NULL, cursor = NULL, ...)

Arguments

Value

list containing URL comments

References

https://docs.virustotal.com/reference

See Also

set_key for setting the API key

Examples

## Not run: 

# Before calling the function, set the API key using set_key('api_key_here')

get_url_comments(url_id='http://www.google.com')

## End(Not run)

Retrieve relationships for a URL

Description

Retrieve relationships for a URL

Usage

get_url_relationships(
  url_id = NULL,
  relationship = NULL,
  limit = NULL,
  cursor = NULL,
  ...
)

Arguments

Value

list containing URL relationships

References

https://docs.virustotal.com/reference

See Also

set_key for setting the API key

Examples

## Not run: 

# Before calling the function, set the API key using set_key('api_key_here')

get_url_relationships(url_id='http://www.google.com', 
                      relationship='communicating_files')

## End(Not run)

Retrieve votes for a URL

Description

Retrieve votes for a URL

Usage

get_url_votes(url_id = NULL, limit = NULL, cursor = NULL, ...)

Arguments

Value

list containing URL votes

References

https://docs.virustotal.com/reference

See Also

set_key for setting the API key

Examples

## Not run: 

# Before calling the function, set the API key using set_key('api_key_here')

get_url_votes(url_id='http://www.google.com')

## End(Not run)

Get IP Address Report

Description

Retrieves comprehensive analysis report for an IP address, including geolocation, ASN information, DNS resolutions, and detected URLs.

Usage

ip_report(ip = NULL, ...)

Arguments

Value

list containing IP analysis results including geolocation, ASN information, DNS resolutions, detected URLs, and threat intelligence

References

https://docs.virustotal.com/reference

See Also

set_key for setting the API key

Examples

## Not run: 

# Before calling the function, set the API key using set_key('api_key_here')

ip_report(ip="8.8.8.8")
ip_report(ip="2001:4860:4860::8888")  # IPv6 example

## End(Not run)

Add a comment to an Internet domain

Description

Add a comment to an Internet domain

Usage

post_domain_comments(domain = NULL, comment = NULL, ...)

Arguments

Value

named list

References

https://docs.virustotal.com/reference

See Also

set_key for setting the API key

Examples

## Not run: 

# Before calling the function, set the API key using set_key('api_key_here')
   
post_domain_comments(domain = "https://google.com", comment = "Great!")

## End(Not run)

Add a vote for a hostname or domain

Description

Add a vote for a hostname or domain

Usage

post_domain_votes(domain = NULL, vote = NULL, ...)

Arguments

Value

named list

References

https://docs.virustotal.com/reference

See Also

set_key for setting the API key

Examples

## Not run: 

# Before calling the function, set the API key using set_key('api_key_here')
   
post_domain_votes("http://google.com", vote = "malicious")

## End(Not run)

Add a comment to a file

Description

Add a comment to a file

Usage

post_file_comments(hash = NULL, comment = NULL, ...)

Arguments

Value

list containing response data

References

https://docs.virustotal.com/reference

See Also

set_key for setting the API key

Examples

## Not run: 

# Before calling the function, set the API key using set_key('api_key_here')

post_file_comments(hash='99017f6eebbac24f351415dd410d522d', 
                   comment='This file appears to be suspicious')

## End(Not run)

Add a vote to a file

Description

Add a vote to a file

Usage

post_file_votes(hash = NULL, verdict = NULL, ...)

Arguments

Value

list containing response data

References

https://docs.virustotal.com/reference

See Also

set_key for setting the API key

Examples

## Not run: 

# Before calling the function, set the API key using set_key('api_key_here')

post_file_votes(hash='99017f6eebbac24f351415dd410d522d', verdict='malicious')

## End(Not run)

Add a comment to an IP address

Description

Add a comment to an IP address

Usage

post_ip_comments(ip = NULL, comment = NULL, ...)

Arguments

Value

named list

References

https://docs.virustotal.com/reference

See Also

set_key for setting the API key

Examples

## Not run: 

# Before calling the function, set the API key using set_key('api_key_here')
   
post_ip_comments(ip = "64.233.160.0", comment = "test")

## End(Not run)

Add a vote for a IP address

Description

Add a vote for a IP address

Usage

post_ip_votes(ip = NULL, vote = NULL, ...)

Arguments

Value

named list

References

https://docs.virustotal.com/reference

See Also

set_key for setting the API key

Examples

## Not run: 

# Before calling the function, set the API key using set_key('api_key_here')
   
post_ip_votes(ip = "64.233.160.0", vote = "malicious")

## End(Not run)

Add a comment to a URL

Description

Add a comment to a URL

Usage

post_url_comments(url_id = NULL, comment = NULL, ...)

Arguments

Value

list containing response data

References

https://docs.virustotal.com/reference

See Also

set_key for setting the API key

Examples

## Not run: 

# Before calling the function, set the API key using set_key('api_key_here')

post_url_comments(url_id='http://www.google.com', 
                  comment='This URL appears suspicious')

## End(Not run)

Add a vote to a URL

Description

Add a vote to a URL

Usage

post_url_votes(url_id = NULL, verdict = NULL, ...)

Arguments

Value

list containing response data

References

https://docs.virustotal.com/reference

See Also

set_key for setting the API key

Examples

## Not run: 

# Before calling the function, set the API key using set_key('api_key_here')

post_url_votes(url_id='http://www.google.com', verdict='harmless')

## End(Not run)

Rate Limits

Description

Virustotal requests throttled at 4 per min. The function creates an env. var. that tracks number of requests per minute, and enforces appropriate waiting.

Usage

rate_limit()

Request rescan of a file

Description

Request a new analysis of a file already present in VirusTotal's database. Returns an analysis ID that can be used to retrieve the report using file_report.

Usage

rescan_file(hash = NULL, ...)

Arguments

Value

list containing analysis details and ID

References

https://docs.virustotal.com/reference

See Also

set_key for setting the API key

Examples

## Not run: 

# Before calling the function, set the API key using set_key('api_key_here')

rescan_file(hash='99017f6eebbac24f351415dd410d522d')

## End(Not run)

Submit a file for scanning

Description

Submit a file for scanning

Usage

scan_file(file_path = NULL, ...)

Arguments

Value

data.frame with the following columns: type, id, links

References

https://docs.virustotal.com/reference

See Also

set_key for setting the API key

Examples

## Not run: 

# Before calling the function, set the API key using set_key('api_key_here')

scan_file(file_path='path_to_suspicious_file')

## End(Not run)

Submit URL for scanning

Description

Submit a URL for analysis. Returns analysis details including an ID that can be used to retrieve the report using url_report

Usage

scan_url(url = NULL, ...)

Arguments

Value

list containing analysis details and ID

References

https://docs.virustotal.com/reference

See Also

set_key for setting the API key

Examples

## Not run: 

# Before calling the function, set the API key using set_key('api_key_here')

scan_url("http://www.google.com")

## End(Not run)

Set API Key

Description

Before anything else, get the API key from https://www.virustotal.com/en/. Next, use set_key to store the API key in an environment variable VirustotalToken. Once you have set the API key, you can use any of the functions.

Usage

set_key(api_key = NULL)

Arguments

References

https://docs.virustotal.com/reference

Examples

## Not run: 

set_key('api_key_here')


## End(Not run)

Get URL Report

Description

Retrieve a scan report for a given URL or URL ID from VirusTotal.

Usage

url_report(url_id = NULL, ...)

Arguments

Value

list containing URL analysis results including scan details, detection information, and metadata

References

https://docs.virustotal.com/reference

See Also

set_key for setting the API key, scan_url for submitting URLs

Examples

## Not run: 

# Before calling the function, set the API key using set_key('api_key_here')

# Get report using URL
url_report("http://www.google.com")

# Get report using URL ID (base64 encoded URL without padding)
url_report("687474703a2f2f7777772e676f6f676c652e636f6d2f")

## End(Not run)

Base POST AND GET functions. Not exported.

Description

GET for the v2 API

Usage

virustotal2_GET(
  query = list(),
  path = path,
  key = Sys.getenv("VirustotalToken"),
  ...
)

Arguments

Value

list

POST for V2 API

Description

POST for V2 API

Usage

virustotal2_POST(
  query = list(),
  path = path,
  body = NULL,
  key = Sys.getenv("VirustotalToken"),
  ...
)

Arguments

Value

list

GET for the Current V3 API

Description

GET for the Current V3 API

Usage

virustotal_GET(path, query = list(), key = Sys.getenv("VirustotalToken"), ...)

Arguments

Value

list

POST for the Current V3 API

Description

POST for the Current V3 API

Usage

virustotal_POST(
  path,
  body = NULL,
  query = list(),
  key = Sys.getenv("VirustotalToken"),
  ...
)

Arguments

Value

list

Request Response Verification

Description

Request Response Verification

Usage

virustotal_check(req)

Arguments

Value

in case of failure, a message