stream_auditor 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 50250b66a46864c7c059e9b0b55983f25086a662
-  data.tar.gz: d0b0f3f9d49fea41c7a24001d0035c022862f4c1
+  metadata.gz: 7d895a8c1753ca74e5ae3c007c4e8330db73138d
+  data.tar.gz: 70ea4dc5e3193f09e51b7b5d61af2194c27ac883
 SHA512:
-  metadata.gz: 4fed046c80026fedecd44e6932339fdef25c67802197bb506697a889810a1456a6ff41917ebb1db12a43b8df51f80685f01ec250deceebd821f91e7f623464f0
-  data.tar.gz: 55f98b27fdc3ce7f24d26da9761005120a42b8a4f899285a613f21b772e4b659d119f45ed368975eef12a41c92177f5f59f98ec488e3ba91fb348f081d218592
+  metadata.gz: bae9104d6cd01600b625e86da2aeb9a17ecf656f6a2e45ec5527eebbd8a37ebac7ed84d693fc9853fec0c6a66ff331b6b4876168aa05592ba97fec283b050023
+  data.tar.gz: d6cc276f4291bbf79431d09dd9a757106170290c1e58e707e60acf39253e8f83bd4f3b58b23a0f808ee9846b6e6721a38cdc6b065ab9002e739fd95b198685c0

data/lib/stream_auditor/version.rb

@@ -1,5 +1,5 @@
 require "soar_auditor_api/auditor_api"
 
 class StreamAuditor < SoarAuditorApi::AuditorAPI
-  VERSION = "1.0.0"
+  VERSION = "1.0.1"
 end

data/lib/stream_auditor.rb

@@ -2,13 +2,86 @@ require "stream_auditor/version"
 require "soar_auditor_api/auditor_api"
 require "fileutils"
 
+##
+# An IO stream (or file) implementation of {http://www.rubydoc.info/gems/soar_auditor_api/SoarAuditorApi/AuditorAPI SoarAuditorApi::AuditorAPI}
+#
+# This implementation supports auditing to:
+#
+#   * an already open {IO} object (or anything that implements {IO#<<} and {IO#flush},
+#   * the standard error stream (+$stderr+),
+#   * the standard output stream (+$stdout+), or
+#   * a file.
+#
+# Developers should not need to work directly with this class. Instead, they should configure it through the
+# {http://www.rubydoc.info/gems/soar_auditing_provider/SoarAuditingProvider/AuditingProvider SOAR auditing provider}.
+#
+# @example Log to file
+#
+#  require "soar_auditing_provider"
+#  require "stream_auditor"
+#
+#  config = {
+#    "auditing" => {
+#      "provider" => "SoarAuditingProvider::AuditingProvider",
+#      "level" => "debug",
+#      "install_exit_handler" => "true",
+#      "direct_auditor_call" => "true",
+#      "queue_worker" => {
+#        "queue_size" => 1,
+#        "back_off_attempts" => 1
+#      },
+#      "auditors" => {
+#        "local" => {
+#          "adaptor" => "StreamAuditor",
+#          "stream" => "/var/log/application.log"
+#        }
+#      }
+#    }
+#  }
+#
+#  auditor = SoarAuditingProvider::AuditingProvider.new(config["auditing"])
+#  auditor.info("Auditor initialized")
+#
 class StreamAuditor < SoarAuditorApi::AuditorAPI
 
+  ##
+  # Write data to the configured stream
+  #
+  # The stream is immediately flushed after the data is written.
+  #
+  # @param [Object] data
+  #   the {String} (or {Object} with +to_s+ method) to write.
+  #   If the string is not newline-terminated, a newline is added.
+  #
   def audit(data)
     stream << data.to_s.chomp + "\n"
     stream.flush
   end
 
+  ##
+  # Apply the configuration supplied to {#initialize}
+  #
+  # @param [Hash] configuration
+  #   This method accepts +nil+ or a {Hash}, but the auditor API only calls
+  #   this method when the configuration is not +nil+.
+  #
+  #   The configuration may contain the following {String} keys:
+  #
+  #   * +adaptor+ - ignored (for compatibility with the SOAR auditing provider
+  #   * +stream+  - the stream to audit to, one of:
+  #     * an {IO} object (or anything that implements {IO#<<} and {IO#flush}
+  #     * the string +$stderr+ for the standard error stream
+  #     * the string +$stdout+ for the standard output stream
+  #     * the string path to a file
+  #
+  #   If the +stream+ key is ommitted, the default is +$stderr+.
+  #
+  #   When the stream is the path to a file:
+  #
+  #   * any missing intermediate directories will be created (mode 0700),
+  #   * the file will be created if missing (mode 0600),
+  #   * the file is opened in append mode.
+  #
   def configure(configuration = nil)
     super
     if configuration
@@ -21,6 +94,15 @@ class StreamAuditor < SoarAuditorApi::AuditorAPI
     end
   end
 
+  ##
+  # Validates the configuration
+  #
+  # @param [Hash] configuration
+  #   the configuration to validate
+  #
+  # @return [true] if the configuration is valid
+  # @return [false] if the configuration is invalid
+  #
   def configuration_is_valid?(configuration)
     return false unless (configuration.keys - ["adaptor", "stream"]).empty?
 
@@ -32,7 +114,7 @@ class StreamAuditor < SoarAuditorApi::AuditorAPI
 
   def creative_open_file(path)
     FileUtils.mkdir_p(File.expand_path("..", path), mode: 0700)
-    File.open(path, "a")
+    File.open(path, "a", 0600)
   end
 
   def stream

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: stream_auditor
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Sheldon Hearn