Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/pwelch/virustotal_api

Ruby Gem for VirusTotal API
https://github.com/pwelch/virustotal_api

malware-analysis ruby security

Last synced: 1 day ago
JSON representation

Ruby Gem for VirusTotal API

Host: GitHub
URL: https://github.com/pwelch/virustotal_api
Owner: pwelch
License: mit
Created: 2014-12-21T18:34:28.000Z (almost 10 years ago)
Default Branch: main
Last Pushed: 2023-01-19T21:34:25.000Z (almost 2 years ago)
Last Synced: 2024-04-25T12:21:06.793Z (7 months ago)
Topics: malware-analysis, ruby, security
Language: Ruby
Homepage: https://pwelch.github.io/virustotal_api
Size: 189 KB
Stars: 27
Watchers: 4
Forks: 17
Open Issues: 0
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE.txt
- Code of conduct: .github/CODE_OF_CONDUCT.md

Awesome Lists containing this project

README

        # VirustotalAPI

Ruby Gem for [VirusTotal](https://www.virustotal.com) [V3 API](https://developers.virustotal.com/v3.0/reference).

If you want the version 2, check out the gem versions up to [0.4.0](https://github.com/crondaemon/virustotal_api/tree/v0.4.0).

![Ruby](https://github.com/pwelch/virustotal_api/workflows/Ruby/badge.svg)

[![Gem Version](https://badge.fury.io/rb/virustotal_api.svg)](http://badge.fury.io/rb/virustotal_api)

## Installation

Add this line to your application's Gemfile:

```ruby

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

```ruby

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

```ruby

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

```ruby

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

```ruby

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

```ruby

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

```ruby

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

```ruby

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

```ruby

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

```ruby

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](https://github.com/jonnynux)

- [@crondaemon](https://github.com/crondaemon/)

- [@postmodern](https://github.com/postmodern)

- [@mkunkel](https://github.com/mkunkel)

- [@Grandman](https://github.com/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