I agree with Allan â so I would add this to the proposal as part of the pull request.
From: aa tt <email@example.com>
Date: Monday, May 10, 2021 at 8:56 PM
To: Rich Piazza <firstname.lastname@example.org>
Subject: Re: [EXT] [cti] Proposal for Housing Extension Definitions
Its kinda important.
Imagine if the consumer of the extension wanted to reach out and discuss technical issues with the extension reps. Or help contribute something more to it.
Knowing the source of an extension by publishing the content of the identity object helps that. The ID only really helps if you already know which org or entity that represents or have it already in your database. But many wonât have that.
Yes. I think including the Identity object of the extension contributor in the pull request is a good idea.
As far as including all identities in the common object repository â I have to give that more thought.
Btw - the identity object (the one defined/referenced by the extension) should be included in the repo somewhere/somehow. Maybe a repo for all identities?
The fact that this identity is DHS is good but if anyone wanted to know that then without some repo somewhere including that identity object definition also would not be possible.
With introduction of extensions in STIX 2.1, we are left with the issue of where to store extension definition objects, related schemas, and documentation. Previously we had the SEP repository, which would have been the location to store
such information and âadvertiseâ it to other community members.
What is being proposed in this email is NOT required of anyone defining extensions or producing and/or consuming content with extensions, but it is something like the SEP repository which would be useful to STIX users. We are not sure if
this proposal needs to be voted on by the TC. However, we are looking for comments, suggestions, etc., to make this as useful as possible to the community.
The recently introduced OASIS CTI common object repository (https://github.com/oasis-open/cti-stix-common-objects) seems like a good place to store extension information.
As part of AIS, DHS/CISA defined ACS data markings and it has been implemented as an extension. We will use it as an example of what we have in mind for storing extension information in that repository.
If you go to the repository, it contains a directory called objects. Within this directory are subdirectories for each STIX object type, which contain individual common objects of that object type. Each file contains one object. The format
of the file is a bundle that contains the one object. A directory for extension objects would contain files who names are extension-definition-<id property of object>.json. See:
Here is the file contents for the ACS data marking extension definition:
"description": "This schema adds ACS data markings",
Notice the created_by_ref property. This is the id of a STIX identity object that DHS/CISA has chosen for itself.
In this repository (NOT a STIX spec requirement) , the name property of the extension definition must correspond with the name of the json schema file (which we will discuss next), assuming there is a json schema for the extension.
The schema property of that object contains a URL that refers to the directory that contains the json schema and documentation for the STIX representation of ACS data markings. These are stored in a different directory which is a sibling
of the objects directory - extension-definition-specifications.
Note: these URLs are âliveâ so you can see what is being proposed, but they are not final, as they exist on a branch in the GitHub repository (for instance, in the final URLs âadding-extensionsâ would be replace by âmainâ)
Since the name property of the extension definition is âisa-acs-3-0â, the json schema will be found in:
Documentation for this extension is provided in the same directory. It should be in the same style as the STIX specification. Using Word is suggested.
If a JSON schema is included, another file is needed by the CTI STIX Validator. It must be named using the type of object that is being extended. For instance, since ACS data markings are an extension of the marking-definition type â
the following file is needed:
View that file to understand the concept. Some details of the contents of this file still need to be worked out to specify extensions so they are easy to incorporate into the validator.
Contributing Your Extension
Assuming this proposal is acceptable, the following guidelines would be used to add new extension definitions to the repository.
The maintainers will entertain contributions via a pull request.
The maintainers will do MINIMAL vetting before accepting the pull request. The contents of the pull request include:
A unique extension definition object in the objects/extensions directory
The name property must correspond to the name of the JSON schema file, if there is one
The created_by_ref property should be related to an Identity object representing the contributor
The specification, in the extension-definition-specifications directory
Written documentation is a must, however, its content will not be vetted.
A JSON schema is a should
If a JSON schema is included, another file related to the type being extended must be included.
Example files of the extension in use would be helpful
All contributions that satisfy the minimal vetting will be accepted. No attempt will be made the evaluate the usefulness of the extension.
Note: this acceptance criteria is unique to extensions. Any pull request to add other new common objects to this repository will be evaluated by the maintainers for its general utility to the community.
All extension contributions will probably be governed by the same IP rules as any other object in this repository (see the README). However, this is something to discuss within the TC and with OASIS.
Currently the maintainers of this repository are me and Chris Lenk (both of MITRE), but it would be preferable to have others from the TC involved.
Lead Cyber Security Engineer