ratonvirus-clamby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2ab97421ef8f1bcf87fc7465487f76f65d703b9e31ffc7fa156846863887ff90
+  data.tar.gz: d917af42da7b4602fb6e674e863c8ee16ba454457cc7d500396f16c35b1b1eaa
+SHA512:
+  metadata.gz: 308ed44513124fd828b795f4bee414ead467a4ff8ae3c086d15b2a02a39a6dcf3fd9ccd7ce180a90e1278f06fdb11eecc923e34bd5a0704f840da11531f16a00
+  data.tar.gz: 6d551e25b9247bc0c72e11a5dce518e6920c8ddc27c6b5d149d3646751b687e32dcb7b4bc2c4759cafc61edee31fe5b088c5c3e6e1b11b03ad2451d6cdd138ea

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,256 @@
+# Ratonvirus - Clamby
+
+Developed by [Mainio Tech](https://www.mainiotech.fi/).
+
+[![Build Status](https://api.travis-ci.org/mainio/ratonvirus-clamby.svg?branch=master)](https://travis-ci.org/mainio/ratonvirus-clamby)
+[![codecov](https://codecov.io/gh/mainio/ratonvirus-clamby/branch/master/graph/badge.svg)](https://codecov.io/gh/mainio/ratonvirus-clamby)
+
+This gem provides a [Clamby](https://github.com/kobaltz/clamby) scanner for
+[Ratonvirus](https://github.com/mainio/ratonvirus).
+
+It allows Ratovirus to scan the files using [ClamAV](https://www.clamav.net/).
+
+## Prerequisites
+
+You need to have ClamAV installed on the target machine for the antivirus checks
+to actually work. With the default configuration, you will also need the ClamAV
+daemon installed in order to make the antivirus checks more efficient.
+
+For full ClamAV installation instructions, please refer to
+[ClamAV documentation](https://www.clamav.net/documents/installing-clamav).
+
+For configuring ClamAV, please refer to
+[Clamby documentation](https://github.com/kobaltz/clamby).
+
+### ClamAV installation on Ubuntu/Debian
+
+For proper ClamAV configuration in Ubuntu/Debian environments, follow these
+steps:
+
+#### 1. ClamAV and daemon installation
+
+```bash
+$ sudo apt install clamav clamav-daemon
+```
+
+#### 2. ClamAV configuration
+
+```
+# Change the following from /etc/clamav/freshclam.conf
+# Change `local` to your country code
+DatabaseMirror db.local.clamav.net
+```
+
+```
+# Change the following from /etc/clamav/clamd.conf
+# Most Rails apps use symlinks in the production environment
+FollowDirectorySymlinks true
+FollowFileSymlinks true
+```
+
+#### 3. AppArmor configuration for clamd
+
+Make sure that the folder where your application is running is included in the
+readable directories list:
+
+```bash
+$ sudo less /etc/apparmor.d/usr.sbin.clamd
+```
+
+If not, edit the local AppArmor configuration:
+
+```bash
+$ sudo nano /etc/apparmor.d/local/usr.sbin.clamd
+```
+
+Add the following line there with your application directory:
+
+```
+# Allow scanning for the application subdirs
+/path/to/your/app/** r,
+```
+
+And finally reload apparmor configuration:
+
+```bash
+$ sudo systemctl reload apparmor
+```
+
+#### 4. Restart ClamAV daemons
+
+```bash
+$ sudo systemctl restart clamav-freshclam
+$ sudo systemctl restart clamav-daemon
+```
+
+### Ensure that ClamAV installation is working properly
+
+Go to your application folder and create simple test files there to test the
+virus scanning:
+
+```bash
+$ cd /path/to/your/app
+$ echo 'This is clean' > clean.pdf
+$ wget -O dirty.pdf https://secure.eicar.org/eicar.com
+```
+
+The file `dirty.pdf` fetched from the URL is an
+[EICAR test file](https://en.wikipedia.org/wiki/EICAR_test_file) used to test
+the response of the antivirus scan.
+
+Run the antivirus tests for both of these files using `clamdscan`:
+
+```bash
+$ clamdscan clean.pdf dirty.pdf
+```
+
+You should see the following type of output from that command when ClamAV and
+its daemon are correctly working:
+
+```
+/path/to/your/app/clean.pdf: OK
+/path/to/your/app/dirty.pdf: Eicar-Test-Signature FOUND
+
+----------- SCAN SUMMARY -----------
+Infected files: 1
+Time: 0.001 sec (0 m 0 s)
+```
+
+NOTE:
+
+It is important that you test this in the actual production environment inside
+the application folder or the folder where the users are uploading the files in
+order to ensure that ClamAV daemon is able to access that folder and read files
+from it.
+
+Also note that Decidim uses
+[CarrierWave](https://github.com/carrierwaveuploader/carrierwave) to handle its
+file uploads and processing on the server, so make sure you are also testing the
+possible temporary paths of CarrierWave.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'ratonvirus'
+gem 'ratonvirus-clamby'
+```
+
+Then execute:
+
+```bash
+$ bundle
+```
+
+And finally configure the scanner for Ratonvirus:
+
+```ruby
+Ratonvirus.configure do |config|
+  config.scanner = :clamby
+end
+```
+
+## Possible scanning errors
+
+There are multiple scanning errors that this script may produce for the file
+attribute. Here are the explanations for each of the errors.
+
+Please note that if you have done any changes to the default configurations,
+not all of these errors may be
+
+### antivirus_virus_detected ("contains a virus")
+
+This means that the given file contains a virus detected by ClamAV.
+
+This virus can be shown in few different occasions:
+
+- The `clamdscan` executable did its work successfully, detected a virus and
+  returned with an exit code 1.
+- The `clamdscan` executable is not executable by the user under which the Rails
+  app is run. This caused the system call to return with an exit code 126.
+- The `clamdscan` executable is not available in the machine. This caused the
+  system call to return with an exit code 127.
+
+Shown when the `clamdscan` executable returns with the exit code other than 0 or
+2.
+
+### antivirus_client_error ("could not be processed for virus scan")
+
+This means that the given file contains a virus detected by ClamAV.
+
+In this case the `clamdscan` executable did not finish its work successfully and
+an error was produced. This can be generally caused by the `clamav-daemon`
+service because of few different reasons:
+
+- The daemon cannot access the file to be checked. Please refer to the
+  configuration section for further information.
+- The daemon service is not running on the target machine. Please refer to the
+  configuration section for further information.
+- The daemon service is currently handling too many concurrent virus checks.
+  This should be fixed by itself once the daemon finishes the previous checks.
+
+Shown when the `clamdscan` executable returns with the exit code 2.
+
+### antivirus_file_not_found ("could not be found for virus scan")
+
+This means that the file passed to the ClamAV virus scan is no longer available
+when the scan was about to be performed.
+
+In this case, the `clamdscan` executable is not run.
+
+Shown when the file has disappeared from the file system between the upload
+procedure and Ratonvirus scans. This could also happen in case there is a
+problem in with the storage engine when moving the file to the local filesystem.
+
+## Testing without installing ClamAV
+
+If you want to test that the scanner is working correctly without installing
+ClamAV, you can create a dummy ClamAV executable in your app's `bin` path as
+follows:
+
+```bash
+$ cd /path/to/your/app
+$ wget -O bin/clamdscan https://git.io/fpKZr && chmod 755 bin/clamdscan
+```
+
+This downloads a bash script created to test the ClamAV executables without
+installing ClamAV. You can inspect the script from
+[here](https://gist.github.com/ahukkanen/ad28be993333b751013ddbc4cde2acef) prior
+to downloading and running it.
+
+The executable is being executed by Clamby to check for the viruses.
+
+After creating these files, you should be able to test the Clamby scanner from
+your Rails application by adding the folder where this executable resides to the
+PATH environment variable for your Rails application. You can do this when you
+start your Rails development server as follows.
+
+```
+$ PATH=./bin:$PATH bundle exec rails s
+```
+
+You should now be able to upload the
+[EICAR test file](https://en.wikipedia.org/wiki/EICAR_test_file) to the proposal
+form and see a `contains a virus` error when submitting the form. When
+submitting any other file, the scanning should pass and you should not see any
+errors produced by Ratonvirus.
+
+Feel free to try the scanner with different exit codes as well, they are
+described below:
+
+- 0: No virus found.
+- 1: Virus(es) found.
+- 2: An error occured.
+- 126: The file is not executable.
+- 127: The executable could not be found.
+
+For testing these, modify the `bin/clamdscan` executable to contain the
+following lines:
+
+```bash
+#!/bin/bash
+exit 1
+```
+
+Modify the exit code to the one you want to test.

data/Rakefile

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'rspec/core/rake_task'
+
+# Run all tests, with coverage report
+RSpec::Core::RakeTask.new(:coverage) do |t, task_args|
+  ENV['CODECOV'] = '1'
+  t.verbose = false
+end
+
+# Run all tests, include all
+RSpec::Core::RakeTask.new(:spec) do |t, task_args|
+  t.verbose = false
+end
+
+# Run both by default
+task default: [:spec, :coverage]

data/lib/ratonvirus/clamby.rb

@@ -0,0 +1,9 @@
+require 'clamby'
+
+require_relative 'clamby/version'
+require_relative 'scanner/clamby'
+
+module Ratonvirus
+  module Clamby
+  end
+end

data/lib/ratonvirus/clamby/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Ratonvirus
+  module Clamby
+    VERSION = "0.1.0"
+  end
+end

data/lib/ratonvirus/scanner/clamby.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Ratonvirus
+  module Scanner
+    class Clamby < Base
+      CLAMBY_DEFAULT_CONFIG = ::Clamby::DEFAULT_CONFIG.merge(
+        # We want to handle checking locally on initialization, not on every
+        # scan.
+        check: false,
+        # Should be encouraged as it is much faster.
+        daemonize: true,
+        # We are checking already executable? and therefore not needed.
+        error_clamscan_missing: false,
+        # We want Ratonvirus to report issues errors on client errors.
+        error_clamscan_client_error: true,
+        # We want Ratonvirus to report issues on file missing errors.
+        error_file_missing: true,
+        # No output is required not to fill the logs. The scanning errors
+        output_level: 'off',
+      ).freeze
+
+      class << self
+        def configure(config={})
+          ::Clamby.configure(config)
+        end
+
+        def reset
+          configure(CLAMBY_DEFAULT_CONFIG.dup)
+        end
+
+        # Avoid multiple calls to the clamscan utility to check whether the
+        # system is executable.
+        def executable?
+          # Clamby should return `nil` when clamscan is not available.
+          !!::Clamby::Command.clamscan_version
+        end
+      end
+
+      # Allow users to configure Clamby the way they want to.
+      def setup
+        self.class.configure(config[:clamby] || {})
+
+        super
+      end
+
+      protected
+        def run_scan(path)
+          # In case the file is not present at all, scanning should always pass
+          # because nil is not a virus.
+          return if path.nil?
+
+          begin
+            errors << :antivirus_virus_detected if ::Clamby.virus?(path)
+          rescue ::Clamby::ClamscanClientError
+            # This can happen e.g. if the clamdscan utility does not have access
+            # to read the file path. For debugging, try to run the clamdscan
+            # utility manually for the same file:
+            # clamdscan /path/to/file.pdf
+            #
+            # Also, make sure that the file uploads store directory is readable
+            # by the clamdscan utility. E.g. /path/to/app/public/uploads/tmp.
+            #
+            # Another possible reason is that in case there are too many
+            # concurrent virus checks ongoing, it may also trigger this error.
+            errors << :antivirus_client_error
+          rescue ::Clamby::FileNotFound
+            # This should be pretty rare since the scanner should not be even
+            # called when the file is not available. As the storage backend may
+            # be configured, this may still happen with some storage backends.
+            errors << :antivirus_file_not_found
+          end
+        end
+
+      # Make sure we are starting up with the default configuration.
+      reset
+    end
+  end
+end

metadata

@@ -0,0 +1,120 @@
+--- !ruby/object:Gem::Specification
+name: ratonvirus-clamby
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Antti Hukkanen
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2018-12-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ratonvirus
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+- !ruby/object:Gem::Dependency
+  name: clamby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '12.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '12.3'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.16.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.16.0
+description: Provides ClamAV scanner backed by Clamby for the Ratonvirus gem.
+email:
+- antti.hukkanen@mainiotech.fi
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- Rakefile
+- lib/ratonvirus/clamby.rb
+- lib/ratonvirus/clamby/version.rb
+- lib/ratonvirus/scanner/clamby.rb
+homepage: https://github.com/mainio/ratonvirus-clamby
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.7.7
+signing_key: 
+specification_version: 4
+summary: Clamby scanner for Ratonvirus.
+test_files: []