OASIS Common Security Advisory Framework (CSAF) TC

 View Only
  • 1.  Contemplating how to describe products in JSON.

    Posted 11-28-2018 07:35
    One of my follow-up actions was to address the description of products in the CSAF JSON format. Until now, I've avoided defining the schema for this problem, because the JSON mapping enables some approaches that are harder to implement in XML. I wrote something up about this in a previous email (May 8). A snippet of a CVRF XML instance looks like this: <ProductTree xmlns=" http://docs.oasis-open.org/csaf/ns/csaf-cvrf/v1.2/prod "> <Branch Name="Cisco" Type="Vendor"> <Branch Name="IOS" Type="Product Name"> <Branch Name="12.2SE" Type="Product Version"> <Branch Name="12.2(55)SE" Type="Service Pack"> <FullProductName ProductID="CVRFPID-103763">Cisco IOS 12.2SE 12.2(55)SE</FullProductName> </Branch> <Branch Name="12.2(55)SE3" Type="Service Pack"> <FullProductName ProductID="CVRFPID-105394">Cisco IOS 12.2SE 12.2(55)SE3</FullProductName> </Branch> <Branch Name="12.2(55)SE2" Type="Service Pack"> <FullProductName ProductID="CVRFPID-105689">Cisco IOS 12.2SE 12.2(55)SE2</FullProductName> </Branch> .... The above defines three products: CVRFPID-103763, CVRFPID-105394, and CVRFPID-105689. Each of these products has associated a "full product name", a "service pack", a "product name", a "product version", and a "vendor". The CVRF specification identifies additional attributes that can be defined in the "branches", however those attributes are not strictly hierarchical - architecture, host name, language, legacy, product family. This makes fitting them into the above structure awkward, at best. The underlying goal here is to associate a bunch of property values with a given product ID. In the most verbose form, the JSON form of the product definition for " CVRFPID-103763 " could just be: { "id": "CVRFPID-103763", "full_name": " Cisco IOS 12.2SE 12.2(55)SE", "service_pack": "12.2(55)SE", "version": "12.2SE", "name": "IOS", "vendor": "Cisco" } (Note that I removed "product" from attribute names, so instead of "product_name" it is just "name".) Keeping with the data model of CVRF, additional properties to allow here would include "architecture", "host_name", "language", "legacy", "product_family", "specification". Of course, we've also been talking about how to identify products uniquely, so "cpe", "swid", and "spdx" are good candidates for properties here as well. And of course, since it is JSON, we can allow for arbitrary vendor extensions here. So far, the proposed JSON definition of a product is a significant improvement over the XML of CVRF, because it has an obvious approach for extensibility, eliminates the arbitrary taxonomy for attributes that don't fit a taxonomy, and allows for multiple different software identity mechanisms. While the above form is explicit and flexible, it is also quite verbose. How do we eliminate the verbosity? Proposal is to allow for the definition of a "set" of attributes that can then be reused. A definition of a set of attributes for the above examples in XML: { "id": "ios-12.2SE", "vendor": "Cisco", "name" : "IOS", "version": "12.2SE" } The above defines three attributes that can be reused in association with a product definition Being able to combine attribute sets will further reduce duplication. So the full proposal is to allow "union" of attribute sets: { "id": "ios", "vendor": "Cisco", "name": "IOS", }, { "id": "ios-12.2SE", "union" : "ios", // this means share properties "vendor" is Cisco, name is "IOS". "version": "12.2SE" } Restating the original XML product descriptions using attribute sets: product_descriptions: [ { "attribute_set": "ios-12.2SE", "products": [ { "id": "CVRFPID-103763", "full_name": "Cisco IOS 12.2SE 12.2(55)SE", "service_pack": "12.2(55)SE", }, { "id": "CVRFPID-105394", "full_name": "Cisco IOS 12.2SE 12.2(55)SE3", "service_pack": "12.2(55)SE3", }, { "id": "CVRFPID-105689", "full_name": "Cisco IOS 12.2SE 12.2(55)SE2", "service_pack": "12.2(55)SE2", }, }, { "attribute_set": "ios-12.2EX", "products": [ ... ] } ] For discussion at our meeting tomorrow: Any objection to me changing the product tree in JSON to match what I describe above? Further enhancement ideas: "id" attribute is optional, if only one of swid, cpe, or spdx is provided, then the value of the one present is used as the "id". full_name - it strikes me that this field could be completely optional. The default might simply be to take the space-separated concatenation of the available attributes (excluding "id"). Eric.


  • 2.  Re: Contemplating how to describe products in JSON.

    Posted 11-29-2018 19:35
    A follow up to my previous email. In that email, I suggested an approach for sharing attributes across multiple products. After reflecting on what was discussed in the call, writing up thoughts from the call, and studying the CVRF documents I have, I have what I think is a better answer. I want to start from the premise that version # is a special attribute of a product's identity. To that end, I propose a fairly radical change, that orients product references and definitions in the JSON around the version property. Looking at the IOS example from Cisco from the previous email, here's the snippet defining the product + version instances: <ProductTree xmlns=" http://docs.oasis-open.org/csaf/ns/csaf-cvrf/v1.2/prod "> <Branch Name="Cisco" Type="Vendor"> <Branch Name="IOS" Type="Product Name"> <Branch Name="12.2SE" Type="Product Version"> <Branch Name="12.2(55)SE" Type="Service Pack"> <FullProductName ProductID="CVRFPID-103763">Cisco IOS 12.2SE 12.2(55)SE</FullProductName> </Branch> <Branch Name="12.2(55)SE3" Type="Service Pack"> <FullProductName ProductID="CVRFPID-105394">Cisco IOS 12.2SE 12.2(55)SE3</FullProductName> </Branch> <Branch Name="12.2(55)SE2" Type="Service Pack"> <FullProductName ProductID="CVRFPID-105689">Cisco IOS 12.2SE 12.2(55)SE2</FullProductName> </Branch> What if the JSON for this looks like this instead: { "vendor": "Cisco", "product_name": "IOS", "label": "ios", "versions": ["12.2(55)SE", "12.2(55)SE3", "12.2(55)SE2"], "full_name": "Cisco IOS ${version}" } ... and references to these product instances from the vulnerabilities section would look like this: "product_status": { "known_affected": [ "ios-12.2(55)SE", "ios-12.2(55)SE3", .... (The above is a little bit of a cheat and simplification, for the purposes of example. Cisco uses "version" and "service pack" to distinguish, and the product names don't match the original document, but those discrepancies can be addressed.) In the definition of the product, the "full_name" property now becomes a computed value, based on the version # in question, as show by the ${version} syntax in the property value. In case it isn't clear from the example, references would now be in the form label + "-" + version. That is, instead of referencing the product by way of "CVRFPID-103763", the reference would be of the form "ios-12.2(55)SE". A more formal description: whenever a reference is encountered, look for a product definition with a label that either exactly matches that reference, or look for a reference that starts with label + "-", and then grab the version number as everything after the hyphen. In the XML-based CVRF document, this approach would be disappointing, because it would then be impossible to validate the references within the XML document using the key/keyref constructs of XML Schema. However, in JSON schema, we don't have the advantage of key/keyref constructs. Given that references need to be verified programmatically anyway, this proposed change doesn't add much additional complexity to a processor of the JSON format. The original CVRF XML for the Cisco example takes 590 lines of XML to capture the definition of all of the versions of Cisco IOS that are identified in the document. Under this alternate proposal, those approximately ~170 product versions could be captured in just a few lines (assuming the JSON lists more than version number one per line). If we're talking character count, it is approximately 150 characters for each version definition in the XML, and would be approximately 15 characters in the JSON.... On top of that, the relationships are now easier to understand, to the point that an alert human stands a chance of noticing possible errors in the JSON. There are some further details we can certainly debate about (allowed characters in labels, whether a label can be reused in a document), but the above discussion boils down to this: Instead of defining unique labels for each version of a product, shall we allow references to product definitions in the form of label + "-" + version, and shall we allow definitions of available versions of a product by simply enumerating versions under the definition of a product? Does this direction make sense to members of the TC? If I don't hear of any objections, I'll go ahead with working up schema and instances to match. Eric. On Tue, Nov 27, 2018 at 11:34 PM Eric Johnson < eric@tibco.com > wrote: One of my follow-up actions was to address the description of products in the CSAF JSON format. Until now, I've avoided defining the schema for this problem, because the JSON mapping enables some approaches that are harder to implement in XML. I wrote something up about this in a previous email (May 8). A snippet of a CVRF XML instance looks like this: <ProductTree xmlns=" http://docs.oasis-open.org/csaf/ns/csaf-cvrf/v1.2/prod "> <Branch Name="Cisco" Type="Vendor"> <Branch Name="IOS" Type="Product Name"> <Branch Name="12.2SE" Type="Product Version"> <Branch Name="12.2(55)SE" Type="Service Pack"> <FullProductName ProductID="CVRFPID-103763">Cisco IOS 12.2SE 12.2(55)SE</FullProductName> </Branch> <Branch Name="12.2(55)SE3" Type="Service Pack"> <FullProductName ProductID="CVRFPID-105394">Cisco IOS 12.2SE 12.2(55)SE3</FullProductName> </Branch> <Branch Name="12.2(55)SE2" Type="Service Pack"> <FullProductName ProductID="CVRFPID-105689">Cisco IOS 12.2SE 12.2(55)SE2</FullProductName> </Branch> .... The above defines three products: CVRFPID-103763, CVRFPID-105394, and CVRFPID-105689. Each of these products has associated a "full product name", a "service pack", a "product name", a "product version", and a "vendor". The CVRF specification identifies additional attributes that can be defined in the "branches", however those attributes are not strictly hierarchical - architecture, host name, language, legacy, product family. This makes fitting them into the above structure awkward, at best. The underlying goal here is to associate a bunch of property values with a given product ID. In the most verbose form, the JSON form of the product definition for " CVRFPID-103763 " could just be: { "id": "CVRFPID-103763", "full_name": " Cisco IOS 12.2SE 12.2(55)SE", "service_pack": "12.2(55)SE", "version": "12.2SE", "name": "IOS", "vendor": "Cisco" } (Note that I removed "product" from attribute names, so instead of "product_name" it is just "name".) Keeping with the data model of CVRF, additional properties to allow here would include "architecture", "host_name", "language", "legacy", "product_family", "specification". Of course, we've also been talking about how to identify products uniquely, so "cpe", "swid", and "spdx" are good candidates for properties here as well. And of course, since it is JSON, we can allow for arbitrary vendor extensions here. So far, the proposed JSON definition of a product is a significant improvement over the XML of CVRF, because it has an obvious approach for extensibility, eliminates the arbitrary taxonomy for attributes that don't fit a taxonomy, and allows for multiple different software identity mechanisms. While the above form is explicit and flexible, it is also quite verbose. How do we eliminate the verbosity? Proposal is to allow for the definition of a "set" of attributes that can then be reused. A definition of a set of attributes for the above examples in XML: { "id": "ios-12.2SE", "vendor": "Cisco", "name" : "IOS", "version": "12.2SE" } The above defines three attributes that can be reused in association with a product definition Being able to combine attribute sets will further reduce duplication. So the full proposal is to allow "union" of attribute sets: { "id": "ios", "vendor": "Cisco", "name": "IOS", }, { "id": "ios-12.2SE", "union" : "ios", // this means share properties "vendor" is Cisco, name is "IOS". "version": "12.2SE" } Restating the original XML product descriptions using attribute sets: product_descriptions: [ { "attribute_set": "ios-12.2SE", "products": [ { "id": "CVRFPID-103763", "full_name": "Cisco IOS 12.2SE 12.2(55)SE", "service_pack": "12.2(55)SE", }, { "id": "CVRFPID-105394", "full_name": "Cisco IOS 12.2SE 12.2(55)SE3", "service_pack": "12.2(55)SE3", }, { "id": "CVRFPID-105689", "full_name": "Cisco IOS 12.2SE 12.2(55)SE2", "service_pack": "12.2(55)SE2", }, }, { "attribute_set": "ios-12.2EX", "products": [ ... ] } ] For discussion at our meeting tomorrow: Any objection to me changing the product tree in JSON to match what I describe above? Further enhancement ideas: "id" attribute is optional, if only one of swid, cpe, or spdx is provided, then the value of the one present is used as the "id". full_name - it strikes me that this field could be completely optional. The default might simply be to take the space-separated concatenation of the available attributes (excluding "id"). Eric.


  • 3.  Re: Contemplating how to describe products in JSON.

    Posted 12-12-2018 01:05
    I've not heard any objections to my proposal here. Just as a reminder, the question is this - does anyone object to treating version labels specially? Assuming "no": does anyone have a problem using a product label + version number as a unique identifier for a product instance? If no objections, I can work up an updated schema that reflects that..... Eric. On Thu, Nov 29, 2018 at 11:35 AM Eric Johnson < eric@tibco.com > wrote: A follow up to my previous email. In that email, I suggested an approach for sharing attributes across multiple products. After reflecting on what was discussed in the call, writing up thoughts from the call, and studying the CVRF documents I have, I have what I think is a better answer. I want to start from the premise that version # is a special attribute of a product's identity. To that end, I propose a fairly radical change, that orients product references and definitions in the JSON around the version property. Looking at the IOS example from Cisco from the previous email, here's the snippet defining the product + version instances: <ProductTree xmlns=" http://docs.oasis-open.org/csaf/ns/csaf-cvrf/v1.2/prod "> <Branch Name="Cisco" Type="Vendor"> <Branch Name="IOS" Type="Product Name"> <Branch Name="12.2SE" Type="Product Version"> <Branch Name="12.2(55)SE" Type="Service Pack"> <FullProductName ProductID="CVRFPID-103763">Cisco IOS 12.2SE 12.2(55)SE</FullProductName> </Branch> <Branch Name="12.2(55)SE3" Type="Service Pack"> <FullProductName ProductID="CVRFPID-105394">Cisco IOS 12.2SE 12.2(55)SE3</FullProductName> </Branch> <Branch Name="12.2(55)SE2" Type="Service Pack"> <FullProductName ProductID="CVRFPID-105689">Cisco IOS 12.2SE 12.2(55)SE2</FullProductName> </Branch> What if the JSON for this looks like this instead: { "vendor": "Cisco", "product_name": "IOS", "label": "ios", "versions": ["12.2(55)SE", "12.2(55)SE3", "12.2(55)SE2"], "full_name": "Cisco IOS ${version}" } ... and references to these product instances from the vulnerabilities section would look like this: "product_status": { "known_affected": [ "ios-12.2(55)SE", "ios-12.2(55)SE3", .... (The above is a little bit of a cheat and simplification, for the purposes of example. Cisco uses "version" and "service pack" to distinguish, and the product names don't match the original document, but those discrepancies can be addressed.) In the definition of the product, the "full_name" property now becomes a computed value, based on the version # in question, as show by the ${version} syntax in the property value. In case it isn't clear from the example, references would now be in the form label + "-" + version. That is, instead of referencing the product by way of "CVRFPID-103763", the reference would be of the form "ios-12.2(55)SE". A more formal description: whenever a reference is encountered, look for a product definition with a label that either exactly matches that reference, or look for a reference that starts with label + "-", and then grab the version number as everything after the hyphen. In the XML-based CVRF document, this approach would be disappointing, because it would then be impossible to validate the references within the XML document using the key/keyref constructs of XML Schema. However, in JSON schema, we don't have the advantage of key/keyref constructs. Given that references need to be verified programmatically anyway, this proposed change doesn't add much additional complexity to a processor of the JSON format. The original CVRF XML for the Cisco example takes 590 lines of XML to capture the definition of all of the versions of Cisco IOS that are identified in the document. Under this alternate proposal, those approximately ~170 product versions could be captured in just a few lines (assuming the JSON lists more than version number one per line). If we're talking character count, it is approximately 150 characters for each version definition in the XML, and would be approximately 15 characters in the JSON.... On top of that, the relationships are now easier to understand, to the point that an alert human stands a chance of noticing possible errors in the JSON. There are some further details we can certainly debate about (allowed characters in labels, whether a label can be reused in a document), but the above discussion boils down to this: Instead of defining unique labels for each version of a product, shall we allow references to product definitions in the form of label + "-" + version, and shall we allow definitions of available versions of a product by simply enumerating versions under the definition of a product? Does this direction make sense to members of the TC? If I don't hear of any objections, I'll go ahead with working up schema and instances to match. Eric. On Tue, Nov 27, 2018 at 11:34 PM Eric Johnson < eric@tibco.com > wrote: One of my follow-up actions was to address the description of products in the CSAF JSON format. Until now, I've avoided defining the schema for this problem, because the JSON mapping enables some approaches that are harder to implement in XML. I wrote something up about this in a previous email (May 8). A snippet of a CVRF XML instance looks like this: <ProductTree xmlns=" http://docs.oasis-open.org/csaf/ns/csaf-cvrf/v1.2/prod "> <Branch Name="Cisco" Type="Vendor"> <Branch Name="IOS" Type="Product Name"> <Branch Name="12.2SE" Type="Product Version"> <Branch Name="12.2(55)SE" Type="Service Pack"> <FullProductName ProductID="CVRFPID-103763">Cisco IOS 12.2SE 12.2(55)SE</FullProductName> </Branch> <Branch Name="12.2(55)SE3" Type="Service Pack"> <FullProductName ProductID="CVRFPID-105394">Cisco IOS 12.2SE 12.2(55)SE3</FullProductName> </Branch> <Branch Name="12.2(55)SE2" Type="Service Pack"> <FullProductName ProductID="CVRFPID-105689">Cisco IOS 12.2SE 12.2(55)SE2</FullProductName> </Branch> .... The above defines three products: CVRFPID-103763, CVRFPID-105394, and CVRFPID-105689. Each of these products has associated a "full product name", a "service pack", a "product name", a "product version", and a "vendor". The CVRF specification identifies additional attributes that can be defined in the "branches", however those attributes are not strictly hierarchical - architecture, host name, language, legacy, product family. This makes fitting them into the above structure awkward, at best. The underlying goal here is to associate a bunch of property values with a given product ID. In the most verbose form, the JSON form of the product definition for " CVRFPID-103763 " could just be: { "id": "CVRFPID-103763", "full_name": " Cisco IOS 12.2SE 12.2(55)SE", "service_pack": "12.2(55)SE", "version": "12.2SE", "name": "IOS", "vendor": "Cisco" } (Note that I removed "product" from attribute names, so instead of "product_name" it is just "name".) Keeping with the data model of CVRF, additional properties to allow here would include "architecture", "host_name", "language", "legacy", "product_family", "specification". Of course, we've also been talking about how to identify products uniquely, so "cpe", "swid", and "spdx" are good candidates for properties here as well. And of course, since it is JSON, we can allow for arbitrary vendor extensions here. So far, the proposed JSON definition of a product is a significant improvement over the XML of CVRF, because it has an obvious approach for extensibility, eliminates the arbitrary taxonomy for attributes that don't fit a taxonomy, and allows for multiple different software identity mechanisms. While the above form is explicit and flexible, it is also quite verbose. How do we eliminate the verbosity? Proposal is to allow for the definition of a "set" of attributes that can then be reused. A definition of a set of attributes for the above examples in XML: { "id": "ios-12.2SE", "vendor": "Cisco", "name" : "IOS", "version": "12.2SE" } The above defines three attributes that can be reused in association with a product definition Being able to combine attribute sets will further reduce duplication. So the full proposal is to allow "union" of attribute sets: { "id": "ios", "vendor": "Cisco", "name": "IOS", }, { "id": "ios-12.2SE", "union" : "ios", // this means share properties "vendor" is Cisco, name is "IOS". "version": "12.2SE" } Restating the original XML product descriptions using attribute sets: product_descriptions: [ { "attribute_set": "ios-12.2SE", "products": [ { "id": "CVRFPID-103763", "full_name": "Cisco IOS 12.2SE 12.2(55)SE", "service_pack": "12.2(55)SE", }, { "id": "CVRFPID-105394", "full_name": "Cisco IOS 12.2SE 12.2(55)SE3", "service_pack": "12.2(55)SE3", }, { "id": "CVRFPID-105689", "full_name": "Cisco IOS 12.2SE 12.2(55)SE2", "service_pack": "12.2(55)SE2", }, }, { "attribute_set": "ios-12.2EX", "products": [ ... ] } ] For discussion at our meeting tomorrow: Any objection to me changing the product tree in JSON to match what I describe above? Further enhancement ideas: "id" attribute is optional, if only one of swid, cpe, or spdx is provided, then the value of the one present is used as the "id". full_name - it strikes me that this field could be completely optional. The default might simply be to take the space-separated concatenation of the available attributes (excluding "id"). Eric.


  • 4.  Re: [csaf] Re: Contemplating how to describe products in JSON.

    Posted 12-12-2018 18:06
    I think we need to reach consensus on how to define the versions first. Thanks, --Feng On 12/11/2018 5:04 PM, Eric Johnson wrote: I've not heard any objections to my proposal here. Just as a reminder, the question is this - does anyone object to treating version labels specially? Assuming no : does anyone have a problem using a product label + version number as a unique identifier for a product instance? If no objections, I can work up an updated schema that reflects that..... Eric. On Thu, Nov 29, 2018 at 11:35 AM Eric Johnson < eric@tibco.com > wrote: A follow up to my previous email. In that email, I suggested an approach for sharing attributes across multiple products. After reflecting on what was discussed in the call, writing up thoughts from the call, and studying the CVRF documents I have, I have what I think is a better answer. I want to start from the premise that version # is a special attribute of a product's identity. To that end, I propose a fairly radical change, that orients product references and definitions in the JSON around the version property. Looking at the IOS example from Cisco from the previous email, here's the snippet defining the product + version instances: <ProductTree xmlns= http://docs.oasis-open.org/csaf/ns/csaf-cvrf/v1.2/prod > <Branch Name= Cisco Type= Vendor > <Branch Name= IOS Type= Product Name > <Branch Name= 12.2SE Type= Product Version > <Branch Name= 12.2(55)SE Type= Service Pack > <FullProductName ProductID= CVRFPID-103763 >Cisco IOS 12.2SE 12.2(55)SE</FullProductName> </Branch> <Branch Name= 12.2(55)SE3 Type= Service Pack > <FullProductName ProductID= CVRFPID-105394 >Cisco IOS 12.2SE 12.2(55)SE3</FullProductName> </Branch> <Branch Name= 12.2(55)SE2 Type= Service Pack > <FullProductName ProductID= CVRFPID-105689 >Cisco IOS 12.2SE 12.2(55)SE2</FullProductName> </Branch> What if the JSON for this looks like this instead: { vendor : Cisco , product_name : IOS , label : ios , versions : [ 12.2(55)SE , 12.2(55)SE3 , 12.2(55)SE2 ], full_name : Cisco IOS ${version} } ... and references to these product instances from the vulnerabilities section would look like this: product_status : { known_affected : [ ios-12.2(55)SE , ios-12.2(55)SE3 , .... (The above is a little bit of a cheat and simplification, for the purposes of example. Cisco uses version and service pack to distinguish, and the product names don't match the original document, but those discrepancies can be addressed.) In the definition of the product, the full_name property now becomes a computed value, based on the version # in question, as show by the ${version} syntax in the property value. In case it isn't clear from the example, references would now be in the form label + - + version. That is, instead of referencing the product by way of CVRFPID-103763 , the reference would be of the form ios-12.2(55)SE . A more formal description: whenever a reference is encountered, look for a product definition with a label that either exactly matches that reference, or look for a reference that starts with label + - , and then grab the version number as everything after the hyphen. In the XML-based CVRF document, this approach would be disappointing, because it would then be impossible to validate the references within the XML document using the key/keyref constructs of XML Schema. However, in JSON schema, we don't have the advantage of key/keyref constructs. Given that references need to be verified programmatically anyway, this proposed change doesn't add much additional complexity to a processor of the JSON format. The original CVRF XML for the Cisco example takes 590 lines of XML to capture the definition of all of the versions of Cisco IOS that are identified in the document. Under this alternate proposal, those approximately ~170 product versions could be captured in just a few lines (assuming the JSON lists more than version number one per line). If we're talking character count, it is approximately 150 characters for each version definition in the XML, and would be approximately 15 characters in the JSON.... On top of that, the relationships are now easier to understand, to the point that an alert human stands a chance of noticing possible errors in the JSON. There are some further details we can certainly debate about (allowed characters in labels, whether a label can be reused in a document), but the above discussion boils down to this: Instead of defining unique labels for each version of a product, shall we allow references to product definitions in the form of label + - + version, and shall we allow definitions of available versions of a product by simply enumerating versions under the definition of a product? Does this direction make sense to members of the TC? If I don't hear of any objections, I'll go ahead with working up schema and instances to match. Eric. On Tue, Nov 27, 2018 at 11:34 PM Eric Johnson < eric@tibco.com > wrote: One of my follow-up actions was to address the description of products in the CSAF JSON format. Until now, I've avoided defining the schema for this problem, because the JSON mapping enables some approaches that are harder to implement in XML. I wrote something up about this in a previous email (May 8). A snippet of a CVRF XML instance looks like this: <ProductTree xmlns= http://docs.oasis-open.org/csaf/ns/csaf-cvrf/v1.2/prod > <Branch Name= Cisco Type= Vendor > <Branch Name= IOS Type= Product Name > <Branch Name= 12.2SE Type= Product Version > <Branch Name= 12.2(55)SE Type= Service Pack > <FullProductName ProductID= CVRFPID-103763 >Cisco IOS 12.2SE 12.2(55)SE</FullProductName> </Branch> <Branch Name= 12.2(55)SE3 Type= Service Pack > <FullProductName ProductID= CVRFPID-105394 >Cisco IOS 12.2SE 12.2(55)SE3</FullProductName> </Branch> <Branch Name= 12.2(55)SE2 Type= Service Pack > <FullProductName ProductID= CVRFPID-105689 >Cisco IOS 12.2SE 12.2(55)SE2</FullProductName> </Branch> .... The above defines three products: CVRFPID-103763, CVRFPID-105394, and CVRFPID-105689. Each of these products has associated a full product name , a service pack , a product name , a product version , and a vendor . The CVRF specification identifies additional attributes that can be defined in the branches , however those attributes are not strictly hierarchical - architecture, host name, language, legacy, product family. This makes fitting them into the above structure awkward, at best. The underlying goal here is to associate a bunch of property values with a given product ID. In the most verbose form, the JSON form of the product definition for CVRFPID-103763 could just be: { id : CVRFPID-103763 , full_name : Cisco IOS 12.2SE 12.2(55)SE , service_pack : 12.2(55)SE , version : 12.2SE , name : IOS , vendor : Cisco } (Note that I removed product from attribute names, so instead of product_name it is just name .) Keeping with the data model of CVRF, additional properties to allow here would include architecture , host_name , language , legacy , product_family , specification . Of course, we've also been talking about how to identify products uniquely, so cpe , swid , and spdx are good candidates for properties here as well. And of course, since it is JSON, we can allow for arbitrary vendor extensions here. So far, the proposed JSON definition of a product is a significant improvement over the XML of CVRF, because it has an obvious approach for extensibility, eliminates the arbitrary taxonomy for attributes that don't fit a taxonomy, and allows for multiple different software identity mechanisms. While the above form is explicit and flexible, it is also quite verbose. How do we eliminate the verbosity? Proposal is to allow for the definition of a set of attributes that can then be reused. A definition of a set of attributes for the above examples in XML: { id : ios-12.2SE , vendor : Cisco , name : IOS , version : 12.2SE } The above defines three attributes that can be reused in association with a product definition Being able to combine attribute sets will further reduce duplication. So the full proposal is to allow union of attribute sets: { id : ios , vendor : Cisco , name : IOS , }, { id : ios-12.2SE , union : ios , // this means share properties vendor is Cisco, name is IOS . version : 12.2SE } Restating the original XML product descriptions using attribute sets: product_descriptions: [ { attribute_set : ios-12.2SE , products : [ { id : CVRFPID-103763 , full_name : Cisco IOS 12.2SE 12.2(55)SE , service_pack : 12.2(55)SE , }, { id : CVRFPID-105394 , full_name : Cisco IOS 12.2SE 12.2(55)SE3 , service_pack : 12.2(55)SE3 , }, { id : CVRFPID-105689 , full_name : Cisco IOS 12.2SE 12.2(55)SE2 , service_pack : 12.2(55)SE2 , }, }, { attribute_set : ios-12.2EX , products : [ ... ] } ] For discussion at our meeting tomorrow: Any objection to me changing the product tree in JSON to match what I describe above? Further enhancement ideas: id attribute is optional, if only one of swid, cpe, or spdx is provided, then the value of the one present is used as the id . full_name - it strikes me that this field could be completely optional. The default might simply be to take the space-separated concatenation of the available attributes (excluding id ). Eric.


  • 5.  Re: [csaf] Re: Contemplating how to describe products in JSON.

    Posted 12-12-2018 19:01
    Hi Feng, On Wed, Dec 12, 2018 at 10:06 AM Feng Cao < feng.cao@oracle.com > wrote: I think we need to reach consensus on how to define the versions first. Interesting. That's not the response I was expecting! Which means there's a good discussion to be had here. Thanks for the reply. If I'm correctly interpreting your email on the subject of versions, it proposes to solve the problem of identifying specific sets of instances of releases of products, by way of specifying constraints on versions. For example, identify the set of "all releases of ProductFoo prior to version 2.5.4" - which could then be identified as vulnerable (or not tested, or not vulnerable - whatever). When posing my question about identifying instances of releases of products, my interpretation was that the question happened to be completely orthogonal to how we identify sets of instances of releases, and whether we overlay semantics on version numbers such there's meaning to assertions such as "interval" that can bound a set. My proposal is simply that an "instance of a release of a product" be identified uniquely within a CSAF JSON document by way of combining a product "label" (scoped to the JSON document) plus an additional label called "version" to identify a specific instance. This differs from the current CVRF approach, in that the CVRF document requires a unique identifier (and a corresponding block of XML to declare it) for each instance of a release of a product. At the risk of repeating myself, why this change? The proposal I put forth leverages three details: At least in the context of security advisories, whatever a company / project / organization does, there's always a version string associated with a particular instance of a release (at least that I've seen - anyone have contrary examples?) JSON doesn't have key/keyref constructs, so a JSON based validation will have to write code to validate references to instances of product releases. There's maybe a portion of a line of code to be gained by the XML-based approach that requires a declaration of an instance of a release of a product in order to establish an identifier for the particular release, at at worst, a whole bunch of additional complexity. 99+% of the time, different instances of releases of a product share the exact same attributes - so requiring a block for declaring each and every release is painful, and leads to bulky portions of a document without adding any value, and in fact make it harder for a human to evaluate a document, because an extra de-reference is required to map a product identifier to a product version. OK - so how is your response interesting? I think it is interesting in that - assuming we identify instances of releases as I've suggested - then it is possible to consider adding semantics on the version strings that then make it easier to specify "sets" of instances of releases of products. For example, rather than specifying the interval [2.0.0, 2.0.6) , we could simply assert something like "minor-release-prior-to 2.0.6". There's some up-side to that. I still think the proposals are orthogonal to each other, although they might be mutually reinforcing. Eric. Thanks, --Feng On 12/11/2018 5:04 PM, Eric Johnson wrote: I've not heard any objections to my proposal here. Just as a reminder, the question is this - does anyone object to treating version labels specially? Assuming "no": does anyone have a problem using a product label + version number as a unique identifier for a product instance? If no objections, I can work up an updated schema that reflects that..... Eric. On Thu, Nov 29, 2018 at 11:35 AM Eric Johnson < eric@tibco.com > wrote: A follow up to my previous email. In that email, I suggested an approach for sharing attributes across multiple products. After reflecting on what was discussed in the call, writing up thoughts from the call, and studying the CVRF documents I have, I have what I think is a better answer. I want to start from the premise that version # is a special attribute of a product's identity. To that end, I propose a fairly radical change, that orients product references and definitions in the JSON around the version property. Looking at the IOS example from Cisco from the previous email, here's the snippet defining the product + version instances: <ProductTree xmlns=" http://docs.oasis-open.org/csaf/ns/csaf-cvrf/v1.2/prod "> <Branch Name="Cisco" Type="Vendor"> <Branch Name="IOS" Type="Product Name"> <Branch Name="12.2SE" Type="Product Version"> <Branch Name="12.2(55)SE" Type="Service Pack"> <FullProductName ProductID="CVRFPID-103763">Cisco IOS 12.2SE 12.2(55)SE</FullProductName> </Branch> <Branch Name="12.2(55)SE3" Type="Service Pack"> <FullProductName ProductID="CVRFPID-105394">Cisco IOS 12.2SE 12.2(55)SE3</FullProductName> </Branch> <Branch Name="12.2(55)SE2" Type="Service Pack"> <FullProductName ProductID="CVRFPID-105689">Cisco IOS 12.2SE 12.2(55)SE2</FullProductName> </Branch> What if the JSON for this looks like this instead: { "vendor": "Cisco", "product_name": "IOS", "label": "ios", "versions": ["12.2(55)SE", "12.2(55)SE3", "12.2(55)SE2"], "full_name": "Cisco IOS ${version}" } ... and references to these product instances from the vulnerabilities section would look like this: "product_status": { "known_affected": [ "ios-12.2(55)SE", "ios-12.2(55)SE3", .... (The above is a little bit of a cheat and simplification, for the purposes of example. Cisco uses "version" and "service pack" to distinguish, and the product names don't match the original document, but those discrepancies can be addressed.) In the definition of the product, the "full_name" property now becomes a computed value, based on the version # in question, as show by the ${version} syntax in the property value. In case it isn't clear from the example, references would now be in the form label + "-" + version. That is, instead of referencing the product by way of "CVRFPID-103763", the reference would be of the form "ios-12.2(55)SE". A more formal description: whenever a reference is encountered, look for a product definition with a label that either exactly matches that reference, or look for a reference that starts with label + "-", and then grab the version number as everything after the hyphen. In the XML-based CVRF document, this approach would be disappointing, because it would then be impossible to validate the references within the XML document using the key/keyref constructs of XML Schema. However, in JSON schema, we don't have the advantage of key/keyref constructs. Given that references need to be verified programmatically anyway, this proposed change doesn't add much additional complexity to a processor of the JSON format. The original CVRF XML for the Cisco example takes 590 lines of XML to capture the definition of all of the versions of Cisco IOS that are identified in the document. Under this alternate proposal, those approximately ~170 product versions could be captured in just a few lines (assuming the JSON lists more than version number one per line). If we're talking character count, it is approximately 150 characters for each version definition in the XML, and would be approximately 15 characters in the JSON.... On top of that, the relationships are now easier to understand, to the point that an alert human stands a chance of noticing possible errors in the JSON. There are some further details we can certainly debate about (allowed characters in labels, whether a label can be reused in a document), but the above discussion boils down to this: Instead of defining unique labels for each version of a product, shall we allow references to product definitions in the form of label + "-" + version, and shall we allow definitions of available versions of a product by simply enumerating versions under the definition of a product? Does this direction make sense to members of the TC? If I don't hear of any objections, I'll go ahead with working up schema and instances to match. Eric. On Tue, Nov 27, 2018 at 11:34 PM Eric Johnson < eric@tibco.com > wrote: One of my follow-up actions was to address the description of products in the CSAF JSON format. Until now, I've avoided defining the schema for this problem, because the JSON mapping enables some approaches that are harder to implement in XML. I wrote something up about this in a previous email (May 8). A snippet of a CVRF XML instance looks like this: <ProductTree xmlns=" http://docs.oasis-open.org/csaf/ns/csaf-cvrf/v1.2/prod "> <Branch Name="Cisco" Type="Vendor"> <Branch Name="IOS" Type="Product Name"> <Branch Name="12.2SE" Type="Product Version"> <Branch Name="12.2(55)SE" Type="Service Pack"> <FullProductName ProductID="CVRFPID-103763">Cisco IOS 12.2SE 12.2(55)SE</FullProductName> </Branch> <Branch Name="12.2(55)SE3" Type="Service Pack"> <FullProductName ProductID="CVRFPID-105394">Cisco IOS 12.2SE 12.2(55)SE3</FullProductName> </Branch> <Branch Name="12.2(55)SE2" Type="Service Pack"> <FullProductName ProductID="CVRFPID-105689">Cisco IOS 12.2SE 12.2(55)SE2</FullProductName> </Branch> .... The above defines three products: CVRFPID-103763, CVRFPID-105394, and CVRFPID-105689. Each of these products has associated a "full product name", a "service pack", a "product name", a "product version", and a "vendor". The CVRF specification identifies additional attributes that can be defined in the "branches", however those attributes are not strictly hierarchical - architecture, host name, language, legacy, product family. This makes fitting them into the above structure awkward, at best. The underlying goal here is to associate a bunch of property values with a given product ID. In the most verbose form, the JSON form of the product definition for " CVRFPID-103763 " could just be: { "id": "CVRFPID-103763", "full_name": " Cisco IOS 12.2SE 12.2(55)SE", "service_pack": "12.2(55)SE", "version": "12.2SE", "name": "IOS", "vendor": "Cisco" } (Note that I removed "product" from attribute names, so instead of "product_name" it is just "name".) Keeping with the data model of CVRF, additional properties to allow here would include "architecture", "host_name", "language", "legacy", "product_family", "specification". Of course, we've also been talking about how to identify products uniquely, so "cpe", "swid", and "spdx" are good candidates for properties here as well. And of course, since it is JSON, we can allow for arbitrary vendor extensions here. So far, the proposed JSON definition of a product is a significant improvement over the XML of CVRF, because it has an obvious approach for extensibility, eliminates the arbitrary taxonomy for attributes that don't fit a taxonomy, and allows for multiple different software identity mechanisms. While the above form is explicit and flexible, it is also quite verbose. How do we eliminate the verbosity? Proposal is to allow for the definition of a "set" of attributes that can then be reused. A definition of a set of attributes for the above examples in XML: { "id": "ios-12.2SE", "vendor": "Cisco", "name" : "IOS", "version": "12.2SE" } The above defines three attributes that can be reused in association with a product definition Being able to combine attribute sets will further reduce duplication. So the full proposal is to allow "union" of attribute sets: { "id": "ios", "vendor": "Cisco", "name": "IOS", }, { "id": "ios-12.2SE", "union" : "ios", // this means share properties "vendor" is Cisco, name is "IOS". "version": "12.2SE" } Restating the original XML product descriptions using attribute sets: product_descriptions: [ { "attribute_set": "ios-12.2SE", "products": [ { "id": "CVRFPID-103763", "full_name": "Cisco IOS 12.2SE 12.2(55)SE", "service_pack": "12.2(55)SE", }, { "id": "CVRFPID-105394", "full_name": "Cisco IOS 12.2SE 12.2(55)SE3", "service_pack": "12.2(55)SE3", }, { "id": "CVRFPID-105689", "full_name": "Cisco IOS 12.2SE 12.2(55)SE2", "service_pack": "12.2(55)SE2", }, }, { "attribute_set": "ios-12.2EX", "products": [ ... ] } ] For discussion at our meeting tomorrow: Any objection to me changing the product tree in JSON to match what I describe above? Further enhancement ideas: "id" attribute is optional, if only one of swid, cpe, or spdx is provided, then the value of the one present is used as the "id". full_name - it strikes me that this field could be completely optional. The default might simply be to take the space-separated concatenation of the available attributes (excluding "id"). Eric.