opentpx 2.2.0.17

data/lib/tpx/2_2/heterogeneous_list.rb

@@ -0,0 +1,136 @@
+  require 'tpx/2_2/exceptions'
+
+module TPX_2_2
+  # A list (Array) whose elements are not all the same type or do not have the same id attribute.
+  # The HeterogenousList defines an array of [ChildClass, child_id_attribute_name] as the accepted :child_types.
+  class HeterogeneousList < Array
+    include Enumerable
+
+    class << self
+      # The types of objects and their id attribute names accepted by the HeterogeneousList.
+      # An Array of Arrays like [[ChildClass, child_id_attribute], [AnotherChildClass, another_child_id_attribute]].
+      attr_accessor :child_types
+
+      # Defines the child class types that the list accepts.  Another accessor for `child_types`.
+      #
+      # @param [Array] child_class_id_array The list of [Class, id_atttribute_name] to accept as list members.
+      def children_of_class_and_id(child_class_id_array)
+        self.child_types = child_class_id_array
+      end
+    end
+
+    # Hash lookup accessor to list members.
+    # Hash of hashes like child_id_of[ChildClass][child_id_val] = child
+    attr_accessor :child_id_of
+
+    # Initialize a new HeterogeneousList from an Array.
+    #
+    # @param [Array] input_array The Array of HeterogeneousList.child_types included classes (or Hash to be initialized as HeterogeneousList.child_type classes) to create the HeterogeneousList object from.
+    def initialize(input_array)
+      unless input_array.is_a? Array
+        raise ValidationError, "Supplied parameter (#{input_array.inspect}) to #{self.class}#initialize should be of type Array!"
+      end
+
+      @child_id_of = {}
+      validated_array = []
+
+      input_array.each_with_index do |child, i|
+        validate_expected_child_type(child, i)
+        new_initialized_child = nil
+        new_initialized_child_type = nil
+
+        self.class.child_types.each do |child_type|
+          if child.class == child_type[0] && child.has_key?(child_type[1])
+            new_initialized_child = child
+            new_initialized_child_type = child_type
+            break
+          elsif child.has_key?(child_type[1])
+            new_initialized_child = child_type[0].new(child)
+            new_initialized_child_type = child_type
+            break
+          end
+        end
+
+        if new_initialized_child
+          validate_unique(new_initialized_child, new_initialized_child_type)
+          child_id_of[new_initialized_child_type[0]] ||= {}
+          child_id_of[new_initialized_child_type[0]][new_initialized_child[new_initialized_child_type[1]]] = new_initialized_child
+          validated_array << new_initialized_child
+        end
+      end
+
+      super validated_array
+    end
+
+    # Add a new child to the HeterogeneousList (push).
+    #
+    # @param [Hash or HeterogeneousList.type] child The object to add to the HeterogeneousList.
+    def <<(child)
+      child_type = validate_expected_child_type(child)
+      validate_unique(child, child_type)
+      child_id_of[child_type[0]] ||= {}
+      child_id_of[child_type[0]][child[child_type[1]]] = child
+      super child
+    end
+
+    # Validate that a child is of the proper type to add to the HeterogeneousList.
+    #
+    # @param [Hash or one of HeterogeneousList.child_types] child The object to verify is one of HeterogeneousList.child_types.
+    # @param [Integer] i The position, if any, in the list of the object to verify is one of HeterogeneousList.child_types.
+    def validate_expected_child_type(child, i=nil)
+      if child.class == Hash || child.class == HashWithIndifferentAccess
+        validate_expected_child_type_from_hash(child, i)
+      else
+        validate_expected_child_type_from_initialized_object(child, i)
+      end
+    end
+
+    # Validate that a child is of the proper type to add to the HeterogeneousList.
+    #
+    # @param [Hash] child The object to verify is one of HeterogeneousList.child_types.
+    # @param [Integer] i The position, if any, in the list of the object to verify is one of HeterogeneousList.child_types.
+    def validate_expected_child_type_from_hash(child, i=nil)
+      child_type_key_count = 0
+      child_type_found = nil
+      self.class.child_types.each do |child_type|
+        if child.has_key?(child_type[1])
+          child_type_key_count += 1
+          child_type_found = child_type
+        end
+      end
+      if child_type_key_count > 1
+        raise ValidationError, "Supplied input object #{child.inspect}#{pos_msg} has multiple subject types in #{self.class}!"
+      elsif child_type_key_count == 0
+        raise ValidationError, "Supplied input object #{child.inspect}#{pos_msg(i)} not one of required types #{self.class.child_types} in #{self.class}!"
+      end
+      return child_type_found
+    end
+
+    # Validate that a child is of the proper type to add to the HeterogeneousList.
+    #
+    # @param [one of HeterogeneousList.child_types] child The object to verify is one of HeterogeneousList.child_types.
+    # @param [Integer] i The position, if any, in the list of the object to verify is one of HeterogeneousList.child_types.
+    def validate_expected_child_type_from_initialized_object(child, i=nil)
+      self.class.child_types.each do |child_type|
+        if child.class == child_type[0] && child.has_key?(child_type[1])
+          return child_type
+        end
+      end
+      raise ValidationError, "Supplied input object #{child.inspect}#{pos_msg(i)} not one of required types #{self.class.child_types} in #{self.class}!"
+    end
+
+    def pos_msg(i)
+      pos_msg = i.nil? ? '' : " at position #{i}"
+    end
+
+    # Validate that a child is not contained in the list prior to adding to the HeterogeneousList.
+    #
+    # @param [Hash or HeterogeneousList.type] child The object to verify is not already contained in HeterogeneousList.
+    def validate_unique(child, child_type)
+      if child_id_of.has_key?(child_type[0]) and child_id_of[child_type[0]].has_key?(child[child_type[1]])
+        raise TPX_2_2::DuplicateElementInsertError, "Duplicate input object id #{child[child_type[1]]} provided to #{self.class}!"
+      end
+    end
+
+  end
+end

data/lib/tpx/2_2/homogeneous_list.rb

@@ -0,0 +1,82 @@
+require 'tpx/2_2/exceptions'
+
+module TPX_2_2
+  # A list (Array) whose elements are all the same type and have the same id attribute (HomogeneousList.child_id).
+  class HomogeneousList < Array
+    include Enumerable
+
+    class << self
+      # The child class type accepted.
+      attr_accessor :type
+      # The id attribute name of the children objects.
+      attr_accessor :child_id
+
+      # Defines the child class that the list accepts.
+      #
+      # @param [Class] klass The Class to accept as list members.
+      def homogeneous_list_of(klass)
+        self.type = klass
+      end
+
+      # Defines the child class id attribute name.
+      #
+      # @param [Symbol] child_id The id field of list members.
+      def children_keyed_by(child_id)
+        self.child_id = child_id
+      end
+    end
+
+    # Hash lookup accessor to list members.
+    # Hash of hashes like child_id_of[ChildClass][child_id_val] = child
+    attr_accessor :child_id_of
+
+    # Initialize a new HomogeneousList from an Array.
+    #
+    # @param [Array] input_array The Array of HomogeneousList.type classes (or Hash to be initialized as HomogeneousList.type classes) to create the HomogeneousList object from.
+    def initialize(input_array)
+      unless input_array.is_a? Array
+        raise ValidationError, "Supplied parameter (#{input_array.inspect}) to #{self.class}#initialize should be of type Array!"
+      end
+      @child_id_of = {}
+      input_array.each_with_index do |child, i|
+        if child.class == Hash || child.class == HashWithIndifferentAccess
+          child = self.class.type.new(child)
+        end
+        validate_homogeneous_type_of(child, i)
+        validate_unique(child)
+        @child_id_of[child[self.class.child_id]] = child
+      end
+      super input_array
+    end
+
+    # Add a new child to the HomogeneousList (push).
+    #
+    # @param [Hash or HomogeneousList.type] child The object to add to the HomogeneousList.
+    def <<(child)
+      validate_homogeneous_type_of(child)
+      validate_unique(child)
+      @child_id_of[child[self.class.child_id]] = child
+      super child
+    end
+
+    # Validate that a child is of the proper type to add to the HomogeneousList.
+    #
+    # @param [Hash or HomogeneousList.type] child The object to verify is one of HomogeneousList.type.
+    # @param [Integer] i The position, if any, in the list of the object to verify is one of HomogeneousList.type.
+    def validate_homogeneous_type_of(child, i=nil)
+      unless child.is_a? self.class.type
+        pos_msg = i.nil? ? '' : " at position #{i}"
+        raise ValidationError, "Supplied input object #{child.inspect}#{pos_msg} not of required type #{self.class.type} in #{self.class}!"
+      end
+    end
+
+    # Validate that a child is not contained in the list prior to adding to the HomogeneousList.
+    #
+    # @param [Hash or HomogeneousList.type] child The object to verify is not already contained in HomogeneousList.
+    def validate_unique(child)
+      if @child_id_of.has_key?(child[self.class.child_id])
+        raise TPX_2_2::DuplicateElementInsertError, "Duplicate input object id #{child[self.class.child_id]} provided to #{self.class}!"
+      end
+    end
+  end
+end

data/lib/tpx/2_2/mandatory_attributes.rb

@@ -0,0 +1,69 @@
+module TPX_2_2
+  module MandatoryAttributes
+    MANDATORY_ATTRIBUTES = [] # override in consumer
+    MUST_HAVE_ONE_OF_ATTRIBUTES = []
+    MUST_HAVE_ONE_AND_ONLY_ONE_OF_ATTRIBUTES = []
+
+    # Perform all validations.
+    def validate!
+      validate_mandatory_attributes!
+
+      validate_must_have_one_of_attributes!
+
+      validate_must_have_one_and_only_one_of_attributes!
+    end # def validate!
+
+    # Perform validation of all mandatory attributes.
+    def validate_mandatory_attributes!
+      self.class::MANDATORY_ATTRIBUTES.each do |attrib|
+        if self[attrib].nil?
+          raise ValidationError, "The mandatory attribute `#{attrib}` is missing from the supplied input_hash paramater to #{self.class}."
+        end
+      end
+    end
+
+    # Perform validation of all sets of attributes of which at least one are required.
+    def validate_must_have_one_of_attributes!
+      self.class::MUST_HAVE_ONE_OF_ATTRIBUTES.each do |attrib_set|
+        unless attrib_set.is_a? Array
+          raise AttributeDefinitionError, "Elements of #{self.class}::MUST_HAVE_ONE_OF_ATTRIBUTES must be of type Array."
+        end
+
+        has_one_of_mandatory_set = false
+        attrib_set.each do |attrib|
+          if self.has_key?(attrib) && !self[attrib].nil?
+            has_one_of_mandatory_set = true
+            break
+          end
+        end
+
+        unless has_one_of_mandatory_set
+          raise ValidationError, "A member of the mandatory attribute set `#{attrib_set}` is missing from the supplied input_hash paramater to #{self.class}."
+        end
+      end
+    end
+
+    # Perform validation of all sets of attributes of which only one is required.
+    def validate_must_have_one_and_only_one_of_attributes!
+      self.class::MUST_HAVE_ONE_AND_ONLY_ONE_OF_ATTRIBUTES.each do |attrib_set|
+        unless attrib_set.is_a? Array
+          raise AttributeDefinitionError, "Elements of #{self.class}::MUST_HAVE_ONE_AND_ONLY_ONE_OF_ATTRIBUTES must be of type Array."
+        end
+
+        count_of_mandatory_set = 0
+        attrib_set.each do |attrib|
+          if self.has_key?(attrib)
+            count_of_mandatory_set += 1
+          end
+        end
+
+        if count_of_mandatory_set == 0
+          raise ValidationError, "A member of the mandatory attribute set `#{attrib_set}` is missing from the supplied input_hash paramater to #{self.class}."
+        elsif count_of_mandatory_set > 1
+          raise ValidationError, "More than one member of the exclusive and mandatory attribute set `#{attrib_set}` was provided to #{self.class}."
+        end
+      end
+    end
+
+  end
+end

data/lib/tpx/2_2/merging_heterogeneous_list.rb

@@ -0,0 +1,36 @@
+require 'tpx/2_2/heterogeneous_list'
+
+module TPX_2_2
+  # A list (Array) whose elements are not all the same type or do not have the same id attribute
+  #   and who merges certain attributes on duplicate object insert.
+  # The MergingHeterogenousList defines an array of [ChildClass, child_id_attribute_name] as the accepted :child_types.
+  class MergingHeterogeneousList < HeterogeneousList
+
+    class << self
+      # This list of attributes to merge on duplicate object id insert.
+      attr_accessor :attributes_to_merge
+
+      def on_duplicate_addition_merge_attributes(attributes)
+        self.attributes_to_merge = attributes
+      end
+    end
+
+    # Add a new child to the MergingHeterogenousList (push). Merge `attributes_to_merge` on a duplicate child id insert.
+    #
+    # @param [Hash or MergingHeterogenousList.type] child The object to add to the MergingHeterogenousList.
+    def <<(child)
+      child_type = validate_expected_child_type(child)
+      if child_id_of.has_key?(child_type[0]) && child_id_of[child_type[0]].has_key?(child[child_type[1]])
+        self.class.attributes_to_merge.each do |attribute|
+          child_id_of[child_type[0]][child[child_type[1]]][attribute].merge!(child[attribute])
+        end
+      else
+        child_id_of[child_type[0]] ||= {}
+        child_id_of[child_type[0]][child[child_type[1]]] = child
+        meth = Array.instance_method(:<<)
+        meth.bind(self).call(child)
+      end
+    end
+
+  end
+end

data/lib/tpx/2_2/merging_homogeneous_list.rb

@@ -0,0 +1,37 @@
+module TPX_2_2
+  # A list (Array) whose elements are all the same type and have the same id attribute
+  #   (MergingHomogeneousList.child_id) and who merges certain attributes on duplicate object insert.
+  class MergingHomogeneousList < HomogeneousList
+
+    class << self
+      # This list of attributes to merge on duplicate object id insert.
+      attr_accessor :attributes_to_merge
+
+      # Defines the child attribute names that the list will merge when an object of the same id as an existing list member is inserted.
+      # Another accessor for `attributes_to_merge`.
+      #
+      # @param [Array] attributes The list of attribute names to merge.
+      def on_duplicate_addition_merge_attributes(attributes)
+        self.attributes_to_merge = attributes
+      end
+    end
+
+    # Add a new child to the MergingHomogeneousList (push). Merge `attributes_to_merge` on a duplicate child id insert.
+    #
+    # @param [Hash or MergingHomogeneousList.type] child The object to add to the MergingHomogeneousList.
+    def <<(child)
+      unless child.is_a?(self.class.type) && child.has_key?(self.class.child_id)
+        raise TPX_2_2::ValidationError, "Element provided to #{self.class}#<< must be #{self.class.type} with key `#{self.class.child_id}`."
+      end
+      element = self.find {|e| e[self.class.child_id] == child[self.class.child_id] }
+      if element.nil?
+        super
+      else
+        self.class.attributes_to_merge.each do |attribute|
+          element[attribute].merge!(child[attribute])
+        end
+      end
+    end
+
+  end
+end

data/lib/tpx/2_2/network.rb

@@ -0,0 +1,23 @@
+require 'tpx/2_2/data_model'
+
+module TPX_2_2
+
+  # A set of defined network membership, routing topology, ownership, and network announcements.
+  class Network < DataModel
+    MANDATORY_ATTRIBUTES = [
+      :occurred_at_t,
+      :asn_number_ui # TODO: Add to specification document
+    ]
+
+    # Overrides the default initialize to add a default occurred_at_t.
+    #
+    # @param [Hash] input_hash The input hash.
+    #
+    # @return [DataModel] The returned object.
+    def initialize(input_hash)
+      input_hash[:occurred_at_t] ||= Time.now.getutc.to_i  # TODO: Should we do this here?  Should we do this everywhere except ThreatObservable?
+      super input_hash
+    end
+
+  end
+end

data/lib/tpx/2_2/network_list.rb

@@ -0,0 +1,11 @@
+require 'tpx/2_2/homogeneous_list'
+require 'tpx/2_2/network'
+
+module TPX_2_2
+
+  # A list of network objects.
+  class NetworkList < HomogeneousList
+    homogeneous_list_of Network
+    children_keyed_by :asn_number_ui
+  end
+end

data/lib/tpx/2_2/observable.rb

@@ -0,0 +1,13 @@
+require 'tpx/2_2/data_model'
+
+module TPX_2_2
+
+  # A name associated with a measurement of risk including a
+  # description of the risk and one or more classifications
+  # associated with one or more network elements
+  class Observable < DataModel
+    MANDATORY_ATTRIBUTES = [
+      :observable_id_s
+    ]
+  end
+end

data/lib/tpx/2_2/observable_attribute_map.rb

@@ -0,0 +1,12 @@
+require 'tpx/2_2/data_model'
+
+module TPX_2_2
+
+  # An map of attributes associated with the observable
+  # that are common across all subjects
+  class ObservableAttributeMap < DataModel
+    MANDATORY_ATTRIBUTES = [
+      :occurred_at_t
+    ]
+  end
+end

data/lib/tpx/2_2/observable_definition.rb

@@ -0,0 +1,15 @@
+require 'tpx/2_2/data_model'
+require 'tpx/2_2/observable_attribute_map'
+require 'tpx/2_2/classification_element_list'
+
+module TPX_2_2
+
+  # The definition of an observable.
+  class ObservableDefinition < DataModel
+    MANDATORY_ATTRIBUTES = [
+      :observable_id_s, # TODO: Clarify handling of file hash in specification document
+      :description_s,
+      :classification_c_array,
+    ]
+  end
+end