op-clamav-client 3.4.2

data/README.md

@@ -0,0 +1,209 @@
+# ClamAV::Client
+
+ClamAV::Client is a client library that can talk to the clam daemon.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'op-clamav-client', require: 'clamav/client'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install op-client-client
+
+Alternatively, you can spawn a `pry` console right away by just running:
+
+    $ rake console
+
+### Installing ClamAV's daemon
+
+#### On OSX
+
+If you are using brew, just run
+
+```shell
+brew install clamav
+```
+#### On Linux (Ubuntu)
+```shell
+sudo apt-get install clamav-daemon clamav-freshclam clamav-unofficial-sigs
+sudo freshclam
+sudo service clamav-daemon start
+```
+#### On Linux (RedHat, CentOS)
+```shell
+sudo yum install clamd clamav clamav-db
+sudo freshclam
+sudo service clamd start
+```
+Under RedHat/CentOS the UNIX Socket, located at `/var/run/clamav/clamd.sock`
+
+## Requirements
+
+* Ruby >= 2.4
+* clamd
+
+## Usage
+
+The `ClamAV::Client` class is responsible for opening a connection to a remote
+ClamAV clam daemon.
+
+See the implemented commands below.
+
+### PING => Boolean
+
+Pings the daemon to check whether it is alive.
+
+```ruby
+client = ClamAV::Client.new
+client.execute(ClamAV::Commands::PingCommand.new)
+# => true
+```
+
+### SCAN <file_or_directory> => Array[Response]
+
+Scans a file or a directory for the existence of a virus.
+
+The absolute path must be given to that command.
+
+```ruby
+client = ClamAV::Client.new
+
+client.execute(ClamAV::Commands::ScanCommand.new('/tmp/path/foo.c'))
+# => [#<ClamAV::SuccessResponse:0x007fbf314b9478 @file="/tmp/foo.c">]
+
+client.execute(ClamAV::Commands::ScanCommand.new('/tmp/path'))
+# => [#<ClamAV::SuccessResponse:0x007fc30c273298 @file="/tmp/path/foo.c">,
+#     #<ClamAV::SuccessResponse:0x007fc30c272910 @file="/tmp/path/foo.cpp">]
+```
+
+### INSTREAM => Response
+
+Scans an IO-like object for the existence of a virus.
+
+```ruby
+client = ClamAV::Client.new
+
+io = StringIO.new('some data')
+client.execute(ClamAV::Commands::InstreamCommand.new(io))
+# => [#<ClamAV::SuccessResponse:0x007fe471cabe50 @file="stream">]
+```
+
+### Custom commands
+
+Custom commands can be given to the client. The contract between the client
+and the command is through the `Command#call` method. The `call` method will
+receive a `Connection` object.
+
+Here's a simple example implementing the `VERSION` command:
+
+```ruby
+# Build the client
+client = ClamAV::Client.new
+
+# Create the command lambda
+version_command = lambda { |conn| conn.send_request("VERSION") }
+# => #<Proc:0x007fc0d0c14b28>
+
+# Execute the command
+client.execute(version_command)
+# => "1: ClamAV 0.98.1/18489/Tue Feb 18 16:00:05 2014"
+```
+
+## Defaults
+
+The default values in use are:
+
+  * clamd socket: UNIX Socket, located at `/var/run/clamav/clamd.ctl`;
+  * New-line terminated commands.
+
+These defaults can be changed:
+
+  * by creating the object graph manually;
+  * by setting environment variables.
+
+### The object graph
+
+#### Client
+
+The main object is the `Client` object. It is responsible for executing the commands.
+It can receive a custom connection object.
+
+#### Connection
+
+The `Connection` object is the bridge between the raw socket object and the
+protocol used between the client and the daemon.
+
+`clamd` supports two kinds of delimiters:
+
+  * NULL terminated commands
+  * New-line terminated commands
+
+The management of those delimiters is done with the wrapper argument.
+
+#### Wrapper
+
+The wrapper is responsible for taking the incoming request with the
+`wrap_request` method, and parsing the response with the `read_response`
+method.
+
+### Environment variables
+
+The variables can be set programmatically in your Ruby programs like
+
+```ruby
+# from a ruby script
+ENV['CLAMD_UNIX_SOCKET'] = '/some/path'
+
+# Now the defaults are changed for any new ClamAV::Client instantiation
+```
+
+or by setting the variables before starting the Ruby process:
+
+```
+# from the command-line
+export CLAMD_UNIX_SOCKET = '/some/path'
+ruby my_program.rb
+# or
+CLAMD_UNIX_SOCKET = '/some/path' ruby my_program.rb
+```
+
+Please note that setting the `CLAMD_TCP_*` variables will have the precedence
+over the `CLAMD_UNIX_SOCKET`.
+
+#### CLAMD_UNIX_SOCKET
+
+Sets the socket path of the ClamAV daemon.
+
+Under RedHat/CentOS this can either be set via an environment variable (above) or in the ClamAV::Connection call
+```
+connection = ClamAV::Connection.new(socket: ::UNIXSocket.new('/var/run/clamav/clamd.sock'), wrapper: ::ClamAV::Wrappers::NewLineWrapper.new)
+client = ClamAV::Client.new(connection)
+```
+
+#### CLAMD_TCP_HOST and CLAMD_TCP_PORT
+
+Sets the host and port of the ClamAV daemon.
+
+## Licensing
+
+GPLv3. COMMERCIAL license available upon request.
+
+## Contributing
+
+1. Fork it ( https://github.com/opf/clamav-client/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 new Pull Request
+
+### Testing
+
+The test suite can be run locally before pushing changes :
+
+    $ docker run --rm -it $(docker build -f test/Dockerfile --build-arg RUBY_VERSION=3.2-slim -q .) rake

data/Rakefile

@@ -0,0 +1,104 @@
+# clamav-client - ClamAV client
+# Copyright (C) 2014 Franck Verrot <franck@verrot.fr>
+
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+require 'rubygems'
+require 'rubygems/specification'
+
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+$:<< 'lib'
+require 'clamav/client'
+
+$stdout.puts """
+ClamAV::Client Copyright (C) 2014 Franck Verrot <franck@verrot.fr>
+This program comes with ABSOLUTELY NO WARRANTY; for details type `rake license'.
+This is free software, and you are welcome to redistribute it
+under certain conditions; type `rake license' for details.
+
+"""
+
+require 'rake/testtask'
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.pattern = "test/**/*_test.rb"
+  #t.verbose = true
+  #t.warning = true
+end
+
+Rake::TestTask.new(:unit_tests) do |t|
+  t.libs << "test"
+  t.pattern = "test/unit/**/*_test.rb"
+  #t.verbose = true
+  #t.warning = true
+end
+
+Rake::TestTask.new(:integration_tests) do |t|
+  t.libs << "test"
+  t.pattern = "test/integration/**/*_test.rb"
+  #t.verbose = true
+  #t.warning = true
+end
+
+
+def gemspec
+  @gemspec ||= begin
+                 file = File.expand_path('../clamav-client.gemspec', __FILE__)
+                 eval(File.read(file), binding, file)
+               end
+end
+
+desc "Clean the current directory"
+task :clean do
+  rm_rf 'tmp'
+  rm_rf 'pkg'
+end
+
+desc "Run the full spec suite"
+task :full => ["clean", "test"]
+
+desc "install the gem locally"
+task :install => :package do
+  sh %{gem install pkg/#{gemspec.name}-#{gemspec.version}}
+end
+
+desc "validate the gemspec"
+task :gemspec do
+  gemspec.validate
+end
+
+desc "Build the gem"
+task :gem => [:gemspec, :build] do
+  mkdir_p "pkg"
+  sh "gem build clamav-client.gemspec"
+  mv "#{gemspec.full_name}.gem", "pkg"
+end
+
+desc "Install ClamAV::Client"
+task :install => :gem do
+  sh "gem install pkg/#{gemspec.full_name}.gem"
+end
+
+task :default => :full
+
+task :license do
+  `open http://www.gnu.org/licenses/gpl.txt`
+end
+
+task :console do
+  require 'pry'
+  Pry.start
+end

data/clamav-client.gemspec

@@ -0,0 +1,25 @@
+# coding: utf-8
+$:<< 'lib'
+
+Gem::Specification.new do |spec|
+  spec.name          = "op-clamav-client"
+  spec.version       = "3.4.2"
+  spec.authors       = ["Franck Verrot"]
+  spec.email         = ["franck@verrot.fr"]
+  spec.summary       = %q{ClamAV::Client connects to a Clam Anti-Virus clam daemon and send commands.}
+  spec.description   = spec.summary
+  spec.homepage      = "https://github.com/franckverrot/clamav-client"
+  spec.license       = "GPL-v3"
+  spec.required_ruby_version = '>= 2.5'
+
+  spec.files = Dir['{lib,test}/**/*', 'LICENSE.txt', 'ChangeLog.md', 'Rakefile', 'README.md', 'Gemfile', 'clamav-client.gemspec'].reject { |f| f['test/fixtures'] }
+
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "pry"
+  spec.add_development_dependency "minitest"
+end

data/lib/clamav/client.rb

@@ -0,0 +1,182 @@
+# clamav-client - ClamAV client
+# Copyright (C) 2014 Franck Verrot <franck@verrot.fr>
+
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+require 'socket'
+require 'timeout'
+
+module ClamAV
+  class Client
+    class Error < StandardError; end
+    class ConnectionError < Error; end
+    class ConnectTimeoutError < ConnectionError; end
+    class ReadTimeoutError < ConnectionError; end
+    class WriteTimeoutError < ConnectionError; end
+
+    attr_accessor :options
+
+    def initialize(*args)
+      @options = env_options
+
+      args.each do |arg|
+        case arg
+        when Connection
+          @connection = arg
+        when Hash
+          @options = env_options.inject({}) do |acc, (option, default)|
+            acc[option] = arg[option] || default
+            acc
+          end
+        end
+      end
+    end
+
+    [
+      :unix_socket,
+      :tcp_host,
+      :tcp_port,
+      :connect_timeout,
+      :write_timeout,
+      :read_timeout,
+    ].each do |m|
+      define_method(m) do
+        options[m]
+      end
+
+      define_method("#{m}=") do |value|
+        options[m] = value
+      end
+    end
+
+    def env_options
+      @env_options ||= {
+        unix_socket: ENV.fetch('CLAMD_UNIX_SOCKET', '/var/run/clamav/clamd.ctl'),
+        tcp_host: ENV.fetch('CLAMD_TCP_HOST', nil),
+        tcp_port: ENV.fetch('CLAMD_TCP_PORT', nil),
+        connect_timeout: ENV.fetch("CLAMD_TCP_CONNECT_TIMEOUT", nil),
+        write_timeout: ENV.fetch("CLAMD_TCP_WRITE_TIMEOUT", nil),
+        read_timeout: ENV.fetch("CLAMD_TCP_READ_TIMEOUT", nil),
+      }
+    end
+
+    def execute(command)
+      begin
+        command.call(connection)
+      rescue Errno::ETIMEDOUT => e
+        disconnect!
+
+        raise ConnectTimeoutError.new(e.to_s)
+      rescue SocketError, Errno::ECONNRESET, Errno::ECONNREFUSED, Errno::ENETDOWN  => e
+        disconnect!
+
+        raise ConnectionError.new(e.to_s)
+      rescue => e
+        disconnect!
+
+        raise e
+      end
+    end
+
+    def connection
+      @connection ||= default_connection.tap do |conn|
+        connect!(conn)
+      end
+    end
+
+    def default_connection
+      ClamAV::Connection.new(
+        client: self,
+        socket: build_socket,
+        wrapper: ::ClamAV::Wrappers::NewLineWrapper.new
+      )
+    end
+
+    def connect!(conn=nil)
+      (conn || @connection).establish_connection
+    rescue Errno::ETIMEDOUT => e
+      @connection = nil
+
+      raise ConnectTimeoutError.new(e.to_s)
+    rescue SocketError, Errno::ECONNRESET, Errno::ECONNREFUSED => e
+      @connection = nil
+
+      raise ConnectionError.new(e.to_s)
+    end
+
+    def disconnect!
+      return true if @connection.nil?
+
+      @connection.disconnect!.tap do
+        @connection = nil
+      end
+    end
+
+    def tcp?
+      !!tcp_host && !!tcp_port
+    end
+
+    def file?
+      !tcp
+    end
+
+    def build_socket
+      return Socket.tcp(tcp_host, tcp_port, connect_timeout: connect_timeout) if tcp?
+
+      ::UNIXSocket.new(unix_socket)
+    rescue Errno::ETIMEDOUT => e
+      raise ConnectTimeoutError.new(e.to_s)
+    rescue SocketError, Errno::ECONNRESET, Errno::ECONNREFUSED => e
+      raise ConnectionError.new(e.to_s)
+    end
+
+    def ping
+      execute Commands::PingCommand.new
+    end
+
+    def safe?(target)
+      return instream(target).virus_name.nil? if target.is_a?(StringIO)
+      scan(target).all? { |file| file.virus_name.nil? }
+    end
+
+    private
+
+    def instream(io)
+      execute Commands::InstreamCommand.new(io)
+    end
+
+    def scan(file_path)
+      execute Commands::ScanCommand.new(file_path)
+    end
+
+    def quit
+      execute Commands::QuitCommand.new
+    end
+  end
+end
+
+require_relative "connection"
+require_relative "commands/command"
+require_relative "commands/ping_command"
+require_relative "commands/quit_command"
+require_relative "commands/scan_command"
+require_relative "commands/instream_command"
+require_relative "response"
+require_relative "responses/error_response"
+require_relative "responses/success_response"
+require_relative "responses/virus_response"
+require_relative "util"
+require_relative "wrapper"
+require_relative "wrappers/new_line_wrapper"
+require_relative "wrappers/null_termination_wrapper"

data/lib/clamav/commands/command.rb

@@ -0,0 +1,38 @@
+# clamav-client - ClamAV client
+# Copyright (C) 2014 Franck Verrot <franck@verrot.fr>
+
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+module ClamAV
+  module Commands
+    class Command
+
+      def call; raise NotImplementedError.new; end
+
+      protected
+
+        # OK response looks like "1: stream: OK" or "1: /tmp/NOT_A_VIRUS.TXT: OK"
+        # FOUND response looks like "1: stream: Eicar-Test-Signature FOUND" or "1: /tmp/EICAR.COM: Eicar-Test-Signature FOUND"
+        def get_status_from_response(str)
+          /^(?<id>\d+): (?<filepath>.*): (?<virus_name>.*)\s?(?<status>(OK|FOUND))$/ =~ str
+          case status
+          when 'OK' then ClamAV::SuccessResponse.new(filepath)
+          when 'FOUND' then ClamAV::VirusResponse.new(filepath, virus_name.strip)
+          else ClamAV::ErrorResponse.new(str)
+          end
+        end
+
+    end
+  end
+end

data/lib/clamav/commands/instream_command.rb

@@ -0,0 +1,39 @@
+# clamav-client - ClamAV client
+# Copyright (C) 2014 Franck Verrot <franck@verrot.fr>
+
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+module ClamAV
+  module Commands
+    class InstreamCommand < Command
+
+      def initialize(io, max_chunk_size = 1024)
+        @io = begin io rescue raise ArgumentError, 'io is required', caller; end
+        @max_chunk_size = max_chunk_size
+      end
+
+      def call(conn)
+        conn.write_request("INSTREAM")
+
+        while(packet = @io.read(@max_chunk_size))
+          packet_size = [packet.size].pack("N")
+          conn.raw_write("#{packet_size}#{packet}")
+        end
+        conn.raw_write("\x00\x00\x00\x00")
+        get_status_from_response(conn.read_response)
+      end
+
+    end
+  end
+end

data/lib/clamav/commands/ping_command.rb

@@ -0,0 +1,25 @@
+# clamav-client - ClamAV client
+# Copyright (C) 2014 Franck Verrot <franck@verrot.fr>
+
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+module ClamAV
+  module Commands
+    class PingCommand < Command
+      def call(conn)
+        !!(/\d+: PONG/.match(conn.send_request("PING")))
+      end
+    end
+  end
+end

data/lib/clamav/commands/quit_command.rb

@@ -0,0 +1,25 @@
+# clamav-client - ClamAV client
+# Copyright (C) 2014 Franck Verrot <franck@verrot.fr>
+
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+module ClamAV
+  module Commands
+    class QuitCommand < Command
+      def call(conn)
+        conn.send_request("QUIT").nil?
+      end
+    end
+  end
+end

data/lib/clamav/commands/scan_command.rb

@@ -0,0 +1,35 @@
+# clamav-client - ClamAV client
+# Copyright (C) 2014 Franck Verrot <franck@verrot.fr>
+
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+module ClamAV
+  module Commands
+    class ScanCommand < Command
+
+      def initialize(path, path_finder = Util)
+        @path, @path_finder = path, path_finder
+      end
+
+      def call(conn)
+        @path_finder.path_to_files(@path).map { |file| scan_file(conn, file) }
+      end
+
+      def scan_file(conn, file)
+        get_status_from_response(conn.send_request("SCAN #{file}"))
+      end
+
+    end
+  end
+end