Discovering and Retrieving Software Transparency and Vulnerability Information
Eliot Lear
Cisco Systems
Richtistrasse 7
Wallisellen
CH-8304
Switzerland
+41 44 878 9200
lear@cisco.com
Scott Rose
NIST
100 Bureau Dr
Gaithersburg MD
20899
USA
+1 301-975-8439
scott.rose@nist.gov
13 September 2022
Internet-Draft
To improve cybersecurity posture, automation is necessary to locate what software is running on a device, whether that software has known vulnerabilities, and what, if any recommendations suppliers may have. This memo specifies a model to provide access to this information. It may optionally be discovered through manufacturer usage descriptions.
Introduction
A number of activities have been working to improve visibility to what software is running on a system, and what vulnerabilities that software may have[EO2021].
Put simply, we seek to answer two classes of questions at scale:
- Is this system vulnerable to a particular vulnerability?
- Which devices in a particular environment contain vulnerabilities that require some action?
This memo doesn't specify the format of this information, but rather only how to locate and retrieve these objects.
Software bills of materials (SBOMs) are descriptions of what software, including versioning and dependencies, a device contains. There are different SBOM formats such as Software Package Data Exchange [SPDX] or CycloneDX[CycloneDX12].
System vulnerabilities may similarly be described using several data formats, including the aforementioned CycloneDX, Common Vulnerability Reporting Framework [CVRF], the Common Security Advisory Format [CSAF]. This information is typically used to report to administrators the state of a system.
These two classes of information can be used in concert. For instance, a network management tool may discover that a system makes use of a particular software component that has a known vulnerability, and a vulnerability report may be used to indicate what if any versions of software correct that vulnerability, or whether the system exercises the vulnerable code at all.
Both classes of information elements are optional under the model specified in this memo. One can provide only an SBOM, only vulnerability information, or both an SBOM and vulnerability information.
Note that SBOM formats may also carry other information, the most common being any licensing terms. Because this specification is neutral regarding content, it is left for format developers such as the Linux Foundation, OASIS, and ISO to decide what attributes they will support.
This memo does not specify how vulnerability information may be retrieved directly from the endpoint. That's because vulnerability information changes occur at different rates to software updates. However, some SBOM formats may also contain vulnerability information.
SBOMs and vulnerability information are advertised and retrieved through the use of a YANG augmentation of the Manufacturer User Description (MUD) model [RFC8520]. Note that the schema creates a grouping that can also be used independently of MUD. Moreover, other MUD features, such as access controls, needn't be present.
The mechanisms specified in this document are meant to satisfy several use cases:
- A network-layer management system retrieving information from an IoT device as part of its ongoing lifecycle. Such devices may or may not have query interfaces available.
- An application-layer management system retrieving vulnerability or SBOM information in order to evaluate the posture of an application server of some form. These application servers may themselves be containers or hypervisors. Discovery of the topology of a server is beyond the scope of this memo.
To satisfy these two key use cases, objects may be found in one of three ways:
- on devices themselves
- on a web site (e.g., via URI)
- through some form of out-of-band contact with the supplier.
In the first case, devices will have interfaces that permit direct retrieval. Examples of these interfaces might be an HTTP [RFC9110], or COAP [RFC7252] endpoint for retrieval. There may also be private interfaces as well.
In the second case, when a device does not have an appropriate retrieval interface, but one is directly available from the manufacturer, a URI to that information MUST be discovered.
In the third case, a supplier may wish to make an SBOM or vulnerability information available under certain circumstances, and may need to individually evaluate requests. The result of that evaluation might be the SBOM or vulnerability itself or a restricted URL or no access.
To enable application-layer discovery, this memo defines a well-known URI [RFC8615]. Management or orchestration tools can query this well-known URI to retrieve a system's SBOM or vulnerability information. Further queries may be necessary based on the content and structure of the response.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
How This Information Is Retrieved
For devices that can emit a URL or can establish a well-known URI, the mechanism may be highly automated. For devices that have a URL in either their documentation or within a QR code on a box, the mechanism is semi-automated (someone has to scan the QR code or enter the URL).
Note that vulnerability and SBOM information is likely to change at different rates. The MUD semantics provide a way for manufacturers to control how often tooling should check for those changes through the cache-validity node.
Formats
There are multiple ways to express both SBOMs and vulnerability information. When these are retrieved either directly from the device or directly from a web server, tools will need to observe the content-type header to determine precisely which format is being transmitted. Because IoT devices in particular have limited capabilities, use of a specific Accept: header in HTTP or the Accept Option in CoAP is NOT RECOMMENDED. Instead, backend tooling is encouraged to support all known formats, and SHOULD silently discard SBOM information sent with a media type that is not understood.
Some formats may support both vulnerability and software inventory information. When both vulnerability and software inventory information is available from the same location, both sbom and vuln nodes MUST indicate that. Network management systems retrieving this information MUST take note that the identical resource is being retrieved rather than retrieving it twice.
Discussion points
The following is discussion to be removed at time of RFC publication.
- Is the model structured correctly?
- Are there other retrieval mechanisms that need to be specified?
- Do we need to be more specific in how to authenticate and retrieve SBOMs?
- What are the implications if the MUD URL is an extension in a certificate (e.g. an IDevID cert)?
The well-known transparency endpoint set
Two well known endpoint is defined:
- "/.well-known/sbom" retrieves an SBOM.
As discussed previously, the precise format of a response is based on the Content-type provided.
The mud-transparency extension model extension
We now formally define this extension. This is done in two parts. First, the extension name "transparency" is listed in the "extensions" array of the MUD file. N.B., this schema extension is intended to be used wherever it might be appropriate (e.g., not just MUD).
Second, the "mud" container is augmented with a list of SBOM sources.
This is done as follows:

module: ietf-mud-transparency

  augment /mud:mud:
    +--rw transparency
       +--rw (sbom-retrieval-method)?
       |  +--:(cloud)
       |  |  +--rw sboms* [version-info]
       |  |     +--rw version-info    string
       |  |     +--rw sbom-url?       inet:uri
       |  +--:(local-well-known)
       |  |  +--rw sbom-local-well-known?   identityref
       |  +--:(sbom-contact-info)
       |     +--rw sbom-contact-uri?        inet:uri
       +--rw archive-list?                  inet:uri
       +--rw (vuln-retrieval-method)?
          +--:(cloud)
          |  +--rw vuln-url?                inet:uri
          +--:(vuln-contact-info)
             +--rw contact-uri?             inet:uri

See [RFC8340] for a description of YANG trees.
The mud-sbom augmentation to the MUD YANG model

<CODE BEGINS>file "ietf-mud-transparency@2022-09-02.yang"
module ietf-mud-transparency {
  yang-version 1.1;
  namespace "urn:ietf:params:xml:ns:yang:ietf-mud-transparency";
  prefix mudtx;

  import ietf-inet-types {
    prefix inet;
    reference
      "RFC 6991";
  }
  import ietf-mud {
    prefix mud;
    reference
      "RFC 8520";
  }

  organization
    "IETF OPSAWG (Ops Area) Working Group";
  contact
    "WG Web: http://datatracker.ietf.org/wg/opsawg/
     WG List: opsawg@ietf.org

     Editor: Eliot Lear lear@cisco.com
     Editor: Scott Rose scott.rose@nist.gov";
  description
    "This YANG module augments the ietf-mud model to provide for
     reporting of SBOMs and vulnerability information.

     Copyright (c) 2022 IETF Trust and the persons identified as
     authors of the code.  All rights reserved.

     Redistribution and use in source and binary forms, with or
     without modification, is permitted pursuant to, and subject to
     the license terms contained in, the Revised BSD License set
     forth in Section 4.c of the IETF Trust's Legal Provisions
     Relating to IETF Documents
     (https://trustee.ietf.org/license-info).

     This version of this YANG module is part of RFC XXXX
     (https://www.rfc-editor.org/info/rfcXXXX);
     see the RFC itself for full legal notices.

     The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL
     NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED',
     'MAY', and 'OPTIONAL' in this document are to be interpreted as
     described in BCP 14 (RFC 2119) (RFC 8174) when, and only when,
     they appear in all capitals, as shown here.  ";

  revision 2022-09-01 {
    description
      "Initial proposed standard.";
    reference
      "RFC XXXX: Discovering and Retrieving Software Transparency
       and Vulnerability Information";
  }

  identity local-type {
    description
      "Base identity for local-well-known choices";
  }

  identity http {
    base mudtx:local-type;
    description
      "Use http (insecure) to retrieve SBOM information.  This
        method is NOT RECOMMENDED, but may be unavoidable for
        certain classes of deployment, where TLS has not or
        cannot be implemented";
  }

  identity https {
    base mudtx:local-type;
    description
      "Use https (secure) to retrieve SBOM information.";
  }

  identity coap {
    base mudtx:local-type;
    description
      "Use COAP [RFC7252] (insecure) to retrieve SBOM.  This method
       is NOT RECOMMENDED, although it may be unavoidable
       for certain classes of implementations/deployments.";
  }

  identity coaps {
    base mudtx:local-type;
    description
      "Use COAPS (secure) to retrieve SBOM";
  }

  grouping transparency-extension {
    description
      "This grouping provides a means to describe the location of
       software bills of material and vulnerability descriptions.";
    container transparency {
      description
        "container of methods to get an SBOM.";
      choice sbom-retrieval-method {
        description
          "How to find SBOM information";
        case cloud {
          list sboms {
            key "version-info";
            description
              "A list of SBOMs tied to different software
               or hardware versions.";
            leaf version-info {
              type string;
              description
                "The version to which this SBOM refers.";
            }
            leaf sbom-url {
              type inet:uri;
              description
                "A statically located URL.";
            }
          }
        }
        case local-well-known {
          leaf sbom-local-well-known {
            type identityref {
              base mudtx:local-type;
            }
            description
              "Which communication protocol to choose.";
          }
        }
        case sbom-contact-info {
          leaf sbom-contact-uri {
            type inet:uri {
              pattern '((mailto)|(https?)|(tel)):.*';
            }
            description
              "This MUST be either a tel, http, https, or
               mailto uri schema that customers can use to
               contact someone for SBOM information.";
          }
        }
      }
      leaf archive-list {
        type inet:uri;
        description
          "This URI returns a JSON list of URLs that consist of
                  SBOMs that were previously published for this
                  device.  Publication dates can found inside
                  the SBOMs.";
      }
      choice vuln-retrieval-method {
        description
          "How to find vulnerability information";
        case cloud {
          leaf vuln-url {
            type inet:uri;
            description
              "A statically located URL.";
          }
        }
        case vuln-contact-info {
          leaf contact-uri {
            type inet:uri;
            description
              "This MUST be either a tel, http, https, or
               mailto uri schema that customers can use to
               contact someone for vulnerability information.";
          }
        }
      }
    }
  }

  augment "/mud:mud" {
    description
      "Add extension for software transparency.";
    uses transparency-extension;
  }
}
<CODE ENDS>

Examples
In this example MUD file that uses a cloud service, the modelX presents a location of the SBOM in a URL. Note, the ACLs in a MUD file are NOT required, although they are a very good idea for IP-based devices.
Without ACLS
This first MUD file demonstrates how to get SBOM and vulnerability information without ACLs.

{
  "ietf-mud:mud": {
    "mud-version": 1,
    "extensions": [
      "ol",
      "transparency"
    ],
    "ol": {
      "owners": [
        "Copyright (c) Example, Inc. 2022. All Rights Reserved"
      ],
      "spdx-tag": "0BSD"
    },
    "mudtx:transparency": {
      "sbom-local-well-known": "https",
      "vuln-url": "https://iot.example.com/info/modelX/csaf.json"
    },
    "mud-url": "https://iot.example.com/modelX.json",
    "mud-signature": "https://iot.example.com/modelX.p7s",
    "last-update": "2022-01-05T13:29:12+00:00",
    "cache-validity": 48,
    "is-supported": true,
    "systeminfo": "retrieving vuln and SBOM info via a cloud service",
    "mfg-name": "Example, Inc.",
    "documentation": "https://iot.example.com/doc/modelX",
    "model-name": "modelX"
  }
}

The second example demonstrates that just SBOM information is included.

{
  "ietf-mud:mud": {
    "mud-version": 1,
    "extensions": [
      "ol",
      "transparency"
    ],
    "ol": {
      "owners": [
        "Copyright (c) Example, Inc. 2022. All Rights Reserved"
      ],
      "spdx-tag": "0BSD"
    },
    "mudtx:transparency": {
      "sbom-local-well-known": "https"
    },
    "mud-url": "https://iot.example.com/modelX.json",
    "mud-signature": "https://iot.example.com/modelX.p7s",
    "last-update": "2022-01-05T13:29:47+00:00",
    "cache-validity": 48,
    "is-supported": true,
    "systeminfo": "retrieving vuln and SBOM info via a cloud service",
    "mfg-name": "Example, Inc.",
    "documentation": "https://iot.example.com/doc/modelX",
    "model-name": "modelX"
  }
}

SBOM Located on the Device
In this example, the SBOM is retrieved from the device, while vulnerability information is available from the cloud. This is likely a common case, because vendors may learn of vulnerability information more frequently than they update software.

{
  "ietf-mud:mud": {
    "mud-version": 1,
    "extensions": [
      "transparency"
    ],
    "mudtx:transparency": {
      "sbom-local-well-known": "https",
      "vuln-url": "https://iot-device.example.com/info/modelX/csaf.json"
    },
    "mud-url": "https://iot-device.example.com/modelX.json",
    "mud-signature": "https://iot-device.example.com/modelX.p7s",
    "last-update": "2022-01-05T13:25:14+00:00",
    "cache-validity": 48,
    "is-supported": true,
    "systeminfo": "retrieving vuln and SBOM info via a cloud service",
    "mfg-name": "Example, Inc.",
    "documentation": "https://iot-device.example.com/doc/modelX",
    "model-name": "modelX"
  }
}

Further contact required.
In this example, the network manager must take further steps to retrieve SBOM information. Vulnerability information is still available.

{
 "ietf-mud:mud": {
  "mud-version": 1,
  "extensions": [
    "transparency"
  ],
  "ietf-mud-transparency:transparency": {
    "contact-info": "https://iot-device.example.com/contact-info.html",
    "vuln-url": "https://iot-device.example.com/info/modelX/csaf.json"
  },
  "mud-url": "https://iot-device.example.com/modelX.json",
  "mud-signature": "https://iot-device.example.com/modelX.p7s",
  "last-update": "2021-07-09T06:16:42+00:00",
  "cache-validity": 48,
  "is-supported": true,
  "systeminfo": "retrieving vuln and SBOM info via a cloud service",
  "mfg-name": "Example, Inc.",
  "documentation": "https://iot-device.example.com/doc/modelX",
  "model-name": "modelX"
 }
}

With ACLS
Finally, here is a complete example where the device provides SBOM and vulnerability information, as well as access-control information.

{
  "ietf-mud:mud": {
    "mud-version": 1,
    "extensions": [
      "ol",
      "transparency"
    ],
    "ol": {
      "owners": [
        "Copyright (c) Example, Inc. 2022. All Rights Reserved"
      ],
      "spdx-tag": "0BSD"
    },
    "mudtx:transparency": {
      "sbom-local-well-known": "https",
      "vuln-url": "https://iot.example.com/info/modelX/csaf.json"
    },
    "mud-url": "https://iot.example.com/modelX.json",
    "mud-signature": "https://iot.example.com/modelX.p7s",
    "last-update": "2022-01-05T13:30:31+00:00",
    "cache-validity": 48,
    "is-supported": true,
    "systeminfo": "retrieving vuln and SBOM info via a cloud service",
    "mfg-name": "Example, Inc.",
    "documentation": "https://iot.example.com/doc/modelX",
    "model-name": "modelX",
    "from-device-policy": {
      "access-lists": {
        "access-list": [
          {
            "name": "mud-65443-v4fr"
          }
        ]
      }
    },
    "to-device-policy": {
      "access-lists": {
        "access-list": [
          {
            "name": "mud-65443-v4to"
          }
        ]
      }
    }
  },
  "ietf-access-control-list:acls": {
    "acl": [
      {
        "name": "mud-65443-v4to",
        "type": "ipv4-acl-type",
        "aces": {
          "ace": [
            {
              "name": "cl0-todev",
              "matches": {
                "ipv4": {
                  "ietf-acldns:src-dnsname": "iotserver.example.com"
                }
              },
              "actions": {
                "forwarding": "accept"
              }
            }
          ]
        }
      },
      {
        "name": "mud-65443-v4fr",
        "type": "ipv4-acl-type",
        "aces": {
          "ace": [
            {
              "name": "cl0-frdev",
              "matches": {
                "ipv4": {
                  "ietf-acldns:dst-dnsname": "iotserver.example.com"
                }
              },
              "actions": {
                "forwarding": "accept"
              }
            }
          ]
        }
      }
    ]
  }
}

At this point, the management system can attempt to retrieve the SBOM, and determine which format is in use through the content-type header on the response to a GET request, independently repeat the process for vulnerability information, and apply ACLs, as appropriate.
Security Considerations
The YANG module specified in this document defines a schema for data that is designed to be accessed via network management protocols such as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer is the secure transport layer, and the mandatory-to-implement secure transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer is HTTPS, and the mandatory-to-implement secure transport is TLS [RFC8446].
N.B., for MUD, the mandatory method of retrieval is TLS.
The Network Configuration Access Control Model (NACM) [RFC8341] provides the means to restrict access for particular NETCONF or RESTCONF users to a preconfigured subset of all available NETCONF or RESTCONF protocol operations and content.
There are a number of data nodes defined in this YANG module that are writable/creatable/deletable (i.e., config true, which is the default). These data nodes may be considered sensitive or vulnerable in some network environments. Write operations (e.g., edit-config) to these data nodes without proper protection can have a negative effect on network operations. These are the subtrees and data nodes and their sensitivity/vulnerability:
The ietf-mud-transparency module has no operational impact on the element itself, and is used to discover state information that may be available on or off the element. In as much as the module itself is made writeable, this only indicates a change in how to retrieve read-only elements. There is no means, for instance, to upload an SBOM. Additional risks are discussed below, and are applicable to all nodes within the transparency container.
If an attacker modifies the elements, they may misdirect automation to retrieve a different set of URLs than was intended by the designer. This in turn leads to two specific sets of risks:
- the information retrieved would be false.
- the URLs themselves point to malware.
To address either risk, any change in a URL, and in particular to the authority section, should be treated with some suspicion. One mitigation would be to test any cloud-based URL against a reputation service.
Some of the readable data nodes in this YANG module may be considered sensitive or vulnerable in some network environments. It is thus important to control read access (e.g., via get, get-config, or notification) to these data nodes. These are the subtrees and data nodes and their sensitivity/vulnerability:
SBOMs provide an inventory of software. If software is available to an attacker, the attacker may well already be able to derive this very same software inventory. Manufacturers MAY restrict access to SBOM information using appropriate authorization semantics within HTTP. In particular, if a system attempts to retrieve an SBOM via HTTP and the client is not authorized, the server MUST produce an appropriate error, with instructions on how to register a particular client. One example may be to issue a certificate to the client for this purpose after a registration process has taken place. Another example would involve the use of OAUTH in combination with a federations of SBOM servers.
Another risk is a skew in the SBOM listing and the actual software inventory of a device/container. For example, a manufacturer may update the SBOM on its server, but an individual device has not been upgraded yet. This may result in an incorrect policy being applied to a device. A unique mapping of a device's software version and its SBOM can minimize this risk.
To further mitigate attacks against a device, manufacturers SHOULD recommend access controls.
Vulnerability information is generally made available to such databases as NIST's National Vulnerability Database. It is possible that vendor may wish to release information early to some customers. We do not discuss here whether that is a good idea, but if it is employed, then appropriate access controls and authorization SHOULD be applied to the vulnerability resource.
IANA Considerations
MUD Extension
The IANA is requested to add "transparency" to the MUD extensions registry as follows:

  Extension Name: transparency
  Standard reference: This document

YANG Registration
The following YANG module should be registered in the "YANG Module Names" registry:

   Name: ietf-mud
   URN: urn:ietf:params:xml:ns:yang:ietf-mud-transparency
   Prefix: mudtx
   Registrant contact: The IESG
   Reference: This memo

The following XML registration is requested:

   URI: urn:ietf:params:xml:ns:yang:ietf-mud-transparency
   Registrant Contact: IESG
   XML: None.  Namespace URIs do not represent an XML specification.

Well-Known Prefix
The following well known URI is requested in accordance with [RFC8615]:
~~~~~~
URI suffix: "sbom" Change controller: "IETF" Specification document: This memo Related information: See ISO/IEC 5962:2021 and SPDX.org
~~~~~~
Acknowledgments
Thanks to Russ Housley, Dick Brooks, Tom Petch, Nicolas Comstedt, who provided review comments.

Normative References
[RFC2119]

Key words for use in RFCs to Indicate Requirement Levels
S. Bradner
March 1997
BCP 14
RFC 2119
DOI 10.17487/RFC2119
[RFC6241]

Network Configuration Protocol (NETCONF)
R. Enns, Ed.
M. Bjorklund, Ed.
J. Schoenwaelder, Ed.
A. Bierman, Ed.
June 2011
RFC 6241
DOI 10.17487/RFC6241
[RFC6242]

Using the NETCONF Protocol over Secure Shell (SSH)
M. Wasserman
June 2011
RFC 6242
DOI 10.17487/RFC6242
[RFC6991]

Common YANG Data Types
J. Schoenwaelder, Ed.
July 2013
RFC 6991
DOI 10.17487/RFC6991
[RFC7252]

The Constrained Application Protocol (CoAP)
Z. Shelby
K. Hartke
C. Bormann
June 2014
RFC 7252
DOI 10.17487/RFC7252
[RFC8040]

RESTCONF Protocol
A. Bierman
M. Bjorklund
K. Watsen
January 2017
RFC 8040
DOI 10.17487/RFC8040
[RFC8341]

Network Configuration Access Control Model
A. Bierman
M. Bjorklund
March 2018
STD 91
RFC 8341
DOI 10.17487/RFC8341
[RFC8446]

The Transport Layer Security (TLS) Protocol Version 1.3
E. Rescorla
August 2018
RFC 8446
DOI 10.17487/RFC8446
[RFC8174]

Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words
B. Leiba
May 2017
BCP 14
RFC 8174
DOI 10.17487/RFC8174
[RFC8520]

Manufacturer Usage Description Specification
E. Lear
R. Droms
D. Romascanu
March 2019
RFC 8520
DOI 10.17487/RFC8520
[RFC8615]

Well-Known Uniform Resource Identifiers (URIs)
M. Nottingham
May 2019
RFC 8615
DOI 10.17487/RFC8615

Informative References
[RFC9110]

HTTP Semantics
R. Fielding, Ed.
M. Nottingham, Ed.
J. Reschke, Ed.
June 2022
STD 97
RFC 9110
DOI 10.17487/RFC9110
[EO2021]

Executive Order 14028, Improving the Nations Cybersecurity
President Joseph Biden
United States Of America
May 2021
[SPDX]

SPDX Specification V2.3
The Linux Foundation
2022
[CycloneDX12]

CycloneDX XML Reference v1.2
cylonedx.org
May 2020
[CSAF]

Common Security Advisory Format
OASIS
July 2021
[CVRF]

Common Vulnerability Reporting Framework (CVRF) Version 1.2
Omar Santos, Ed.
OASIS
September 2017
[RFC8340]

YANG Tree Diagrams
M. Bjorklund
L. Berger, Ed.
March 2018
BCP 215
RFC 8340
DOI 10.17487/RFC8340
Changes from Earlier Versions
Draft -04: * Address review comments
Draft -02:
- include vulnerability information
Draft -01:
- some modest changes
Draft -00:
- Initial revision