ruby_clamdscan 0.1.2 → 0.1.3
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/CHANGELOG.md +4 -0
- data/Gemfile.lock +1 -1
- data/README.md +44 -5
- data/lib/ruby_clamdscan/commands/manage.rb +8 -2
- data/lib/ruby_clamdscan/commands/status.rb +5 -0
- data/lib/ruby_clamdscan/commands/utils.rb +5 -2
- data/lib/ruby_clamdscan/configuration.rb +1 -0
- data/lib/ruby_clamdscan/version.rb +1 -1
- data/lib/ruby_clamdscan.rb +30 -3
- metadata +1 -1
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: df6892cd797e6ec9172e3737d789ed283034b95e86ed65f5fb08651ae05c055b
|
4
|
+
data.tar.gz: 425ca033634e107fec64f0441d54c36fbbcefa56e339e698980ecff87ecbedfe
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: a20206c40cb86ceb2fbedddd57f6f5a1f4d1b434b1f455d47c8691e1805e2c7231c0e02d7b365110c8bdc369ae84794a86d84cd700af09800bca7765efb5aa87
|
7
|
+
data.tar.gz: ae755aa70063996f21e28e19bc55fdc9d741a497069712610eb265e0a7c269052cef4f05a2e8043f4b44365bd38e84b41a0dc1f76c97a571968c35006b9fb33b
|
data/CHANGELOG.md
CHANGED
data/Gemfile.lock
CHANGED
data/README.md
CHANGED
@@ -1,8 +1,8 @@
|
|
1
1
|
# RubyClamdscan
|
2
2
|
|
3
|
-
|
3
|
+
Implementing most `clamdscan` commands as a Ruby Gem using socket communication.
|
4
4
|
|
5
|
-
|
5
|
+
This is a personal project to learn more about how Ruby gem development works and may not be actively developed.
|
6
6
|
|
7
7
|
## Installation
|
8
8
|
|
@@ -16,7 +16,46 @@ If bundler is not being used to manage dependencies, install the gem by executin
|
|
16
16
|
|
17
17
|
## Usage
|
18
18
|
|
19
|
-
|
19
|
+
Set the configuration for this gem by using:
|
20
|
+
|
21
|
+
```ruby
|
22
|
+
RubyClamdscan.configure do |conf|
|
23
|
+
conf.use_tcp_socket = true
|
24
|
+
end
|
25
|
+
```
|
26
|
+
|
27
|
+
Scan files by using:
|
28
|
+
```ruby
|
29
|
+
RubyClamdscan.scan_file_from_path("/path/to/local/file")
|
30
|
+
```
|
31
|
+
|
32
|
+
or
|
33
|
+
|
34
|
+
```ruby
|
35
|
+
RubyClamdscan.scan_contents(IO)
|
36
|
+
```
|
37
|
+
|
38
|
+
Both return instances of `RubyClamdscan::Models::ScanResults` with information about the scan
|
39
|
+
|
40
|
+
### Configuration options
|
41
|
+
```ruby
|
42
|
+
RubyClamdscan.configure do |conf|
|
43
|
+
conf.use_tcp_socket = true # If using TCP socket, defaults to false to use local unix socket
|
44
|
+
conf.tcp_port = 3310 # TCP Port where ClamAV is listening
|
45
|
+
conf.tcp_host = "localhost" # Host where ClamAV is listening
|
46
|
+
conf.unix_socket = "/tmp/clamd.socket" # If using UNIX socket, what file represents the socket
|
47
|
+
conf.chunk_size = 1024 # Size of chunk in bytes to send to ClamAV for scanning
|
48
|
+
conf.raise_error_on_empty_response = true # If the socket responds empty, raise `RubyClamdscan::Errors::EmptyResponseError` instead of returning an empty string
|
49
|
+
conf.raise_error_on_virus_detected = true # If a virus is detected, raise `RubyClamdscan::Errors::VirusDetectedError` instead of just returning the result
|
50
|
+
end
|
51
|
+
```
|
52
|
+
|
53
|
+
### Commands
|
54
|
+
* `RubyClamdscan.ping_server` - Ping server, should respond with "PONG"
|
55
|
+
* `RubyClamdscan.server_version` - Query ClamAV for server version info - response format may change
|
56
|
+
* `RubyClamdscan.server_stats` - Query ClamAV for server stats, resources, etc - response format may change
|
57
|
+
* `RubyClamdscan.reload_server_database` - Tell ClamAV server to reload virus db
|
58
|
+
* `RubyClamdscan.shutdown_server` - Tell ClamAV server shutdown and stop listening to requests
|
20
59
|
|
21
60
|
## Development
|
22
61
|
|
@@ -26,8 +65,8 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
|
|
26
65
|
|
27
66
|
## Contributing
|
28
67
|
|
29
|
-
Bug reports and pull requests are welcome on GitHub at https://github.com/
|
68
|
+
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).
|
30
69
|
|
31
70
|
## Code of Conduct
|
32
71
|
|
33
|
-
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/
|
72
|
+
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).
|
@@ -4,10 +4,13 @@ require "ruby_clamdscan/commands/utils"
|
|
4
4
|
|
5
5
|
module RubyClamdscan
|
6
6
|
module Commands
|
7
|
-
# Management commands for
|
7
|
+
# Management commands for ClamAV server
|
8
8
|
module Manage
|
9
9
|
# Force ClamAV to reload the virus databases
|
10
10
|
# @param configuration [RubyClamdscan::Configuration] configuration for building the ClamAV connection
|
11
|
+
# @return [String] "RELOADING"
|
12
|
+
# @raise [RubyClamdscan::Errors::ClamAVCommunicationError] if communication with ClamAV server fails
|
13
|
+
# @raise [RubyClamdscan::Errors::EmptyResponseError] If server response is empty
|
11
14
|
def self.reload_server_database(configuration)
|
12
15
|
RubyClamdscan::Commands::Utils.send_single_command("RELOAD", configuration)
|
13
16
|
end
|
@@ -15,8 +18,11 @@ module RubyClamdscan
|
|
15
18
|
# Shutdown ClamAV server
|
16
19
|
# Note: this will completely close socket communication. Server cannot be restarted through this library
|
17
20
|
# @param configuration [RubyClamdscan::Configuration] configuration for building the ClamAV connection
|
21
|
+
# @raise [RubyClamdscan::Errors::ClamAVCommunicationError] if communication with ClamAV server fails
|
22
|
+
# @return [Boolean] true if shutdown command was sent
|
18
23
|
def self.shutdown_server(configuration)
|
19
|
-
RubyClamdscan::Commands::Utils.send_single_command("SHUTDOWN", configuration)
|
24
|
+
true if RubyClamdscan::Commands::Utils.send_single_command("SHUTDOWN", configuration, ignore_empty_response: true)
|
25
|
+
false
|
20
26
|
end
|
21
27
|
end
|
22
28
|
end
|
@@ -8,6 +8,8 @@ module RubyClamdscan
|
|
8
8
|
module Status
|
9
9
|
# Attempts to ping the ClamAV server
|
10
10
|
# @param configuration [RubyClamdscan::Configuration] configuration for building the ClamAV connection
|
11
|
+
# @return [String] "PONG"
|
12
|
+
# @raise [RubyClamdscan::Errors::ClamAVCommunicationError] if communication with ClamAV server fails
|
11
13
|
# @raise [RubyClamdscan::Exceptions::EmptyResponseError] If server response is empty
|
12
14
|
def self.ping_server(configuration)
|
13
15
|
RubyClamdscan::Commands::Utils.send_single_command("PING", configuration)
|
@@ -15,6 +17,8 @@ module RubyClamdscan
|
|
15
17
|
|
16
18
|
# Attempts to retrieve the ClamAV server's version information
|
17
19
|
# @param configuration [RubyClamdscan::Configuration] configuration for building the ClamAV connection
|
20
|
+
# @return [String] Server information
|
21
|
+
# @raise [RubyClamdscan::Errors::ClamAVCommunicationError] if communication with ClamAV server fails
|
18
22
|
# @raise [RubyClamdscan::Exceptions::EmptyResponseError] If server response is empty
|
19
23
|
def self.server_version(configuration)
|
20
24
|
RubyClamdscan::Commands::Utils.send_single_command("VERSION", configuration)
|
@@ -27,6 +31,7 @@ module RubyClamdscan
|
|
27
31
|
# @return [String] Format (currently):
|
28
32
|
# "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
|
29
33
|
# 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"
|
34
|
+
# @raise [RubyClamdscan::Errors::ClamAVCommunicationError] if communication with ClamAV server fails
|
30
35
|
# @raise [RubyClamdscan::Errors::EmptyResponseError] If server response is empty
|
31
36
|
def self.server_stats(configuration)
|
32
37
|
RubyClamdscan::Commands::Utils.send_single_command("nSTATS\n", configuration)
|
@@ -12,7 +12,7 @@ module RubyClamdscan
|
|
12
12
|
# @return [String] Response from ClamAV server
|
13
13
|
# @raise [RubyClamdscan::Errors::EmptyResponseError] if configuration.raise_error_on_empty_response is true and server doesn't send response
|
14
14
|
# @raise
|
15
|
-
def self.send_single_command(command, configuration)
|
15
|
+
def self.send_single_command(command, configuration, ignore_empty_response: false)
|
16
16
|
response = ""
|
17
17
|
begin
|
18
18
|
clam_av_stream = RubyClamdscan::Socket.open_clamav_socket(configuration)
|
@@ -30,7 +30,10 @@ module RubyClamdscan
|
|
30
30
|
clam_av_stream&.close
|
31
31
|
end
|
32
32
|
|
33
|
-
|
33
|
+
if !ignore_empty_response && configuration.raise_error_on_empty_response && response.empty?
|
34
|
+
raise RubyClamdscan::Errors::EmptyResponseError,
|
35
|
+
command
|
36
|
+
end
|
34
37
|
|
35
38
|
response
|
36
39
|
end
|
data/lib/ruby_clamdscan.rb
CHANGED
@@ -13,9 +13,6 @@ module RubyClamdscan
|
|
13
13
|
# Configuration to use interacting with the ClamAV server
|
14
14
|
def configuration
|
15
15
|
@configuration ||= Configuration.new
|
16
|
-
@configuration.use_tcp_socket = true
|
17
|
-
@configuration.tcp_host = "localhost"
|
18
|
-
@configuration.tcp_port = 3310
|
19
16
|
|
20
17
|
@configuration
|
21
18
|
end
|
@@ -28,6 +25,9 @@ module RubyClamdscan
|
|
28
25
|
# Scans a file
|
29
26
|
# @param filepath [String] Path to file in local storage
|
30
27
|
# @return [RubyClamdscan::Models::ScanResult] Result from the scan attempt
|
28
|
+
# @return [RubyClamdscan::Models::ScanResult]
|
29
|
+
# @raise [RubyClamdscan::Errors::VirusDetectedError] if Configuration is set to raise exception and malware is detected
|
30
|
+
# @raise [RubyClamdscan::Errors::ClamAVCommunicationError] if communication with ClamAV server fails
|
31
31
|
def scan_file_from_path(filepath)
|
32
32
|
RubyClamdscan::Commands::Scan.scan_file(filepath, @configuration)
|
33
33
|
end
|
@@ -35,26 +35,53 @@ module RubyClamdscan
|
|
35
35
|
# Scans the contents of the stream passed in
|
36
36
|
# @param stream [IO] stream of file contents
|
37
37
|
# @return [RubyClamdscan::Models::ScanResult] Result from the scan attempt
|
38
|
+
# @return [RubyClamdscan::Models::ScanResult]
|
39
|
+
# @raise [RubyClamdscan::Errors::VirusDetectedError] if Configuration is set to raise exception and malware is detected
|
40
|
+
# @raise [RubyClamdscan::Errors::ClamAVCommunicationError] if communication with ClamAV server fails
|
38
41
|
def scan_contents(stream)
|
39
42
|
RubyClamdscan::Commands::Scan.scan(stream, @configuration)
|
40
43
|
end
|
41
44
|
|
45
|
+
# Attempts to ping the ClamAV server
|
46
|
+
# @return [String] "PONG"
|
47
|
+
# @raise [RubyClamdscan::Errors::ClamAVCommunicationError] if communication with ClamAV server fails
|
48
|
+
# @raise [RubyClamdscan::Exceptions::EmptyResponseError] If server response is empty
|
42
49
|
def ping_server
|
43
50
|
RubyClamdscan::Commands::Status.ping_server(@configuration)
|
44
51
|
end
|
45
52
|
|
53
|
+
# Attempts to retrieve the ClamAV server's version information
|
54
|
+
# @return [String] Server information
|
55
|
+
# @raise [RubyClamdscan::Errors::ClamAVCommunicationError] if communication with ClamAV server fails
|
56
|
+
# @raise [RubyClamdscan::Exceptions::EmptyResponseError] If server response is empty
|
46
57
|
def server_version
|
47
58
|
RubyClamdscan::Commands::Status.server_version(@configuration)
|
48
59
|
end
|
49
60
|
|
61
|
+
# Replies with statistics about the scan queue, contents of scan queue, and memory usage
|
62
|
+
# Because the format of this response is subject to change, this method will only return the string
|
63
|
+
# Uses "nSTATS\n", blocks in the returned response will be separated by the \n character
|
64
|
+
# @return [String] Format (currently):
|
65
|
+
# "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
|
66
|
+
# 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"
|
67
|
+
# @raise [RubyClamdscan::Errors::ClamAVCommunicationError] if communication with ClamAV server fails
|
68
|
+
# @raise [RubyClamdscan::Errors::EmptyResponseError] If server response is empty
|
50
69
|
def server_stats
|
51
70
|
RubyClamdscan::Commands::Status.server_stats(@configuration)
|
52
71
|
end
|
53
72
|
|
73
|
+
# Force ClamAV to reload the virus databases
|
74
|
+
# @return [String] "RELOADING"
|
75
|
+
# @raise [RubyClamdscan::Errors::ClamAVCommunicationError] if communication with ClamAV server fails
|
76
|
+
# @raise [RubyClamdscan::Errors::EmptyResponseError] If server response is empty
|
54
77
|
def reload_server_database
|
55
78
|
RubyClamdscan::Commands::Manage.reload_server_database(@configuration)
|
56
79
|
end
|
57
80
|
|
81
|
+
# Shutdown ClamAV server
|
82
|
+
# Note: this will completely close socket communication. Server cannot be restarted through this library
|
83
|
+
# @raise [RubyClamdscan::Errors::ClamAVCommunicationError] if communication with ClamAV server fails
|
84
|
+
# @return [Boolean] true if shutdown command was sent
|
58
85
|
def shutdown_server
|
59
86
|
RubyClamdscan::Commands::Manage.shutdown_server(@configuration)
|
60
87
|
end
|