Skip to content

Proposal: Make Relationships Top Level Entities

Jump to bottom
Desiree Beck edited this page Aug 15, 2015 · 39 revisions

Status: Open
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 them 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.
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 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 the 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.

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>

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