Re: [csaf] Re: Contemplating how to describe products in JSON.
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
<>
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
<> 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.