metascan 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ef3bca447dda61607d61ce407a66fe8a87cd1b0e
-  data.tar.gz: f7c01b0c3cc710864aa86ecb7a02a89dbae82f0a
+  metadata.gz: b8b106f508db192aa4466c1a3d02026eff07f26f
+  data.tar.gz: 41e9c4da741cba423929530e55bd010af0f4cbf8
 SHA512:
-  metadata.gz: 985594e081de4084d684ac4d6261a1995759bd6f3e9626a31489248c5f6c0f8c8f23ea83139dd1ca882aa50e1f1af6178661aa63bc7fdd0b0bcc82a05179459b
-  data.tar.gz: 4cdf9e857fa9ae41531f8322e0a1a8dc1dab5db2d658cfa89fd4c1e6bcb82af371f681a403a6523c415e762c3a25fe916887d451aa3a94d71591f352f07f8bae
+  metadata.gz: 4abbce86ee4991ab4f081741eb897fa73830b70b0ff5c654e6bb71a3f7792eb18b58c459078a9472d3fcea4b18a80abb42a2da99f56168e54d9302162d06972b
+  data.tar.gz: abffaaa71c84dae9b6d547ec1c351f23353060a97008c05e65e0fd7063a967aa59c9ffe762bb32355bc5a26da1fc1d7dd8ee4931c68d06cbf0e944a96e830c16

data/lib/batch.rb

@@ -0,0 +1,59 @@
+module Metascan
+
+  require_relative 'scan'
+  require_relative 'client'
+
+  # A batch of scanned files. Exposes similar methods to Scan, but
+  # for a group of files.
+  class Batch
+
+    # @scans is a hash like so:
+    # {
+    #   filename (string) => <Metascan::Scan>,
+    #   filename (string) => <Metascan::Scan>,
+    #   ...
+    # }
+    attr_accessor :scans
+
+    def initialize(hydra)
+      @scans = {}
+      @hydra = hydra
+    end
+
+    # Add a scan to my scans, man.
+    def add(scan)
+      unless scan.kind_of? Metascan::Scan
+       raise TypeError, "Must pass a Scan object to Batch.add"
+      end
+      @scans = @scans.merge({ scan.filename => scan })
+      @hydra.queue scan.request
+    end
+
+    # Return true iff all my scans are clean.
+    def clean?
+      @scans.map{ |id, s| s.clean? poll: true }.inject{ |s1, s2| s1 && s2 }
+    end
+
+    # Return a list of all the dirty scans in my batch.
+    def dirty
+      @scans.select{ |id, s| !(s.clean? poll: true) }.map{ |id, s| s }
+    end
+
+    def run
+      @hydra.run
+    end
+
+    # Retrieve results for all the Scans in my batch.
+    # Uses the hydra for parallel processing.
+    # Call this AFTER calling #run.
+    def retrieve_results
+      results_hydra = Typhoeus::Hydra.new
+      @scans.each do |id, s|
+        results_hydra.queue(s.retrieve_results)
+      end
+      results_hydra.run
+    end
+
+  end
+
+end

data/lib/client.rb

@@ -0,0 +1,60 @@
+module Metascan
+
+  require 'typhoeus'
+
+  # The Client object, which stores an API key and has a (currently not used)
+  # Typhoeus::Hydra for when you have a lot of requests to make at once.
+  class Client
+    # An API key is required. Free at www.metascan-online.com
+    def initialize(api_key)
+      @api_key = api_key
+      @hydra   = Typhoeus::Hydra.hydra
+    end
+
+    def api_key
+      @api_key
+    end
+
+    # A Typhoeus Hydra manages parallel HTTP requests.
+    def hydra
+      if !@hydra
+        @hydra = Typhoeus::Hydra.hydra
+      end
+      @hydra
+    end
+
+    # Returns a Scan object
+    # Sample usage:
+    #
+    #   scanner = Metascan::Client.new(MY_API_KEY) 
+    #   filename = "/etc/unwise-backups/passwd.rar" # FULLY QUALIFIED
+    #   scanner.scan_file(filename, archivepwd: "the eagle has left the nest")
+    #   => <Metascan::Scan ... >
+    #
+    # https://www.metascan-online.com/en/public-api
+    def scan_file(filename, archivepwd: nil)
+      scan = Metascan::Scan.new(filename, self)
+      scan.run
+      scan
+    end
+
+    # Scan a batch of files by processing the requests in parallel with
+    # Typhoeus::Hydra. Returns a Metascan::Batch object, which can iterate
+    # over the set of finished scans.
+    # Sample usage:
+    #
+    #   scanner = Metascan::Client.new(MY_API_KEY)
+    #   filenames = ["/etc/passwd", "/dev/sda0", "/dev/random.tgz"] # don't try this
+    #   scanner.scan_batch(filenames, archivepwds: { "/dev/random.tgz" => "hunter2" })
+    #   => <Metascan::Batch ...>
+    def scan_batch(filenames, archivepwds: nil)
+      scans = Metascan::Batch.new(self.hydra)
+      filenames.each do |f|
+        scan = Metascan::Scan.new(f, self)
+        scans.add(scan)
+      end
+      scans.run
+      scans
+    end
+  end
+end

data/lib/scan.rb

@@ -0,0 +1,86 @@
+module Metascan
+
+  require 'typhoeus'
+  require 'json'
+
+  # A single scan on the Metascan service.
+  # Initialized with the parameters to scan,
+  # exposes methods to inspect the scan results.
+  class Scan
+    attr_reader :data_id
+    attr_reader :filename
+
+    def initialize(filename, client, archivepwd: nil)
+      @filename   = filename
+      @client     = client
+      @archivepwd = archivepwd
+    end
+
+    # Initiate a scan of @filename
+    def run
+      self.request.run
+    end
+
+    # Construct and return the request I use, for the purpose of
+    # queueing in a Typhoeus::Hydra.
+    def request
+      request = Typhoeus::Request.new(
+        Metascan::PATHS[:scan_file],
+        headers: {
+          'filename' => @filename,
+          'archivepwd' => @archivepwd,
+          'apikey' => @client.api_key
+        }.select { |k, v| !v.nil? },
+        method: :post,
+        body: { file: File.open(@filename, "r") }
+      )
+
+      request.on_complete do |r|
+        @data_id = JSON.parse(r.body)["data_id"]
+      end
+
+      request
+    end
+
+    # Returns true iff the Metascan virus scan found no threats.
+    # If POLL is true (false by default) then retrieve_results first.
+    def clean?(poll: false)
+      self.results(poll: poll)["scan_results"]["scan_all_result_i"] == 0
+    end
+
+    # Only useful for testing.
+    def results=(results)
+      @results = results
+    end
+
+    # Return the results of my scan.
+    # If the optional argument "poll" is set to true, then attempt
+    # to requery Metascan for the results before returning them.
+    def results(poll: false)
+      if poll and
+        (!@results or @results["scan_results"]["progress_percentage"] < 100) then
+        retrieve_results.run
+      end
+      @results
+    end
+
+    # Returns a HTTP request to retrieve the latest scan results for me.
+    # Fails if called before @data_id is set (when self.run is called, or
+    # my Batch runs me)
+    def retrieve_results
+      request = Typhoeus::Request.new(
+        Metascan::PATHS[:results_by_data_id] + @data_id,
+        headers: {
+          'apikey' => @client.api_key
+        },
+        method: :get
+      )
+
+      request.on_complete do |r|
+        @results = JSON.parse(r.body)
+      end
+
+      request
+    end
+  end
+end

data/metascan.rb

@@ -0,0 +1,18 @@
+module Metascan
+
+  require 'typhoeus'
+  require 'json'
+
+  # Paths to use for api calls.
+  PATHS = {
+    :scan_file            => "https://api.metascan-online.com/v1/file",
+    :results_by_data_id   => "https://api.metascan-online.com/v1/file/",
+    :results_by_file_hash => "https://api.metascan-online.com/v1/hash/"
+  }
+
+  # a miserable pile of library classes!
+  require_relative 'lib/scan'
+  require_relative 'lib/client'
+  require_relative 'lib/batch'
+
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: metascan
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - Grayson Chao
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-04-18 00:00:00.000000000 Z
+date: 2014-04-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -24,6 +24,20 @@ dependencies:
     - - '>='
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: typhoeus
   requirement: !ruby/object:Gem::Requirement
@@ -38,13 +52,16 @@ dependencies:
     - - '>='
       - !ruby/object:Gem::Version
         version: 0.6.8
-description: Allows scanning files using the Metascan public API. https://www.metascan-online.com/en/public-api
+description: Allows virus scanning files using the Metascan public API. https://www.metascan-online.com/en/public-api
 email: graysonchao@berkeley.edu
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- lib/metascan.rb
+- metascan.rb
+- lib/client.rb
+- lib/batch.rb
+- lib/scan.rb
 homepage: http://rubygems.org/gems/metascan
 licenses:
 - MIT
@@ -68,5 +85,5 @@ rubyforge_project:
 rubygems_version: 2.0.3
 signing_key: 
 specification_version: 4
-summary: Scan files using the Metascan public API.
+summary: Scan files for viruses using the Metascan public API.
 test_files: []

data/lib/metascan.rb

@@ -1,119 +0,0 @@
-module Metascan
-
-  require 'typhoeus'
-  require 'json'
-
-  # Constants like paths and stuff.
-  PATHS = {
-    :scan_file            => "https://api.metascan-online.com/v1/file",
-    :results_by_data_id   => "https://api.metascan-online.com/v1/file/",
-    :results_by_file_hash => "https://api.metascan-online.com/v1/hash/"
-  }
-
-  # A single scan on the Metascan service.
-  # Initialized with the parameters to scan,
-  # exposes methods to inspect the scan results.
-  class Scan
-    def initialize(filename, client, archivepwd: nil)
-      @filename   = filename
-      @client     = client
-      @archivepwd = archivepwd
-    end
-
-    # Initiate a scan of @filename
-    def run
-      request = Typhoeus::Request.new(
-        Metascan::PATHS[:scan_file],
-        headers: {
-          'filename' => @filename,
-          'archivepwd' => @archivepwd,
-          'apikey' => @client.api_key
-        }.select { |k, v| !v.nil? },
-        method: :post,
-        body: { file: File.open(@filename, "r") }
-      )
-
-      request.on_complete do |r|
-        @data_id = JSON.parse(r.body)["data_id"]
-        retrieve_results
-      end
-
-      request.run
-    end
-
-    # Is my file clean?
-    def clean?
-      self.results["scan_results"]["scan_all_result_i"] == 0
-    end
-
-    # Only useful for testing.
-    def results=(results)
-      @results = results
-    end
-
-    # Return the results of my scan.
-    # If the optional argument "poll" is set to true, then attempt
-    # to requery Metascan for the results before returning them.
-    def results(poll: true)
-      if !@results or 
-        (poll and @results["scan_results"]["progress_percentage"] < 100) then
-        @results = retrieve_results
-      end
-      @results
-    end
-
-    def data_id
-      @data_id
-    end
-
-    def retrieve_results
-      request = Typhoeus::Request.new(
-        Metascan::PATHS[:results_by_data_id] + @data_id,
-        headers: {
-          'apikey' => @client.api_key
-        },
-        method: :get
-      )
-
-      response = request.run
-      JSON.parse(response.body)
-    end
-  end
-
-  # The Client object, which stores an API key and has a (currently not used)
-  # Typhoeus::Hydra for when you have a lot of requests to make at once.
-  class Client
-    # An API key is required. Free at www.metascan-online.com
-    def initialize(api_key)
-      @api_key = api_key
-      @hydra   = Typhoeus::Hydra.hydra
-    end
-
-    def api_key
-      @api_key
-    end
-
-    # A Typhoeus Hydra manages parallel HTTP requests.
-    def hydra
-      if !@hydra
-        @hydra = Typhoeus::Hydra.hydra
-      end
-      @hydra
-    end
-
-    # Returns a Scan object
-    # Sample usage:
-    #
-    #   scanner = Metascan::Client.new(MY_API_KEY) 
-    #   filename = "/etc/unwise-backups/passwd.rar" # FULLY QUALIFIED
-    #   scanner.scan_file(filename, archivepwd: "the eagle has left the nest")
-    #   => <Metascan::Scan ... >
-    #
-    # https://www.metascan-online.com/en/public-api
-    def scan_file(filename, archivepwd: nil)
-      scan = Metascan::Scan.new(filename, self)
-      scan.run
-      scan
-    end
-  end
-end