unified2 0.1.1

data/gemspec.yml

@@ -0,0 +1,14 @@
+name: unified2
+summary: "A ruby interface for unified2 output."
+description: "A ruby interface for unified2 output. rUnified2 allows you to manipulate unified2 output for custom storage and/or analysis."
+license: MIT
+authors: Dustin Willis Webber
+email: dustin.webber@gmail.com
+homepage: https://github.com/mephux/unified2
+
+development_dependencies:
+  bindata: ~> 1.3.1
+  hexdump: ~> 0.1.0
+  ore-tasks: ~> 0.4
+  rspec: ~> 2.4
+  yard: ~> 0.6.0

data/lib/unified2/classification.rb

@@ -0,0 +1,14 @@
+module Unified2
+  class Classification
+
+    attr_accessor :id, :name, :short, :priority
+
+    def initialize(classification={})
+      @id = classification[:classification_id]
+      @name = classification[:name]
+      @short = classification[:short]
+      @priority = classification[:priority]
+    end
+
+  end
+end

data/lib/unified2/construct.rb

@@ -0,0 +1,54 @@
+require 'unified2/event_ip4'
+require 'unified2/event_ip6'
+require 'unified2/record_header'
+require 'unified2/packet'
+
+module Unified2
+  
+  class Construct < ::BinData::Record
+    record_header :header
+    
+    choice :data, :selection => :type_selection do
+      packet "packet"
+      event_ip4  "ev4"
+      event_ip6 "ev6"
+    end
+
+    # padding
+    string :read_length => :padding_length
+
+    def type_selection
+      case header.u2type.to_i
+      when 1
+        # define UNIFIED2_EVENT 1
+      when 2
+        # define UNIFIED2_PACKET 2
+        "packet"
+      when 7
+        # define UNIFIED2_IDS_EVENT 7
+        "ev4"
+      when 66
+        # define UNIFIED2_EVENT_EXTENDED 66
+      when 67
+        # define UNIFIED2_PERFORMANCE 67
+      when 68
+        # define UNIFIED2_PORTSCAN 68
+      when 72
+        # define UNIFIED2_IDS_EVENT_IPV6 72
+        "ev6"
+      else
+        "unknown type #{header.u2type}"
+      end
+    end
+
+    # sometimes the data needs extra padding
+    def padding_length
+      if header.u2length > data.num_bytes
+        header.u2length - data.num_bytes
+      else
+        0
+      end
+    end
+  end
+  
+end

data/lib/unified2/core_ext/string.rb

@@ -0,0 +1,8 @@
+class String
+  
+  def blank?
+    return true if (self.nil? || self == '')
+    false
+  end
+  
+end

data/lib/unified2/core_ext.rb

@@ -0,0 +1 @@
+require 'unified2/core_ext/string'

data/lib/unified2/event.rb

@@ -0,0 +1,315 @@
+require 'ipaddr'
+require 'json'
+require 'unified2/classification'
+require 'unified2/payload'
+require 'unified2/sensor'
+require 'unified2/signature'
+
+module Unified2
+
+  class Event
+
+    attr_accessor :id, :metadata, :packet
+
+    def initialize(id)
+      @id = id
+    end
+
+    def packet_time
+      if @packet.has_key?(:packet_second)
+        @packet[:packet_second]
+        @timestamp = Time.at(@packet[:packet_second].to_i)
+      end
+    end
+
+    def event_time
+      if @packet.has_key?(:event_second)
+        @timestamp = Time.at(@packet[:event_second].to_i)
+      end
+    end
+    alias :timestamp :event_time
+
+    def microseconds
+      if @metadata.has_key?(:event_microsecond)
+        @microseconds = @metadata[:event_microsecond]
+      end
+    end
+
+    def sensor
+      @sensor ||= Unified2.sensor
+    end
+
+    def packet_action
+      if @metadata.has_key?(:event_second)
+        @packet_action = @metadata[:packet_action]
+      end
+    end
+
+    def protocol
+      if @metadata.has_key?(:protocol)
+        @protocol = determine_protocol(@metadata[:protocol])
+      end
+    end
+
+    def icmp?
+      return true if protocol == :ICMP
+      false
+    end
+
+    def tcp?
+      return true if protocol == :TCP
+      false
+    end
+
+    def udp?
+      return true if protocol == :UDP
+      false
+    end
+
+    def classification
+      if @metadata.is_a?(Hash)
+        @classification = Classification.new(@metadata[:classification]) if @metadata[:classification]
+      end
+    end
+
+    def signature
+      if @metadata.is_a?(Hash)
+        @signature = Signature.new(@metadata[:signature])
+      end
+    end
+
+    def generator_id
+      if @metadata.is_a?(Hash)
+        @metadata[:generator_id] if @metadata.has_key?(:generator_id)
+      end
+    end
+
+    def ip_source
+      if @metadata.is_a?(Hash)
+        @metadata[:ip_source] if @metadata.has_key?(:ip_source)
+      end
+    end
+    alias :source_ip :ip_source
+
+    # Add ICMP type
+    def source_port
+      return 0 if icmp?
+      @source_port = @metadata[:sport_itype] if @metadata.has_key?(:sport_itype)
+    end
+
+    def ip_destination
+      if @metadata.is_a?(Hash)
+        @metadata[:ip_destination] if @metadata.has_key?(:ip_destination)
+      end
+    end
+    alias :destination_ip :ip_destination
+
+    # Add ICMP code
+    def destination_port
+      return 0 if icmp?
+      @source_port = @metadata[:dport_icode] if @metadata.has_key?(:dport_icode)
+    end
+
+    def severity
+      @severity = @metadata[:priority_id] if @metadata.has_key?(:priority_id)
+    end
+
+    def payload
+      if @packet.is_a?(Hash)
+        Payload.new(@packet)
+      else
+        Payload.new
+      end
+    end
+
+    def load(event)
+      if event.data.respond_to?(:signature_id)
+        @metadata ||= build_event_metadata(event)
+      end
+
+      if event.data.respond_to?(:packet_data)
+        @packet ||= build_packet_metadata(event)
+      end
+    end
+
+    def to_h
+      if @metadata.is_a?(Hash)
+        if @packet.is_a?(Hash)
+          data = {}
+          data.merge!(@metadata)
+          data.merge!(@packet)
+          return data
+        end
+      else
+        if @packet.is_a?(Hash)
+          return @packet
+        end
+      end
+    end
+
+    def to_i
+      @id.to_i
+    end
+
+    def json
+      to_h.to_json
+    end
+
+    def to_s
+data = %{
+#############################################################################
+Event ID: #{id}
+Timestamp: #{timestamp}
+Severity: #{severity}
+Protocol: #{protocol}
+Source IP: #{source_ip}:#{source_port}
+Destination IP: #{destination_ip}:#{destination_port}
+Signature: #{signature.name}
+Payload:
+
+}
+      if payload.blank?
+        data + '#############################################################################'
+      else
+        payload.dump(:width => 30, :output => data)
+        data + "#############################################################################"
+      end
+    end
+
+    private
+
+      def build_event_metadata(event)
+        @event_hash = {}
+
+        @event_hash = {
+          :ip_destination => event.data.ip_destination,
+          :priority_id => event.data.priority_id,
+          :signature_revision => event.data.signature_revision,
+          :event_id => event.data.event_id,
+          :protocol => event.data.protocol,
+          :sport_itype => event.data.sport_itype,
+          :event_second => event.data.event_second,
+          :packet_action => event.data.packet_action,
+          :dport_icode => event.data.dport_icode,
+          :sensor_id => event.data.sensor_id,
+          :generator_id => event.data.generator_id,
+          :ip_source => event.data.ip_source,
+          :event_microsecond => event.data.event_microsecond
+        }
+
+        build_classifications(event)
+
+        if event.data.generator_id.to_i == 1
+          build_signature(event)
+        else
+          build_generator(event)
+        end
+
+        @event_hash
+      end
+
+      def build_packet_metadata(event)
+        @packet_hash = {}
+        @packet_hash = {
+          :linktype => event.data.linktype,
+          :packet_microsecond => event.data.packet_microsecond,
+          :packet_second => event.data.packet_second,
+          :payload => event.data.packet_data,
+          :event_second => event.data.event_second,
+          :packet_length => event.data.packet_length
+        }
+
+        @packet_hash
+      end
+
+      def build_generator(event)
+        if Unified2.generators
+          if Unified2.generators.has_key?("#{event.data.generator_id}.#{event.data.signature_id}")
+            sig = Unified2.generators["#{event.data.generator_id}.#{event.data.signature_id}"]
+
+            @event_hash[:signature] = {
+              :signature_id => event.data.signature_id,
+              :revision => event.data.signature_revision,
+              :name => sig[:name],
+              :references => sig[:references],
+              :blank => false
+            }
+          end
+        end
+
+        unless @event_hash.has_key?(:signature)
+          @event_hash[:signature] = {
+            :signature_id => event.data.signature_id,
+            :revision => 0,
+            :name => "Unknown Signature #{event.data.signature_id}",
+            :references => [],
+            :blank => true
+          }
+        end
+      end
+
+      def build_signature(event)
+        if Unified2.signatures
+          if Unified2.signatures.has_key?(event.data.signature_id.to_s)
+            sig = Unified2.signatures[event.data.signature_id.to_s]
+
+            @event_hash[:signature] = {
+              :signature_id => event.data.signature_id,
+              :revision => event.data.signature_revision,
+              :name => sig[:name],
+              :references => sig[:references]
+            }
+          end
+        end
+
+        unless @event_hash.has_key?(:signature)
+          @event_hash[:signature] = {
+            :signature_id => event.data.signature_id,
+            :revision => 0,
+            :name => "Unknown Signature #{event.data.signature_id}",
+            :references => []
+          }
+        end
+      end
+
+      def build_classifications(event)
+        if Unified2.classifications
+          if Unified2.classifications.has_key?("#{event.data.classification_id}")
+            classification = Unified2.classifications["#{event.data.classification_id}"]
+
+            @event_hash[:classification] = {
+              :classification_id => event.data.classification_id,
+              :name => classification[:name],
+              :short => classification[:short],
+              :priority => classification[:priority]
+            }
+          end
+        end
+
+        unless @event_hash.has_key?(:classification)
+          @event_hash[:classification] = {
+            :classification_id => event.data.classification_id,
+            :name => 'Unknown',
+            :short => 'n/a',
+            :priority => 0
+          }
+        end
+      end
+
+      def determine_protocol(protocol)
+        case protocol.to_i
+        when 1
+          :ICMP # ICMP (Internet Control Message Protocol) packet type.
+        when 2
+          :IGMP # IGMP (Internet Group Message Protocol) packet type.
+        when 6
+          :TCP # TCP (Transmition Control Protocol) packet type.
+        when 17
+          :UDP # UDP (User Datagram Protocol) packet type.
+        else
+          :'N/A'
+        end
+      end
+
+  end
+end

data/lib/unified2/event_ip4.rb

@@ -0,0 +1,26 @@
+require 'unified2/primitive/ipv4'
+
+module Unified2
+  
+  class EventIP4 < ::BinData::Record
+    
+    endian :big
+
+    uint32    :sensor_id
+    uint32    :event_id
+    uint32    :event_second
+    uint32    :event_microsecond
+    uint32    :signature_id
+    uint32    :generator_id
+    uint32    :signature_revision
+    uint32    :classification_id
+    uint32    :priority_id
+    ipv4      :ip_source
+    ipv4      :ip_destination
+    uint16    :sport_itype
+    uint16    :dport_icode
+    uint8     :protocol
+    uint8     :packet_action
+  end
+
+end

data/lib/unified2/event_ip6.rb

@@ -0,0 +1,23 @@
+module Unified2
+  
+  class EventIP6 < ::BinData::Record
+    endian :big
+
+    uint32    :sensor_id
+    uint32    :event_id
+    uint32    :event_second
+    uint32    :event_microsecond
+    uint32    :signature_id
+    uint32    :generator_id
+    uint32    :signature_revision
+    uint32    :classification_id
+    uint32    :priority_id
+    uint128   :ip_source
+    uint128   :ip_destination
+    uint16    :sport_itype
+    uint16    :dport_icode
+    uint8     :protocol
+    uint8     :packet_action
+  end
+  
+end

data/lib/unified2/exceptions/file_not_found.rb

@@ -0,0 +1,4 @@
+module Unified2
+  class FileNotFound < StandardError
+  end
+end

data/lib/unified2/exceptions/file_not_readable.rb

@@ -0,0 +1,4 @@
+module Unified2
+  class FileNotReadable < StandardError
+  end
+end

data/lib/unified2/exceptions/unknown_load_type.rb

@@ -0,0 +1,4 @@
+module Unified2
+  class UnknownLoadType < StandardError
+  end
+end

data/lib/unified2/exceptions.rb

@@ -0,0 +1,2 @@
+require 'unified2/exceptions/file_not_found'
+require 'unified2/exceptions/file_not_readable'

data/lib/unified2/packet.rb

@@ -0,0 +1,16 @@
+module Unified2
+  
+  class Packet < ::BinData::Record
+    endian :big
+
+    uint32 :sensor_id
+    uint32 :event_id
+    uint32 :event_second
+    uint32 :packet_second
+    uint32 :packet_microsecond
+    uint32 :linktype
+    uint32 :packet_length
+    string :packet_data, :read_length => :packet_length
+  end
+  
+end

data/lib/unified2/payload.rb

@@ -0,0 +1,32 @@
+require 'hexdump'
+
+module Unified2
+  class Payload
+    
+    attr_accessor :linktype, :length
+    
+    def initialize(payload={})
+      @payload = payload[:payload]
+      @length = payload[:packet_length].to_i
+      @linktype = payload[:linktype]
+    end
+
+    def blank?
+      return true unless @payload
+      false
+    end
+
+    def raw
+      @payload.to_s
+    end
+    
+    def hex
+      @payload.to_s.unpack('H*')
+    end
+
+    def dump(options={})
+      Hexdump.dump(@payload, options)
+    end
+
+  end
+end

data/lib/unified2/primitive/ipv4.rb

@@ -0,0 +1,19 @@
+module Unified2
+  module Primitive
+    
+    class IPV4 < ::BinData::Primitive
+      array :octets, :type => :uint8, :initial_length => 4
+
+      def set(val)
+        ints = val.split(/\./).collect { |int| int.to_i }
+        self.octets = ints
+      end
+
+      def get
+        self.octets.collect { |octet| "%d" % octet }.join(".")
+      end
+
+    end
+    
+  end
+end

data/lib/unified2/primitive.rb

@@ -0,0 +1 @@
+require 'primitive/ipv4'

data/lib/unified2/record_header.rb

@@ -0,0 +1,10 @@
+module Unified2
+  
+  class RecordHeader < ::BinData::Record
+    endian :big
+
+    uint32 :u2type
+    uint32 :u2length
+  end
+  
+end

data/lib/unified2/sensor.rb

@@ -0,0 +1,26 @@
+module Unified2
+  class Sensor
+    
+    attr_accessor :id, :hostname, 
+    :interface, :name
+    
+    def initialize(options={})
+      @id = options[:id] || 0
+      @name = options[:name] || ""
+      @hostname ||= Socket.gethostname
+      @interface ||= options[:interface] || nil
+    end
+    
+    def update(attributes={})
+      return self if attributes.empty?
+      
+      attributes.each do |key, value|
+        next unless self.respond_to?(key.to_sym)
+        instance_variable_set(:"@#{key}", value)
+      end
+      
+      self
+    end
+    
+  end
+end

data/lib/unified2/signature.rb

@@ -0,0 +1,24 @@
+module Unified2
+
+  class Signature
+
+    attr_accessor :id, :revision, :name, :references
+
+    def initialize(signature={})
+      @id = signature[:signature_id] || 0
+      @revision = signature[:revision]
+      @name = signature[:name].strip
+      @references = signature[:references]
+      @blank = signature[:blank]
+    end
+
+    def blank?
+      @blank
+    end
+
+    def references
+      @references
+    end
+
+  end
+end

data/lib/unified2/version.rb

@@ -0,0 +1,4 @@
+module Unified2
+  # unified2 version
+  VERSION = "0.1.1"
+end