ruby_clamdscan 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 761b30b0097a5134e14f00417a2c2684762dd45caaaab0308a84e35002125647
-  data.tar.gz: 06435db3a0774fbd6810a80f28f39624ee2f592407e91fd3a57723292314dd87
+  metadata.gz: df6892cd797e6ec9172e3737d789ed283034b95e86ed65f5fb08651ae05c055b
+  data.tar.gz: 425ca033634e107fec64f0441d54c36fbbcefa56e339e698980ecff87ecbedfe
 SHA512:
-  metadata.gz: 7854440fdeea3c7b9a979141a0fad877480d38daa6a720b282ee67e80d8437b7df4155a908e72b6492d3525dfe84262ed426a446d886b6e171af34a07a274ac3
-  data.tar.gz: 79d47810175c6642a12a9af984bec3a7d67573bfdcf6bbacde02ffe62805ae98e4fec952207cefc4c4e872081e4c502b9b1b3ea9dd09724f5f6e7b44552385d9
+  metadata.gz: a20206c40cb86ceb2fbedddd57f6f5a1f4d1b434b1f455d47c8691e1805e2c7231c0e02d7b365110c8bdc369ae84794a86d84cd700af09800bca7765efb5aa87
+  data.tar.gz: ae755aa70063996f21e28e19bc55fdc9d741a497069712610eb265e0a7c269052cef4f05a2e8043f4b44365bd38e84b41a0dc1f76c97a571968c35006b9fb33b

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 ## [Released]
 
+## [0.1.3] - 2023-03-08
+
+- More doc fixes, also fix configuration defaulting
+
 ## [0.1.2] - 2023-03-08
 
 - Fix docs a bit, increase version

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    ruby_clamdscan (0.1.2)
+    ruby_clamdscan (0.1.3)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -1,8 +1,8 @@
 # RubyClamdscan
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/ruby_clamdscan`. To experiment with that code, run `bin/console` for an interactive prompt.
+Implementing most `clamdscan` commands as a Ruby Gem using socket communication. 
 
-TODO: Delete this and the text above, and describe your gem
+This is a personal project to learn more about how Ruby gem development works and may not be actively developed.
 
 ## Installation
 
@@ -16,7 +16,46 @@ If bundler is not being used to manage dependencies, install the gem by executin
 
 ## Usage
 
-TODO: Write usage instructions here
+Set the configuration for this gem by using:
+
+```ruby
+RubyClamdscan.configure do |conf|
+  conf.use_tcp_socket = true
+end
+```
+
+Scan files by using:
+```ruby
+RubyClamdscan.scan_file_from_path("/path/to/local/file")
+```
+
+or
+
+```ruby
+RubyClamdscan.scan_contents(IO)
+```
+
+Both return instances of `RubyClamdscan::Models::ScanResults` with information about the scan
+
+### Configuration options
+```ruby
+RubyClamdscan.configure do |conf|
+  conf.use_tcp_socket = true # If using TCP socket, defaults to false to use local unix socket
+  conf.tcp_port = 3310 # TCP Port where ClamAV is listening
+  conf.tcp_host = "localhost" # Host where ClamAV is listening
+  conf.unix_socket = "/tmp/clamd.socket" # If using UNIX socket, what file represents the socket
+  conf.chunk_size = 1024 # Size of chunk in bytes to send to ClamAV for scanning
+  conf.raise_error_on_empty_response = true # If the socket responds empty, raise `RubyClamdscan::Errors::EmptyResponseError` instead of returning an empty string
+  conf.raise_error_on_virus_detected = true # If a virus is detected, raise `RubyClamdscan::Errors::VirusDetectedError` instead of just returning the result
+end
+```
+
+### Commands
+* `RubyClamdscan.ping_server` - Ping server, should respond with "PONG"
+* `RubyClamdscan.server_version` - Query ClamAV for server version info - response format may change
+* `RubyClamdscan.server_stats` - Query ClamAV for server stats, resources, etc - response format may change
+* `RubyClamdscan.reload_server_database` - Tell ClamAV server to reload virus db
+* `RubyClamdscan.shutdown_server` - Tell ClamAV server shutdown and stop listening to requests
 
 ## Development
 
@@ -26,8 +65,8 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/ruby_clamdscan. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/ruby_clamdscan/blob/main/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at https://github.com/jacobrayschwartz/ruby_clamdscan. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/jacobrayschwartz/ruby_clamdscan/blob/main/CODE_OF_CONDUCT.md).
 
 ## Code of Conduct
 
-Everyone interacting in the RubyClamdscan project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/ruby_clamdscan/blob/main/CODE_OF_CONDUCT.md).
+Everyone interacting in the RubyClamdscan project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/jacobrayschwartz/ruby_clamdscan/blob/main/CODE_OF_CONDUCT.md).

data/lib/ruby_clamdscan/commands/manage.rb

@@ -4,10 +4,13 @@ require "ruby_clamdscan/commands/utils"
 
 module RubyClamdscan
   module Commands
-    # Management commands for
+    # Management commands for ClamAV server
     module Manage
       # Force ClamAV to reload the virus databases
       # @param configuration [RubyClamdscan::Configuration] configuration for building the ClamAV connection
+      # @return [String] "RELOADING"
+      # @raise [RubyClamdscan::Errors::ClamAVCommunicationError] if communication with ClamAV server fails
+      # @raise [RubyClamdscan::Errors::EmptyResponseError] If server response is empty
       def self.reload_server_database(configuration)
         RubyClamdscan::Commands::Utils.send_single_command("RELOAD", configuration)
       end
@@ -15,8 +18,11 @@ module RubyClamdscan
       # Shutdown ClamAV server
       # Note: this will completely close socket communication. Server cannot be restarted through this library
       # @param configuration [RubyClamdscan::Configuration] configuration for building the ClamAV connection
+      # @raise [RubyClamdscan::Errors::ClamAVCommunicationError] if communication with ClamAV server fails
+      # @return [Boolean] true if shutdown command was sent
       def self.shutdown_server(configuration)
-        RubyClamdscan::Commands::Utils.send_single_command("SHUTDOWN", configuration)
+        true if RubyClamdscan::Commands::Utils.send_single_command("SHUTDOWN", configuration, ignore_empty_response: true)
+        false
       end
     end
   end

data/lib/ruby_clamdscan/commands/status.rb

@@ -8,6 +8,8 @@ module RubyClamdscan
     module Status
       # Attempts to ping the ClamAV server
       # @param configuration [RubyClamdscan::Configuration] configuration for building the ClamAV connection
+      # @return [String] "PONG"
+      # @raise [RubyClamdscan::Errors::ClamAVCommunicationError] if communication with ClamAV server fails
       # @raise [RubyClamdscan::Exceptions::EmptyResponseError] If server response is empty
       def self.ping_server(configuration)
         RubyClamdscan::Commands::Utils.send_single_command("PING", configuration)
@@ -15,6 +17,8 @@ module RubyClamdscan
 
       # Attempts to retrieve the ClamAV server's version information
       # @param configuration [RubyClamdscan::Configuration] configuration for building the ClamAV connection
+      # @return [String] Server information
+      # @raise [RubyClamdscan::Errors::ClamAVCommunicationError] if communication with ClamAV server fails
       # @raise [RubyClamdscan::Exceptions::EmptyResponseError] If server response is empty
       def self.server_version(configuration)
         RubyClamdscan::Commands::Utils.send_single_command("VERSION", configuration)
@@ -27,6 +31,7 @@ module RubyClamdscan
       # @return [String] Format (currently):
       # "POOLS: 1\n\nSTATE: VALID PRIMARY\nTHREADS: live 1  idle 0 max 10 idle-timeout 30\nQUEUE: 0 items\n\tSTATS 0.000375 \n\n
       # MEMSTATS: heap N/A mmap N/A used N/A free N/A releasable N/A pools 1 pools_used 1281.773M pools_total 1281.827M\nEND"
+      # @raise [RubyClamdscan::Errors::ClamAVCommunicationError] if communication with ClamAV server fails
       # @raise [RubyClamdscan::Errors::EmptyResponseError] If server response is empty
       def self.server_stats(configuration)
         RubyClamdscan::Commands::Utils.send_single_command("nSTATS\n", configuration)

data/lib/ruby_clamdscan/commands/utils.rb

@@ -12,7 +12,7 @@ module RubyClamdscan
       # @return [String] Response from ClamAV server
       # @raise [RubyClamdscan::Errors::EmptyResponseError] if configuration.raise_error_on_empty_response is true and server doesn't send response
       # @raise
-      def self.send_single_command(command, configuration)
+      def self.send_single_command(command, configuration, ignore_empty_response: false)
         response = ""
         begin
           clam_av_stream = RubyClamdscan::Socket.open_clamav_socket(configuration)
@@ -30,7 +30,10 @@ module RubyClamdscan
           clam_av_stream&.close
         end
 
-        raise RubyClamdscan::Errors::EmptyResponseError, command if configuration.raise_error_on_empty_response && response.empty?
+        if !ignore_empty_response && configuration.raise_error_on_empty_response && response.empty?
+          raise RubyClamdscan::Errors::EmptyResponseError,
+                command
+        end
 
         response
       end

data/lib/ruby_clamdscan/configuration.rb

@@ -41,6 +41,7 @@ module RubyClamdscan
     attr_accessor :raise_error_on_virus_detected
 
     def initialize
+      @use_tcp_socket = false
       @tcp_host = "localhost"
       @tcp_port = 3310
       @chunk_size = 1024

data/lib/ruby_clamdscan/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RubyClamdscan
-  VERSION = "0.1.2"
+  VERSION = "0.1.3"
 end

data/lib/ruby_clamdscan.rb

@@ -13,9 +13,6 @@ module RubyClamdscan
     # Configuration to use interacting with the ClamAV server
     def configuration
       @configuration ||= Configuration.new
-      @configuration.use_tcp_socket = true
-      @configuration.tcp_host = "localhost"
-      @configuration.tcp_port = 3310
 
       @configuration
     end
@@ -28,6 +25,9 @@ module RubyClamdscan
     # Scans a file
     # @param filepath [String] Path to file in local storage
     # @return [RubyClamdscan::Models::ScanResult] Result from the scan attempt
+    # @return [RubyClamdscan::Models::ScanResult]
+    # @raise [RubyClamdscan::Errors::VirusDetectedError] if Configuration is set to raise exception and malware is detected
+    # @raise [RubyClamdscan::Errors::ClamAVCommunicationError] if communication with ClamAV server fails
     def scan_file_from_path(filepath)
       RubyClamdscan::Commands::Scan.scan_file(filepath, @configuration)
     end
@@ -35,26 +35,53 @@ module RubyClamdscan
     # Scans the contents of the stream passed in
     # @param stream [IO] stream of file contents
     # @return [RubyClamdscan::Models::ScanResult] Result from the scan attempt
+    # @return [RubyClamdscan::Models::ScanResult]
+    # @raise [RubyClamdscan::Errors::VirusDetectedError] if Configuration is set to raise exception and malware is detected
+    # @raise [RubyClamdscan::Errors::ClamAVCommunicationError] if communication with ClamAV server fails
     def scan_contents(stream)
       RubyClamdscan::Commands::Scan.scan(stream, @configuration)
     end
 
+    # Attempts to ping the ClamAV server
+    # @return [String] "PONG"
+    # @raise [RubyClamdscan::Errors::ClamAVCommunicationError] if communication with ClamAV server fails
+    # @raise [RubyClamdscan::Exceptions::EmptyResponseError] If server response is empty
     def ping_server
       RubyClamdscan::Commands::Status.ping_server(@configuration)
     end
 
+    # Attempts to retrieve the ClamAV server's version information
+    # @return [String] Server information
+    # @raise [RubyClamdscan::Errors::ClamAVCommunicationError] if communication with ClamAV server fails
+    # @raise [RubyClamdscan::Exceptions::EmptyResponseError] If server response is empty
     def server_version
       RubyClamdscan::Commands::Status.server_version(@configuration)
     end
 
+    # Replies with statistics about the scan queue, contents of scan queue, and memory usage
+    # Because the format of this response is subject to change, this method will only return the string
+    # Uses "nSTATS\n", blocks in the returned response will be separated by the \n character
+    # @return [String] Format (currently):
+    # "POOLS: 1\n\nSTATE: VALID PRIMARY\nTHREADS: live 1  idle 0 max 10 idle-timeout 30\nQUEUE: 0 items\n\tSTATS 0.000375 \n\n
+    # MEMSTATS: heap N/A mmap N/A used N/A free N/A releasable N/A pools 1 pools_used 1281.773M pools_total 1281.827M\nEND"
+    # @raise [RubyClamdscan::Errors::ClamAVCommunicationError] if communication with ClamAV server fails
+    # @raise [RubyClamdscan::Errors::EmptyResponseError] If server response is empty
     def server_stats
       RubyClamdscan::Commands::Status.server_stats(@configuration)
     end
 
+    # Force ClamAV to reload the virus databases
+    # @return [String] "RELOADING"
+    # @raise [RubyClamdscan::Errors::ClamAVCommunicationError] if communication with ClamAV server fails
+    # @raise [RubyClamdscan::Errors::EmptyResponseError] If server response is empty
     def reload_server_database
       RubyClamdscan::Commands::Manage.reload_server_database(@configuration)
     end
 
+    # Shutdown ClamAV server
+    # Note: this will completely close socket communication. Server cannot be restarted through this library
+    # @raise [RubyClamdscan::Errors::ClamAVCommunicationError] if communication with ClamAV server fails
+    # @return [Boolean] true if shutdown command was sent
     def shutdown_server
       RubyClamdscan::Commands::Manage.shutdown_server(@configuration)
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_clamdscan
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Jacob Schwartz