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 for most auditors

Future work:

• The API should support the reformating of timestamps to a standardized ISO8601 format.

Installation

Add this line to your auditor Gemfile:

gem 'soar_auditor_api'

And then execute:

$ bundle

Or install it yourself as:

$ gem install soar_auditor_api

Testing

Behavioural driven testing can be performed:

$ bundle exec rspec -cfd spec/*

Usage

Auditors that extend from the AuditorAPI

Extend from the AuditorAPI as follow

class MyAuditor < SoarAuditorApi::AuditorAPI
end

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.

def configuration_is_valid(configuration)
  return configuration.include?("something_needed")
end

The audit method will be called when the base API wants to publish an audit event after it has been formatted and filtered.

def audit(data)
  puts data
end

The configuration is made available to the auditor through the @configuration attribute in the API class.

def audit(data)
  puts @configuration["preprefix"] + data
end

Auditing Providers that utilize the AuditorAPI as clients

Instantiate an auditor that extends the AuditorAPI:

@iut = SanityAuditor.new

Configure the auditor with required parameters:

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.

@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.:

@iut.info("This is info")
@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'

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).

some_debug_object = 123
@iut.debug(some_debug_object)

Serializable classes

Class instances to be logged in the message field can be serialized by extending from the SoarAuditorApi::Serializable class. Store the data in the @data attribute and implement the to_s method that calls the serialize method in the base class.

class TestSerializable < SoarAuditorApi::Serializable
  attr_accessor :data

  def to_s
    serialize
  end
end

Detailed example

require 'soar_auditor_api'
require 'byebug'

class SanityAuditor < SoarAuditorApi::AuditorAPI
  def configuration_is_valid(configuration)
    return configuration.include?("preprefix")
  end

  def audit(data)
    puts @configuration["preprefix"] + data
  end
end

class Main
  def test_sanity
    @iut = SanityAuditor.new
    configuration = { "preprefix" => "very important:" }
    @iut.configure(configuration)
    @iut.set_audit_level(:debug)

    some_debug_object = 123
    @iut.info("This is info")
    @iut.debug(some_debug_object)
    dropped = 95
    @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

main = Main.new
main.test_sanity

Contributing

Bug reports and feature requests are welcome by email to barney dot de dot villiers at hetzner dot co dot za. This gem is sponsored by Hetzner (Pty) Ltd (http://hetzner.co.za)

Notes

Though out of scope for the provider, auditors should take into account encoding, serialization, and other NFRs.

License

The gem is available as open source under the terms of the MIT License.