deepsecurity 0.0.19 → 0.0.20

data/lib/deepsecurity/transport_objects/id_filter.rb

@@ -17,7 +17,7 @@ module DeepSecurity
     # @!group High-Level SOAP Wrapper
 
     # Return a new instance for events with the given event id.
-    # @param [Integer] id
+    # @param id [Integer]
     # @return [IDFilter]
     def self.equals(id)
       instance = self.new()
@@ -27,7 +27,7 @@ module DeepSecurity
     end
 
     # Return a new instance for events with event ids less than the given event id.
-    # @param [Integer] id
+    # @param id [Integer]
     # @return [IDFilter]
     def self.less_than(id)
       instance = self.new()
@@ -37,7 +37,7 @@ module DeepSecurity
     end
 
     # Return a new instance for events with event ids greater than the given event id.
-    # @param [Integer] id
+    # @param id [Integer]
     # @return [IDFilter]
     def self.greater_than(id)
       instance = self.new()

data/lib/deepsecurity/transport_objects/system_event.rb

@@ -36,7 +36,7 @@ module DeepSecurity
           :includeNonHostEvents => includeNonHostEvents ? "true" : "false"})[:system_events]
       return [] if events.nil?
       events[:item].map do |each|
-        SystemEvent.from_savon_data(each)
+        SystemEvent.convert_from_savon(each)
       end
     end
 

data/lib/deepsecurity/transport_objects/time_filter.rb

@@ -45,7 +45,7 @@ module DeepSecurity
     end
 
     # Return a new instance for the given datetime range.
-    # @param [Range] datetime_range A range of two datetimes
+    # @param datetime_range [Range] A range of two datetimes
     # @return [TimeFilter]
     def self.custom_range(datetime_range)
       instance = self.new()
@@ -56,7 +56,7 @@ module DeepSecurity
     end
 
     # Return a new instance for the given datetime.
-    # @param [DateTime] datetime
+    # @param datetime [DateTime]
     # @return [TimeFilter]
     def self.specificTime(datetime)
       instance = self.new()

data/lib/deepsecurity/version.rb

@@ -1,3 +1,3 @@
 module DeepSecurity
-  VERSION = "0.0.19"
+  VERSION = "0.0.20"
 end

data/lib/dsc/anti_malware_event_command.rb

@@ -1,12 +1,20 @@
+# @author Udo Schneider <Udo.Schneider@homeaddress.de>
+
 module Dsc
 
+  # This class defines the arguments, options and implementation for the `anti_malware_event` command/subcommand.
   class AntiMalwareEventCommand < Command
 
-
+    # DeepSecurity object covered by this class.
+    # @return [DeepSecurity::AntiMalwareEvent]
     def self.transport_class
       DeepSecurity::AntiMalwareEvent
     end
 
+    # @!group Fields flag
+
+    # Default fields if no argument is given
+    # @return [Array<String>] Default fields if no argument is given
     def self.default_fields
       [
           # DNS name of system
@@ -52,17 +60,56 @@ module Dsc
       ]
     end
 
-    def list(options, args)
+    # @!endgroup
+
+    # @!group Command definitions
+
+    # Define all commands for this available for this (sub) command_context
+    # @param command_context [CLI::App] The current context of the command.
+    # @return [void]
+    def self.define_commands(command_context)
+      command_context.desc "Access #{transport_class_string}s"
+      command_context.command command_symbol do |anti_malware_event_command|
+        define_list_command(anti_malware_event_command)
+        define_schema_command(anti_malware_event_command)
+      end
+    end
+
+    # Define `list` command_context
+    # @param command_context [CLI::App] The current context of the command.
+    # @yieldparam list_command [GLI::Command] The just defined list command_context
+    # @yield [list_command] Gives the list command_context to the block
+    # @return [void]
+    def self.define_list_command(command_context)
+      super(command_context) do |list|
+        define_time_filter_flag(list)
+        define_time_format_flag(list)
+      end
+    end
+
+    # @!endgroup
+
+    # @!group Command Implementations
+
+    # `list` Implementation.
+    # List all entries of the `transport_class` type according to given filter parameters.
+    # @param options [Hash<Symbol => Object>] Merged global/local options from GLI
+    # @option options [String] :fields The fields to display.
+    # @option options [String] :time_filter Timeframe to request.
+    # @param args [Array<String>] Arguments from GLI
+    # @return [void]
+    def list_command(options, args)
       fields = parse_fields(options[:fields])
       time_filter = parse_time_filter(options[:time_filter])
+      parse_time_format(options[:time_format])
       output do |output|
-        authenticate do |dsm|
+        authenticate do |manager|
           progressBar = ProgressBar.new("anti_malware_event", 100) if @show_progress_bar
-          DeepSecurity::Host.all # Make sure that hosts are cached
+          manager.hosts() # Make sure that hosts are cached
           progressBar.set(10) if @show_progress_bar
           hostFilter = DeepSecurity::HostFilter.all_hosts
           eventIdFilter = DeepSecurity::IDFilter.greater_than(0)
-          anti_malware_events = DeepSecurity::AntiMalwareEvent.find_all(time_filter, hostFilter, eventIdFilter)
+          anti_malware_events = manager.anti_malware_events_by_time_host_event(time_filter, hostFilter, eventIdFilter)
           progressBar.set(25) if @show_progress_bar
           csv = CSV.new(output)
           csv << fields
@@ -70,7 +117,7 @@ module Dsc
             progressBar.inc(75/anti_malware_events.size) if @show_progress_bar
             csv << fields.map do |attribute|
               begin
-                anti_malware_event.instance_eval(attribute)
+                to_display_string(anti_malware_event.instance_eval(attribute))
               rescue => e
                 "ERROR (#{e.message}"
               end
@@ -81,11 +128,7 @@ module Dsc
       end
     end
 
-    def self.define_list_command(c)
-      super(c) do |list|
-        define_time_filter_argument(list)
-      end
-    end
+    # @!endgroup
 
   end
 

data/lib/dsc/command.rb

@@ -1,72 +1,298 @@
+# @author Udo Schneider <Udo.Schneider@homeaddress.de>
 require "progressbar"
 require "csv"
 
 module Dsc
 
+  # This class defines an superclass for all `dsc` commands. It defines several helper methods which either define
+  # flags, options and commands or helpers to define them.
+  # @abstract
   class Command
 
+    # @abstract DeepSecurity object covered by this class.
+    # @return [DeepSecurity::TransportObject]
     def self.transport_class
       nil
     end
 
+    # @!group Helper methods
+
+    # Transport class name without namespace
+    # @return [String] Transport class name without namespace
     def self.transport_class_name
-      class_name = transport_class.name.split('::').last || ''
+      transport_class.name_without_namespace
     end
 
+    #  Human readable transport class name without namespace
+    # @return [String] Human readable transport class name without namespace
     def self.transport_class_string
       transport_class_name.split(/(?=[A-Z])/).join(" ")
     end
 
+    # Class name without namespace as command_context symbol
+    # @return [Symbol] Class name without namespace as command_context symbol
     def self.command_symbol
       transport_class_name.split(/(?=[A-Z])/).join("_").downcase.to_sym
     end
 
+    # The schema of the transport class
+    # @return [Hash<Symbol => SavonHelper::TypeMapping]
     def self.schema
-      transport_class.mappings
+      transport_class.all_type_mappings
     end
 
+    # @!endgroup
+
+    # @param global_options [Hash] Global options passed to the `dsc` command_context.
+    # @option global_options [String] :manager The hostname of the DeepSecurity Manager.
+    # @option global_options [String] :port The TCP port to use.
+    # @option global_options [String, nil] :tenant The tenant name or nil.
+    # @option global_options [String] :username The username.
+    # @option global_options [String] :password The password.
+    # @option global_options [Boolean] :P Show progessbar?
+    # @option global_options [String, nil] :debug The debug level.
+    # @option global_options [String] :outfile The outfile.
     def initialize(global_options)
-      @hostname = global_options[:m]
+      @hostname = global_options[:manager]
       @port = global_options[:port].to_i
-      @tenant = global_options[:t]
-      @username =global_options[:u]
-      @password = global_options[:p]
+      @tenant = global_options[:tenant]
+      @username = global_options[:username]
+      @password = global_options[:password]
       @show_progress_bar = global_options[:P]
-      @debug_level = debug_level_from_option(global_options[:d])
-      @output = global_options[:o]
+      @debug_level = parse_debug_level(global_options[:debug])
+      @output = global_options[:outfile]
+    end
+
+    # @!group Helper methods
+
+    # Provide an open output while executing the block.
+    # @yieldparam output [IO] Opened IO
+    # @yield [output] Gives the output to the block
+    # @return [void]
+    def output
+      unless @output == '--'
+        output = File.open(option, 'w')
+      else
+        output = STDOUT
+      end
+      yield output
+      output.close() unless @output == '--'
+    end
+
+    # Provides a connection to the DeepSecurity Manager  while executing the block.
+    # @yieldparam manager [DeepSecurity::Manager] DeepSecurity Manager
+    # @yield [manager] Gives the manager to the block
+    # @return [void]
+    def connect
+      manager = DeepSecurity::Manager.server(@hostname, @port, @debug_level)
+      yield manager
+    end
+
+    # Provides an authenticated connection to the DeepSecurity Manager  while executing the block.
+    # @yieldparam manager [DeepSecurity::Manager] DeepSecurity Manager
+    # @yield [manager] Gives the manager to the block
+    # @return [void]
+    def authenticate
+      connect do |manager|
+        begin
+          manager.connect(@tenant, @username, @password)
+          yield manager
+        rescue DeepSecurity::AuthenticationFailedException => e
+          puts "Authentication failed! #{e.message}"
+        ensure
+          manager.disconnect()
+        end
+      end
+    end
+
+    def to_display_string(value)
+      return "" if value.blank?
+      return value.strftime($time_format) if (value.is_a?(DateTime) && !$time_format.nil?)
+      value.to_s
+    end
+
+    # @!endgroup
+
+    # @!group Misc global flags/options definitions
+
+    # Define flags
+    # @return [void]
+    def self.define_global_flags(command_context)
+      define_debug_flag(command_context)
+      define_manager_flag(command_context)
+      define_port_flag(command_context)
+      define_tenant_flag(command_context)
+      define_username_flag(command_context)
+      define_password_flag(command_context)
+      define_outfile_flag(command_context)
+      define_progress_bar_option(command_context)
     end
 
+    # Define manager hostname flag
+    # @param command_context [CLI::App] The current context of the command.
+    # @return [void]
+    def self.define_manager_flag(command_context)
+      command_context.flag [:m, :manager],
+                           :desc => 'Deep Security Manager Host',
+                           :arg_name => 'hostname'
+    end
+
+    # Define manager TCP Port flag
+    # @param command_context [CLI::App] The current context of the command.
+    # @return [void]
+    def self.define_port_flag(command_context)
+      command_context.flag [:port],
+                           :desc => 'Webservice Port',
+                           :arg_name => 'port',
+                           :default_value => '4119'
+    end
+
+    # Define tenant flag
+    # @param command_context [CLI::App] The current context of the command.
+    # @return [void]
+    def self.define_tenant_flag(command_context)
+      command_context.flag [:t, :tenant],
+                           :desc => 'Tenat Name',
+                           :arg_name => 'tenat',
+                           :default_value => ''
+    end
+
+    # Define username flag
+    # @param command_context [CLI::App] The current context of the command.
+    # @return [void]
+    def self.define_username_flag(command_context)
+      command_context.flag [:u, :username],
+                           :desc => 'Username',
+                           :arg_name => 'username',
+                           :default_value => 'MasterAdmin'
+    end
+
+    # Define password flag
+    # @param command_context [CLI::App] The current context of the command.
+    # @return [void]
+    def self.define_password_flag(command_context)
+      command_context.flag [:p, :password],
+                           :desc => 'Password',
+                           :arg_name => 'password'
+    end
+
+    # Define outfile flag
+    # @param command_context [CLI::App] The current context of the command.
+    # @return [void]
+    def self.define_outfile_flag(command_context)
+      command_context.flag [:o, :outfile],
+                           :desc => 'Output filename',
+                           :default_value => '--'
+    end
+
+    # Define outfile flag
+    # @param command_context [CLI::App] The current context of the command.
+    # @return [void]
+    def self.define_outfile_flag(command_context)
+      command_context.flag [:o, :outfile],
+                           :desc => 'Output filename',
+                           :default_value => '--'
+    end
+
+    # Define progress_bar option
+    # @param command_context [CLI::App] The current context of the command.
+    # @return [void]
+    def self.define_progress_bar_option(command_context)
+      command_context.switch [:P, :'progress_bar'],
+                             :desc => 'Show progressbar',
+                             :default_value => false
+    end
+
+    # @!endgroup
+
+    # @!group Debug Level flag
+
+    # Valid debug levels
+    # @return [Array<String>] Valid debug levels
     def self.valid_debug_levels
       DeepSecurity::LOG_MAPPING.keys
     end
 
+    # String of debug levels for help string
+    # @return [String] String of debug levels for help string
     def self.valid_debug_levels_string
       valid_debug_levels.join(", ")
     end
 
+    # Parse debug level argument
+    # @return [nil, DeepSecurity::LOG_MAPPING] Return parsed debug level
+    def parse_debug_level(argument)
+      return nil if argument.blank?
+      return argument.to_sym if (DeepSecurity::LOG_MAPPING.keys.include?(argument.to_sym))
+      :debug
+    end
+
+    # Define debug level flag
+    # @return [void]
+    def self.define_debug_flag(command_context)
+      command_context.flag [:d, :debug],
+                           :desc => "Enable client debug output. (One of #{Dsc::Command.valid_debug_levels_string})",
+                           :arg_name => 'debug_level'
+    end
+
+    # @!endgroup
+
+    # @!group Fields flag
+
+    # Default fields if no argument is given
+    # @note Needs to be overridden by subclass
+    # @return [Array<String>] Default fields if no argument is given
     def self.default_fields
       []
     end
 
+    # String of default fields for help string
+    # @return [String]  String of default fields for help string
     def self.default_fields_string
       default_fields.join(",")
     end
 
+    # Sorted list of available fields
+    # @return [Array<String>] Sorted list of available fields
     def self.valid_fields
       transport_class.defined_attributes.sort
     end
 
+    # String of available fields for help string
+    # @return [String]  String of available fields for help string
     def self.valid_fields_string
       valid_fields.join(", ")
     end
 
-    def parse_fields(string)
-      fields = string.split(",").map(&:strip)
+    # Parse fields argument. Either split the string or read from file
+    # @return [Array<String>] parse fields
+    def parse_fields(fields_string_or_filename_argument)
+      filename = File.absolute_path(fields_string_or_filename_argument)
+      if File.exists?(filename)
+        fields_string = File.read(filename)
+      else
+        fields_string = fields_string_or_filename_argument
+      end
+      fields = fields_string.split(",").map(&:strip)
       unknown_fields = fields.reject { |each| self.class.transport_class.has_attribute_chain(each) }
-      raise "Unknown field found (#{unknown_fields.join(', ')}) - known fields are: #{self.class.valid_fields.join(', ')}" unless unknown_fields.empty?
+      raise "Unknown filename or field found (#{unknown_fields.join(', ')}) - known fields are: #{self.class.valid_fields.join(', ')}" unless unknown_fields.empty?
       fields
     end
 
+    # Define fields flag
+    # @return [void]
+    def self.define_fields_flag(command_context)
+      command_context.flag [:fields],
+                           :desc => "A comma separated list of fields to display or a file containing those fields. (Available fields: #{self.valid_fields_string})",
+                           :default_value => self.default_fields_string
+    end
+
+    # @!endgroup
+
+    # @!group Time filter flag
+
+    # Valid timefilter mapping (symbol to instance)
+    # @return [Hash<Symbol => DeepSecurity::TimeFilter>] Valid timefilter mapping
     def self.valid_time_filters
       {
           :last_hour => DeepSecurity::TimeFilter.last_hour,
@@ -76,109 +302,199 @@ module Dsc
       }
     end
 
+    # Valid time filter string for help string
+    # @return[String] Valid time filters
     def self.valid_time_filters_string
       valid_time_filters.keys.join(', ')
     end
 
-    def parse_time_filter(string)
-      filter = self.class.valid_time_filters[string.to_sym]
+    # Parse time_filter argument
+    # @return [DeepSecurity::TimeFilter] Time filter
+    def parse_time_filter(argument)
+      filter = self.class.valid_time_filters[argument.to_sym]
       raise "Unknown time filter" if filter.nil?
       filter
     end
 
+    # Define time_filter flag
+    # @return [void]
+    def self.define_time_filter_flag(command_context)
+      command_context.flag [:time_filter],
+                           :desc => "A filter specifying the time interval to query (One of #{self.valid_time_filters_string})",
+                           :default_value => "last_day"
+    end
 
-    def debug_level_from_option(option)
-      return nil if option.blank?
-      return option.to_sym if (DeepSecurity::LOG_MAPPING.keys.include?(option.to_sym))
-      :debug
+    # @!endgroup
+
+    # @!group Detail level flag
+
+    # Valid detail levels
+    # @return [Array<String>] Valid detail levels
+    def self.valid_detail_levels
+      DeepSecurity::EnumHostDetailLevel.keys()
     end
 
-    def output
-      unless @output == '--'
-        output = File.open(option, 'w')
-      else
-        output = STDOUT
-      end
-      yield output
-      output.close() unless @output == '--'
+    # Valid detail levels for help string
+    # @return [String]  Valid detail levels for help string
+    def self.valid_detail_levels_string
+      valid_detail_levels.map(&:downcase).join(", ")
     end
 
-    def connect
-      yield DeepSecurity::Manager.server(@hostname, @port, @debug_level)
+    # Parse detail_level argument
+    # @return [EnumHostDetailLevel] Detail level
+    def parse_detail_level(argument)
+      detail_level = DeepSecurity::EnumHostDetailLevel[argument.upcase.strip]
+      raise "Unknown detail level filter" if detail_level.nil?
+      detail_level
     end
 
-    def authenticate
-      connect do |dsm|
-        begin
-          dsm.connect(@tenant, @username, @password)
-          yield dsm
-        rescue DeepSecurity::AuthenticationFailedException => e
-          puts "Authentication failed! #{e.message}"
-        ensure
-          dsm.disconnect()
-        end
-      end
+    # Define detail_level flag
+    # @return [void]
+    def self.define_detail_level_flag(command_context)
+      command_context.flag [:detail_level],
+                           :desc => "A detail level specifiying the extent of data returned. (Available values: #{self.valid_detail_levels_string})",
+                           :default_value => "low"
     end
 
+    # @!endgroup
 
-    def print_api_version(options, args)
-      output do |output|
-        authenticate do |dsm|
-          output.puts dsm.api_version()
+    # @!group Time format flag
+
+    # Parse detail_level argument
+    # @return [EnumHostDetailLevel] Detail level
+    def parse_time_format(argument)
+      $time_format = argument.nil? ? "" : argument
+    end
+
+    # Define detail_level flag
+    # @return [void]
+    def self.define_time_format_flag(command_context)
+      command_context.flag [:time_format],
+                           :desc => "An strftime() compatible string to use for outputting date/time."
+    end
+
+    # @!endgroup
+
+    # @!group Command definitions
+
+    # @abstract Define all commands for this available for this (sub) command_context
+    # @param command_context [CLI::App] The current context of the command.
+    # @return [void]
+    def self.define_commands(command_context)
+    end
+
+    # Define some simple commands.
+    # @param command_context [CLI::App] The current context of the command.
+    # @return [void]
+    def self.define_misc_commands(command_context)
+      self.define_api_version_command(command_context)
+      self.define_manager_time_command(command_context)
+    end
+
+    # Define `api_version` command_context
+    # @param command_context [CLI::App] The current context of the command.
+    # @return [void]
+    def self.define_api_version_command(command_context)
+      command_context.desc 'Display API Version'
+      command_context.command :api_version do |api_version_command|
+        api_version_command.action do |global_options, options, args|
+          self.new(global_options).api_version_command(options, args)
         end
       end
     end
 
-    def print_manager_time(options, args)
-      output do |output|
-        authenticate do |dsm|
-          output.puts dsm.manager_time()
+    # Define `manager_time` command_context
+    # @param command_context [CLI::App] The current context of the command.
+    # @return [void]
+    def self.define_manager_time_command(command_context)
+      command_context.desc 'Display Manager time'
+      command_context.command :manager_time do |manager_time_command|
+        manager_time_command.action do |global_options, options, args|
+          self.new(global_options).manager_time_command(options, args)
         end
       end
     end
 
-    def print_schema(options, args)
-      output do |output|
-        schema = self.class.schema()
-        schema.keys.sort.each do |key|
-          output.puts "#{key} (#{schema[key].type_string}): #{schema[key].description}"
+    # Define `list` command_context
+    # @param command_context [CLI::App] The current context of the command.
+    # @yieldparam list_command [GLI::Command] The just defined list command_context
+    # @yield [list_command] Gives the list command_context to the block
+    # @return [void]
+    def self.define_list_command(command_context)
+      command_context.desc "List #{self.transport_class_string}s"
+      command_context.command :list do |list_command|
+        define_fields_flag(list_command)
+        yield list_command if block_given?
+        list_command.action do |global_options, options, args|
+          self.new(global_options).list_command(options, args)
         end
       end
     end
 
-    def self.define_list_command(command)
-      command.desc "List #{self.transport_class_string}s"
-      command.command :list do |list|
-        define_fields_argument(list)
-        yield list if block_given?
-        list.action do |global_options, options, args|
-          self.new(global_options).list(options, args)
+    # Define `schema` command_context
+    # @param command_context [CLI::App] The current context of the command.
+    # @yieldparam schema_command [GLI::Command] The just defined schema command_context
+    # @yield [schema_command] Gives the schema command_context to the block
+    # @return [void]
+    def self.define_schema_command(command_context)
+      command_context.desc "Show #{self.transport_class_string} schema"
+      command_context.command :schema do |schema_command|
+        yield schema_command if block_given?
+        schema_command.action do |global_options, options, args|
+          self.new(global_options).schema_command(options, args)
         end
       end
     end
 
-    def self.define_schema_command(command)
-      command.desc "Show #{self.transport_class_string} schema"
-      command.command :schema do |schema|
-        yield schema if block_given?
-        schema.action do |global_options, options, args|
-          self.new(global_options).print_schema(options, args)
+    # @!endgroup
+
+    # @!group Command Implementations
+
+    # `api_version` Implementation.
+    # Display the API version in use by the DeepSecurity Manager.
+    # @note Does not require authentication
+    # @param options [Hash<Symbol => Object>] Merged global/local options from GLI
+    # @param args [Array<String>] Arguments from GLI
+    # @return [void]
+    def api_version_command(options, args)
+      output do |output|
+        connect do |manager|
+          output.puts manager.api_version()
         end
       end
     end
 
-    def self.define_time_filter_argument(command)
-      command.desc "A filter specifying the time interval to query (One of #{self.valid_time_filters_string})"
-      command.default_value "last_day"
-      command.flag [:time_filter]
+    # `manager_time` Implementation.
+    # Display the local time of the DeepSecurity Manager.
+    # @note Does not require authentication
+    # @param options [Hash<Symbol => Object>] Merged global/local options from GLI
+    # @param args [Array<String>] Arguments from GLI
+    # @return [void]
+    def manager_time_command(options, args)
+      output do |output|
+        connect do |manager|
+          output.puts manager.manager_time()
+        end
+      end
     end
 
-    def self.define_fields_argument(command)
-      command.desc "A comma separated list of fields to display. (Available fields: #{self.valid_fields_string})"
-      command.default_value self.default_fields_string
-      command.flag [:fields]
+    # `schema` Implementation.
+    # Display schema of the current datatype (defined by `transport_class`).
+    # @note Does not require authentication
+    # @param options [Hash<Symbol => Object>] Merged global/local options from GLI
+    # @param args [Array<String>] Arguments from GLI
+    # @return [void]
+    def schema_command(options, args)
+      output do |output|
+        schema = self.class.schema()
+        schema.keys.sort.each do |key|
+          output.puts "#{key} (#{schema[key].type_string}): #{schema[key].description}"
+        end
+      end
     end
 
+    # @!endgroup
+
   end
 
 end