Skip to content

Proposal: Make Relationships Top Level Entities

Jump to bottom
Ivan Kirillov edited this page Sep 8, 2015 · 39 revisions

Status: CLOSED
Comment Period Closes: August 20th, 2015
Affects Backwards Compatibility: Yes
Relevant Issues: https://github.com/MAECProject/schemas/issues/74

Background Information

Currently, relationships in MAEC are unidirectional, which means that a relationship between two entities must be defined separately on each entity (such as on two Malware Subjects), making relationships cumbersome to define and use. To make relationships easier to use, define, and more flexible, we suggest deprecating their current, entity-defined implementation, and instead making them top-level entities.

Related Proposals

This proposal is related to the following proposed changes to the schema: https://github.com/MAECProject/schemas/wiki/Proposal:-Deprecate-MAEC-Bundle-(as-a-concept-and-output-format)

Proposal

We propose to deprecate entity-defined relationships in favor of pairwise (i.e., one-to-one) top-level relationships. Top-level relationships would be easier to use and be more flexible because:

  • Relationships could be expressed between any two identifiable entities, not just between Actions, Behaviors, Capabilities, Malware Subjects, and Objects.
  • Each relationship would capture both the source and target entity.
  • All relationships would reside in the same location in a MAEC document.

The following schema types would be deprecated:

  • maecBundle:BehaviorRelationshipType
  • maecBundle:BehaviorRelationshipListType
  • maecBundle:CapabilityRelationshipType
  • maecBundle:CapabilityObjectiveRelationshipType
  • maecPackage:MalwareSubjectRelationshipType
  • maecPackage:MalwareSubjectRelationshipListType
  • maecPackage:ObjectEquivalenceListType
  • maecPackage:ActionEquivalenceType
  • maecPackage:ActionEquivalenceListType

A new RelationshipType schema type would be defined in the MAEC Package schema with the following fields:

Field Type Multiplicity Description
@id xs:QName 0-1 The id field specifies a unique identifier for the relationship.
@source_id xs:QName 1 The required source_id field specifies a reference to the ID of the entity in the MAEC document that corresponds to the source in the (source->target) relationship.
@target_id xs:QName 1 The required target_id field specifies a reference to the ID of the entity in the MAEC document that corresponds to the target in the (source->target) relationship.
@timestamp xs:dateTime 0-1 The timestamp field specifies a timestamp that states when the relationship was created.
Type cyboxCommon:ControlledVocabularyStringType 1 The Type field specifies the type of relationship being expressed, and may make use of a defined controlled vocabulary when used with the xsi:type extension mechanism. The possible vocabularies for use with this field are the MalwareSubjectRelationshipTypeVocab, CapabilityObjectiveRelationshipTypeVocab, and GeneralRelationshipTypeVocab.
Additional_Metadata maecPackage:RelationshipMetadataType 0-1 The Additional_Metadata field captures any additional metadata that may associated with the Relationship.
Supporting_Reference maecPackage:EntityReferenceType 0-* The Supporting_Reference field references an entity in the MAEC document (e.g., Action or Object) that may support the Relationship.

Note that maecPackage:EntityReferenceType is defined in the MAEC Bundle Deprecation proposal.

A new abstract RelationshipMetadataType would be defined in the MAEC Package schema. Given that this is an abstract type, it is intended for extension by other types (like the RelationshipDistanceMetadataType below) and accordingly has no fields.

Accordingly, a new RelationshipDistanceMetadataType would be defined in the MAEC Package schema, for capturing distance measures between the source and target in a relationship, and is most applicable to Malware Subjects and CybOX Objects. This type would extend the RelationshipMetadataType with the following fields:

Field Type Multiplicity Description
Distance_Score xs:double 1 The required Distance_Score field captures the distance score between the source and target in the relationship. This is most commonly represented as a floating point value between zero and one (with a higher value representing a greater distance between the two), e.g., "0.62".
Algorithm_Name xs:string 0-1 The Algorithm_Name field captures the name of the algorithm used in calculating the distance score specified in the Distance_Score field.
Algorithm_Version xs:string 0-1 The Algorithm_Version field captures the version of the algorithm used in calculating the distance score specified in the Distance_Score field.

Additional extensions of the RelationshipMetadataType, for capturing other types of relationship metadata, may be defined in future versions of MAEC.

A new RelationshipListType schema type would be defined in the MAEC Package schema with the following fields:

Field Type Multiplicity Description
Relationship maecPackage:RelationshipType 0-* The Relationship field captures a single relationship between two entities in the MAEC document.

A new 'Relationships' field, for capturing all relationships in a MAEC document, would be appended to the existing PackageType in the MAEC Package schema:

Field Type Multiplicity Description
Relationships maecPackage:RelationshipListType 0-1 The Relationships field captures the relationships between the entities in the MAEC document.

With Relationships defined as top level entities, the following existing fields would be deprecated:

  • 'Relationships' in the maecBundle:BehaviorType
  • 'Relationship' in the maecBundle:CapabilityType
  • 'Relationships' in the maecPackage:MalwareSubjectType

Furthermore, the following existing vocabularies pertaining to relationships will remain unchanged:

  • CapabilityObjectRelationshipTypeVocab
  • MalwareSubjectRelationshipTypeVocab

In addition, a new GeneralRelationshipTypeVocab vocabulary would be added to the MAEC Default vocabularies schema along with a corresponding GeneralRelationshipTypeEnum enumeration:

Value Description
equivalent The 'equivalent' value specifies that the pair of entities referenced by the source_id and target_id fields in the relationship are equivalent.
has distance The 'has distance' value specifies that the pair of entities referenced by the source_id and target_id fields have some associated distance score, which is captured via the Additional_Metadata field.

Example

Before (with old entity-defined relationships) - MAEC 4.1
<Malware_Subjects>
  <Malware_Subject id="malware-subject-1">
    <Relationships>
      <Relationship>
        <Type xsi:type="maecVocabs:MalwareSubjectRelationshipTypeVocab-1.1">drops</Type>
        <Malware_Subject_Reference malware_subject_idref="malware-subject-2"/>
      </Relationship>
    </Relationships>
  </Malware_Subject>

  <Malware_Subject id="malware-subject-2">
    <Relationships>
      <Relationship>
        <Type xsi:type="maecVocabs:MalwareSubjectRelationshipTypeVocab-1.1">dropped by</Type>
        <Malware_Subject_Reference malware_subject_idref="malware-subject-1"/>
      </Relationship>
    </Relationships>
  </Malware_Subject>
</Malware_Subjects>
After (with top-level relationships) - MAEC 5.0
<Malware_Subjects>
  <Malware_Subject id="malware-subject-1">
   ...
  </Malware_Subject>

  <Malware_Subject id="malware-subject-2">
   ...
  </Malware_Subject>
</Malware_Subjects>

<Relationships>
  <Relationship id="relationship-1" source_id="malware-subject-1" target_id="malware-subject-2" timestamp="2015-05-30T09:00:00">
    <Type xsi:type="maecVocabs:MalwareSubjectRelationshipTypeVocab-1.1">drops</Type>
  </Relationship>
</Relationships>
Capturing distance scores - MAEC 5.0

The following example demonstrates how the new RelationshipType can be used to capture distance scores in conjunction with the RelationshipDistanceMetadataType.

<Malware_Subjects>
  <Malware_Subject id="malware-subject-1">
   ...
  </Malware_Subject>

  <Malware_Subject id="malware-subject-2">
   ...
  </Malware_Subject>
</Malware_Subjects>

<Relationships>
  <Relationship id="relationship-1" source_id="malware-subject-1" target_id="malware-subject-2">
    <Type xsi:type="maecVocabs:GeneralRelationshipTypeVocab-1.0">has distance</Type>
    <Additional_Metadata xsi:type="maecPackage:RelationshipDistanceMetadataType">
      <Distance_Score>0.33</Distance_Score>
      <Algorithm_Name>NCD</Algorithm_Name>
      <Algorithm_Version>1.0</Algorithm_Version>
    </Additional_Metadata>
  </Relationship>
</Relationships>

Impact

This change will not be backward compatible and is one of several revisions planned in new major version.

Requested Feedback

  1. Should Relationships be top-level entities?
  2. Does the outlined set of changes to the MAEC schema to enable relationships to serve as top-level entities make sense?
  3. Do the values in the GeneralRelationshipTypeEnum enumeration make sense? Are there any missing values that should be added?
Clone this wiki locally