ruby_clamdscan 0.1.1 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b7a8da5150aeff1cdcb9fcda9e6d898e5c58847e6a73d9d4c62291cf8ec01f28
-  data.tar.gz: a530c4ec6b0b937d506682c1eca2ce0ec2e938a0173bf1f5aa41600ad8194ceb
+  metadata.gz: df6892cd797e6ec9172e3737d789ed283034b95e86ed65f5fb08651ae05c055b
+  data.tar.gz: 425ca033634e107fec64f0441d54c36fbbcefa56e339e698980ecff87ecbedfe
 SHA512:
-  metadata.gz: 0a2505078b6335e3b9ad0e4df85be094e3fa18291659a348c8eb26a538e1e059512504e2749b6c61c15050221fafbd8d511b3cc42acfa0ce83f585cd54c02a2d
-  data.tar.gz: 394fc501e68f4896bd2be28c9ec9963333e35073b39956783af1265d2d7e84fc2c999d3ce7f5fcc5f35a1c61db646107a745a29b6b4f00f149b7af1c505f322a
+  metadata.gz: a20206c40cb86ceb2fbedddd57f6f5a1f4d1b434b1f455d47c8691e1805e2c7231c0e02d7b365110c8bdc369ae84794a86d84cd700af09800bca7765efb5aa87
+  data.tar.gz: ae755aa70063996f21e28e19bc55fdc9d741a497069712610eb265e0a7c269052cef4f05a2e8043f4b44365bd38e84b41a0dc1f76c97a571968c35006b9fb33b

data/CHANGELOG.md

@@ -1,5 +1,13 @@
-## [Unreleased]
+## [Released]
 
-## [0.1.0] - 2022-09-07
+## [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
+
+## [0.1.0] - 2023-03-08
 
 - Initial release

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    ruby_clamdscan (0.1.0)
+    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.1"
+  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,11 +1,11 @@
 --- !ruby/object:Gem::Specification
 name: ruby_clamdscan
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.3
 platform: ruby
 authors:
 - Jacob Schwartz
-autorequire:
+autorequire: 
 bindir: exe
 cert_chain: []
 date: 2023-05-08 00:00:00.000000000 Z
@@ -55,7 +55,7 @@ metadata:
   homepage_uri: https://jacobrayschwartz.com
   source_code_uri: https://github.com/jacobrayschwartz/ruby_clamdscan
   changelog_uri: https://github.com/jacobrayschwartz/ruby_clamdscan/blob/main/CHANGELOG.md
-post_install_message:
+post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -71,7 +71,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubygems_version: 3.3.26
-signing_key:
+signing_key: 
 specification_version: 4
 summary: Wrapper around TCP socket communication with a clamd instance
 test_files: []