ratonvirus 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2858dfe945bf74c96269185692c5737c5469adf2404f144aeb4f04e9ae546687
+  data.tar.gz: 07262f10a07c229a92fa8e0b7f7747cff8f33d538804048706b0bd60650d8aeb
+SHA512:
+  metadata.gz: 0f039177a939be1eb63a0fc00c626b533dffafae9c906c607e22bf968247e602380304e6075b636d3d08daaa98815adaca5cafa8d3cf87572fd232a15cb3c1c1
+  data.tar.gz: 041f921088ba88398efddd3d437a38360435b88b4a0ab424047768c59b3ecabda69ca1597a5e0a6ac555a818946713b18492597858b29c167d755c3811ccafb4

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+# v0.1.0
+
+Initial public release.

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2018 Mainio Tech Ltd.
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,247 @@
+# <img alt="Ratonvirus" src="https://raw.githubusercontent.com/mainio/ratonvirus/master/ratonvirus.png" width="600">
+
+Rails antivirus made easy.
+Developed by [Mainio Tech](https://www.mainiotech.fi/).
+
+[![Build Status](https://travis-ci.org/mainio/ratonvirus.svg?branch=master)](https://travis-ci.org/mainio/ratonvirus)
+[![codecov](https://codecov.io/gh/mainio/ratonvirus/branch/master/graph/badge.svg)](https://codecov.io/gh/mainio/ratonvirus)
+
+Ratonvirus allows your Rails application to rat on the viruses that your users
+try to upload to your site. This works through Rails validators that you can
+easily attach to your models.
+
+The purpose of Ratonvirus is to act as the glue that binds your Rails
+application to a virus scanner and file storage engine of your choise.
+
+Setting up scanning for files attached to models:
+
+```ruby
+class Model < ApplicationRecord
+  # ...
+  validates :file, antivirus: true
+  # ...
+end
+```
+
+Running manual scans:
+
+```ruby
+puts "File contains a virus" if Ratonvirus.scanner.virus?('/path/to/file.pdf')
+```
+
+Manual scanning works e.g. for file uploads, file object and file paths.
+
+Ratonvirus works well with Active Storage out of the box. Support for
+CarrierWave is provided through an additional gem (see details well).
+
+## When to use this?
+
+This gem can be handy if you want to:
+
+- Scan files for viruses in Ruby, especially in Rails
+- Make the scanning logic agnostic of the
+  * scanner implementation (e.g. ClamAV)
+  * file storage (e.g. Active Storage, CarrierWave, no storage engine)
+- Separate testing code for the scanner implementation or the file storage
+  cleanly into its own place.
+
+## Prerequisites
+
+There is no fully Ruby-based virus scanner available on the market for a good
+reason: it is a heavy task. Therefore, this gem may not work as automagically
+as you are used to with many other gems.
+
+You will need to setup a virus scanner on your machine. If you have done that
+before, configuration should be rather simple. Instructions are provided for
+the open source ClamAV scanner.
+
+This gem ships with an example
+[EICAR file](https://en.wikipedia.org/wiki/EICAR_test_file) scanner to test out
+the configuration process. This scanner allows you to test the functionality of
+this gem with no external requirements but it should not be used in production
+environments.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'ratonvirus'
+```
+
+And then execute:
+
+```bash
+$ bundle
+```
+
+Add this initializer to your application's `config/initializers/ratonvirus.rb`:
+
+```ruby
+# config/initializers/ratonvirus.rb
+Ratonvirus.configure do |config|
+  config.scanner = :eicar
+  config.storage = :active_storage
+end
+```
+
+After installation, test that the gem is loaded properly in your it is ready to
+do a sample validation:
+
+```bash
+$ bundle exec rails ratonvirus:test
+```
+
+This command should show the following message when correctly installed:
+
+```
+Ratonvirus correctly configured.
+```
+
+**NOTE:**
+
+By default Ratonvirus is set to remove all infected files that it detects after
+scanning them. If you want to remove this functionality, please refer to the
+[Scanner addons](doc/index.md#scanner-addons) section of the developer
+documentation.
+
+## Usage
+
+### Applying the antivirus validator to your models
+
+In order to apply the antivirus validator, you need to have your file uploads
+handled by a storage backend such as Active Storage. Examples are provided below
+for the most common options.
+
+#### Example with Active Storage
+
+Your model should look similar to this:
+
+```ruby
+class YourModel < ApplicationRecord
+  has_one_attached :file
+  validates :file, antivirus: true # Add this for antivirus validation
+end
+```
+
+#### Example with CarrierWave
+
+Your model should look similar to this:
+
+```ruby
+class YourModel < ApplicationRecord
+  mount_uploader :file, YourUploader
+  validates :file, antivirus: true # Add this for antivirus validation
+end
+```
+
+Please note the extra configuration you need for CarrierWave from the
+configuration examples.
+
+### Manually checking for viruses
+
+For the manual scans to work you need to configure the correct storage backend
+first that accepts these resources:
+
+```ruby
+# config/initializers/ratonvirus.rb
+
+# When scanning files or file paths only
+Ratonvirus.configure do |config|
+  config.storage = :filepath
+end
+
+# When scanning files, file paths or active storage resources
+Ratonvirus.configure do |config|
+  config.storage = :multi, [:filepath, :active_storage]
+end
+```
+
+In case you want to manually scan for viruses, you can use any of the following
+examples:
+
+```ruby
+# It is a good idea to check first that the scanner is available.
+if Ratonvirus.scanner.available?
+  # Scanning a file path
+  path = '/path/to/file.pdf'
+  if Ratonvirus.scanner.virus?(path)
+    puts "There is a virus at #{path}"
+  end
+
+  # Scanning a File object
+  file = File.new(path)
+  if Ratonvirus.scanner.virus?(file)
+    puts "There is a virus at #{file.path}"
+  end
+end
+```
+
+### Sample configurations
+
+Here are few sample configurations to speed up the configuration process.
+
+#### Active Storage and ClamAV
+
+Gemfile:
+
+```ruby
+gem 'ratonvirus'
+gem 'ratonvirus-clamby'
+```
+
+Initializer:
+
+```ruby
+# config/initializers/ratonvirus.rb
+Ratonvirus.configure do |config|
+  config.scanner = :clamby
+  config.storage = :active_storage
+end
+```
+
+Model:
+
+```ruby
+class YourModel < ApplicationRecord
+  has_one_attached :file
+  validates :file, antivirus: true
+end
+```
+
+#### CarrierWave and ClamAV
+
+Gemfile:
+
+```ruby
+gem 'ratonvirus'
+gem 'ratonvirus-clamby'
+```
+
+Initializer:
+
+```ruby
+# config/initializers/ratonvirus.rb
+Ratonvirus.configure do |config|
+  config.scanner = :clamby
+  config.storage = :carrierwave
+end
+```
+
+Model:
+
+```ruby
+class YourModel < ApplicationRecord
+  mount_uploader :file, YourUploader
+  validates :file, antivirus: true
+end
+```
+
+## Further configuration and development
+
+For further information about the configurations and how to create custom
+scanners, please refer to the [documentation](doc/index.md).
+
+## License
+
+MIT, see [LICENSE](LICENSE).

data/app/validators/antivirus_validator.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+class AntivirusValidator < ActiveModel::EachValidator
+  def validate_each(record, attribute, value)
+    # Avoid unnecessary scans in case
+    # a) the storage backend does not accept the resource
+    # b) the attribute has not changed
+    storage = Ratonvirus.storage
+    return unless storage.accept?(value)
+    return unless storage.changed?(record, attribute)
+
+    # Only scan if the scanner is available
+    scanner = Ratonvirus.scanner
+    return unless scanner.available?
+
+    if scanner.virus?(value)
+      if scanner.errors.any?
+        scanner.errors.each do |err|
+          record.errors.add attribute, err
+        end
+      else
+        record.errors.add attribute, :antivirus_virus_detected
+      end
+    end
+  end
+end

data/config/locales/en.yml

@@ -0,0 +1,6 @@
+en:
+  errors:
+    messages:
+      antivirus_virus_detected: 'contains a virus'
+      antivirus_client_error: 'could not be processed for virus scan'
+      antivirus_file_not_found: 'could not be found for virus scan'

data/config/locales/fi.yml

@@ -0,0 +1,6 @@
+fi:
+  errors:
+    messages:
+      antivirus_virus_detected: 'sisältää viruksen'
+      antivirus_client_error: 'ei voitu käsitellä virustarkistusta varten'
+      antivirus_file_not_found: 'ei ollut saatavilla virustarkistusta varten'

data/config/locales/sv.yml

@@ -0,0 +1,6 @@
+sv:
+  errors:
+    messages:
+      antivirus_virus_detected: 'innehåller ett virus'
+      antivirus_client_error: 'kunde inte behandlas för virusskanning'
+      antivirus_file_not_found: 'kunde inte hittas för virusskanning'

data/lib/ratonvirus.rb

@@ -0,0 +1,109 @@
+require "fileutils"
+require "active_support"
+require "digest"
+
+require_relative "ratonvirus/version"
+require_relative "ratonvirus/error"
+require_relative "ratonvirus/processable"
+require_relative "ratonvirus/support/backend"
+require_relative "ratonvirus/scanner/support/callbacks"
+require_relative "ratonvirus/scanner/base"
+require_relative "ratonvirus/scanner/eicar"
+require_relative "ratonvirus/scanner/addon/remove_infected"
+require_relative "ratonvirus/storage/base"
+require_relative "ratonvirus/storage/filepath"
+require_relative "ratonvirus/storage/active_storage"
+require_relative "ratonvirus/storage/carrierwave"
+require_relative "ratonvirus/storage/multi"
+
+require_relative "ratonvirus/engine" if defined?(Rails)
+
+module Ratonvirus
+  extend Ratonvirus::Support::Backend
+
+  # Usage:
+  #   Ratonvirus.configure do |config|
+  #     config.scanner = :eicar
+  #     config.storage = :active_storage
+  #     config.addons  = [:remove_infected]
+  #   end
+  def self.configure
+    yield self
+  end
+
+  # Usage (set):
+  #   Ratonvirus.scanner = :eicar
+  #   Ratonvirus.scanner = :eicar, {option: 'value'}
+  #   Ratonvirus.scanner = Ratonvirus::Scanner::Eicar.new
+  #   Ratonvirus.scanner = Ratonvirus::Scanner::Eicar.new({option: 'value'})
+  #
+  # Usage (get):
+  #   Ratonvirus.scanner
+  #
+  # Usage (destroy):
+  #   Ratonvirus.destroy_scanner
+  define_backend :scanner, 'Scanner'
+
+  # Usage (set):
+  #   Ratonvirus.storage = :active_storage
+  #   Ratonvirus.storage = :active_storage, {option: 'value'}
+  #   Ratonvirus.storage = Ratonvirus::Storage::ActiveStorage.new
+  #   Ratonvirus.storage = Ratonvirus::Storage::ActiveStorage.new({option: 'value'})
+  #
+  # Usage (get):
+  #   Ratonvirus.storage
+  #
+  # Usage (destroy):
+  #   Ratonvirus.destroy_storage
+  define_backend :storage, 'Storage'
+
+  # Resets Ratonvirus to its initial state and configuration
+  def self.reset
+    # Default addons
+    @addons = [
+      ActiveSupport::Inflector.constantize(
+        "#{self.name}::Scanner::Addon::RemoveInfected"
+      ),
+    ]
+
+    self.destroy_scanner
+    self.destroy_storage
+  end
+
+  def self.addons
+    @addons
+  end
+
+  def self.addons=(addons)
+    @addons = []
+    addons.each do |addon|
+      self.add_addon addon
+    end
+  end
+
+  def self.add_addon(addon)
+    addon_cls = addon_class(addon)
+    unless @addons.include?(addon_cls)
+      @addons << addon_cls
+    end
+  end
+
+  def self.remove_addon(addon)
+    addon_cls = addon_class(addon)
+    @addons.delete(addon_cls)
+  end
+
+  # private
+  def self.addon_class(type)
+    return type if type.is_a?(Class)
+
+    subclass = ActiveSupport::Inflector.camelize(type.to_s)
+    ActiveSupport::Inflector.constantize(
+      "#{self.name}::Scanner::Addon::#{subclass}"
+    )
+  end
+  private_class_method :addon_class
+
+  # Reset the utility to start with
+  reset
+end

data/lib/ratonvirus/engine.rb

@@ -0,0 +1,6 @@
+# Binding it to rails to make the app and config folders available in the Rails
+# load paths.
+module Ratonvirus
+  class Engine < ::Rails::Engine
+  end
+end