soar_auditor_api 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9879b49a5a82d14cc2fe47b7ebddaf5c63d482c0
-  data.tar.gz: 6b5131d74480cd7d7a4c5f15f11dfdcbe87b77e5
+  metadata.gz: 86bd2491171a982f60f65da6895a59d063339d35
+  data.tar.gz: b9c2e332fa486de9d2426d62c82c0f3cec123c2d
 SHA512:
-  metadata.gz: a696ee6e0c1572c352e0990f3ee788a1d4929914287e5d59271863a66d82718c699168d411851af30b2be2232fda78822ee0ee76103f0ec4a52630ef2a579deb
-  data.tar.gz: 242caa4d8d79f6e521ceae3156885383b9227f5878be3f2c5028de8131f500fce233b3a26557553ef34186c8cc401a506666cce07281d39fab4ce41af3de5a63
+  metadata.gz: 260db2993a63524491abf76e5819ab0e58fbcd16aea12835acf06a9e90c761072aad52256274fe6ec01330d8d12a28636fd56b7e2e3257882f43c1c3017aee2d
+  data.tar.gz: 01d1e3b6d87b79e1146066c159a5db24b8cd0082b5babe411eb59a222d8852620c4231c8a3dbd8bc7cd312c6ebcc39344fdd5cfaaf957d62c37d8d35ed06fdc5

data/README.md

@@ -1,12 +1,10 @@
-#TODO fix this file
-
 # SoarAuditorApi
 
 This gem provides the auditor api for the SOAR architecture.
 
 ## State of the API
 
-
+This API is still a work in progress but should be sufficient to most auditors
 
 ## Installation
 
@@ -32,14 +30,6 @@ Behavioural driven testing can be performed:
 
 ## Usage
 
-
-
-### Auditing Providers that utilize the SoarAuditorAPI as clients
-
-
-Note that the APIs (debug/info/warn/error/fatal) accept any object as a parameter. The object will be serialized using the .to_s method and therefore the object must implement the .to_s method (or already be a string that has the .to_s method).
-
-
 ### Auditors that extend from the SoarAuditorAPI
 
 Extend from the SoarAuditorAPI as follow
@@ -49,7 +39,7 @@ class MyAuditor < SoarAuditorApi::SoarAuditorAPI
 end
 ```
 
-The auditors that extend from this API must implement two methods: "audit" and "configuration_is_valid"
+It is required that the auditors that extend from this API implement two methods: "audit" and "configuration_is_valid". The API will call these methods using inversion of control as follow:
 
 The configuration_is_valid method provides the API with a way of ensuring that a configuration is valid for the auditor.
 ```ruby
@@ -65,68 +55,69 @@ def audit(data)
 end
 ```
 
-The configuration is made available to the auditor through the @configuration attribute in the API.
-
-
-
-
-#TODO complete this section
-#TODO Extend the SoarAuditorApi::AuditingProviderAPI to create an auditing provider:
-
-
-
-Provide the required inversion of control method to configure (an) injected auditor(s):
-
-```
-def configure_auditor(configuration = nil)
-  @auditor.configure(configuration)
+The configuration is made available to the auditor through the @configuration attribute in the API class.
+```ruby
+def audit(data)
+  puts @configuration["preprefix"] + data
 end
 ```
 
-Initialize the provider so:
 
-```
-auditor = MyAuditor.new
-auditor_configuration = { 'some' => 'configuration' }
-@iut = MyAuditingProvider.new(auditor, auditor_configuration)
+### Auditing Providers that utilize the SoarAuditorAPI as clients
+
+Instantiate an auditor that extends the SoarAuditorAPI:
+```ruby
+@iut = SanityAuditor.new
 ```
 
-Audit using the API methods, e.g.:
+Configure the auditor with required parameters:
+```ruby
+configuration = { "preprefix" => "very important:" }
+@iut.configure(configuration)
+```
 
+Set the desired audit level. Allowed levels (in increasing level of priority) are :debug, :info, :warn, :error and :fatal.  As an example only :warn, :error and :fatal audit events will be logged if you set the level to :warn.
+```ruby
+@iut.set_audit_level(:warn)
 ```
+
+Use the auditing interfaces as follow. The API also supports appending as below, enabling support, e.g. for Rack::CommonLogger, etc.:
+```ruby
 @iut.info("This is info")
-@iut.debug(some_debug_object)
 @iut.warn("Statistics show that dropped packets have increased to #{dropped}%")
 @iut.error("Could not resend some dropped packets. They have been lost. All is still OK, I could compensate")
 @iut.fatal("Unable to perform action, too many dropped packets. Functional degradation.")
 @iut << 'Rack::CommonLogger requires this'
 ```
 
-The API also supports appending as below, enabling support, e.g. for Rack::CommonLogger, etc.:
-
-```
-<<
+Note that the APIs (debug/info/warn/error/fatal) accept any object as a parameter. The object will be serialized using the .to_s method and therefore the object must implement the .to_s method (or already be of a basic object type that has the .to_s method).
+```ruby
+some_debug_object = 123
+@iut.debug(some_debug_object)
 ```
 
 ## Detailed example
 
-```
-require 'log4r'
+```ruby
 require 'soar_auditor_api'
+require 'byebug'
+
+class SanityAuditor < SoarAuditorApi::SoarAuditorAPI
+  def configuration_is_valid(configuration)
+    return configuration.include?("preprefix")
+  end
 
-class Log4rAuditingProvider < SoarAuditorApi::AuditingProviderAPI
-  def configure_auditor(configuration = nil)
-    @auditor.outputters = configuration['outputter']
+  def audit(data)
+    puts @configuration["preprefix"] + data
   end
 end
 
 class Main
-  include Log4r
-
   def test_sanity
-    auditor = Logger.new 'sanity'
-    auditor_configuration = { 'outputter' => Outputter.stdout }
-    @iut = Log4rAuditingProvider.new(auditor, auditor_configuration)
+    @iut = SanityAuditor.new
+    configuration = { "preprefix" => "very important:" }
+    @iut.configure(configuration)
+    @iut.set_audit_level(:debug)
 
     some_debug_object = 123
     @iut.info("This is info")
@@ -135,6 +126,7 @@ class Main
     @iut.warn("Statistics show that dropped packets have increased to #{dropped}%")
     @iut.error("Could not resend some dropped packets. They have been lost. All is still OK, I could compensate")
     @iut.fatal("Unable to perform action, too many dropped packets. Functional degradation.")
+    @iut << 'Rack::CommonLogger requires this'
   end
 end
 

data/lib/soar_auditor_api/version.rb

@@ -1,3 +1,3 @@
 module SoarAuditorApi
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

data/sanity/Gemfile

@@ -1,5 +1,4 @@
 source 'https://rubygems.org'
 
-gem 'log4r'
 gem 'byebug'
-gem 'soar_auditor_api', "~> 0.0.1"
+gem 'soar_auditor_api', "~> 0.0.2"

data/sanity/sanity.rb

@@ -1,20 +1,22 @@
 require 'soar_auditor_api'
 require 'byebug'
 
-class SanityAuditor < SoarAuditorAPI
+class SanityAuditor < SoarAuditorApi::SoarAuditorAPI
   def configuration_is_valid(configuration)
-    return true
+    return configuration.include?("preprefix")
   end
 
   def audit(data)
-    puts data
+    puts @configuration["preprefix"] + data
   end
 end
 
 class Main
   def test_sanity
     @iut = SanityAuditor.new
-    @iut.configure(nil)
+    configuration = { "preprefix" => "very important:" }
+    @iut.configure(configuration)
+    @iut.set_audit_level(:debug)
 
     some_debug_object = 123
     @iut.info("This is info")

data/soar_auditor_api.gemspec

@@ -10,7 +10,7 @@ Gem::Specification.new do |spec|
   spec.email         = ["barney.de.villiers@hetzner.co.za"]
 
   spec.summary       = %q{SOAR auditor api}
-  spec.description   = %q{SOAR auditor api from which auditors will extend from}
+  spec.description   = %q{SOAR auditor api from which auditor implementations will extend}
   spec.homepage      = "https://github.hetzner.co.za/hetznerZA/soar_auditor_api"
   spec.license       = "MIT"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: soar_auditor_api
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Barney de Villiers
@@ -66,7 +66,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '9'
-description: SOAR auditor api from which auditors will extend from
+description: SOAR auditor api from which auditor implementations will extend
 email:
 - barney.de.villiers@hetzner.co.za
 executables: []