CWE Schema Proposal

classic Classic list List threaded Threaded
2 messages Options
Reply | Threaded
Open this post in threaded view
|

CWE Schema Proposal

Andrew Buttner
Administrator
CWE Community,

As we look forward to the next release of CWE (target is late July), one item that we would like to improve is the XML schema. The existing schema is used for two very different purposes:

1) To support the CWE List and enable the community to browse and download the list, and use it for their own needs. The CWE List leverages structures like <Views> and <Categories>.

2) To enable encoding/sharing/submission of weaknesses. Since the CWE List targets only "Common" weaknesses, there may be organization specific, or rarely seen weaknesses that an individual user needs to describe. The CWE schema can be imported and used by other systems to satisfy this need.

The existing CWE XML schema could use some clean up as there are inconsistencies in the naming of elements, the use of types, where elements are used, and some other issues that lead to a schema that is difficult to understand.

Below is a proposal to improve the CWE schema. The goal is not to change the CWE content and the fields that are available, but rather to improve the behind-the-scenes XML that is used to share weaknesses. Granted, there are a few instances where certain fields are not used or don't make sense, and we are proposing removing them in this new schema.  (see item #6)

*** Please note that these proposed changes will likely REQUIRE existing scripts that work with the CWE XML to be reworked to accept the proposed XML. We would love to get a feel for how big of an issue this will cause. ***

We plan to use the new schema starting with the next CWE release, which we expect to publish in July 2017.

These proposals are subject to change. We welcome your feedback!

===================================

1) Make the <Weakness_Catalog> the only valid root element. The existing schema allows any number of elements to valid root elements. As part of this, since CWE is focused on weaknesses, make the <Weaknesses> child element required, while the other children (Views, Categories, and External_References)  are optional. The current <Weakness_Catalog> requires all of the children even if they are empty. For example, the empty element <Views/> is required to produce valid XML.

2) Remove the <Compound_Element> : The rationale for this is that named chains and composites are weaknesses themselves and should therefore be defined by <weakness> elements. Currently, all the fields are the same for a compound element and a weakness as both leverage the Common_Attributes group. To enable the distinction of the compound elements going forward, we will add a new "structure" attribute to <weakness> element with values of: simple, chain, composite

3) Add <External_References> to the weakness catalog : Previously, references were defined inside an individual weakness, but assigned an ID so that they could be reused if the reference was used elsewhere. We feel like it is cleaner and easier to understand if we have a central collection of references that individual weaknesses can pull from as needed. As a side benefit, there is no longer a need to have a local reference ID as the main ID can be used.

4) Tweak the child elements of a <View> :

Current Elements | New Elements | Note / Reason
--------------------------------------------------------------------------------------------------------------
View_Structure | | moved to the "Type" attribute
View_Objective | Objective |
View_Audience | Audience | changed to require description
Relationships | Members | only allowed relationship is <Has_Member>
Relationship_Notes | | combined with <Notes>
Maintenance_Notes | | combined with <Notes>
Other_Notes | Notes | added "Type" attribute
Alternate_Terms | | doesn't make sense for views
Research_Gaps | | doesn't make sense for views
References | References |
View_Filter | Filter |
Content_History | Content_History |

5) Tweak the child elements of a <Category> as it currently uses the same Common_Attributes group as weaknesses do. Many of these fields are not applicable to categories. We propose the following set of fields going forward.

Summary
Relationships (memberOf and hasMember)
References
Notes (with new Type attribute)
Content_History

The removed fields are:

Weakness_Ordinalities
Applicable_Platforms
Background_Details
Alternate_Terms
Time_of_Introduction
Modes_of_Introduction
Enabling_Factors_for_Exploitation
Likelihood_of_Exploit
Common_Consequences
Detection_Methods
Potential_Mitigations
Causal_Nature
Demonstrative_Examples
Observed_Examples
Functional_Areas
Relevant_Properties
Affected_Resources
Research_Gaps
Taxonomy_Mappings
White_Box_Definitions
Black_Box_Definitions
Related_Attack_Patterns

6) Remove the following child elements of <Weakness> as they are only used in a limited manner and do not currently hold unique information. Both items were originally added to the schema to support formalized weakness definitions. Unfortunately, this is an area that has not advanced very far within CWE and should likely be part of separate projects going forward.

White_Box_Definitions
Black_Box_Definitions

5) For many elements like <Alternate_Term> and <Weakness_Ordinalities> : Change to require a description, this will force us to fill out the fields completely.

6) CPE : move the CPE platform reference element to be an optional attribute on <operating_system>. The reason is that CPE is only applicable for the OS field and not languages, architectures, paradigms, or environments.

7) For weaknesses, tweak the names of the "Description" elements. Previously there was a <Description> element with two children; the short description was named <Description_Summary>, and the long was named <Extended_Description>. The proposed schema removes the nested elements and just had two top-level elements: <Description> and <Extended_Description>.

8) Change the <Relationships> element to only be used for views and categories. Also limit the values to memberOf and hasMember since these are the only ones that are appropriate for views and categories. For weaknesses, add a new <Related_Weaknesses> element that holds all the different types of relationships that weaknesses can have with each other. The reason for this change is to keep people from incorrectly using memberOf and hasMember relationships with weaknesses, and incorrectly using parentOf and childOf with views and categories.

9) Combine all the top-level note elements into a single <notes> element. Add a type attribute that allows for a distinction between: maintenance, platform, relationship, terminology, theoretical, other. This is done to simplify the schema and the resulting XML by having less elements.

10) Rewrite the StructuredTextType and add a new StructuredCodeType : We found the previous Structured_Text_Type to be cumbersome and unnecessary. It was in place for two primary reasons: First was to enable the encoding of bulleted lists and indention within text fields. Second was to provide formatting options such as new lines and shading for code examples. The first can be solved easily by leveraging the existing XHTML standard. The new StructuredTextType does this. The second is accomplished by the new StructuredCodeType which also leverages XHTML but includes a couple of existing attributes (language, nature)

---------

Andrew Buttner
The MITRE Corporation
[hidden email]
781-271-3515

To unsubscribe, send an email message to [hidden email] with SIGNOFF CWE-RESEARCH-LIST in the BODY of the message. If you have difficulties, write to [hidden email].
Reply | Threaded
Open this post in threaded view
|

Re: CWE Schema Proposal

Andrew Buttner
Administrator
All,

I want to bring this topic of an updated XML schema back to the top of the queue and make sure that everyone understands what we are proposing. Many of you may not use the CWE XML and so you can ignore this discussion, but for those that do rely on the format of the XML (maybe you import CWE your tool), please look at the proposal and voice your opinions.

BENEFIT = hopefully a more consistent and easy to use XML format

DRAWBACK = tools that rely on the format of the XML will need to be updated

I personally see the benefit as outweighing the drawback, but I would like to hear from anyone that does not agree with this.

Thanks
Drew



> -----Original Message-----
> From: [hidden email] [mailto:owner-cwe-research-
> [hidden email]] On Behalf Of Buttner, Drew
> Sent: Monday, June 5, 2017 4:38 PM
> To: cwe-research-list CWE Research Discussion <cwe-research-
> [hidden email]>
> Subject: CWE Schema Proposal
>
> CWE Community,
>
> As we look forward to the next release of CWE (target is late July), one item
> that we would like to improve is the XML schema. The existing schema is
> used for two very different purposes:
>
> 1) To support the CWE List and enable the community to browse and
> download the list, and use it for their own needs. The CWE List leverages
> structures like <Views> and <Categories>.
>
> 2) To enable encoding/sharing/submission of weaknesses. Since the CWE List
> targets only "Common" weaknesses, there may be organization specific, or
> rarely seen weaknesses that an individual user needs to describe. The CWE
> schema can be imported and used by other systems to satisfy this need.
>
> The existing CWE XML schema could use some clean up as there are
> inconsistencies in the naming of elements, the use of types, where elements
> are used, and some other issues that lead to a schema that is difficult to
> understand.
>
> Below is a proposal to improve the CWE schema. The goal is not to change
> the CWE content and the fields that are available, but rather to improve the
> behind-the-scenes XML that is used to share weaknesses. Granted, there
> are a few instances where certain fields are not used or don't make sense,
> and we are proposing removing them in this new schema.  (see item #6)
>
> *** Please note that these proposed changes will likely REQUIRE existing
> scripts that work with the CWE XML to be reworked to accept the proposed
> XML. We would love to get a feel for how big of an issue this will cause. ***
>
> We plan to use the new schema starting with the next CWE release, which
> we expect to publish in July 2017.
>
> These proposals are subject to change. We welcome your feedback!
>
> ===================================
>
> 1) Make the <Weakness_Catalog> the only valid root element. The existing
> schema allows any number of elements to valid root elements. As part of
> this, since CWE is focused on weaknesses, make the <Weaknesses> child
> element required, while the other children (Views, Categories, and
> External_References)  are optional. The current <Weakness_Catalog>
> requires all of the children even if they are empty. For example, the empty
> element <Views/> is required to produce valid XML.
>
> 2) Remove the <Compound_Element> : The rationale for this is that named
> chains and composites are weaknesses themselves and should therefore be
> defined by <weakness> elements. Currently, all the fields are the same for a
> compound element and a weakness as both leverage the
> Common_Attributes group. To enable the distinction of the compound
> elements going forward, we will add a new "structure" attribute to
> <weakness> element with values of: simple, chain, composite
>
> 3) Add <External_References> to the weakness catalog : Previously,
> references were defined inside an individual weakness, but assigned an ID so
> that they could be reused if the reference was used elsewhere. We feel like
> it is cleaner and easier to understand if we have a central collection of
> references that individual weaknesses can pull from as needed. As a side
> benefit, there is no longer a need to have a local reference ID as the main ID
> can be used.
>
> 4) Tweak the child elements of a <View> :
>
> Current Elements | New Elements | Note /
> Reason
> ----------------------------------------------------------------------------------------------
> ----------------
> View_Structure | | moved to the
> "Type" attribute
> View_Objective | Objective |
> View_Audience | Audience | changed to require
> description
> Relationships | Members | only allowed relationship is
> <Has_Member>
> Relationship_Notes | | combined with <Notes>
> Maintenance_Notes | | combined with <Notes>
> Other_Notes | Notes | added "Type"
> attribute
> Alternate_Terms | | doesn't make sense
> for views
> Research_Gaps | | doesn't make sense
> for views
> References | References |
> View_Filter | Filter |
> Content_History | Content_History |
>
> 5) Tweak the child elements of a <Category> as it currently uses the same
> Common_Attributes group as weaknesses do. Many of these fields are not
> applicable to categories. We propose the following set of fields going
> forward.
>
> Summary
> Relationships (memberOf and hasMember)
> References
> Notes (with new Type attribute)
> Content_History
>
> The removed fields are:
>
> Weakness_Ordinalities
> Applicable_Platforms
> Background_Details
> Alternate_Terms
> Time_of_Introduction
> Modes_of_Introduction
> Enabling_Factors_for_Exploitation
> Likelihood_of_Exploit
> Common_Consequences
> Detection_Methods
> Potential_Mitigations
> Causal_Nature
> Demonstrative_Examples
> Observed_Examples
> Functional_Areas
> Relevant_Properties
> Affected_Resources
> Research_Gaps
> Taxonomy_Mappings
> White_Box_Definitions
> Black_Box_Definitions
> Related_Attack_Patterns
>
> 6) Remove the following child elements of <Weakness> as they are only
> used in a limited manner and do not currently hold unique information. Both
> items were originally added to the schema to support formalized weakness
> definitions. Unfortunately, this is an area that has not advanced very far
> within CWE and should likely be part of separate projects going forward.
>
> White_Box_Definitions
> Black_Box_Definitions
>
> 5) For many elements like <Alternate_Term> and <Weakness_Ordinalities> :
> Change to require a description, this will force us to fill out the fields
> completely.
>
> 6) CPE : move the CPE platform reference element to be an optional
> attribute on <operating_system>. The reason is that CPE is only applicable for
> the OS field and not languages, architectures, paradigms, or environments.
>
> 7) For weaknesses, tweak the names of the "Description" elements.
> Previously there was a <Description> element with two children; the short
> description was named <Description_Summary>, and the long was named
> <Extended_Description>. The proposed schema removes the nested
> elements and just had two top-level elements: <Description> and
> <Extended_Description>.
>
> 8) Change the <Relationships> element to only be used for views and
> categories. Also limit the values to memberOf and hasMember since these
> are the only ones that are appropriate for views and categories. For
> weaknesses, add a new <Related_Weaknesses> element that holds all the
> different types of relationships that weaknesses can have with each other.
> The reason for this change is to keep people from incorrectly using
> memberOf and hasMember relationships with weaknesses, and incorrectly
> using parentOf and childOf with views and categories.
>
> 9) Combine all the top-level note elements into a single <notes> element.
> Add a type attribute that allows for a distinction between: maintenance,
> platform, relationship, terminology, theoretical, other. This is done to
> simplify the schema and the resulting XML by having less elements.
>
> 10) Rewrite the StructuredTextType and add a new StructuredCodeType :
> We found the previous Structured_Text_Type to be cumbersome and
> unnecessary. It was in place for two primary reasons: First was to enable the
> encoding of bulleted lists and indention within text fields. Second was to
> provide formatting options such as new lines and shading for code examples.
> The first can be solved easily by leveraging the existing XHTML standard. The
> new StructuredTextType does this. The second is accomplished by the new
> StructuredCodeType which also leverages XHTML but includes a couple of
> existing attributes (language, nature)
>
> ---------
>
> Andrew Buttner
> The MITRE Corporation
> [hidden email]
> 781-271-3515
>
> To unsubscribe, send an email message to [hidden email] with
> SIGNOFF CWE-RESEARCH-LIST in the BODY of the message. If you have
> difficulties, write to [hidden email].

To unsubscribe, send an email message to [hidden email] with SIGNOFF CWE-RESEARCH-LIST in the BODY of the message. If you have difficulties, write to [hidden email].