Package {virustotal}

virustotal: Access Virustotal API

Description

Access virustotal API. See https://www.virustotal.com/. Details about API calls: 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/.

Options

virustotal.timeout

Request timeout in seconds. Default 60.

virustotal.max_tries

Maximum attempts per request; retries honor HTTP 429/503 and their Retry-After header. Default 3.

virustotal.requests_per_minute

Client-side throttle. Default 4, the public API allowance; premium keys can raise it.

virustotal.throttle

Set FALSE to disable the client-side throttle entirely. Default TRUE.

Author(s)

Gaurav Sood

See Also

Useful links:

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

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

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

Clean up temporary files and directories

Description

Safely removes temporary files and directories created during VirusTotal operations.

Usage

cleanup_temp_files(paths)

Arguments

Value

Logical indicating success

See Also

Other utilities: create_safe_temp_dir(), format_file_size(), is_safe_environment(), utilities, validate_vt_response(), virustotal_info(), virustotal_version()

Create a safe temporary directory for file operations

Description

Creates a temporary directory with restricted permissions for secure file operations during malware analysis.

Usage

create_safe_temp_dir()

Value

Path to the temporary directory

See Also

Other utilities: cleanup_temp_files(), format_file_size(), is_safe_environment(), utilities, validate_vt_response(), virustotal_info(), virustotal_version()

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

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

References

https://docs.virustotal.com/reference/domains

See Also

set_key for setting the API key

Examples

## Not run: 
# Set API key first
set_key('your_api_key_here')

# Get domain reports
report1 <- domain_report("google.com")
report2 <- domain_report("https://www.example.com/path")

print(report1)
summary(report1)

## 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

Retrieves detailed analysis results for a file from VirusTotal using the v3 API.

Usage

file_report(hash, ...)

Arguments

Value

A virustotal_file_report object containing file analysis results including antivirus scans, file metadata, and threat detection information

References

https://docs.virustotal.com/reference/files

See Also

set_key for setting the API key, scan_file for submitting files

Examples

## Not run: 
# Set API key first
set_key('your_api_key_here')

# Get file report using hash
report <- file_report(hash = '99017f6eebbac24f351415dd410d522d')
print(report)
summary(report)

# Work with the rich nested structure returned by v3 API
print(report$data$attributes$last_analysis_stats)

## End(Not run)

Convert file size to human readable format

Description

Convert file size to human readable format

Usage

format_file_size(size_bytes)

Arguments

Value

Character string with human-readable size

See Also

Other utilities: cleanup_temp_files(), create_safe_temp_dir(), is_safe_environment(), utilities, validate_vt_response(), virustotal_info(), virustotal_version()

Get Analysis Results

Description

Retrieves the results of a file or URL analysis by its analysis ID.

Usage

get_analysis(id = NULL, ...)

Arguments

Value

list containing analysis results including status and detection stats

References

https://docs.virustotal.com/reference/analysis

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_analysis(id = 'NjY0MjRlOTFjMDIyYTkyNWM0NjU2NWQzYWNlMzFmZmI6MTI4NTk')

## End(Not run)

Get Behaviour EVTX File

Description

Retrieves the EVTX (Windows Event Log) file from a sandbox analysis.

Usage

get_behaviour_evtx(sandbox_id = NULL, output_path = NULL, ...)

Arguments

Value

Raw EVTX content or saves to file if output_path specified

References

https://docs.virustotal.com/reference

See Also

set_key for setting the API key, get_behaviour_report for JSON report

Examples

## Not run: 

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

evtx <- get_behaviour_evtx(sandbox_id = 'hash_sandboxname')
get_behaviour_evtx(
  sandbox_id = 'hash_sandboxname',
  output_path = '/tmp/events.evtx'
)

## End(Not run)

Get Behaviour HTML Report

Description

Retrieves a detailed HTML report from a sandbox analysis.

Usage

get_behaviour_html(sandbox_id = NULL, output_path = NULL, ...)

Arguments

Value

Raw HTML content or saves to file if output_path specified

References

https://docs.virustotal.com/reference

See Also

set_key for setting the API key, get_behaviour_report for JSON report

Examples

## Not run: 

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

html <- get_behaviour_html(sandbox_id = 'hash_sandboxname')
get_behaviour_html(
  sandbox_id = 'hash_sandboxname',
  output_path = '/tmp/report.html'
)

## End(Not run)

Get Behaviour Memory Dump

Description

Retrieves the memory dump file from a sandbox analysis.

Usage

get_behaviour_memdump(sandbox_id = NULL, output_path = NULL, ...)

Arguments

Value

Raw memory dump content or saves to file if output_path specified

References

https://docs.virustotal.com/reference

See Also

set_key for setting the API key, get_behaviour_report for JSON report

Examples

## Not run: 

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

memdump <- get_behaviour_memdump(sandbox_id = 'hash_sandboxname')
get_behaviour_memdump(
  sandbox_id = 'hash_sandboxname',
  output_path = '/tmp/memory.dmp'
)

## End(Not run)

Get Behaviour PCAP File

Description

Retrieves the PCAP (network capture) file from a sandbox analysis.

Usage

get_behaviour_pcap(sandbox_id = NULL, output_path = NULL, ...)

Arguments

Value

Raw PCAP content or saves to file if output_path specified

References

https://docs.virustotal.com/reference

See Also

set_key for setting the API key, get_behaviour_report for JSON report

Examples

## Not run: 

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

pcap <- get_behaviour_pcap(sandbox_id = 'hash_sandboxname')
get_behaviour_pcap(
  sandbox_id = 'hash_sandboxname',
  output_path = '/tmp/capture.pcap'
)

## End(Not run)

Get Behaviour Report

Description

Retrieves a specific behaviour report from a sandbox analysis.

Usage

get_behaviour_report(sandbox_id = NULL, ...)

Arguments

Value

list containing detailed behaviour report from the sandbox

References

https://docs.virustotal.com/reference

See Also

set_key for setting the API key, get_file_behaviours for listing all behaviour reports

Examples

## Not run: 

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

get_behaviour_report(sandbox_id = 'hash_sandboxname')

## End(Not run)

Retrieve comments for an Internet domain

Description

Retrieve comments for an Internet domain

Usage

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

Arguments

Value

list containing domain comment data including comment text, authors, dates, and any associated metadata from the VirusTotal v3.0 API

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("https://www.example.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("https://www.example.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.example.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("https://www.example.com") # Domain not found

## End(Not run)

Get File Behaviour MITRE ATT&CK Trees

Description

Retrieves MITRE ATT&CK techniques observed in file behaviour reports.

Usage

get_file_behaviour_mitre_trees(hash = NULL, ...)

Arguments

Value

list containing MITRE ATT&CK technique mappings

References

https://docs.virustotal.com/reference

See Also

set_key for setting the API key, get_file_behaviour_summary for behaviour summary

Examples

## Not run: 

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

get_file_behaviour_mitre_trees(hash = '99017f6eebbac24f351415dd410d522d')

## End(Not run)

Get File Behaviour Summary

Description

Retrieves a summary of all behaviour reports for a file.

Usage

get_file_behaviour_summary(hash = NULL, ...)

Arguments

Value

list containing behaviour summary from all sandboxes

References

https://docs.virustotal.com/reference/file-all-behaviours-summary

See Also

set_key for setting the API key, get_file_behaviours for full behaviour reports

Examples

## Not run: 

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

get_file_behaviour_summary(hash = '99017f6eebbac24f351415dd410d522d')

## End(Not run)

Get File Behaviours

Description

Retrieves all behaviour reports for a file from various sandboxes.

Usage

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

Arguments

Value

list containing behaviour reports from various sandboxes

References

https://docs.virustotal.com/reference

See Also

set_key for setting the API key, get_file_behaviour_summary for summary, get_behaviour_report for individual sandbox reports

Examples

## Not run: 

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

get_file_behaviours(hash = '99017f6eebbac24f351415dd410d522d')
get_file_behaviours(hash = '99017f6eebbac24f351415dd410d522d', limit = 5)

## 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 IP address.

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)

Get current rate limit status

Description

Get current rate limit status

Usage

get_rate_limit_status()

Value

List with current status information

See Also

Other rate limiting: rate-limiting, record_request(), reset_rate_limit()

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)

Is an API key set in either environment variable?

Description

Is an API key set in either environment variable?

Usage

has_vt_key()

Value

Logical.

See Also

Other authentication: set_key(), vt_key()

Initialize the request log

Description

Initialize the request log

Usage

init_rate_limit()

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")

## End(Not run)

Check if API key is properly configured

Description

Verifies that the API key is set and appears to be valid format.

Usage

is_api_key_configured()

Value

Logical indicating if API key is configured

See Also

Other security: sanitize_domain(), sanitize_file_path(), sanitize_hash(), sanitize_ip(), sanitize_url(), security-utilities

Is the request log initialized?

Description

Is the request log initialized?

Usage

is_rate_limit_initialized()

Check if running in a safe environment

Description

Verifies that the package is running in an appropriate environment for security analysis work.

Usage

is_safe_environment()

Value

Logical indicating if environment is considered safe

See Also

Other utilities: cleanup_temp_files(), create_safe_temp_dir(), format_file_size(), utilities, validate_vt_response(), virustotal_info(), virustotal_version()

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 an IP address

Description

Add a vote for an 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)

Print method for domain reports

Description

Print method for domain reports

Usage

## S3 method for class 'virustotal_domain_report'
print(x, ...)

Arguments

Value

The object, invisibly. Called for the side effect of printing a summary of the domain report.

Print method for VirusTotal errors

Description

Print method for VirusTotal errors

Usage

## S3 method for class 'virustotal_error'
print(x, ...)

Arguments

Value

The object, invisibly. Called for the side effect of printing the error.

Print method for file reports

Description

Print method for file reports

Usage

## S3 method for class 'virustotal_file_report'
print(x, ...)

Arguments

Value

The object, invisibly. Called for the side effect of printing a summary of the file report.

Print method for VirusTotal responses

Description

Print method for VirusTotal responses

Usage

## S3 method for class 'virustotal_response'
print(x, ...)

Arguments

Value

The object, invisibly. Called for the side effect of printing a summary of the API response.

Rate Limiting for VirusTotal API

Description

Pacing is enforced by httr2::req_throttle() inside the shared request builder (see vt_request), tunable via options(virustotal.requests_per_minute=) and switchable via options(virustotal.throttle=). What lives here is a passive log of request times, kept so virustotal_info() can report usage against the public API's 4-per-minute allowance.

See Also

Other rate limiting: get_rate_limit_status(), record_request(), reset_rate_limit()

Record a performed request

Description

Appends a timestamp to the log. Called after each successful req_perform(); enforcement is httr2's job, not this function's.

Usage

record_request()

Value

Invisible TRUE

See Also

Other rate limiting: get_rate_limit_status(), rate-limiting, reset_rate_limit()

Request rescan of a domain

Description

Request a new analysis of a domain already in VirusTotal's database. Returns an analysis ID for use with domain_report.

Usage

rescan_domain(domain = NULL, ...)

Arguments

Value

list containing analysis details and ID

References

https://docs.virustotal.com/reference

See Also

set_key for setting the API key, domain_report for getting reports

Examples

## Not run: 

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

# Request rescan of a domain
rescan_domain("google.com")

## End(Not run)

Request rescan of a file

Description

Request a new analysis of a file already present in VirusTotal's database. Returns an analysis ID for use with 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)

Request rescan of an IP address

Description

Request a new analysis of an IP address already in VirusTotal's database. Returns an analysis ID for use with ip_report.

Usage

rescan_ip(ip = NULL, ...)

Arguments

Value

list containing analysis details and ID

References

https://docs.virustotal.com/reference

See Also

set_key for setting the API key, ip_report for getting reports

Examples

## Not run: 

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

# Request rescan of an IPv4 address
rescan_ip("8.8.8.8")

# Request rescan of an IPv6 address
rescan_ip("2001:4860:4860::8888")

## End(Not run)

Request rescan of a URL

Description

Request a new analysis of a URL already present in VirusTotal's database. Returns an analysis ID for use with url_report.

Usage

rescan_url(url_id = NULL, ...)

Arguments

Value

list containing analysis details and ID

References

https://docs.virustotal.com/reference

See Also

set_key for setting the API key, url_report for getting reports

Examples

## Not run: 

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

# Request rescan using URL
rescan_url("http://www.google.com")

# Request rescan using URL ID
rescan_url("687474703a2f2f7777772e676f6f676c652e636f6d2f")

## End(Not run)

Reset the request log

Description

Clears all recorded request times. Useful for testing.

Usage

reset_rate_limit()

See Also

Other rate limiting: get_rate_limit_status(), rate-limiting, record_request()

Sanitize domain input

Description

Validates and sanitizes domain names to prevent injection attacks while allowing legitimate domain analysis.

Usage

sanitize_domain(domain)

Arguments

Value

Sanitized domain or throws error if invalid

See Also

Other security: is_api_key_configured(), sanitize_file_path(), sanitize_hash(), sanitize_ip(), sanitize_url(), security-utilities

Sanitize file path input

Description

Validates and sanitizes file paths to prevent directory traversal attacks and ensure safe file operations.

Usage

sanitize_file_path(file_path, allow_relative = FALSE)

Arguments

Value

Sanitized file path or throws error if invalid

See Also

Other security: is_api_key_configured(), sanitize_domain(), sanitize_hash(), sanitize_ip(), sanitize_url(), security-utilities

Sanitize hash input

Description

Validates hash inputs to ensure they conform to expected formats (MD5, SHA1, SHA256) and contain only valid hexadecimal characters.

Usage

sanitize_hash(hash)

Arguments

Value

Sanitized hash or throws error if invalid

See Also

Other security: is_api_key_configured(), sanitize_domain(), sanitize_file_path(), sanitize_ip(), sanitize_url(), security-utilities

Sanitize IP address input

Description

Validates IP addresses (IPv4 and IPv6) and checks for private ranges that shouldn't be submitted to VirusTotal.

Usage

sanitize_ip(ip)

Arguments

Value

Sanitized IP address or throws error if invalid

See Also

Other security: is_api_key_configured(), sanitize_domain(), sanitize_file_path(), sanitize_hash(), sanitize_url(), security-utilities

Sanitize URL input

Description

Validates and sanitizes URLs to prevent malicious inputs while preserving legitimate URLs for analysis.

Usage

sanitize_url(url)

Arguments

Value

Sanitized URL or throws error if invalid

See Also

Other security: is_api_key_configured(), sanitize_domain(), sanitize_file_path(), sanitize_hash(), sanitize_ip(), security-utilities

Submit a file for scanning

Description

Uploads a file to VirusTotal for malware analysis using the v3 API.

Usage

scan_file(file_path, ...)

Arguments

Value

A virustotal_file_scan object with analysis ID and links

References

https://docs.virustotal.com/reference/files-scan

See Also

set_key for setting the API key, file_report for retrieving scan results

Examples

## Not run: 
# Set API key first
set_key('your_api_key_here')

# Scan a file
result <- scan_file(file_path = 'suspicious_file.exe')
print(result)

## 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)

Security Utilities for VirusTotal Package

Description

Security functions for input sanitization and validation to prevent common security issues when working with potentially malicious inputs.

See Also

Other security: is_api_key_configured(), sanitize_domain(), sanitize_file_path(), sanitize_hash(), sanitize_ip(), sanitize_url()

Set VirusTotal API Key

Description

Stores your VirusTotal API key in an environment variable for use by other package functions. Get your API key from https://www.virustotal.com/.

Usage

set_key(api_key = NULL)

Arguments

Details

The canonical environment variable is VIRUSTOTAL_API_KEY; the historical VirustotalToken is also set for compatibility with code that reads it directly. Setting either variable before loading the package works without calling this function at all.

Value

Invisibly returns TRUE on success

References

https://docs.virustotal.com/reference

See Also

Other authentication: has_vt_key(), vt_key()

Examples

## Not run: 
# Set your API key
set_key('your_64_character_api_key_here')

# Verify it's set
Sys.getenv("VIRUSTOTAL_API_KEY")

## End(Not run)

Summary method for VirusTotal responses

Description

Summary method for VirusTotal responses

Usage

## S3 method for class 'virustotal_response'
summary(object, ...)

Arguments

Value

The object, invisibly. Called for the side effect of printing a summary of the API response.

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)

Utility Functions for VirusTotal Package

Description

Helper functions and utilities for the VirusTotal package.

See Also

Other utilities: cleanup_temp_files(), create_safe_temp_dir(), format_file_size(), is_safe_environment(), validate_vt_response(), virustotal_info(), virustotal_version()

Simple input validation

Description

Basic input validation and sanitization for VirusTotal API calls. Replaces over-engineered security functions with simpler checks.

Usage

validate_input(input)

Arguments

Value

Cleaned input string

Validate VirusTotal response structure

Description

Checks if a response from VirusTotal API has the expected structure.

Usage

validate_vt_response(response)

Arguments

Value

Logical indicating if response structure is valid

See Also

Other utilities: cleanup_temp_files(), create_safe_temp_dir(), format_file_size(), is_safe_environment(), utilities, virustotal_info(), virustotal_version()

S3 Classes for VirusTotal Responses

Description

S3 classes to provide structured responses and better user experience when working with VirusTotal API results.

See Also

Other response classes: virustotal_domain_report(), virustotal_file_report(), virustotal_file_scan(), virustotal_ip_report(), virustotal_url_scan()

VirusTotal API Error Classes

Description

Custom error classes for structured error handling in the virustotal package.

See Also

Other error handling: virustotal_auth_error(), virustotal_check(), virustotal_error(), virustotal_rate_limit_error(), virustotal_validation_error()

GET for the Current V3 API

Description

GET for the Current V3 API

Usage

virustotal_GET(path, query = list(), key = vt_key(), ...)

Arguments

Value

list

GET a binary body from the V3 API

Description

For the download and sandbox-artifact endpoints, which return file content rather than JSON. Performed in memory so an error body is never written to a caller's output path.

Usage

virustotal_GET_raw(path, key = vt_key(), ...)

Arguments

Value

A raw vector.

POST for the Current V3 API

Description

POST for the Current V3 API

Usage

virustotal_POST(
  path,
  body = NULL,
  query = list(),
  key = vt_key(),
  encode = "json",
  ...
)

Arguments

Value

list

Create an authentication error

Description

Create an authentication error

Usage

virustotal_auth_error(
  message = "Invalid or missing API key",
  call = sys.call(-1)
)

Arguments

Value

An error object of class virustotal_auth_error

See Also

Other error handling: virustotal-errors, virustotal_check(), virustotal_error(), virustotal_rate_limit_error(), virustotal_validation_error()

Request Response Verification

Description

Enhanced error checking with structured error classes

Usage

virustotal_check(resp)

Arguments

Value

Invisible NULL on success, throws structured errors on failure

See Also

Other error handling: virustotal-errors, virustotal_auth_error(), virustotal_error(), virustotal_rate_limit_error(), virustotal_validation_error()

Create a VirusTotal domain report

Description

Create a VirusTotal domain report

Usage

virustotal_domain_report(data)

Arguments

Value

Object of class virustotal_domain_report

See Also

Other response classes: virustotal-classes, virustotal_file_report(), virustotal_file_scan(), virustotal_ip_report(), virustotal_url_scan()

Create a VirusTotal API error

Description

Create a VirusTotal API error

Usage

virustotal_error(
  message,
  status_code = NULL,
  response = NULL,
  call = sys.call(-1)
)

Arguments

Value

An error object of class virustotal_error

See Also

Other error handling: virustotal-errors, virustotal_auth_error(), virustotal_check(), virustotal_rate_limit_error(), virustotal_validation_error()

Create a VirusTotal file report

Description

Create a VirusTotal file report

Usage

virustotal_file_report(data)

Arguments

Value

Object of class virustotal_file_report

See Also

Other response classes: virustotal-classes, virustotal_domain_report(), virustotal_file_scan(), virustotal_ip_report(), virustotal_url_scan()

Create a VirusTotal file scan result

Description

Create a VirusTotal file scan result

Usage

virustotal_file_scan(data)

Arguments

Value

Object of class virustotal_file_scan

See Also

Other response classes: virustotal-classes, virustotal_domain_report(), virustotal_file_report(), virustotal_ip_report(), virustotal_url_scan()

Print package information and configuration status

Description

Print package information and configuration status

Usage

virustotal_info()

Value

Invisible NULL

See Also

Other utilities: cleanup_temp_files(), create_safe_temp_dir(), format_file_size(), is_safe_environment(), utilities, validate_vt_response(), virustotal_version()

Create a VirusTotal IP report

Description

Create a VirusTotal IP report

Usage

virustotal_ip_report(data)

Arguments

Value

Object of class virustotal_ip_report

See Also

Other response classes: virustotal-classes, virustotal_domain_report(), virustotal_file_report(), virustotal_file_scan(), virustotal_url_scan()

Create a rate limit error

Description

Create a rate limit error

Usage

virustotal_rate_limit_error(
  message = "Rate limit exceeded",
  retry_after = 60,
  call = sys.call(-1)
)

Arguments

Value

An error object of class virustotal_rate_limit_error

See Also

Other error handling: virustotal-errors, virustotal_auth_error(), virustotal_check(), virustotal_error(), virustotal_validation_error()

Create a VirusTotal URL scan result

Description

Create a VirusTotal URL scan result

Usage

virustotal_url_scan(data)

Arguments

Value

Object of class virustotal_url_scan

See Also

Other response classes: virustotal-classes, virustotal_domain_report(), virustotal_file_report(), virustotal_file_scan(), virustotal_ip_report()

Create a validation error

Description

Create a validation error

Usage

virustotal_validation_error(
  message,
  parameter = NULL,
  value = NULL,
  call = sys.call(-1)
)

Arguments

Value

An error object of class virustotal_validation_error

See Also

Other error handling: virustotal-errors, virustotal_auth_error(), virustotal_check(), virustotal_error(), virustotal_rate_limit_error()

Get package version information

Description

Get package version information

Usage

virustotal_version()

Value

Character string with package version

See Also

Other utilities: cleanup_temp_files(), create_safe_temp_dir(), format_file_size(), is_safe_environment(), utilities, validate_vt_response(), virustotal_info()

Resolve the VirusTotal API key

Description

The canonical environment variable is VIRUSTOTAL_API_KEY; VirustotalToken is the historical name and is still honored. set_key() sets both.

Usage

vt_key()

Value

The API key. Throws a virustotal_auth_error if none is set.

See Also

Other authentication: has_vt_key(), set_key()

Build the shared request object

Description

Every endpoint funnels through here, so the user agent, timeout, retry policy and client-side throttle apply uniformly – including the binary download endpoints that used to bypass them.

Usage

vt_request(path, key = vt_key())

Arguments

Value

An httr2 request.

Encode a URL as a VirusTotal v3 URL identifier

Description

The API identifies a URL by its unpadded URL-safe base64 encoding, i.e. base64.urlsafe_b64encode(url).strip("="). The standard base64 alphabet is not interchangeable: a / in the identifier would be read as a path separator and the request would address no endpoint.

Usage

vt_url_id(url)

Arguments

Value

A character string containing the URL identifier.