Expand hardware support

[stevespringett]

CycloneDX has support for components of type 'device'. However, device-specific fields have been left out of the core specification as they are better suited as a schema extension.

This ticket describes a proposed schema extension that adds proper fields for describing physical devices.

[stevespringett]

The proposed namespace is: http://cyclonedx.org/schema/ext/device/1.0

[stevespringett]

Proposed fields include:

• EAN/UPC
• Global Trade Item Number (GTIN)
• Global Location Number (GLN)
• Global Individual Asset Identifier (GIAI)
• Global Model Number (GMN)
• EPC/RFID
• Serial Number
• SKU
• Lot number
• Production timestamp
• MAC Address

Instead of individual fields, it may be interesting to have a large enum of available hardward field types, and simply have key/value pairs within the hardware schema. Notice the use of OTHER. The idea is to provide as many types as possible knowing that it will be impossible to cover all types. This would allow built-in extensibility of the extension itself.

For example:

<components>
    <component type="device">
        <name>My Refrigerator</name>
        <version>Model A - Revision 2</version>
        <hw:metadata>
            <property key="SERIAL_NUMBER" value="12345"/>
            <property key="UPC" value="72527273070"/>
            <property key="LOT_NUMBER" value="11443"/>
            <property key="PRODUCTION_TIMESTAMP" value="2017-07-16T19:20+01:00"/>
            <property key="OTHER" name="QC_PERSON" value="Joe"/>
        <hw:metadata>
    </component>
</components>

[theCamelCaser]

Some nice ideas. I guess if we talk about hardware, we always talk about a closed system (like your fridge) with software - so no screws :) However, i want to throw some ideas in:

1. i guess it would be important to take FOTA in consideration. 1.1 this implementation with LOT_NUMBER may help with a 'native' product but my product will change in future

2. Products change over lifetime. 2.1 Maybe a component changes here or there(revisions) 2.3 Maybe a module in fw will be changed (switch on/off)

3. I miss the implementation details. 3.1 A vendor can create a device which is in general identical but software configuration differs for customer(aka the ecu for automotive ) 3.2 Features can be active or inactive for a specific version (aka buy your autopilot for your tesla) 3.3 A vendor need to adjust it product for the specific country (automotive engine restriction)

In general the threat models / attack vectors / whatsoever could change with a new combination of fw/hw

My ideas are:

Enduser Devices:

Your example with the fridge. The same fridge could have implementations details like network, display, camera. So maybe only my fridge with the HW Version 2, Software Version 123, and the network connection have the vulnerability x As mentioned the SN and LN will only help me partial.

My Refrigerator KGN39AI5 (smth like 'with network, 'with display') 2 123.4

but this example is somehow not relevant for vulnerability management. as enduser i am probably not interested in vulnerability management so i wont have a BoM of my home devices holding all information. In this case the vendor will find a vulnerability and will fix it with an updated. As vendor i am not interested in which person exactly own this devices is just send a over-the-air update. In B2B this maybe changes. As vendor i have an interest in informing my customers if they have a vulnerable devices (vendor A sells security cams to customer B). On the other hand my customer may have its own vulnerability management.

Supply Chain hardware:

An example from the automotive area. (I am no hw developer but i assume its not totally wrong) Since the ECU's are quite similar you can use a base ECU for different vendors, different engines and configuration. So you need an implementation for Vendor A, Model B, Engine C with HSM D, Configuration E (BMW G21 330i Germany). The combination of the Firmware includes HSM_version, Bootload_Version, Autosar-features and Autosar-configuration.

ECU XYZ abc def

I already had some discussions and we never find a proper solution in the end.

[stevespringett]

• FOTA should already be supported through the use of CycloneDX service definitions. The external service itself can be defined, data flow, etc, and of course firmware components can already be specified. If there are specific requirements necessary to capture FOTA-specific concerns, then proposals of those should be included in this ticket.
• Any change to a final goods (firmware update, ecu replacement due to recall, etc) results in a new SBOM. This is the approach that CycloneDX takes and its based on the guidance of NTIA. How this will impact FOTA is to be determined.
• Runtime behavior (e.g. configuration settings based on what a tesla customer pays for) is outside the scope of what an SBOM is designed to do. In most cases, the software is the same on every device and the manufacture may optionally enable or disable specific features based on subscription, market, or model number. Software that disables features based on these conditions usually already have the software necessary to have those features enabled already installed on the device. Thus, the SBOM describes ALL parts, software, etc, that are delivered in the final goods, regardless of whether features are enabled or not. If this is a use case the industry would like to have, I'd recommend and industry specific extension that accounts for runtime behavior or configuration settings. There has been some interest from others in attempting to capture config and runtime info, but I think it needs to be in a dedicated extension so that it's applicable and available to everyone, not just hardware use cases.
• For IoT devices, CycloneDX is compatible with Manufacture Usage Description (MUD) which allows devices to advertise their capabilities and their SBOM. Cisco and others are already experimenting with this capability which will likely find its way into enterprise and eventually consumer devices.

[stevespringett]

I ran across this paper which led me to the IPC-2570 (PDX package) standard. I don't know if this standard is still relevant or not, so may take a bit of investigation. The PDX standard seems to contain static facts such as inventory as well as dynamic facts such as approved manufactures lists. If the standard is still relevant, it may be possible to reuse the static parts of it so that the hardware extension can capture the factual data of what is delivered in a given device.

[stevespringett]

Due to issues with JSON extensibility (or lack thereof), extended support for hardware is being proposed as part of the core spec in v1.4.

[stevespringett]

Example implementation of proposed solution (in JSON):

{
  "bomFormat": "CycloneDX",
  "specVersion": "1.4",
  "serialNumber": "urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79",
  "version": 1,
  "components": [
    {
      "type": "device",
      "name": "acme-iot-toaster",
      "version": "model 1",
      "deviceInfo": {
        "quantity": 1,
        "function": "Bluetooth, network, storage, microprocessor, connector, etc",
        "location": "Location on the board, related daughterboards",
        "deviceType": "type of component such as SMD, thru-hole, etc",
        "serialNumber": "Unique identifier using serial number if available",
        "sku": "Internal inventory reference if available",
        "lotNumber": "Lot or batch identification for the component",
        "prodTimestamp": "Production timestamp for the component",
        "macAddress": "Hardware address for network interfaces",
        "certifications" : [
          {
            "authority": "FCC",
            "id": "Identifier for radio components",
            "url": "URL to certification details"
          }
        ],
        "eanUpc": "EAN/UPC barcodes are printed on virtually every consumer product in the world.",
        "gtin": "Global Trade Identification Number (GTIN)",
        "gln": "Global Location Number (GLN)",
        "giai": "Global Individual Asset Identifier (GIAI)",
        "gmn": "Global Model Number (GMN)",
        "epcRfid": "EPC/RFID"
      }
    }
  ]
}

There may also be a desire to have physical location of the hardware manufacturer and where the programming takes place. We might be able to use the existing support for OrganizationalEntity here.

We might also be able to move prodTimestamp to the component object itself, as it would allow us to specify when a software or hardware component was created or manufactured.

[stevespringett]

Is GTIN and EAN/UPC the same thing?

According to https://feedonomics.com/blog/what-is-the-relationship-between-a-gtin-upc-isbn-asin/

GTIN stands for Global Tracking ID Number. This is a family of data structures. The number that is encoded into a barcode is the GTIN. The type of barcode can be UPC or EAN or ISBN

The GTIN-12 is used in the United States and Canada and is encoded into a 12-digit UPC (Universal Product Code) Barcodes. The GTIN-13 is used outside of the United States and Canada and is encoded as an EAN-13.

Should deviceInfo support gtin in a generic sense, or should it support very specific types?

[coderpatros]

EAN/UPC are just ways of representing the GTINs as a barcode. I guess you could think of EAN/UPC as a serialization format.

I have some serious reservations about expanding hardware support, as represented above, and incorporating it into the core spec.

A lot of software component information is the same regardless of industry or country. But, IMHO, with hardware there will be a lot of industry/country specific variations.

I think a lot of the above information would be more cleanly handled with an official property name. i.e. cdx:device:gtin-12

Either way, I think we probably need to identify some industries, i.e. telecommunications, networking, medical, energy, defense, consumer and seek the right industry specific feedback (that shouldn't be that hard, I think we could easily come up with a list of people we should reach out to)

Currently, my vote would be that anything that is industry/country specific is handled by properties. And the more universal hardware information, i.e. MAC address, could be incorporated into the core spec (although that's perhaps a bad example, hardware devices can have multiple MAC addresses)

[stevespringett]

Currently, my vote would be that anything that is industry/country specific is handled by properties. And the more universal hardware information, i.e. MAC address, could be incorporated into the core spec

I like that approach as I believe it aligns to the projects guiding principals AND would provide a way to add more industry-specific capabilities to the spec without requiring an updated version of the spec. Win-Win.

although that's perhaps a bad example, hardware devices can have multiple MAC addresses

As far as I know, a NIC can only have a single MAC address, although multiple NICs could be incorporated into a device and the resulting device could then have multiple MAC addresses. Is there an example where this is not the case?

[coderpatros]

As far as I know, a NIC can only have a single MAC address, although multiple NICs could be incorporated into a device and the resulting device could then have multiple MAC addresses. Is there an example where this is not the case?

Yeah I think that's correct. I was just thinking of an industrial router I was messing around with the other day that had a MAC address for the LAN, WAN and bluetooth interfaces. It also had dual SIM cards, but I think MAC addresses are dynamically allocated when it comes to 4G LTE.

In the above example, the MAC address seems to be at the assembled IoT Toaster device level. Surely you're not going to purchase an IOT Toaster that doesn't at least support wifi and bluetooth as a minimum :stuck_out_tongue_winking_eye:

But that raises an interesting point. MAC addresses are only relevant for particular classes of hardware components.

[stevespringett]

But that raises an interesting point. MAC addresses are only relevant for particular classes of hardware components.

Fair point. I think we need some insight into the types of devices that are commonly used in hardware supporting software stacks. I would imagine that MAC addresses for NICs, WiFi, and Bluetooth would be a common type of device. But I'm making an assumption without empirical data.

Currently, my vote would be that anything that is industry/country specific is handled by properties

Agreed. And developing a taxonomy of device specific properties can evolve independently from the spec.

[stevespringett]

The more people I talk with about MBOM use cases, the more I'm leaning towards building up a formal taxonomy of device information rather than incorporating it into the core spec. We can support hardware via properties as long as we have a formal naming taxonomy. This will allow us to increase support over time and independent of the spec.

Thoughts?

[coderpatros]

Yeah, I don't have enough hardware experience to have a strong opinion on this. But that's what I was thinking too.