Proposal: Make Relationships Top Level Entities

Status: Open
Comment Period Closes:
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 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 be bidirectional, capturing 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
• maecPackage:GroupingRelationshipType (renamed, not actually deprecated)
• maecPackage:GroupingRelationshipListType

---

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	0-1	The 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. This field should only be used for pairwise relationships, that is, when the scope field is set to a value of "pairwise".
@target_id	xs:QName	0-1	The target field specifies a reference to the ID of the entity in the MAEC document that corresponds to the target in the (source->target) relationship. This field should only be used for pairwise relationships, that is, when the scope field is set to a value of "pairwise".
@timestamp	xs:dateTime	0-1	The timestamp field specifies a timestamp that states when the relationship was created.
@scope	maecPackage:RelationshipScopeEnum	1	The required scope field specifies the scope of the relationship, in terms of whether it is a pairwise relationship (i.e. just between the two entities specified in the source_id and target_id fields) or global (i.e. between all entities in the MAEC document). The default value for this field is "pairwise".
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, GroupingRelationshipTypeVocab, and GeneralRelationshipTypeVocab.
Supporting_Information	maecPackage:RelationshipSupportingInformationType	0-1	The Supporting_Information field captures any supporting information relevant to the relationship, including information specific to global (grouping) relationships.

---

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

Field	Type	Multiplicity	Description
Grouping_Relationship_Information	maecPackage:GroupingRelationshipInformationType	0-1	The Grouping_Relationship_Information field captures information specific to global/grouping relationships.
Supporting_Reference	maecPackage:EntityReferenceType	0-*	The Supporting_Reference field references an entity in the MAEC document that may support the relationship, such as an Action or Object.

---

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 or more 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.

---

The existing maecPackage:GroupingRelationshipType would be renamed to maecPackage:GroupingRelationshipInformationType and its Type field would be deprecated.

---

Accordingly, the following existing fields would be deprecated:

• Relationships in the maecBundle:BehaviorType
• Relationship in the maecBundle:CapabilityType
• Relationships in the maecPackage:MalwareSubjectType
• Grouping_Relationships in the maecPackage:PackageType
• Type in the maecPackage:GroupingRelationshipType (which will be renamed to maecPackage:GroupingRelationshipInformationType)

---

With regards to enumerations and vocabularies, a new 'GeneralRelationshipTypeEnum' enumeration and corresponding vocabulary type, GeneralRelationshipTypeVocab-1.0, would be added to the MAEC Default vocabularies schema with the following values:

Value	Description
equivalent	The 'equivalent' value specifies that the entities referenced by the source_id and target_id fields in the relationship are equivalent. Note that this relationship is only valid for pairwise instances.

Also, the new 'RelationshipScopeEnum' enumeration would have the following values:

Value	Description
pairwise	The 'pairwise' value specifies that the relationship is between a pair of entities in the MAEC document, defined by the source_id and target_id fields.
malware subjects	The 'malware subjects' value specifies that the relationship is global and between ALL Malware Subjects in the document.
objects	The 'objects' value specifies that the relationship is global and between ALL CybOX Objects in the document.
actions	The 'actions' value specifies that the relationship is global and between ALL Actions in the document.
behaviors	The 'behaviors' value specifies that the relationship is global and between ALL Behaviors in the document.

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

• CapabilityObjectRelationshipTypeVocab
• GroupingRelationshipTypeVocab
• MalwareSubjectRelationshipTypeVocab

Example

Before (with old entity-defined relationships) - MAEC 4.1

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

After (with top-level relationships) - MAEC 5.0

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

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

<Relationships>
  <Relationship id="relationship-1" scope="pairwise" 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 and RelationshipScopeEnum make sense? Are there any missing values that should be added to these enumerations?