VirustotalAPI

Ruby Gem for VirusTotal V3 API. If you want the version 2, check out the gem versions up to 0.4.0.

Installation

Add this line to your application's Gemfile:

gem 'virustotal_api'

And then execute:

$ bundle

Or install it yourself as:

$ gem install virustotal_api

Usage

VirusTotal only allows 4 queries per minute for their Public API. https://www.virustotal.com/en/faq/

You will need a Private API Key if you require more queries per minute.

File Find

require 'virustotal_api'

sha256  = '01ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b'
api_key = 'MY_API_KEY'

vtreport = VirustotalAPI::File.find(sha256, api_key)

# Does the resource have any results?
vtreport.exists?
# => true

# URL for File Report (if it exists)
vtreport.report_url
# => "https://www.virustotal.com/api/v3/files/01ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b"

# Report results (if they exist) are available via #report
vtreport.report['data']['attributes']['last_analysis_results']['ClamAV']
# => {"category"=>"undetected", "engine_name"=>"ClamAV", "engine_update"=>"20200826",
# "engine_version"=>"0.102.4.0", "method"=>"blacklist", "result"=>nil}

# Check whether an Antivirus detected this sample or not
vtreport.detected_by('ClamAV')
# => false

File Upload

require 'virustotal_api'

file    = '/path/to/file'
api_key = 'MY_API_KEY'

# for upload file
vtscan = VirustotalAPI::File.upload(file, api_key)
# or large file (more than 32MB)
vtscan = VirustotalAPI::File.upload_large(file, api_key)

# Virustotal ID of file
vtscan.id
# => "01ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b-1419454668"

# Response results are available via #response
vtscan.report
# =>
{"data"=>
  {"id"=>"MTkxNDBmMjU4ZGY1OGZiYzZjNmU2ODcyMWNhYjhkZTM6MTU5ODUzMTE5OQ==",
   "type"=>"analysis"}}

File Analyse

require 'virustotal_api'

sha256  = '01ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b'
api_key = 'MY_API_KEY'

vtrescan = VirustotalAPI::File.analyse(sha256, api_key)

# Virustotal ID of file
vtrescan.id
# => "MTkxNDBmMjU4ZGY1OGZiYzZjNmU2ODcyMWNhYjhkZTM6MTU5ODUzMTE5OQ=="

# Response results are available via #response
vtrescan.report
# =>
{"data"=>
  {"id"=>"MTkxNDBmMjU4ZGY1OGZiYzZjNmU2ODcyMWNhYjhkZTM6MTU5ODUzMTE5OQ==",
   "type"=>"analysis"}}

URL find

require 'virustotal_api'

url     = 'http://www.google.com'
api_key = 'MY_API_KEY'

vturl_report = VirustotalAPI::URL.find(url, api_key)

# Does the resource have any results?
vturl_report.exists?
# => true

# URL for Report (if it exists)
vturl_report.report_url
# => "https://www.virustotal.com/api/v3/urls/dd014af5ed6b38d9130e3f466f850e46d21b951199d53a18ef29ee9341614eaf"

# Report results (if they exist) are available via #report
vturl_report.report['data']['attributes']['last_analysis_results']['Avira']
# => {"category"=>"harmless", "engine_name"=>"Avira", "method"=>"blacklist", "result"=>"clean"}

URL Upload

require 'virustotal_api'

url     = 'http://www.google.com'
api_key = 'MY_API_KEY'

vturl_scan = VirustotalAPI::URL.upload(url, api_key)

# Virustotal ID of file
vturl_scan.id
# => "u-dd014af5ed6b38d9130e3f466f850e46d21b951199d53a18ef29ee9341614eaf-1598531929"

# Response results are available via #response
vturl_scan.report
# =>
{"data"=>
  {"id"=>
    "u-dd014af5ed6b38d9130e3f466f850e46d21b951199d53a18ef29ee9341614eaf-1598531929",
   "type"=>"analysis"}}

IP Find

require 'virustotal_api'

ip      = '8.8.8.8'
api_key = 'MY_API_KEY'

vtip_report = VirustotalAPI::IP.find(ip, api_key)

# Does the resource have any results?
vtip_report.exists?
# => true

# URL for Report (if it exists)
vtip_report.report_url
# => "https://www.virustotal.com/api/v3/ip_addresses/8.8.8.8"

# Report results (if they exist) are available via #report
vtip_report.report
# => Hash of report results

Domain Find

require 'virustotal_api'

domain  = 'virustotal.com'
api_key = 'MY_API_KEY'

vtdomain_report = VirustotalAPI::Domain.find(domain, api_key)

# Does the resource have any results?
vtdomain_report.exists?
# => true

# URL for Report (if it exists)
vtdomain_report.report_url
# => "https://www.virustotal.com/api/v3/domains/virustotal.com"

# Report results (if they exist) are available via #report
vtdomain_report.report
# => Hash of report results

User Find

require 'virustotal_api'

user_key  = 'user_key' # user_id or api_key
api_key = 'MY_API_KEY'

vtuser_report = VirustotalAPI::User.find(user_key, api_key)

# Does the resource have any results?
vtuser_report.exists?
# => true

# Report results (if they exist) are available via #report
vtuser_report.report
# => Hash of report results

Group Find

require 'virustotal_api'

group_id  = 'GROUP_id'
api_key = 'MY_API_KEY'

vtgroup_report = VirustotalAPI::Group.find(group_id, api_key)

# Does the resource have any results?
vtgroup_report.exists?
# => true

# Report results (if they exist) are available via #report
vtgroup_report.report
# => Hash of report results

Contributors

• @jonnynux
• @crondaemon
• @postmodern
• @mkunkel
• @Grandman

Contributing

1. Fork it ( https://github.com/pwelch/virustotal_api/fork )
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request