Proposal: Make Tools Top Level Entities

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

Background Information

It is awkward to define and use Tools in the current version of the schema, especially where multiple Analyses make use of the same tool. In such cases, the Tool must be defined in one Analysis, and when it is used in another Analysis, a reference must be made to its nested definition in the first Analysis.

Proposal

We propose to make Tools top-level entities in the MAEC Package. Tools would then only be referenced (but not defined) from inside Analyses. This would make referencing Tools much more straightforward.

Schema changes would include:

---

Modifying maecPackage:PackageType to have a top-level Tools field:

Field	Type	Multiplicity	Description
Tools	ToolsListType	0-1	The Tools field captures a set of one or more Tools relevant to the Package content.

---

Modifying the Tools field in maecPackage:AnalysisType to allow only tool references (rather than the inline definition of tools), through the use of the maecPackage:ToolReferenceListType:

Field	Type	Multiplicity	Description
Tools	ToolReferenceListType	0-1	The Tools field captures a set references to one or more Tools used in the analysis of a Malware Subject.

---

Accordingly, the ToolReferenceListType would have the following structure:

Field	Type	Multiplicity	Description
Tool_Reference	ToolReferenceType	0-N	The Tool_Reference field specifies a reference to an existing tool found in the MAEC Package document.

Likewise, the ToolReferenceType used in the ToolReferenceListType would have the following structure:

Field	Type	Multiplicity	Description
@tool_idref	xs:QName	0-N	The tool_idref field specifies a reference to an existing tool found in the MAEC document, via its ID.

Example

<Package>
  <Tools>
    <Tool id="tool-1">
      <Name>Some analysis tool</Name>
      <Version>2.3.1</Version>
    </Tool>
  </Tools>
  <Malware_Subjects>
    <Malware_Subject>
      <Analyses>
        <Analysis id="analysis-1">
          <Tools>
            <Tool_Reference tool_idref="tool-1"/>
          </Tools>
        </Analysis>
      </Analysis>
    </Malware_Subject>
  </Malware_Subjects>
</Package>

Impact

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

Requested Feedback

1. Does it make sense to make Tools top-level entities?
2. Are there preferable alternatives for making Tools easier to use?