RFC 8412
Software Inventory Message and Attributes (SWIMA) for PA-TNC
Software Inventory Message and Attributes (SWIMA) for PA-TNC 💖
okay bestie, so this is RFC 8412 🦋 It's titled Software Inventory Message and Attributes (SWIMA) for PA-TNC, it's from the Internet Engineering Task Force (IETF), and it was published in July 2018. It's on the Standards Track (ISSN 2070-1721), and its header doesn't have an "Obsoletes" or "Updates" line, so it doesn't replace or update any other RFC 🌸
Five authors wrote it, and they're all giving serious brain 🧠✨ C. Schmidt, D. Haynes, and C. Coffin are from The MITRE Corporation. D. Waltermire is from the National Institute of Standards and Technology. J. Fitzgerald-McKay is from the United States National Security Agency. Iconic team 👑
Abstract 💅
so the abstract is basically the pitch 🎀 This document builds on "PA-TNC: A Posture Attribute (PA) Protocol Compatible with Trusted Network Connect (TNC)" (RFC 5792). It adds specific attributes and message exchanges so that endpoints can report their installed software inventory information to a NEA Server, which is defined in "Network Endpoint Assessment (NEA): Overview and Requirements" (RFC 5209). The vibe is: endpoints tell the server what software they have installed, and the protocol makes that possible 💜
Status of This Memo 🎀
this one's a Internet Standards Track document 🔥 Like, it's officially on the standards path, not just a casual draft.
it's a product of the Internet Engineering Task Force (IETF) 🌈 It represents the consensus of the IETF community, and it went through public review and got approved for publication by the Internet Engineering Steering Group (IESG). If you want more info on Internet Standards, check out Section 2 of RFC 7841 📚
for the current status of this document, any errata, and how to give feedback on it, go to https://www.rfc-editor.org/info/rfc8412 🧚
Copyright Notice 🌈
copyright is 2018, held by the IETF Trust and the people listed as the document's authors, with all rights reserved 🦋
this document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info), as they stood on the day it was published. please read those carefully, because they explain what you can and can't do with this document 🫶
one important bit: any Code Components pulled out of this document must include Simplified BSD License text, as described in Section 4.e of the Trust Legal Provisions. They also come with no warranty, as described in the Simplified BSD License 💀
Table of Contents 🧚
1. Introduction ....................................................4
1.1. Network Endpoint Assessment (NEA) ..........................6
1.2. Conventions Used in This Document ..........................7
1.3. Definitions ................................................7
2. Background ......................................................8
2.1. Supported Use Cases ........................................8
2.1.1. Use Software Inventory as an Access Control Factor ..8
2.1.2. Central Stores of Up-to-Date Endpoint
Software Inventory Data .............................9
2.1.3. PA-TNC Use Cases ....................................9
2.2. Use Cases That Are Not Supported ...........................9
2.3. SWIMA Requirements ........................................10
2.4. Non-SWIMA Requirements ....................................11
2.5. Assumptions ...............................................12
2.6. Assumptions Not Made ......................................12
3. System Requirements ............................................12
3.1. Data Sources ..............................................13
3.2. Data Models ...............................................14
3.3. Basic Attribute Exchange ..................................16
3.4. Core Software-Reporting Information .......................17
3.4.1. Software Identifiers ...............................17
3.4.2. Data Model Type ....................................19
3.4.3. Record Identifiers .................................19
3.4.4. Software Locators ..................................20
3.4.5. Source Identifiers .................................21
3.4.6. Using Software and Record Identifiers in
SWIMA Attributes ...................................22
3.5. Targeted Requests .........................................22
3.6. Monitoring Changes in an Endpoint's Software
Inventory Evidence Collection .............................23
3.7. Reporting Change Events ...................................26
3.7.1. Event Identifiers ..................................27
3.7.2. Core Event-Tracking Information ....................28
3.7.3. Updating Inventory Knowledge Based on Events .......29
3.7.4. Using Event Records in SWIMA Attributes ............29
3.7.5. Partial and Complete Lists of Event Records
in SWIMA Attributes ................................30
3.7.6. Synchronizing Event Identifiers and Epochs .........32
3.8. Subscriptions .............................................33
3.8.1. Establishing Subscriptions .........................34
3.8.2. Managing Subscriptions .............................35
3.8.3. Terminating Subscriptions ..........................36
3.8.4. Subscription Status ................................36
3.8.5. Fulfilling Subscriptions ...........................37
3.8.5.1. Subscriptions That Report Inventories .....38
3.8.5.2. Subscriptions That Report Events ..........38
3.8.5.3. Targeted Subscriptions ....................40
3.8.5.4. No Subscription Consolidation .............40
3.8.5.5. Delayed Subscription Fulfillment ..........41
3.9. Error Handling ............................................41
4. Protocol .......................................................43
4.1. Direct Response to a SWIMA Request ........................44
4.2. Subscription-Based Response ...............................45
4.3. Required Exchanges ........................................45
5. Software Inventory Messages and Attributes .....................46
5.1. PA Subtype (aka PA-TNC Component Type) ....................46
5.2. SWIMA Attribute Overview ..................................46
5.3. Message Diagram Syntax ....................................48
5.4. Normalization of Text Encoding ............................49
5.5. Request IDs ...............................................49
5.6. SWIMA Request .............................................50
5.7. Software Identifier Inventory .............................54
5.8. Software Identifier Events ................................58
5.9. Software Inventory ........................................64
5.10. Software Events ..........................................67
5.11. Subscription Status Request ..............................72
5.12. Subscription Status Response .............................73
5.13. Source Metadata Request ..................................75
5.14. Source Metadata Response .................................76
5.15. PA-TNC Error as Used by SWIMA ............................78
5.15.1. SWIMA_ERROR, SWIMA_SUBSCRIPTION_DENIED_ERROR, and
SWIMA_SUBSCRIPTION_ID_REUSE_ERROR Information .....81
5.15.2. SWIMA_RESPONSE_TOO_LARGE_ERROR Information ........83
5.15.3. SWIMA_SUBSCRIPTION_FULFILLMENT_ERROR Information ..85
6. Supported Data Models ..........................................87
6.1. ISO 2015 SWID Tags Using XML ..............................87
6.1.1. Guidance on Normalizing Source Data to ISO 2015
SWID Tags Using XML ................................87
6.1.2. Guidance on Creation of Software Identifiers from
ISO 2015 SWID Tags .................................88
6.2. ISO 2009 SWID Tags Using XML ..............................88
6.2.1. Guidance on Normalizing Source Data to ISO 2009
SWID Tags Using XML ................................88
6.2.2. Guidance on Creation of Software Identifiers from
ISO 2009 SWID Tags .................................89
7. Relationship to Other Specifications ...........................89
8. Security Considerations ........................................90
8.1. Evidentiary Value of Software Inventory Evidence Records ..90
8.2. Sensitivity of Collected Records ..........................91
8.3. Integrity of Endpoint Records .............................92
8.4. SWIMA-PC Access Permissions ...............................92
8.5. Sanitization of Record Fields .............................93
8.6. PA-TNC Security Threats ...................................93
9. Privacy Considerations .........................................93
10. IANA Considerations ...........................................94
10.1. Guidance for the Designated Experts ......................94
10.2. PA Subtypes ..............................................95
10.3. PA-TNC Attribute Types ...................................96
10.4. PA-TNC Error Codes .......................................97
10.5. Software Data Model Types ................................97
11. References ....................................................98
11.1. Normative References .....................................98
11.2. Informative References ...................................99
Authors' Addresses ...............................................1011. Introduction ✨
okay so knowing what software is installed on endpoints is lowkey essential for keeping a network secure 🔐 like, if an enterprise policy says certain software MUST be there and other software MUST NOT be there, reported installs can prove you're compliant (or not 💀). inventories can also show whether an endpoint is exposed to attacks by comparing vulnerability or threat alerts against each app's patch level. these are some seriously main character management use cases 💅
Software Inventory Message and Attributes (SWIMA) for PA-TNC (see "PA-TNC: A Posture Attribute (PA) Protocol Compatible with Trusted Network Connect (TNC)" [RFC5792]) gives everyone a standard way to swap software inventory data, including a unique Software Identifier tied to a specific version of a product 🎀 it can also carry extra metadata about those products. SWIMA lets software identification, installation, and characterization info get sent to a central server from any endpoint that supports this spec ✨ that info can come from tons of places: tag files (like ISO Software Identification (SWID) tags [SWID15]), reports from third-party inventory tools, package manager output, and more 🧚 SWIMA doesn't decide how software gets detected. it relies on a set of "data sources" to tell it what's installed, and it's a flexible transport that carries that info no matter how it's written 💖
this spec only reports software that's installed on a target endpoint. it does NOT monitor or report what's running 🙈 (ok fine, it's not "MUST NOT" here, that's the original's point: it is not intended to do that). it's also not meant to report individual files, libraries, installation packages, or similar artifacts. those things are useful too, but they need different metadata and monitoring methods, so this spec stays laser-focused on software inventory and leaves other endpoint info to other specs 🦋
quick aside: even though this spec is all about "software inventory", the same mechanisms could also convey info about firmware and operating systems on an endpoint. the software focus shouldn't be read as blocking SWIMA from those other uses ✨
this spec defines a new set of PA-TNC attributes. these attributes are used to request software inventory information and to communicate software installation change events 🌸 that lets software inventory info get sent to a Network Endpoint Assessment (NEA) Server, which can then make it available to other applications 🫶
part of why SWIMA was built was to support the IETF's Security Automation and Continuous Monitoring (SACM) architecture. more on SWIMA's role in SACM is in Section 7 💜 but SWIMA has no dependencies on any part of SACM, so it's usable anywhere the NEA architecture is employed 🍓
1.1. Network Endpoint Assessment (NEA)
SWIMA extends the PA-TNC spec [RFC5792], and these extensions are part of the NEA architecture 🧚 the NEA specs describe an open solution architecture that lets network operators collect and use info about endpoint configuration and state. that info can enforce policies and monitor endpoint health, among lots of other stuff 🔥 info about software on an endpoint is a big deal for all of that 💅 the new PA-TNC attributes in this doc carry software inventory evidence, gathered from a range of possible sources, from the Posture Collector on the endpoint to the Posture Validator on a NEA Server over the PA-TNC interface. see Figure 1 below 👑
+-------------+ +--------------+
| Posture | <--------PA--------> | Posture |
| Collectors | | Validators |
| (1 .. N) | | (1 .. N) |
+-------------+ +--------------+
| |
| |
| |
+-------------+ +--------------+
| Posture | | Posture |
| Broker | <--------PB--------> | Broker |
| Client | | Server |
+-------------+ +--------------+
| |
| |
+-------------+ +--------------+
| Posture | | Posture |
| Transport | <--------PT--------> | Transport |
| Client | | Server |
| (1 .. N) | | (1 .. N) |
+-------------+ +--------------+
NEA CLIENT NEA SERVER
Figure 1: NEA Reference Modelto get this spec, check out the NEA reference architecture in "Network Endpoint Assessment (NEA): Overview and Requirements" [RFC5209] 🌈 you should also look at the PA-TNC interfaces defined in RFC 5792 [RFC5792] 🧠
this doc is based on standards published by the Trusted Computing Group's Trusted Network Communications (TNC) workgroup (see <https://trustedcomputinggroup.org/>) 🎀 the TNC and NEA architectures are interoperable, and a lot of their components are equivalent 🦋
1.2. Conventions Used in This Document
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 📚 so only the ALL CAPS versions are the official keywords. lowercase is just regular English 🙃
1.3. Definitions
this section defines terms with special meaning in this doc 📝
- SWIMA-PC - A NEA Posture Collector (PC) that interprets SWIMA attributes sent by SWIMA-PVs and that conforms to this specification. Note that such a Posture Collector might also support other PA-TNC exchanges beyond those defined herein. 🧚
- SWIMA-PV - A NEA Posture Validator (PV) that interprets SWIMA attributes sent by SWIMA-PCs and that conforms to this specification. Note that such a Posture Validator might also support other PA-TNC exchanges beyond those defined herein. 💜
- SWIMA Attribute - A PA-TNC attribute (as defined in RFC 5792 [RFC5792]) whose structure and behavior is defined in this specification. 🌸
- Endpoint's Software Inventory Evidence Collection - The set of information regarding the set of software installed on an endpoint. An endpoint's Software Inventory Evidence Collection might include information created by or derived from multiple sources, including but not limited to SWID tag files deposited on the filesystem during software installation, information generated by software discovery tools, and information dynamically generated by a software or package management system on an endpoint. 🗂️
- Software Inventory Evidence Record - Part of the endpoint's Software Inventory Evidence Collection (which is composed of "records"). Each record corresponds to one installed instance of a particular software product as reported by some data source. It is possible for a single installed instance to have multiple Software Inventory Evidence Records in an endpoint's Software Inventory Evidence Collection -- this can happen if multiple sources all report the same software installation instance. 🍓
- Software Identifier - A string associated with a specific version of a specific software product. These identifiers are derived from the records used to describe software products. SWIMA does not limit the formats of these records, nor does it enforce that all data sources populate records using the same format. As such, while each Software Identifier uniquely identifies a specific software product, the same software product might be associated with multiple Software Identifiers reflecting differences between different data sources and supported record formats. 🔑
2. Background ✨
2.1. Supported Use Cases
this section describes the use cases this spec supports 🌈 the main reason to exchange software inventory info over the PA-TNC interface is so a challenger (e.g., a NEA Server) can get inventory evidence about some system in a way that follows NEA procedures 🫶 that collected software info can power a bunch of security stuff, like deciding whether an endpoint is allowed to connect to the enterprise, figuring out which endpoints have software that needs patching, and similar stuff 🛡️
2.1.1. Use Software Inventory as an Access Control Factor
some enterprises might have security policies that require connected endpoints to have certain security software installed 🔐 the flip side: some policies might block access to resources from endpoints that have certain prohibited software, since those apps could be a security risk 💀 to make this work, the NEA Server needs to collect software inventory evidence from a target endpoint that's trying to start or keep a connection to the enterprise resource 🙈
based on this spec, the SWIMA-PC can give the SWIMA-PV a complete or partial inventory, as needed to figure out policy compliance ✨ the SWIMA-PV can then use that as evidence of compliance or non-compliance to make a policy-based access decision 👑
2.1.2. Central Stores of Up-to-Date Endpoint Software Inventory Data 🗂️✨
Okay so a bunch of tools need to know what software is sitting on each endpoint, because that's how they keep the network safe 🔐 🌸 For example, a software-patching tool has to figure out if there's out-of-date software installed that needs updating. A vulnerability management tool needs to find endpoints with known vulnerable software installed (patched or otherwise) to see how exposed an endpoint is to attack 😬 A license management tool needs to check that all installed software in the enterprise is accounted for 📋 A central repository holding an up-to-date picture of each endpoint's software inventory makes all of this way easier 💅 Multiple tools can share one repository, so the inventory info gets collected more often and more efficiently. Compared to every tool collecting the same info from endpoints on its own, you get a more complete and consistent view of what's installed 🫶
This specification helps with all of that through a few mechanisms 🦋 As noted above, a SWIMA-PC can give the SWIMA-PV a complete list of the software in an endpoint's Software Inventory Evidence Collection, and the SWIMA-PV can then pass it along to a central repository, such as a Configuration Management Database (CMDB) or a similar application 🗃️ Also, SWIMA-PCs are required to be able to monitor for changes to an endpoint's Software Inventory Evidence Collection in near real time, and they can be asked to immediately push reports of detected changes to the SWIMA-PV ⚡ So any central repository fed by a SWIMA-PV that receives inventory information can get updated quickly after a change happens. Keeping a central repository synced with current software inventory information like this lets tools make efficient decisions based on up-to-date, consistent info 🎀
2.1.3. PA-TNC Use Cases 🧩
SWIMA is intended to operate over the PA-TNC interface, and as such, it's intended to meet the use cases set out in the PA-TNC specification 💖
2.2. Use Cases That Are Not Supported 🙅♀️
Some use cases aren't covered by this specification, bestie, including:
- Addressing how the endpoint's Software Inventory Evidence Collection gets populated. In particular, NEA components are not expected to do software discovery beyond compiling information into an endpoint's Software Inventory Evidence Collection. This collection might come from multiple sources on the endpoint (e.g., information generated dynamically by package management tools or discovery tools, as well as SWID tag files discovered on the filesystem). An enterprise might use software discovery capabilities to identify installed software, but those capabilities are outside the scope of this specification 🔍
- Converting inventory information written in a proprietary format into the formats used in the attributes described in this specification. Instead, this specification focuses exclusively on defining interfaces for transporting software information, and it expects reporting tools to converge around some set of standardized formats for this info 🧃
- Mechanisms for a Posture Validator to request a specific list of software information based on arbitrary software properties. For example, requesting only information about software from a particular vendor is not supported. After the endpoint's Software Inventory Evidence Collection has been copied to some central location, such as the CMDB, processes there can run queries based on any criteria present in the collected information. But this specification doesn't address using such queries to constrain the initial collection of this information from the endpoint 🙈
- Use of properties of certain sources of software information that might make local tests (i.e., on the endpoint) of endpoint state easier. For example, the optional
package_footprintfield of an ISO SWID tag can contain a list of files and hash values associated with the software indicated by the tag. Tools on the endpoint can use the values in this field to test for the presence of the indicated files, and successful evaluation of such tests gives greater assurance that the indicated software is present on the endpoint 🧪 Right now, most SWID tag creators don't provide values for tag fields that support local testing. Because of that, the added complexity of supporting endpoint testing with these fields is out of scope for this specification, though this topic may be considered in a future version 🔮
2.3. SWIMA Requirements 📜
Below are the requirements that SWIMA must meet in order to successfully play its role in the NEA architecture 👑
- Efficient: The NEA architecture enables delay of network access until the endpoint is determined not to pose a security threat to the network, based on its asserted integrity information. To minimize user frustration, SWIMA ought to minimize overhead delays and make PA-TNC communications as rapid and efficient as possible ⚡
- Scalable: SWIMA needs to be usable in enterprises that contain tens of thousands of endpoints or more. So it needs to let security tools make decisions based on up-to-date information about an endpoint's software inventory without creating an excessive burden on the enterprise's network 🌐
- Support precise and complete historical reporting: This specification outlines capabilities that support real-time understanding of the state of endpoints in a network, in a way that other tools can use 🕰️ One way to make that happen is for a CMDB to be able to contain information about all endpoints connected to the enterprise, for all points in time between the endpoint's first connection and the present. In that scenario, it's necessary that any SWIMA-PC be able to report any changes to its Software Inventory Evidence Collection in near real time while connected. And upon reconnection to the enterprise, it needs to be able to update the NEA Server (and, through it, the CMDB) about the state of its Software Inventory Evidence Collection throughout the entire interval when it wasn't connected 📚
2.4. Non-SWIMA Requirements 🌷
There are certain capabilities that SWIMA users might require but that are beyond the scope of SWIMA itself, so they need to be addressed by other standards 🧚
- Confidentiality: SWIMA doesn't define a mechanism for confidentiality, and confidentiality isn't automatically provided just by using the PA-TNC interface. In the NEA architecture, confidentiality is generally provided by the underlying transport protocols, such as the PT binding to TLS [RFC6876] or PT-EAP (Posture Transport for Tunneled Extensible Authentication Protocol (EAP) Methods) [RFC7171]. See Section 7 for more info on related standards 🔒 The information SWIMA conveys is often sensitive for both security (Section 8) and privacy (Section 9) reasons. So the people implementing SWIMA need to make sure appropriate NEA transport mechanisms are used to meet confidentiality requirements 🫢
2.5. Assumptions 🤝
The Posture Broker Client and Posture Broker Server are assumed to provide reliable delivery for PA-TNC messages and attributes sent between the SWIMA-PCs and the SWIMA-PVs. "Reliable delivery" means that either a message is delivered or the sender is made aware of the delivery failure. If reliable delivery can't be provided, some SWIMA features, primarily subscriptions, might not behave as expected 😬
2.6. Assumptions Not Made 🙅
This specification explicitly does not assume that software inventory information exchanges reflect the software installation state of the endpoint. It also doesn't try to detect when the endpoint is providing false information, whether through malice or error. Instead, it focuses on correctly and reliably providing the reported Software Inventory Evidence Collection to the NEA Server 📦 Tools that use the SWIMA standard can include methods to help verify the accuracy of reports, but how those tools do that is beyond the scope of this specification 🔎
Similarly, this specification makes no assumption about how complete the Software Inventory Evidence Collection's coverage is of the total set of software installed on the endpoint. It's possible, and even likely, that some installed software isn't represented by a record in an endpoint's Software Inventory Evidence Collection. Instead, SWIMA makes sure that what does get reported is reported consistently, and that the reported software products can be reliably tracked 🧾
See Section 8 for more on this security consideration 🛡️
3. System Requirements 🎀
SWIMA facilitates the exchange of software inventory and event information 💌 Specifically, each application supporting SWIMA includes a component known as the SWIMA-PC that receives SWIMA attributes. The SWIMA-PC is also responsible for sending appropriate SWIMA attributes back to the SWIMA-PV in response. This section outlines what software inventories and events are, plus the requirements on SWIMA-PCs and SWIMA-PVs needed to support the stated use cases of this specification 🦋
3.1. Data Sources ✨
okay bestie, so the records in an endpoint's Software Inventory Evidence Collection come from one or more "sources" 🗂️. A source is basically one collection of software inventory info about the endpoint. Examples include (but aren't limited to) ISO SWID tags deposited on the filesystem and collected from there 🏷️, info derived from package managers 📦, and the output of software inventory-scanning tools 🔍.
Nobody has perfect or complete inventory info, ngl 💀, so this spec lets you use multiple sources at the same time 🫶. Each source might have its own "sphere of expertise" and only report the software inside that sphere 👑. Like, a package manager knows everything it manages super well, but it has zero idea about stuff installed some other way 🙈.
A SWIMA-PC is not required to use every possible source of software info on its endpoint 🌸. Some SWIMA-PCs are tied to just one or a handful of sources, and others could be designed to dynamically accommodate new sources 🦋. For every software inventory evidence source that a particular SWIMA-PC supports, it MUST completely support all requirements of this specification with regard to those sources 💅. A potential source that can't support some required functionality (e.g., it's unable to monitor the software it reports for change events, as discussed in Section 3.6) MUST NOT be used as a source of endpoint software inventory information, even if it could provide some info 🚫. In other words, a source either gets full functionality as described here or it can't be used at all. Periodt 💅✨
If a previously used source becomes unavailable, that counts as a discontinuity in the SWIMA-PC's reporting ⏳. Section 3.7.1 describes how to use changes in the Event Identifier (EID) Epoch value to indicate a reporting discontinuity.
Heads up! When sending info about installed software, the SWIMA-PC MUST include the complete set of relevant data from all supported sources 🚨. Sources need to be used consistently. Why? If a source shows up in an initial inventory but is missing from a later one, the SWIMA-PV receiving it might reasonably conclude that the software reported by that source is no longer installed on the endpoint 😱. So every supported source should be used every single time the SWIMA-PC provides info to a SWIMA-PV 🔁.
Also, if a SWIMA-PC collects data from multiple sources, some software products might get "double counted" 👯♀️. This can happen if two or more sources give a record for one single installation of a software product. When a SWIMA-PC reports info or records events from multiple inventory evidence sources, it MUST use the information those sources provide, rather than attempt to perform some form of reduction 🙅♀️. So if multiple sources report records for one installation, all of those records from each source are required to be part of the SWIMA-PC's processing, even if that leads to multiple reporting. The SWIMA-PC is not to ignore some records just to avoid that 🙈.
All inventory records reported by a SWIMA-PC include a Source Identifier linking them to a particular source 🔗. Source Identifiers are discussed more in Section 3.4.5, and as that section explains, they can help consumers of SWIMA data spot cases of multiple reporting 🕵️♀️💜.
3.2. Data Models 🧩
SWIMA conveys records about software presence from a SWIMA-PC to a SWIMA-PV. SWIMA does not manage the actual generation or collection of those records on the endpoint 🙅. So info available to SWIMA-PCs might come in a bunch of different formats, and a SWIMA-PC could have little control over the format of the data it's given. Because of this, SWIMA places no constraints on the format of these generated records and supports an open set of record formats for describing installed software instances 🌈. The following terms are used in this document:
- Data model - The format used to structure data within a given record. SWIMA does not constrain the data models it conveys.
- Record - A populated instance of some data model that describes a software product.
Don't confuse the "data model" here with the structure of the SWIMA messages and attributes used to convey info between SWIMA-PVs and SWIMA-PCs 🙃. The SWIMA standard dictates the structure of its messages and attributes. Some attributes, however, have specific fields used to convey inventory records, and those fields support an extensible list of data models for their values. In other words, SWIMA data models are an extension point within SWIMA attributes, which lets the structure of inventory records evolve 🦋.
The data model used to structure software inventory info has very little impact on how the components defined in this spec behave 💁♀️. The SWIMA-PV has no dependency on the data model of records conveyed in SWIMA messages. For this reason, it MUST NOT reject a message or respond with a PA-TNC Error due to the data model used to structure records in attributes it receives. Similarly, it MUST NOT reject a message or respond with a PA-TNC Error if a record fails to comply with a stated format, unless that failure prevents correct parsing of the attribute itself. Short version: the SWIMA-PV treats record bodies as "black boxes" 📦⬛. (Note that the SWIMA-PV might serve as the "front end" of other functionality that does depend on the data model used to structure software info, but any such dependency is beyond the scope of this spec and needs to be addressed outside the behaviors specified here. This spec is only concerned with collecting and delivering software inventory info. Components that consume and use this info are a separate concern 💅.)
The SWIMA-PC does have one functional dependency on the data models used in the software records it delivers 🎀. It's only insofar as the SWIMA-PC is required to deterministically create a Software Identifier (described in Section 3.4.1) based on each record it delivers. The SWIMA-PC MUST be able to generate a Software Identifier for each record it delivers, and if it can't do that, it can't deliver the record 🚫. All SWIMA-PCs MUST at least be able to generate Software Identifiers for the data model types specified in Section 6 of this document 📜. A SWIMA-PC MAY include the ability to generate Software Identifiers for other data model types, and thus be able to support them as well ✨.
3.3. Basic Attribute Exchange 🤝
In the most basic exchange supported by this spec, a SWIMA-PV sends a request to the SWIMA-PC asking for some type of info about the endpoint's software inventory 💌. This simple exchange is shown in Figure 2.
+-------------+ +--------------+
| SWIMA-PC | | SWIMA-PV | Time
+-------------+ +--------------+ |
| | |
|<------------SWIMA Request---------------| |
| | |
|-------------SWIMA Response------------->| |
| | V
Figure 2: Basic SWIMA Attribute ExchangeWhen the SWIMA-PC gets a SWIMA Request from the SWIMA-PV, it's expected to collect all the relevant software inventory info from the endpoint's Software Inventory Evidence Collection and place it within its response attribute 📥.
SWIMA-PVs MUST discard, without error, any SWIMA Response attributes they receive for which they don't know the SWIMA Request parameters that led to that SWIMA Response 🗑️. This is because the SWIMA Request includes parameters that control the nature of the response (as the following sections describe). Without knowing those parameters, the SWIMA Response can't be reliably interpreted 🧐. Each SWIMA Request includes a Request ID, which is echoed in any SWIMA Response to that request and lets responses be matched to requests. See Section 5.5 for more on Request IDs 🔢.
Receiving an unsolicited SWIMA Response attribute will most often happen when a NEA Server has multiple SWIMA-PVs 👀. One SWIMA-PV sends a SWIMA Request, but unless exclusive delivery [RFC5793] is set by the sender and honored by the recipient, multiple SWIMA-PVs will receive copies of the resulting SWIMA Response. In this case, the SWIMA-PV that didn't send the SWIMA Request would lack the context needed to correctly interpret the SWIMA Response it got, so it would simply discard it 🫠. Note, however, that proprietary measures might let a SWIMA-PV discover the SWIMA Request parameters for a SWIMA Response even if that SWIMA-PV didn't send the given SWIMA Request 🕵️. So there's no blanket requirement for a SWIMA-PV to discard all SWIMA Responses to SWIMA Requests it didn't generate itself. SWIMA-PVs are only required to discard SWIMA Responses for which they can't get the necessary context to interpret 💅.
When it's possible to do so, the SWIMA-PC SHOULD send its SWIMA Response attribute to the SWIMA-PV that requested it, using exclusive delivery as described in Section 4.5 of "PB-TNC: A Posture Broker (PB) Protocol Compatible with Trusted Network Connect (TNC)" [RFC5793] 🎯. Exclusive delivery requests that only the sender of the SWIMA Request be the receiver of the resulting SWIMA Response. Note, however, that PB-TNC doesn't require the recipient to honor the exclusive delivery flag in messages it receives. So setting the flag can't be guaranteed to stop a SWIMA-PV from receiving unsolicited SWIMA Responses 🙃.
Note that if a single endpoint hosts multiple SWIMA-PCs, one SWIMA Request could result in multiple SWIMA Responses 🐣. SWIMA-PVs need to handle that without error.
All numeric values sent in SWIMA messages are sent in network (big endian) byte order 🔢💜.
3.4. Core Software-Reporting Information 📋
Different parameters in the SWIMA Request can influence what info is returned in the SWIMA Response. But even though each SWIMA Response gives different extra info about installed software, all the responses share a common set of fields that support reliable software identification on an endpoint 🪪. These fields include Software Identifiers, Data Model Type, Record Identifiers, Software Locators, and Source Identifiers. They're present for each reported piece of software in every type of SWIMA Response. The following sections look at these info types in more detail 🔍🌷.
3.4.1. Software Identifiers ✨
okay so a Software Identifier uniquely identifies one specific version of one specific software product 💖 the SWIMA standard doesn't dictate what the structure looks like (beyond saying it's a string 🎀) and it doesn't define how it gets created 🤷♀️ instead, every data model listed in the "Software Data Model Types" registry (Section 10.5) has its own rules for building a Software Identifier from a record in the endpoint's Software Inventory Evidence Collection that's written in that data model 🧚 other data models will have their own procedures for making their Software Identifiers too 🌈 and within SWIMA, the identifier is just an opaque string, so there is never any reason to unpack the info hiding inside it 🙈
a Software Identifier is a tiny fraction of the size of the inventory record it came from 🦋 so it's often way more efficient to collect full inventories using Software Identifiers and only grab full records when you actually need them, using targeted requests 🍓 for some combos of data models and sources, the full record might never be necessary, because the identifier can be directly correlated to the contents of the full record 💅 this is possible with authoritative SWID tags, since those tags always have the same contents, so a Software Identifier derived from one can be used as a lookup to a local copy of the full tag 🔥 for other combos of source and data model, a server might not be able to figure out the specific software product and version tied to the identifier without requesting delivery of the full record 😭 but even then, downstream consumers might never need the full record as long as the Software Identifiers they receive can be tracked reliably 🫶 a SWIMA-PV can use Software Identifiers to track the presence of specific software products on an endpoint over time in a bandwidth-efficient way ✨
there are two important limitations of Software Identifiers to keep in mind 👑
- the identifiers do not necessarily change when the associated record changes 💀 sometimes a record in the endpoint's Software Inventory Evidence Collection changes because new info became available or to fix prior errors 🌸 those changes might or might not change the Software Identifier, depending on the nature of the change and the rules for deriving identifiers from records of that data model 💜
- it's possible that a single software product is installed on a single endpoint multiple times 🎀 if those multiple installation instances are reported by the same source using the same data format, they can end up with identical Software Identifiers for both instances 😭 in other words, Software Identifiers might not uniquely identify installation instances; they're just meant to uniquely identify software products (which might have more than one installation instance) 🦋 to reliably tell apart multiple instances of a single software product, you need to use Record Identifiers as described in Section 3.4.3 🧚
3.4.2. Data Model Type 💅
the Data Model Type is made of two fields: Data Model Type PEN and Data Model Type 🎀 ("PEN" stands for "Private Enterprise Number" 🌈) the combo of these two fields is used to identify the type of data model of the associated software inventory record 💖 the data model matters not only because it tells the recipient what data model the record uses, but also because the process for generating the Software Identifier depends on the record's data model 🔥 so clearly identifying the data model the Software Identifier came from gives really useful context for that value ✨
the PEN identifies the organization that assigns meaning to the Data Model Type field value 👑 PENs are managed by IANA in the "Private Enterprise Numbers" registry 🌸 PENs let vendors designate their own set of data models for software inventory description 🍓 IANA reserves the PEN of 0x000000 🫶 Data Model Types associated with this PEN are defined in the "Software Data Model Types" registry; see Section 10.5 of this specification 🦋 note that this IANA table reserves all values greater than or equal to 0xC0 (192) for local enterprise use 😭 this means local enterprises can use custom data formats and indicate them with the IANA PEN and a Data Model Type value between 0xC0 and 0xFF, inclusive 💅 those enterprises are responsible for configuring their SWIMA-PCs to correctly report those custom data models 🧚
3.4.3. Record Identifiers 🌈
a Record Identifier is a 4-byte unsigned integer that the SWIMA-PC generates, and it's uniquely associated with one specific record within the endpoint's Software Inventory Evidence Collection 💖 the SWIMA-PC MUST assign a unique identifier to each record when it's added to the endpoint's Software Inventory Evidence Collection 🎀 the Record Identifier SHOULD stay unchanged if that record is modified 🔥 however, it's recognized that in some circumstances, record modification might be hard to tell apart from record deletion followed by creation of a new record 🙈 so retaining a constant Record Identifier across a record modification is recommended but not required 💜 similarly, if the software product associated with a record is moved, ideally the Record Identifier for that record stays the same, reflecting that it's the same software product instance, just in a new location 🦋 but this level of tracking could prove difficult to achieve and is not required 😭 the SWIMA-PC might wish to assign Record Identifiers sequentially, but any scheme is acceptable, as long as no two records receive the same identifier ✨
servers can use Record Identifiers to distinguish between multiple instances of a single software product installed on an endpoint 👑 since each installation instance is associated with a separate record, servers can use the Record Identifier to tell instances apart 🌸 for example, if an event is reported (as described in Section 3.7), the Record Identifier lets the server figure out which instance of a software product is involved 🍓
3.4.4. Software Locators 🧚
okay so beyond needing to know what software products are on an endpoint, some processes that use inventory info also need to know where the software is located on the endpoint 🫶 this info might be needed to direct remediation actions or similar processes 💅 for this reason, every reported software product also includes a Software Locator to identify where the software is installed on the endpoint 🔥
if the location is not provided directly by the data source, the SWIMA-PC is responsible for attempting to determine the location of the software product 🎀 the "location" of a product SHOULD be the directory in which the software product's executables are kept 🌈 the SWIMA-PC MUST be consistent in reporting the location of a software product 💖 in other words, assuming the product hasn't moved, the SWIMA-PC cannot use one location in one report and a different location for the same product in another 🙈 (if a software product has moved, the Software Locator needs to reflect the new location 🦋)
the location is expressed as a URI string 🌸 the string MUST conform to URI syntax requirements [RFC3986] 👑 the URI scheme describes the context of the described location 🍓 for example, in most cases the location of the installed product will be expressed in terms of its path in the filesystem 💜 for such locations, the location URI scheme MUST be "file", and the URI MUST conform to the "file" URI scheme standard [RFC8089], including the percent-encoding of whitespace and other special characters 😭 it's possible that other schemes could be used to represent other location contexts 🫶 apart from specifying the use of the "file" scheme, this specification doesn't identify other schemes or define their use ✨ when representing software products in other location contexts, tools MUST be consistent in their use of schemes, but the exact schemes aren't normatively defined here 💅 SWIMA implementations are not limited to the IANA list of URI schemes <https://www.iana.org/assignments/uri-schemes/> and can define new schemes to support other types of application locations 🧚
it's possible that a SWIMA-PC is unable to determine the location of a reported software product 🌈 in this case, the SWIMA-PC MUST provide a zero-length Software Locator 💀
3.4.5. Source Identifiers ✨
okay so every SWIMA-PC MUST keep track of where each bit of software info came from 🕵️♀️ Whenever a SWIMA-PC gets info to send to a SWIMA-PV from a source that's new (from that SWIMA-PV's point of view), it MUST give that source a Source Identifier. That's an 8-bit unsigned integer 🎀 Every item reported carries the number of the Source Identifier for whoever provided it, and everything from that source MUST go out with that same number. This MUST happen for every source used. If the SWIMA-PC isn't sure whether a source is new, it MUST assume it is and give it a brand new Source Identifier 💅 The numbers don't have to be sequential, btw. SWIMA doesn't support more than 256 sources, because the chance that one endpoint has more than 256 ways of collecting inventory info is vanishingly small 🙈 Every value from 0 to 255 is valid, and there are no reserved numbers. Iconic, no notes.
Source Identifiers can help with (but won't fully fix) the mess that happens when one software instance gets reported multiple times 🫶 If several sources each report the same type of product once, it's most likely one instance installed on the endpoint, which each source spotted on its own. But if a single source reports multiple instances, that almost certainly means there really are multiple instances 🌸
The SWIMA-PC is responsible for tracking which Source Identifier goes with which data source 🦋 That association MUST stay consistent for a given SWIMA-PV for as long as there's an active PB-TNC session with that SWIMA-PV. The SWIMA-PC MAY use a different association for different SWIMA-PVs. It also MAY change the association for a given SWIMA-PV if the PB-TNC session ends. Honestly though, implementers will probably find it way easier to keep the same association for every SWIMA-PV and across sessions 🧚
Of special note 👑 event records from the SWIMA-PC's event log (see Section 3.7) also need to go out with their data source. The Source Identifier reported with an event MUST be the current one (meaning the one in effect when the event is sent) tied to the data source that made the event, no matter how long ago it happened. Event logs tend to stick around way longer than one PB-TNC session, so SWIMA-PCs MUST make sure every event can still be linked to the right data source, even if the Source Identifiers from when the event was created have since been reassigned. Basically, when an event gets sent, it goes out with whatever Source Identifier is currently linked to its data source, even if a different one would have applied back when the event first happened 💀
Note that Source Identifiers are mainly for recognition, not identification 💖 A Source Identifier can tell a recipient that two events came from the same source, but the number won't necessarily tell them which source that actually was. Also, different SWIMA-PCs won't necessarily use the same Source Identifiers for the same sources 🌈 So SWIMA-PCs MUST track how they assign Source Identifiers so they use them consistently. SWIMA-PCs MUST also track which Source Identifiers have been used with each SWIMA-PV they talk to. Main character tracking energy ✨
3.4.6. Using Software and Record Identifiers in SWIMA Attributes 🌸
A SWIMA attribute reporting an endpoint's Software Inventory Evidence Collection always includes the Software Identifiers for the software products it identifies. It might or might not also include copies of Software Inventory Evidence Records. The attribute exchange looks exactly like the diagram in Figure 2, whether or not Software Inventory Evidence Records are included. The SWIMA Request attribute says whether the response is required to include Software Inventory Evidence Records. Leaving the records out can shrink the response size by multiple orders of magnitude compared to sending the same inventory with full records 🔥 That's a whole glow-up for your bandwidth 🫶
3.5. Targeted Requests 🎯
Sometimes a SWIMA-PV doesn't need info about every single piece of software on an endpoint and just wants updates about certain software instances 💅 For example, enterprise endpoints might be required to have certain products installed and kept up to date. Instead of asking for the whole inventory just to check whether those products are there, the SWIMA-PV can make a "targeted request" for the software it cares about ✨
Targeted requests follow the same attribute exchange as the one in Figure 2 🦋 The SWIMA-PV targets its request by putting one or more Software Identifiers in its SWIMA Request attribute. The SWIMA-PC MUST then limit its response to records that match those Software Identifiers. This lets the exchange skip anything that isn't relevant to the policy question, which cuts down on unnecessary bandwidth use 🍓 The SWIMA-PC's response might or might not include Software Inventory Evidence Records, depending on the parameters of the SWIMA Request.
Note that targeted requests identify relevant software only through Software Identifiers 🙈 This specification does not support arbitrary, parameterized querying of records. For example, you can't ask for all records from a certain software publisher, or all records created by a particular data source. Targeted requests only let a requester ask for specific software (named by its Software Identifiers) and get back a response limited to that named software. Very focused, very intentional 💜
There's no assumption that a SWIMA-PC will recognize "synonymous records," meaning records from different sources for the same software 😭 Remember that different sources and data models can use different Software Identifier strings for the same product. The SWIMA-PC returns only the records that match the Software Identifiers in the SWIMA Request, even if other records in the endpoint's Software Inventory Evidence Collection are for the same product. This is necessary because SWIMA-PCs might not be able to tell that two Software Identifiers refer to the same product 🌈
A targeted SWIMA Request attribute doesn't specify Record Identifiers or Software Locators 🧚 The response to a targeted request MUST include all records associated with the named Software Identifiers, including when there are multiple records tied to a single Software Identifier 👑
SWIMA-PCs MUST accept targeted requests and process them correctly as described above 💖 SWIMA-PVs MUST be capable of making targeted requests and processing the responses to them. Iykyk, and now you do too 🫶✨
Okay bestie, picking up right where we left off, so let's get into it 💅
3.6. Monitoring Changes in an Endpoint's Software Inventory Evidence Collection ✨
3.6.
Okay so the software collection on an endpoint is NOT static, bestie 🙈 As software gets installed, uninstalled, patched, or updated, the Software Inventory Evidence Collection is supposed to change too, so it matches what's actually on the endpoint 🧚 Different data sources can update the evidence collection at different speeds. Like, a package manager might update its records immediately whenever it's used to add or remove a software product 🔥 Meanwhile, sources that do periodic examinations of the endpoint would probably only update their records after each examination 🌸
Here's the deal: all SWIMA-PCs MUST be able to detect changes to the Software Inventory Evidence Collection. Specifically, SWIMA-PCs MUST be able to detect:
- The creation of records
- The deletion of records
- The alteration of records
An "alteration" is anything that modifies the contents of a record (or would modify it, if the record is generated on demand) in any way, even if the change isn't functionally meaningful 💀 It's giving "every single byte counts" energy 👑
SWIMA-PCs MUST detect these changes in close to real time (aka within seconds) while the SWIMA-PC is operating 🦋 And if there's a stretch where the SWIMA-PC isn't operating, then when it comes back it MUST be able to figure out the net change over that gap 💖 The "net change" is the difference between (1) the state of the Software Inventory Evidence Collection when the SWIMA-PC was last operational and monitoring it, and (2) the state when the SWIMA-PC resumed operation 🎀
Heads up: a net change might not show the total number of change events in that interval 👀 Like, if a record got altered three times while the SWIMA-PC couldn't monitor, the net change might just say "this record was altered" and not how many times it happened 🙃 That's totally fine, since it's enough to note that there was a difference between the earlier and current state. No need to list every single event that got us to the current state 💅
The SWIMA-PC MUST assign a time to each detected change. These timestamps are the SWIMA-PC's best understanding of when the change happened ⏰ For changes that happen while the SWIMA-PC is operating, it ought to be accurate to within a few seconds 💜 For changes that happen while it's NOT operational, once it's back up it needs to make a best guess (maybe by checking timestamps on files), but those values might be a little off 🙈 For dynamically generated records, the time of change is when the data the records are generated from changes, not when the changed record gets generated 🌈 For example, if records are generated from an RPM database (<http://rpm.org/>), the time of change would be when the RPM database changed 🍓
About deletions: the SWIMA-PC needs to detect when a record is deleted, and it MUST keep a copy of the full deleted record, along with its Record Identifier and Software Locator, so that the record and its info can be sent to the SWIMA-PV when requested 🫶 This copy MUST be kept for a reasonable amount of time. Vendors and admins decide what "reasonable" means, but a copy SHOULD be kept for as long as the deletion event stays in the SWIMA-PC's event log (see Section 3.7) 🧚 This is recommended because while the event is in the log, the SWIMA-PC might send a change event attribute (see Section 3.7) that references this record, and the SWIMA-PV might want the full copy 💖 If the SWIMA-PC gets asked to report a deletion event that's still in the log but the record itself is gone, it will still return an entry for that deletion event, but the field that would normally hold the full record SHOULD be zero-length 🎀
About alterations: SWIMA-PCs MUST detect any alteration to the contents of a record, even if it has no functional impact 🔥 A good rule of thumb is that any alteration that might change the value of a hash taken on the record's contents needs to be detected 🌸 A SWIMA-PC might not be able to tell apart changes to a record's contents from changes to the metadata the filesystem keeps for it 🙃 For example, a SWIMA-PC might use the "last modification" timestamp to spot alterations, but that timestamp can change for reasons other than changes to the contents, lol 💀 A SWIMA-PC is still compliant if it also reports metadata change events that don't change the record itself, as alterations to the record 🦋 So, yes, SWIMA-PC implementers are encouraged to exclude modifications that don't affect the bytes inside the record, but telling file contents apart from file metadata can be hard and time-consuming on some systems 😭 As long as the detected alterations always cover every modification to the contents, the SWIMA-PC is compliant even if it also catches some alterations that don't change the contents 🫶 When it records an alteration, the SWIMA-PC only has to note that an alteration happened 🌈 It doesn't have to note or record how the record was altered, and there's no way to include those details in SWIMA attributes reporting the change to a SWIMA-PV 💅 And there's no need to keep a copy of the original record from before the alteration ✨
When a record changes, it SHOULD keep the same Record Identifier 🧚 The Software Locator might or might not change, depending on whether the software moved locations during the changes that led to the record change 🍓 A record change MUST keep the same Software Identifier 👑 That means any action that changes a software product (like applying a patch that changes the product's version) MUST NOT be shown as a record change 💀 Instead it MUST result in deleting the old record and creating a new one 😭 This is because a record in the endpoint's Software Inventory Evidence Collection has to correspond directly with one instance of a specific software product 🔥
3.7. Reporting Change Events 🦋
As noted in Section 3.6, SWIMA-PCs are required to detect changes to the endpoint's Software Inventory Evidence Collection (creation, deletion, and alteration) in near real time while they're operational 💖 And a given SWIMA-PC MUST be able to account for any net change to the collection that happens while it's not operational 🎀 But here's the thing: to actually be useful to the enterprise, the NEA Server needs to receive these events and understand how new changes relate to earlier ones 🫶 In SWIMA, this is handled by reporting change events ✨ All SWIMA-PCs MUST be capable of receiving requests for change events and sending change event attributes 🌈 All SWIMA-PVs MUST be capable of requesting and receiving change event attributes 💅
3.7.1. Event Identifiers ✨
okay so change events have to be correctly ordered, or nothing makes sense 😭🫶 two things help with that: an Event Identifier (EID) value and an EID Epoch value 🎀
an EID is a 4-byte unsigned integer that the SWIMA-PC hands out sequentially to each event it observes. That includes events it catches in real time and events it works out by looking for net changes after a stretch of SWIMA-PC inactivity 🧚 every EID lives inside some "EID Epoch," which is also a 4-byte unsigned integer. EID Epochs keep the SWIMA-PC and any SWIMA-PVs it talks to in sync 💖 EID Epoch values MUST be generated so that an Epoch is as unlikely as possible to ever get reused, even if the SWIMA-PC rolls back to an earlier state 🙈 that's why sequential EID Epochs are discouraged, because if state gets lost, reuse can happen. there are a bunch of reasons a SWIMA-PC might need to reset its EID counter on purpose: running out of EID values, needing to purge the event log to free up memory, or the event log getting corrupted 💀 whenever a SWIMA-PC resets its EID counter, a new EID Epoch MUST be selected. no exceptions, bestie 👑
inside an Epoch, EIDs MUST be assigned sequentially, so if an event gets an EID of N, the next event observed gets N+1 🔥 sometimes events happen at the same time, or the SWIMA-PC just can't tell what order they came in. in those cases the SWIMA-PC makes up an arbitrary ordering and hands out EIDs following that order 🌸 two change events MUST NOT ever get the same EID within the same EID Epoch 🙅♀️ and there's no meaningful way to compare EID values across different Epochs, so don't even try 🦋
the EID value of 0 is reserved and MUST NOT be associated with any event 💅 it does double duty: in a SWIMA Request attribute, an EID of 0 means the SWIMA-PV wants an inventory response instead of an event response, and in a SWIMA Response it shows the starting state of the endpoint's Software Inventory Evidence Collection before any events have been observed 🌈 which means the very first recorded event in a SWIMA-PC's records within an EID Epoch MUST be assigned a value of 1 ✨ also, EID and EID Epoch values are assigned by the SWIMA-PC no matter whether anyone is receiving the events. the SWIMA-PC records events and hands out EIDs while it runs, and every SWIMA-PV asking for event info gets served from those same records, so they all see the same EIDs and Epochs for the same events 💜
if a SWIMA-PC uses multiple sources, its EID assignments MUST reflect the presence and order of all events on the endpoint (at least for supported sources), no matter which source they came from 🎀 for example, say source A has an event, then source B has two events, then source A has two more. the SWIMA-PC is required to capture five events with consecutive EID values that match the order things actually happened in 🧩
the SWIMA-PC MUST make sure there's no coverage gap (meaning change events that aren't recorded in its records) 😭 this matters because a gap can give a SWIMA-PV a totally wrong picture of the endpoint's state. like, if a SWIMA-PV sees an event saying a record was added to the endpoint's Software Inventory Evidence Collection, but never sees a later event saying that record was deleted, it could reasonably assume the record is still there and the software is still installed (as long as the Epoch hasn't changed) 🫠 if there's a gap in the event records, that assumption could be false. so the SWIMA-PC's event records MUST NOT contain gaps 🚫 and when there are stretches where changes might have happened without the SWIMA-PC noticing or recording them, the SWIMA-PC MUST either (1) compute a net change and update its event records to match, or (2) pick a new EID Epoch to show there's a discontinuity with the earlier records 🦋
once an event has an EID inside an Epoch, that pairing MUST NOT be changed 💖 that means the EID can't be moved to a different event, and the event can't get a different EID either. when the SWIMA-PC's Epoch changes, all those EID-to-event pairings get cancelled and the EID values become free to assign again 🔄
3.7.2. Core Event-Tracking Information 🌷
whether a response is reporting events or a full inventory, it's really important to know where that info fits on the overall timeline of change events 🕰️ that's why every SWIMA Response attribute has fields that pin the response to a spot in the sequence of detected events. specifically, every SWIMA Response includes a Last EID field and an EID Epoch field 💅 the EID Epoch field says which EID Epoch the SWIMA Response was sent in. if the SWIMA Response is reporting events, all of those events happened inside that named Epoch. the Last EID (which is also always from that named Epoch) tells you the EID of the last recorded change event at the moment the SWIMA Response was sent 🎀 together, those two fields let any response get placed in the full context of all the detected change events within a given EID Epoch 🧠✨
3.7.3. Updating Inventory Knowledge Based on Events 🧚
okay, so modern endpoints can have hundreds of software products installed, and most of them aren't going to change from one day to the next 🙄 so instead of trading a complete inventory list on a regular basis, you might just want to find out what changed since some earlier known state of that inventory 💖 EIDs make this easy, since they let you place change events in context relative to that earlier state 🦋
like we said before, every SWIMA Response a SWIMA-PC sends to a SWIMA-PV (as described in Sections 3.3 through 3.5) includes the EID Epoch and EID of the last event recorded before that response was put together 🫶 this lets the SWIMA-PV place all the event records it receives afterward in context relative to that SWIMA Response attribute, because the EIDs give a total ordering of every change to the endpoint's Software Inventory Evidence Collection 🌈 so a SWIMA-PV (or, more likely, a database that collects and stores its findings) can save an endpoint's full inventory along with the EID and Epoch of the most recent event reflected at that time 📚 from then on, if change events show up, the attribute describing them tells you the nature of each change, which records were affected, and what order things happened in (based on the sequential EIDs) ✨ using that, any remote copy of the endpoint's Software Inventory Evidence Collection can be updated to match 🔥
3.7.4. Using Event Records in SWIMA Attributes 💜
a SWIMA-PV MUST be able to ask for a list of event records instead of an inventory 🎀 the attribute flow in that kind of exchange looks just like the basic flow in Figure 2 🧩 the only difference is that the SWIMA-PV puts an EID other than 0 in the SWIMA Request attribute (an EID of 0 in a SWIMA Request means "give me an inventory," remember 🙈). when the SWIMA-PC gets a request like that, it doesn't look through the endpoint's Software Inventory Evidence Collection. instead it checks its list of detected changes 💅 the SWIMA-PC MUST add an event record to the SWIMA Response attribute for every recorded change event whose EID is greater than or equal to the EID in the SWIMA Request attribute (though targeting, described in the next paragraph, can narrow that list down) 🌸 and a list of event records MUST only contain events whose EIDs all come from the current Epoch 🔒
SWIMA-PVs can target their event-record requests by including one or more Software Identifiers (as described in Section 3.5) in the SWIMA Request that asks for an event record list 🎯 a targeted request for event records says "only send me events about software that matches one of these Software Identifiers" 💖 specifically, in response to a targeted request for event records, the SWIMA-PC MUST exclude any event records with EIDs less than the indicated EID (within the current EID Epoch), and MUST exclude any event records where the affected software doesn't match one of the provided Software Identifiers 🙅♀️ that means the resulting list in the response attribute might not be a continuous run of EIDs, so don't freak out if you see gaps there 🫠 and both SWIMA-PCs and SWIMA-PVs MUST support targeted requests for event records 👑🌈
3.7.5. Partial and Complete Lists of Event Records in SWIMA Attributes 📜
Okay so over time, a SWIMA-PC might record a lot of change events 📚. If a SWIMA-PV asks for every change event across a long stretch of time, the SWIMA Response attribute could get sooo huge, especially if the SWIMA-PV also asks for Software Inventory Evidence Records to be included 😩. If the attribute ends up too big to send, because it goes over either (1) the 4 GB attribute size limit from the PA-TNC specification or (2) some smaller size limit that's been set on the SWIMA-PC, then the SWIMA-PC MAY send a partial list of event records back to the SWIMA-PV 🎀.
Making a partial list means the SWIMA-PC has to figure out a "consulted range" of EIDs ✨. The consulted range is the set of event records that get looked at for the SWIMA Response attribute, and the ones that actually make it in are included if they apply 👀. Remember that if a SWIMA Request is targeted, only the event records about the software that was named would count (see Section 3.5 for all the targeted request tea 🫖). If a request isn't targeted, then every event record in the consulted range counts and goes into the SWIMA Response attribute 💖.
The lower bound of the consulted range MUST be the EID given in the SWIMA Request 🧚. (Quick reminder: a SWIMA-PV asks for event records by sending a non-zero EID value in the SWIMA Request. See Section 3.7.4.) The upper bound is the EID of the latest event record, going by EID values, that's in the SWIMA Response attribute, as long as it actually applies to the request. That last EID is called the "Last Consulted EID" 🦋. The SWIMA-PC picks this Last Consulted EID based on how big a list of event records it's willing to hand over to the SWIMA-PV 📏.
A partial result list MUST include all applicable event records inside the consulted range 💅. So for any applicable event record (that's any event record in a non-targeted request, or any event record tied to software that matches a requested Software Identifier in a targeted request) whose EID is greater than or equal to the EID given in the SWIMA Request and less than or equal to the Last Consulted EID, that event record MUST be included in the SWIMA Response carrying this partial list 🫶. This is what keeps every partial list complete within its range 🔥. And for targeted requests, "complete" does not mean every EID between the endpoints is there. It only means every matching EID between the endpoints made it in 🙈.
Every SWIMA Response has the EID Epoch and Last EID fields, and any SWIMA Response attribute that carries event records also has a Last Consulted EID field 🌸. Heads up: if you're answering a targeted SWIMA Request, the SWIMA Response attribute might not contain the event record that matches the Last Consulted EID value 😭. That can happen when that record got judged inapplicable because it didn't match the Software Identifiers in the SWIMA Request 🤷♀️.
If a SWIMA-PV gets a SWIMA Response attribute where the Last EID and Last Consulted EID fields are identical, it knows it has a complete result list, given the request parameters, all the way up to now 🌈✨.
On the flip side, if the Last EID is greater than the Last Consulted EID, the SWIMA-PV has a partial result list 🥺. (The Last Consulted EID MUST NOT exceed the Last EID 🙅♀️.) If the SWIMA-PV wants to collect the rest, it sends a brand-new SWIMA Request whose EID is one greater than the Last Consulted EID from the previous response 🏃♀️. That makes the SWIMA-PC generate another SWIMA Response attribute, and the earliest event record in it is the one right after the record with the Last Consulted EID (since EIDs are assigned one after another 🔢). The SWIMA-PV keeps repeating this until it gets a SWIMA Response where the Last EID and Last Consulted EID are equal 🎉. That's how it can collect every event record over a given range, even if the whole set would be too big to deliver in one attribute 👑.
Heads up, implementers: a SWIMA Request might ask for an EID that's bigger than the EID of the last event the SWIMA-PC recorded 👀. Following the behaviors described in Section 3.7.4, a SWIMA-PC MUST answer that kind of request with a SWIMA Response attribute that contains zero event records 🫥. That's because the SWIMA-PC hasn't recorded any event records with EIDs greater than or equal to the EID in the SWIMA Request. In that case, the Last Consulted EID field MUST be set to the same value as the Last EID field in that SWIMA Response attribute 💜. This one gets called out because the consulted range in this situation is a negative range, where the "first" EID (from the SWIMA Request) is bigger than the "last" EID (the EID of the last recorded event on the SWIMA-PC) 🙃. Implementers need to make sure SWIMA-PCs don't run into problems in this spot 🛠️.
One more thing: this spec only supports partial results when returning event records 💁♀️. There's no way to return a partial inventory list under this spec 🚫.
3.7.6. Synchronizing Event Identifiers and Epochs 🔄
Since EIDs are sequential within an Epoch, if a SWIMA-PV's list of event records has gaps in the EID values within a single Epoch, the SWIMA-PV knows there are events it hasn't accounted for 🕵️♀️. It can ask for either (1) a new event list to collect the missing events, or (2) a full inventory to resync its understanding of the endpoint's Software Inventory Evidence Collection 🔁. Either way, once the SWIMA-PV has updated its record of that collection, it can record the new latest EID value and track events normally from there 💖.
If the SWIMA-PV gets any attribute from a SWIMA-PC where the EID Epoch is different from the EID Epoch it used before, then the SWIMA-PV (or anything else using this info to track the endpoint's Software Inventory Evidence Collection) knows there's a discontinuity in its understanding of the endpoint's state 🚨. To get past that discontinuity and rebuild a current understanding of the collection's state, the SWIMA-PV needs a full inventory from the endpoint 📦. It can't get back in sync by collecting any set of event records in this situation 🙅♀️. That's because there's no way to account for all the events on the SWIMA-PC since the previous Epoch was used, since there's no way to query for EIDs from a previous Epoch 😵. Once the SWIMA-PV has a full inventory for the new Epoch, it records the latest EID reported in that new Epoch and can track future events normally 🦋.
A SWIMA-PC MUST NOT report events with EIDs from any Epoch other than the current EID Epoch 🚫. After an Epoch change, the SWIMA-PC MAY purge all event records from a previous Epoch from memory 🧹. Or, it MAY choose to keep some event records from a previous EID Epoch and give them new EIDs in the current Epoch 🔖. But if a SWIMA-PC goes with that second option, it MUST make sure the order of events by their EIDs stays the same, and that there's no coverage gap between the first retained event from the previous Epoch (now reassigned an EID in the current Epoch) and the first event recorded in the current Epoch 🧩. In particular, the SWIMA-PC MUST make sure that all change events that happened after the last recorded event from the previous Epoch are known and recorded 📝. (This might not be possible if the Epoch change is caused by state corruption on the SWIMA-PC 💀.) A SWIMA-PC might decide to reassign EIDs to records from a preceding Epoch to create a "sliding window" of events 🪟, where each Epoch change is a shift in the window of available events ✨.
If a SWIMA-PC crashes and loses track of its current EID Epoch or its current EID, then it MUST generate a new EID Epoch value and start assigning EIDs within that Epoch 💥. In that case, the SWIMA-PC MUST purge all event records from before the crash 🗑️, because it can't make sure there's no gap between the last of those records and the next detected event. The process for generating a new EID Epoch MUST minimize the chance that the newly generated EID Epoch is the same as one that was used before 🎲.
The SWIMA-PV will normally never get an attribute saying the latest EID is less than the latest EID reported in a previous attribute within the same EID Epoch 🙃. If that does happen, the SWIMA-PC has run into some kind of error, which could mean its event log is at least partly corrupted 😱. In that case, the SWIMA-PV MUST treat the situation as if there was a change in Epoch, and treat any local copy of the endpoint's Software Inventory Evidence Collection as out of sync until the SWIMA-PC can report a full inventory 🚧. The SWIMA-PV SHOULD log what happened, so the SWIMA-PC can be checked to make sure it's running properly again 🔍💅.
3.8. Subscriptions 📣
So far, every attribute exchange we've talked about assumes that a SWIMA-PV sent a SWIMA Request attribute and the SWIMA-PC is giving a direct answer to that request 📨. SWIMA also lets a SWIMA-PC send a SWIMA Response to the SWIMA-PV when it notices changes in the endpoint's Software Inventory Evidence Collection, instead of replying to a SWIMA Request 🔔. When a SWIMA-PC agrees to send content whenever certain changes to that collection are detected, this spec calls it a "subscription" 🎀, and the SWIMA-PV that gets this content is said to be "subscribed to" that SWIMA-PC 🫶. All SWIMA-PCs and SWIMA-PVs MUST support the use of subscriptions 💖.
3.8.1. Establishing Subscriptions ✨
Okay bestie, so a SWIMA-PV sets up a subscription on a SWIMA-PC by sending a SWIMA Request attribute with the Subscribe flag set 💖. The SWIMA Request attribute is otherwise identical to the SWIMA Requests we've covered in earlier sections 🎀. So a request like this might or might not ask for Software Inventory Evidence Records, might or might not be targeted, and might ask for change event records or endpoint inventory 🧚. As long as no error pops up, a SWIMA-PC MUST send a SWIMA Response attribute in direct response to this SWIMA Request attribute, just like it would if the Subscribe flag wasn't set 💅. The attribute exchange that sets up a new subscription has the same flow as the earlier exchanges, as shown in Figure 2 🦋. If the SWIMA-PV doesn't get a PA-TNC Error attribute back for its subscription request (see Sections 3.9 and 5.15), the subscription is officially established on the SWIMA-PC 🎉. The SWIMA Request attribute that sets up a new subscription is called the "establishing request" for that subscription 👑.
When a subscription is established, it gets a Subscription ID value 🌸. The Subscription ID is equal to the value of the Request ID of the establishing request. (For more about Request IDs, see Section 5.5 🧾.)
A SWIMA-PC MUST have the ability to record and support at least 8 simultaneous subscriptions, and SHOULD have the ability to support more than that 💜. These subscriptions might all come from one SWIMA-PV, might all come from different SWIMA-PVs (living on the same or different NEA Servers), or might be a mix 🌈. If a SWIMA-PC gets a subscription request but can't fit one more subscription, it MUST respond to that request with a PA-TNC Error attribute with the error code SWIMA_SUBSCRIPTION_DENIED_ERROR 🙈.
A SWIMA-PV MUST have the ability to record and support at least 256 simultaneous subscriptions, and SHOULD have the ability to support more than that 🔥. Any number of these subscriptions might go to the same SWIMA-PC, and any number might go to different SWIMA-PCs. In that second case, some of those SWIMA-PCs might share a single endpoint, while others might sit on different endpoints 🫶.
3.8.2. Managing Subscriptions 🗂️
The SWIMA-PC MUST record each accepted subscription along with the identity of the party that attributes are to be pushed to 💌. That identity has two parts:
- An identifier for the PB-TNC session between the Posture Broker Server on a NEA Server and the Posture Broker Client on the endpoint. This identifier is called the "Connection ID".
- The Posture Validator Identifier for the SWIMA-PV that made the subscription request.
The Posture Validator Identifier shows up in the field with the same name in the PB-PA message that wraps the subscription request attribute (Section 4.5 of [RFC5793]), and that info gets passed along to NEA Posture Collectors (Section 3.3 of [RFC5792]) 📬. The Connection ID is a value that's local to a particular endpoint's Posture Broker Client, and it identifies an ongoing session between one specific Posture Broker Client and one specific Posture Broker Server 🔗. Posture Broker Clients and Posture Broker Servers need to be able to handle multiple simultaneous sessions, so they already need a way to tell each ongoing session apart locally (see Section 3.1 of [RFC5793]) 🧠. A Posture Broker Client needs to give each session happening at a given time its own Connection ID, and that ID lasts for the life of that session 🎟️. Connection IDs only need to be unique among the Connection IDs of sessions happening at the same time on that endpoint. This Connection ID needs to be exposed to the SWIMA-PC, and the SWIMA-PC needs to be told when the Connection ID gets unbound because that connection closed 🚪.
Same deal on the other side: SWIMA-PVs MUST record each accepted subscription they're the subscribing party for, including the parameters of the establishing request, along with the associated Subscription ID and the identity of the SWIMA-PC that's going to fulfill the subscription 📝. The SWIMA-PV needs to keep this info so it can correctly interpret pushed SWIMA Response attributes sent in fulfillment of the subscription 🕵️♀️. The identity of the SWIMA-PC is given in the Posture Collector Identifier [RFC5793] in the PB-PA message header of every message from that SWIMA-PC. The SWIMA-PV doesn't need to record the subscription's associated Connection ID, since once a subscription is set up, the SWIMA-PV is only receiving attributes, not sending them 📥.
3.8.3. Terminating Subscriptions 🧹
Subscriptions MAY be terminated at any time by the subscribing SWIMA-PV by setting the Clear Subscriptions flag in a SWIMA Request (check Section 5.6 for more on using this flag 🔍). If a SWIMA Request with the Clear Subscriptions flag set comes in, the SWIMA-PC MUST only clear subscriptions that match both the NEA Server's Connection ID and the SWIMA-PV's Posture Validator Identifier for this SWIMA Request, and it MUST clear all such subscriptions 🧽.
This spec doesn't let the SWIMA-PV terminate subscriptions one at a time. All subscriptions to the SWIMA-PV get cleared when the Clear Subscriptions flag is set 💥.
This spec also doesn't let the SWIMA-PC terminate a subscription on its own. BUT, if the SWIMA-PC runs into a fatal error while fulfilling a subscription, which leads to sending a PA-TNC Error attribute with the error code SWIMA_SUBSCRIPTION_FULFILLMENT_ERROR, then the subscription whose fulfillment caused the error MUST be treated as terminated by both the SWIMA-PC and the SWIMA-PV 😭. Only the subscription that hit the error gets cancelled. Everyone else is unaffected ✅. Check Section 3.9 for more on this error condition.
Finally, a subscription is terminated if the connection between the SWIMA-PC and SWIMA-PV closes 🔌. That happens when the Connection ID used in messages between them becomes unbound. Losing this Connection ID would stop the SWIMA-PC from sending messages in fulfillment of the subscription, so losing it always forces the subscription to end between the affected parties 💀.
3.8.4. Subscription Status 📋
A SWIMA-PV can ask a SWIMA-PC to report the list of active subscriptions where the SWIMA-PV is the subscriber 🙋♀️. It can use this to recover lost info about its active subscriptions 🛟. It can also use this to check that a SWIMA-PC hasn't forgotten any of its subscriptions 👀. That last one is especially handy when a SWIMA-PC hasn't sent any attributes for a given subscription in a long time. The SWIMA-PV can check the SWIMA-PC's list of active subscriptions and figure out whether the quiet is due to (1) a lack of reportable events, or (2) the SWIMA-PC forgetting it owes a given subscription its fulfillment 🤔.
A SWIMA-PV asks a SWIMA-PC for its list of subscriptions by sending that SWIMA-PC a Subscription Status Request 📨. The SWIMA-PC MUST then respond with a Subscription Status Response (or a PA-TNC Error if it runs into an error condition) 🎁. The Subscription Status Response MUST contain one subscription record for each of the active subscriptions where the SWIMA-PV is the subscribing party 💯.
3.8.5. Fulfilling Subscriptions 🚀
As noted in Section 3.6, SWIMA-PCs are required to automatically detect changes to an endpoint's Software Inventory Evidence Collection in near real time ⏱️. For every active subscription, the SWIMA-PC MUST send an attribute to the subscribed SWIMA-PV whenever it detects a change to relevant records inside the endpoint's Software Inventory Evidence Collection 🔔. An attribute like that is said to be sent "in fulfillment of" the given subscription, and any such attribute MUST include that subscription's Subscription ID 🏷️. If the establishing request for that subscription was a targeted request, then only records that match the Software Identifiers given in that establishing request count as relevant 🎯. Otherwise (for non-targeted requests), any record counts as relevant 🌍. Figure 3 shows a sample attribute exchange where a subscription gets established and then attributes get sent from the SWIMA-PC in fulfillment of it 🎬.
+-------------+ +--------------+
| SWIMA-PC | | SWIMA-PV | Time
+-------------+ +--------------+ |
| | |
|<----------SWIMA Request-----------| |
| | |
|-----------SWIMA Response--------->| |
| | |
. . .
. . .
. . .
<Change Event>| | |
|----------SWIMA Response---------->| |
| | |
. . .
. . .
. . .
<Change Event>| | |
|----------SWIMA Response---------->| |
| | VFigure 3: Subscription Establishment and Fulfillment
The contents of an attribute sent in fulfillment of a subscription depend on the parameters given in the establishing request for that subscription 🧩. Specifically, the attribute sent in fulfillment has the same attribute type that a direct response to the establishing request would have 🪞. For example, if the establishing request asked for a response containing an event record list that included Software Inventory Evidence Records, then every attribute sent in fulfillment of that subscription will also be an event record list with Software Inventory Evidence Records 📚. That's why all the SWIMA Responses in the Figure 3 exchange are the same attribute type 🫧. A SWIMA Response generated in fulfillment of an active subscription MUST be a valid SWIMA Response attribute under all the rules in the preceding sections 💎. Put another way, an attribute built in fulfillment of a subscription looks the same as an attribute sent in direct response to an explicit request from a SWIMA-PV that had the same request parameters and arrived right after the given change event 🥰. There are a few special rules that expand on this guideline, which are covered in Sections 3.8.5.1 through 3.8.5.5 💅✨
3.8.5.1. Subscriptions That Report Inventories ✨
Okay so, when a SWIMA-PV subscribes to a SWIMA-PC and asks for an inventory attribute whenever changes get detected (aka the EID in the establishing request is 0), the SWIMA-PC MUST send the requested inventory every time a relevant change is detected. 🦋 A "relevant change" is any change for non-targeted requests, or a change to an indicated record in a targeted request. Once a relevant change shows up for an active subscription, the SWIMA-PC sends the right inventory info like it had just received the establishing request all over again. 💅 Inventory attributes sent for this subscription are probably going to be super repetitive, because the same records keep showing up in every single one. 😭 The whole point of an inventory subscription is NOT to report only the items that changed. That job belongs to the event-reporting subscription (see Section 3.8.5.2). A SWIMA-PC MUST NOT leave a record out of an attribute sent for an inventory subscription just because that record wasn't part of the event that triggered it. 🙅♀️ The only exception is when there's a different reason to leave it out, like the subscription being targeted (see Section 3.8.5.3). Iconic behavior, honestly. 👑
3.8.5.2. Subscriptions That Report Events 🎀
Let's talk about event subscriptions, bestie. 💖 A SWIMA-PV says it wants event records by putting a non-zero EID in the SWIMA Request that sets up the subscription (see Section 3.7.1). Here's the twist though: when the SWIMA-PC builds an attribute for the subscription (anything except the direct reply to the establishing request), it MUST only include event records for the detected change(s) that caused that particular response attribute. 🌸 Put simply, it MUST NOT send a full list of every change from the establishing request's EID all the way up to the latest change each time a new event pops up. 🙅♀️ Basically, the EID from the establishing request gets bumped forward every time an attribute goes out for this subscription, so a single event never gets reported twice for the same subscription. 🧚 Because of that, every SWIMA-PC MUST track the EID of the last event that triggered an attribute for the given subscription. When the next event (or batch of events) shows up, the SWIMA-PC MUST only report events with EIDs after the last reported one. 💜 If the SWIMA-PC's EID Epoch changes, the SWIMA-PC MUST reset this EID tracker to zero (if the event log got completely purged), or to the new EID of the last reported retained event (if the event log got partially purged to make a "sliding window"). 🔥 Doing all of this means the SWIMA-PC keeps sending only events that haven't been reported yet. Slay. 💅
Also, while a subscription is active, the subscribing SWIMA-PV MAY make other requests for event records that overlap with events already being reported for the subscription. 🦋 Those requests don't get affected by the subscription, and the subscription doesn't get affected by them either. ✨ In other words, a request gets the same results back whether or not there's a subscription, and an attribute sent for a subscription has the same info whether or not the SWIMA-PV has made other requests. Main character energy. 👑
Heads up, though: a SWIMA-PV needs to keep an eye on the EID Epoch in these attributes 👀, because when the Epoch changes it can create gaps in the SWIMA-PV's understanding of the endpoint's Software Inventory Evidence Collection state (see Section 3.7.6). Once the EID Epoch changes, the SWIMA-PV can't be confident that it understands the endpoint's state until it collects a complete inventory. 😭 > Don't skip this part, it's a big deal.
SWIMA-PCs MAY send partial lists of event records in fulfillment of a subscription. (See Section 3.7.5 for more on partial lists of event records.) If a SWIMA-PC sends a partial list for a subscription, it MUST immediately send the next consecutive partial list and keep going until it has sent the equivalent of the complete list of event records. 🫶 So it does NOT wait around for another change event to send the next SWIMA Response. It just keeps sending SWIMA Responses until everything that would have been in a complete fulfillment has gone out. 🚀 Note that the direct response to the establishing request does NOT count as being sent in fulfillment of a subscription. Still, in that case the SWIMA-PC MUST treat any unreported events as a triggering event for pushing more messages for the brand-new subscription. 💫 So the net effect is this: if the direct response to the establishing request is partial (meaning the Subscription Fulfillment flag is unset in Subscription Fulfillment flag), the SWIMA-PC will immediately follow up with more attributes (with the Subscription Fulfillment flag set) until the SWIMA-PV has the complete set of events. 🍓
3.8.5.3. Targeted Subscriptions 🎯
Subscriptions MAY be targeted so they only apply to records matching a given set of Software Identifiers. 🧁 Now, say changes affect multiple records and only some of them match the establishing request's Software Identifiers. The attribute sent for the subscription MUST only include inventory or events (whichever is relevant) for the records that match. 🌈 The SWIMA-PC MUST NOT include non-matching records in the attribute, even if those non-matching records had change events at the same time as the matching ones. Not the vibe, no cap. 🙅♀️
Also, a SWIMA-PC MUST only send an attribute for a targeted subscription when changes to the endpoint's Software Inventory Evidence Collection actually impact one or more records matching the subscription's establishing request's Software Identifiers. 💖 A SWIMA-PC MUST NOT send any attribute for a targeted subscription based on changes that didn't involve any of the records the subscription was targeting. Bestie, that would be so noisy. 🙈
3.8.5.4. No Subscription Consolidation 🚫
A SWIMA-PV MAY set up multiple subscriptions to a given SWIMA-PC. 🌷 If it does, a single change event on the endpoint might need to be fulfilled by several subscriptions at once, and the info in the attributes for each of those subscriptions could overlap. 🫠 The SWIMA-PC MUST send separate attributes for each established subscription that needs a response because of that event. Each one of those attributes MUST contain all the info needed to fulfill its own subscription, even if that same info also shows up in other attributes sent for other subscriptions at the same time. 💅 In other words, SWIMA-PCs MUST NOT try to combine information when fulfilling multiple subscriptions at once, even though that means some redundancy in what the SWIMA-PV receives. 🔁 It's extra, but it's correct. 💜
3.8.5.5. Delayed Subscription Fulfillment ⏳
A SWIMA-PC MAY delay fulfilling a subscription after a change event, so it can wait and see if more change events are coming and then send all the relevant records back in one SWIMA Response attribute. 🐝 This can help cut down on network bandwidth use between the SWIMA-PC and the SWIMA-PV. For example, imagine 10 changes happen a tenth of a second apart. If the SWIMA-PC doesn't delay assembling and sending SWIMA Response attributes, the SWIMA-PV gets 10 separate SWIMA Response attributes over a period of 1 second. 😩 But if the SWIMA-PC waits half a second after the first event before assembling a SWIMA Response, the SWIMA-PV only gets two SWIMA Response attributes over that same stretch of time. ✨ Galaxy brain, honestly. 🧠
Note that consolidating events for a single subscription over a period of time does not contradict the rules in Section 3.8.5.4, which prohibit consolidation across multiple subscriptions. 🎀 When delaying fulfillment, SWIMA-PCs are still required to fulfill each individual subscription separately. Also, if the change events inside the delay window cancel each other out (say a record gets deleted and then re-added), the SWIMA-PC MUST still report each change event, and NOT just the net effect of the changes over the delay period. 🙅♀️ So yeah: delayed fulfillment can reduce how many attributes the SWIMA-PC sends, but it does NOT reduce the total number of change events reported. 🌸
SWIMA-PCs are not required to support delayed fulfillment of subscriptions. 🦄 However, if a SWIMA-PC does support delayed subscription fulfillment, it MUST be possible to configure the SWIMA-PC to disable delayed fulfillment. 🔧 In other words, the people deploying SWIMA-PCs need to be able to turn delayed subscription fulfillment off. How that configuration happens is up to implementers 🤷♀️, but implementers MUST protect the configuration procedure from unauthorized tampering. 🔒 Basically, there needs to be some assurance that random unauthorized people can't sneak in and cause long delays in subscription fulfillment. Not on my watch. 😤
3.9. Error Handling ✨
Okay bestie, let's talk about what happens when things go wrong 🙈 If the SWIMA-PC spots an error in a SWIMA Request attribute it receives, it MUST respond with a PA-TNC Error attribute carrying an error code that fits the problem. (Check Section 4.2.8 of PA-TNC [RFC5792] for the deets on PA-TNC Error attributes and error codes, and Section 5.15 in this specification for the error codes that are specific to SWIMA attributes 💅.) If an error shows up in a SWIMA Request, the SWIMA-PC MUST NOT take any action that request asked for, even if it could partially finish the job 🚫. So a SWIMA Request with an error gets completely ignored by the SWIMA-PC, apart from sending back a PA-TNC Error attribute and maybe logging the error locally 💀. No partial credit, no partial completion, periodt.
Now the other situation: the SWIMA-PC gets a totally valid SWIMA Request attribute, but then runs into an error while carrying out its instructions, and that error stops it from properly or fully finishing the request 😭. In that case, the SWIMA-PC MUST send a PA-TNC Error attribute with an error code that fits the problem. And once a PA-TNC Error attribute is being sent, the SWIMA-PC MUST NOT take any of the actions the SWIMA Request attribute asked for. That's true even if some of those actions would have worked fine, and even if it means the SWIMA-PC has to undo some successful stuff it already did before the error showed up 🔄. So it's all or nothing: either (1) every aspect of the SWIMA Request completes fully and successfully (and then the SWIMA-PC sends a SWIMA Response attribute), or (2) none of the SWIMA Request happens (and then the SWIMA-PC sends a PA-TNC Error attribute). If the SWIMA-PC sends a PA-TNC Error attribute in response to a SWIMA Request, it MUST NOT also send any SWIMA Response attribute for that same request. That's why sending a SWIMA Response attribute MUST be the very last thing the SWIMA-PC does in response to a SWIMA Request, so no processing error can sneak in after the response has already gone out 🎀.
If the SWIMA-PC detects an error that stops it from properly or completely meeting its obligations under an active subscription, it MUST send a PA-TNC Error attribute with error code SWIMA_SUBSCRIPTION_FULFILLMENT_ERROR to the SWIMA-PV that established this subscription 📣. This type of PA-TNC Error attribute identifies the specific subscription that can't be adequately honored because of the error, and it also identifies an error "subtype" ✨. The error subtype is the error code for the error condition the SWIMA-PC ran into that prevented it from honoring the subscription. If the error condition can't be identified, or it doesn't line up with any of the defined error codes, the SWIMA_ERROR error code SHOULD be used in the subtype 🤷♀️. And whenever a SWIMA_SUBSCRIPTION_FULFILLMENT_ERROR is sent, the associated subscription MUST be treated as cancelled by both the SWIMA-PC and the SWIMA-PV 🚫.
The SWIMA-PV MUST NOT send any PA-TNC Error attributes to SWIMA-PCs 🙅. If the SWIMA-PV detects an error condition, it SHOULD log the error, but it does not inform any SWIMA-PCs of this event. Errors might include, but are not limited to, the detection of malformed SWIMA Response attributes sent from a given SWIMA-PC, as well as the detection of error conditions when the SWIMA-PV processes SWIMA Responses 🧐.
Both SWIMA-PCs and SWIMA-PVs SHOULD log errors so administrators can trace what caused them 🔍. Log entries SHOULD include the code of the error, the time it was detected, and additional descriptive information to help make sense of the nature and cause of the error 📝. Logs are a seriously important debugging tool, and implementers are strongly advised to include comprehensive logging capabilities in their products 💖.
4. Protocol 🎀
The SWIMA protocol supports two different types of message exchanges for conveying software inventory information 📦. Those are described in the subsections below, along with the implementation requirements for supporting them 💅.
The SWIMA protocol also has two simple status exchanges ✨: a Subscription Status exchange for conveying information about active subscriptions, and a Source Metadata exchange for conveying information about a SWIMA-PC's data sources. In both cases, a SWIMA-PV sends a request attribute (Subscription Status Request or Source Metadata Request, respectively) and a SWIMA-PC responds with a matching response attribute (Subscription Status Response or Source Metadata Response, respectively). Since these exchanges are straightforward, no additional information on them is provided 🫶.
4.1. Direct Response to a SWIMA Request 🦋
The first type of software information exchange is used to give the SWIMA-PV a software inventory or event collection from the queried endpoint 🗂️.
+-------------+ +--------------+
| SWIMA-PC | | SWIMA-PV | Time
+-------------+ +--------------+ |
| | |
|<-----------SWIMA Request------------| |
| | |
| SWIMA Response* | |
|-----------------or----------------->| |
| PA-TNC Error | |
| | V
*SWIMA Response is one of the following: Software Identifier
Inventory, Software Identifier Events, Software Inventory,
or Software Events.Figure 4: SWIMA Attribute Exchange (Direct Response to SWIMA Request)
In this exchange, the SWIMA-PV tells the SWIMA-PC, via a SWIMA Request, the nature of the information it wants (inventory vs. events, full or targeted) and how it wants the returned inventory expressed (with or without Software Inventory Evidence Records) 📝. The SWIMA-PC replies with the requested information using the appropriate attribute type. A single SWIMA Request MUST only lead to a single SWIMA Response or PA-TNC Error that is in direct response to that request 💜.
4.2. Subscription-Based Response 🌈
The second type of software information exchange allows change-event-based reporting based on a subscription 🔔. If there is an active subscription on the endpoint, the SWIMA-PC sends a SWIMA Response to the SWIMA-PV following a change event on the endpoint in fulfillment of that subscription. Peep Figure 5 for how that goes 👀.
+-------------+ +--------------+
| SWIMA-PC | | SWIMA-PV | Time
+-------------+ +--------------+ |
| | |
<Change Event>| | |
|------SWIMA Response(s)*------>| |
| | |
| | V
*SWIMA Response is one of the following: Software Identifier
Inventory, Software Identifier Events, Software Inventory,
or Software Events.Figure 5: SWIMA Attribute Exchange (in Fulfillment of an Active Subscription)
Note that unlike direct responses to a SWIMA Request, a single change event can set off multiple SWIMA Responses for a single subscription, but only if all but the last of those SWIMA Responses convey partial lists of event records 🧩. When multiple SWIMA Responses are provided this way, the early responses contain partial lists of event records, and the last one conveys the remainder of the relevant event records, completing delivery of all relevant events for that change event 🎉. A single change event MUST NOT otherwise be followed by multiple SWIMA Responses or PA-TNC Error attributes in any combination 🙅.
4.3. Required Exchanges 📋
All SWIMA-PVs and SWIMA-PCs MUST support both types of software information exchanges. In particular, SWIMA-PCs MUST be capable of pushing a SWIMA Response to a SWIMA-PV immediately upon detection of a change to the endpoint's Software Inventory Evidence Collection in fulfillment of established SWIMA-PV subscriptions, as described in Section 3.8 🫶.
All SWIMA-PCs MUST support both status exchanges (Subscription Status and Source Metadata). SWIMA-PVs are recommended to support these status exchanges, but doing so is not required 💖.
5. Software Inventory Messages and Attributes 🧾
This section describes the format and semantics of the SWIMA protocol 🧠. This protocol uses the PA-TNC message header format [RFC5792].
5.1. PA Subtype (aka PA-TNC Component Type) 🏷️
The NEA PB-TNC [RFC5793] interface provides a general message-batching protocol that's capable of carrying one or more PA-TNC messages between the Posture Broker Client and Posture Broker Server 📬. When PB-TNC is carrying a PA-TNC message, the PB-TNC message headers contain a 32-bit identifier called the "PA Subtype". The PA Subtype field indicates the type of component associated with all of the PA-TNC attributes carried by the PB-TNC message. The core set of PA Subtypes is defined in the PA-TNC specification. This specification defines a new "SWIMA Attributes" PA Subtype, which is registered in Section 10.2 of this document and is used as a namespace for the collection of SWIMA attributes defined in this document 🌸.
For more information on PB-TNC messages and PA-TNC messages, as well as their message headers, see the PB-TNC [RFC5793] and PA-TNC [RFC5792] specifications, respectively ✨.
5.2. SWIMA Attribute Overview 💅
okay so every PA-TNC attribute in this spec is meant to zip back and forth between the SWIMA-PC and the SWIMA-PV, which means it rides inside a PB-TNC message tagged with a PA Subtype of "SWIMA Attributes" 🎀 PB-TNC messages MUST always include the SWIMA Attributes Subtype defined in Section 5.1 when carrying SWIMA attributes over PA-TNC. Here's the whole lineup with a quick vibe check on each one ✨
+--------------+-----------------+----------------------------------+
| Attribute | Integer | Description |
| Name | | |
+--------------+-----------------+----------------------------------+
| SWIMA | 0x0000000D (13) | Request sent from a SWIMA-PV to |
| Request | | a SWIMA-PC for the SWIMA-PC to |
| | | provide a software inventory or |
| | | event list. It might also |
| | | establish a subscription. |
| | | (Section 5.6) |
| | | |
| Software | 0x0000000E (14) | An inventory sent without |
| Identifier | | Software Inventory Evidence |
| Inventory | | Records sent from a SWIMA-PC. |
| | | (Section 5.7) |
| | | |
| Software | 0x0000000F (15) | A collection of events impacting |
| Identifier | | the endpoint's Software |
| Events | | Inventory Evidence Collection, |
| | | where events do not include |
| | | Software Inventory Evidence |
| | | Records. (Section 5.8) |
| | | |
| Software | 0x00000010 (16) | An inventory including Software |
| Inventory | | Inventory Evidence Records sent |
| | | from a SWIMA-PC. (Section 5.9) |
| | | |
| Software | 0x00000011 (17) | A collection of events impacting |
| Events | | the endpoint's Software |
| | | Inventory Evidence Collection, |
| | | where events include Software |
| | | Inventory Evidence Records. |
| | | (Section 5.10) |
| | | |
| Subscription | 0x00000012 (18) | A request for a list of a |
| Status | | SWIMA-PV's active subscriptions |
| Request | | on a SWIMA-PC. (Section 5.11) |
| | | |
| Subscription | 0x00000013 (19) | A list of a SWIMA-PV's active |
| Status | | subscriptions on a SWIMA-PC. |
| Response | | (Section 5.12) |
| | | |
| Source | 0x00000014 (20) | A request for information about |
| Metadata | | a SWIMA-PC's data sources. |
| Request | | (Section 5.13) |
| | | |
| Source | 0x00000015 (21) | Descriptive metadata about a |
| Metadata | | SWIMA-PC's data sources. |
| Response | | (Section 5.14) |
| | | |
| PA-TNC Error | 0x00000008 (8) | An error attribute as defined in |
| | | the PA-TNC specification |
| | | [RFC5792]. |
+--------------+-----------------+----------------------------------+
Table 1: SWIMA Attribute EnumerationAttribute type IDs live in the PA-TNC Attribute Header, via the PA-TNC Attribute Vendor ID field and the PA-TNC Attribute Type field. Check Section 4.1 of [RFC5792] for the full scoop 🧚 Table 1 gives you the exact values for every SWIMA attribute type. Every single one has a PEN value of 0x000000, and both hex and decimal show up in the Integer column. Each attribute gets its own deep dive in the section listed in the Description column 🦋
Because one of the Software Identifier Inventory, Software Identifier Events, Software Inventory, or Software Events attributes is expected to be sent to a SWIMA-PV in direct response to a SWIMA Request attribute or in fulfillment of an active subscription, those four attribute types are referred to collectively in this document as "SWIMA Response attributes". Main character group name, honestly 👑
All SWIMA-PVs MUST be capable of sending SWIMA Request attributes and be capable of receiving and processing all SWIMA Response attributes as well as PA-TNC Error attributes. All SWIMA-PCs MUST be capable of receiving and processing SWIMA Request attributes and be capable of sending all types of SWIMA Response attributes as well as PA-TNC Error attributes. SWIMA-PVs MUST ignore any SWIMA Request attributes that they receive. SWIMA-PCs MUST ignore any SWIMA Response attributes or PA-TNC Error attributes that they receive. So basically, the PV asks and the PC answers, and nobody gets to be weird about it 🙈
5.3. Message Diagram Syntax 🍓
this spec uses diagrams to define the syntax of new PA-TNC messages and attributes, and each one shows the format and size of every field in bits. Implementations MUST send the bits depicted in each diagram as they are shown from left to right for each 32-bit quantity, "traversing" the diagram from top to bottom. Fields representing numeric values MUST be sent in network (big endian) byte order. Bit-order-wise, the bit positions are numbered from the most significant bit through the least significant bit, so this part is giving clarity 💜
Descriptions of bit field (e.g., flag) values refer to the position of the bit within the field. As such, an octet with only bit 0 set would have a value of 0x80 (1000 0000), an octet with only bit 1 set would have a value of 0x40 (0100 0000), and an octet with only bit 7 set would have a value of 0x01 (0000 0001). Bit 0 is the big boss at the top, so don't get it twisted 😭
5.4. Normalization of Text Encoding 🌸
okay so, to keep transmitted attributes consistent, some fields need their format normalized. When that's necessary, the field's description tells you so. In those cases, the field contents MUST be normalized to Network Unicode format as defined in RFC 5198 [RFC5198]. Network Unicode format is a refinement of UTF-8 [RFC3629] that makes sure characters get a single normalized spelling, which is very much a "one true form" energy 💅
SWIMA-PCs and SWIMA-PVs MUST NOT perform conversion and normalization on any field values except those specifically identified in the following sections as requiring normalization. Note, however, that some data models require additional normalization before source information is added to an endpoint's Software Inventory Evidence Collection as a record. The references from the "Software Data Model Types" registry (see Section 10.5) will note where this is necessary. So check that registry before you go poking at anything 🔥
5.5. Request IDs 🎀
All SWIMA Request attributes MUST include a Request ID value. The Request ID field gives a value that identifies a given request relative to other requests between a SWIMA-PV and the receiving SWIMA-PC. Specifically, the SWIMA-PV assigns each SWIMA Request attribute a Request ID value that is intended to be unique within the lifetime of a given network Connection ID. Unique IDs, no cap 🧚
In the case that a SWIMA Request requests the establishment of a subscription and the receiving SWIMA-PC agrees to that subscription, the Request ID of that SWIMA Request (i.e., the establishing request of the subscription) becomes that subscription's Subscription ID. All attributes sent in fulfillment of this subscription include a flag indicating that the attribute fulfills a subscription and the subscription's Subscription ID. A SWIMA-PV MUST NOT reuse a Request ID value in communications with a given SWIMA-PC while that Request ID is also serving as a Subscription ID for an active subscription with that SWIMA-PC. In the case where a SWIMA-PC receives a SWIMA Request from a given SWIMA-PV where that Request ID is also the Subscription ID of an active subscription with that SWIMA-PV, the SWIMA-PC MUST respond with a PA-TNC Error attribute with an error code of SWIMA_SUBSCRIPTION_ID_REUSE_ERROR. Note that this error does not cancel the indicated subscription. So the error is loud, but the subscription is still alive and well 💖
Subscription Status Requests and Subscription Status Responses do not include Request IDs. Just a little plot twist for you 🦋
In the case where all possible Request ID values have been exhausted within the lifetime of a single network Connection ID, the sender MAY reuse previously used Request IDs within the same network connection if the ID is not being used as a Subscription ID. In the case where reuse is necessary due to exhaustion of possible ID values, the SWIMA-PV SHOULD structure the reuse to maximize the time between original and subsequent use. The Request ID value is included in a SWIMA Response attribute directly responding to this SWIMA Request to indicate which SWIMA Request was received and caused the response. Request IDs can be randomly generated or sequential, as long as values are not repeated per the rules in this paragraph. SWIMA-PCs are not required to check for duplicate Request IDs, except insofar as is necessary to detect Subscription ID reuse. Basically, when you run out of IDs, spread the reuse out as far as you can, and the PC only has to care about duplicates when it's checking for subscription reuse 🌈
5.6. SWIMA Request ⭐
A SWIMA-PV sends this attribute to a SWIMA-PC to request that the SWIMA-PC send software inventory information to the SWIMA-PV. A SWIMA-PC MUST NOT send this attribute. Only the PV gets to ask, bestie 💅
1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Flags | Software Identifier Count |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Request ID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Earliest EID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
| SUB-BLOCK (Repeated "Software Identifier Count" times) |
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Figure 6: SWIMA Request Attribute 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Software Identifier Length | Software Identifier (var len) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Figure 7: SWIMA Request Attribute SUB-BLOCK +---------------+---------------------------------------------------+
| Field | Description |
+---------------+---------------------------------------------------+
| Flags: Bit 0 | If set (1), the SWIMA-PC MUST delete all |
| - Clear | subscriptions established by the requesting |
| Subscriptions | SWIMA-PV (barring any errors). |
| | |
| Flags: Bit 1 | If set (1), in addition to responding to the |
| - Subscribe | request as described, the SWIMA-PC MUST establish |
| | a subscription with parameters matching those in |
| | the SWIMA Request attribute (barring any errors). |
| | |
| Flags: Bit 2 | If unset (0), the SWIMA-PC's response MUST |
| - Result Type | include Software Inventory Evidence Records, and |
| | thus the response MUST be a Software Inventory, |
| | Software Events, or PA-TNC Error attribute. If |
| | set (1), the response MUST NOT include Software |
| | Inventory Evidence Records, and thus the response |
| | MUST be a Software Identifier Inventory, Software |
| | Identifier Events, or PA-TNC Error attribute. |
| | |
| Flags: Bits | Reserved for future use. This field MUST be set |
| 3-7 - | to zero on transmission and ignored upon |
| Reserved | reception. |
| | |
| Software | A 3-byte unsigned integer indicating the number |
| Identifier | of Software Identifiers that follow. If this |
| Count | value is non-zero, this is a targeted request, as |
| | described in Section 3.5. The Software |
| | Identifier Length and Software Identifier fields |
| | are repeated, in order, the number of times |
| | indicated in this field. In the case where |
| | Software Identifiers are present, the SWIMA-PC |
| | MUST only report software that corresponds to the |
| | identifiers the SWIMA-PV provided in this |
| | attribute (or respond with a PA-TNC Error |
| | attribute). This field value MAY be 0, in which |
| | case there are no instances of the Software |
| | Identifier Length and Software Identifier fields. |
| | In this case, the SWIMA-PV is indicating an |
| | interest in all Software Inventory Evidence |
| | Records on the endpoint (i.e., this is not a |
| | targeted request). |
| | |
| Request ID | A value that uniquely identifies this SWIMA |
| | Request from a particular SWIMA-PV. |
| | |
| Earliest EID | In the case where the SWIMA-PV is requesting |
| | software events, this field contains the EID |
| | value of the earliest event the SWIMA-PV wishes |
| | to have reported. (Note: The report will be |
| | inclusive of the event with this EID value.) In |
| | the case where the SWIMA-PV is requesting an |
| | inventory, then this field MUST be 0 |
| | (0x00000000). In the case where this field is |
| | non-zero, the SWIMA-PV is requesting events, and |
| | the SWIMA-PC MUST respond using a Software |
| | Events, Software Identifier Events, or PA-TNC |
| | Error attribute. In the case where this field is |
| | zero, the SWIMA-PV is requesting an inventory, |
| | and the SWIMA-PC MUST respond using a Software |
| | Inventory, Software Identifier Inventory, or |
| | PA-TNC Error attribute. |
| | |
| Software | A 2-byte unsigned integer indicating the length, |
| Identifier | in bytes, of the Software Identifier field. |
| Length | |
| | |
| Software | A string containing the Software Identifier value |
| Identifier | from a Software Inventory Evidence Record. This |
| | field value MUST be normalized to Network Unicode |
| | format, as described in Section 5.4. This string |
| | MUST NOT be null terminated. |
+---------------+---------------------------------------------------+
Table 2: SWIMA Request Attribute FieldsOkay bestie, so the SWIMA-PV slides a SWIMA Request attribute over to a SWIMA-PC 💌 to ask for exactly the info it wants ✨. Between the Result Type flag and the Earliest EID field, the SWIMA-PC is locked into one possible SWIMA Response attribute type (or a PA-TNC Error attribute) for its reply 🔒. No freestyling here 💅.
The Subscribe flag and the Clear Subscriptions flag are the subscription managers 🦋. Subscribe set means the requesting SWIMA-PV wants a brand new subscription with that SWIMA-PC. Clear Subscriptions set means it wants every existing subscription it has with that SWIMA-PC deleted. Heads up though: in that second case, only the subscriptions tied to the requester's Connection ID and Posture Validator Identifier get wiped, as described in Section 3.8.3 🫶. A new subscription takes its vibe from the SWIMA Request attribute. The Result Type flag decides what kind of result gets sent, the Earliest EID value decides whether the fulfillment lists inventories or events, and the Software Identifier fields (if they're there) decide whether and how the subscription is targeted 🎯. If the SWIMA-PC is unable or unwilling to do the subscribing or clearing, it MUST respond with a PA-TNC Error attribute with the SWIMA_SUBSCRIPTION_DENIED_ERROR error code 😭. And if the SWIMA-PV asks to clear subscriptions it doesn't have? Not an error, chill 🌸.
Subscribing is giving main character "double duty" energy 👑. It's an immediate request for a response and a subscription setup at the same time. If the SWIMA-PC is willing to go along with the subscription, it MUST send an appropriate response attribute containing all of the requested information. The Clear Subscriptions flag works the same way: as long as there's no error, the SWIMA-PC MUST generate a response attribute no matter whether this flag is there, and it also clears its subscription list 🧹.
Both the Subscribe flag and the Clear Subscriptions flag MAY be set in one SWIMA Request attribute 🍓. When that request works out, the end result MUST be the same as the SWIMA-PC clearing its subscription list for that SWIMA-PV first and only then creating the new subscription using the request parameters. So do not create the new subscription first and then clear everything, because that would wipe out the one you just made 🙅♀️. If the requested actions are completed successfully, the SWIMA-PC MUST respond with a SWIMA Response attribute, and the exact type depends on the Result Type flag and the Earliest EID field, as covered above ✅. But if something fails and stops any part of the request from finishing, the SWIMA-PC MUST NOT add a new subscription, MUST NOT clear the old subscriptions, and MUST respond with a PA-TNC Error attribute 🚫. In other words, the SWIMA-PC MUST NOT partially succeed at this. It's all or nothing, babe: either every action works or none of them do 💀.
The Earliest EID field tells the SWIMA-PC whether the SWIMA-PV wants an inventory or an event list 📋. A value of 0 (0x00000000) means "give me the inventory info." Anything else means "give me the event info." For Earliest EID values other than 0, the SWIMA-PC MUST respond with event records, as described in Section 3.7 📜. Also, the request doesn't name a particular EID Epoch, because responses can only include events from the SWIMA-PC's current EID Epoch 🧚.
The Software Identifier Count tells you how many Software Identifiers are in the attribute, and it can be any value from 0 to 16,777,216, inclusive 🔢. Each single Software Identifier is made of two fields: Software Identifier Length and Software Identifier. Those two fields repeat as many times as the Software Identifier Count says, and that count is allowed to be 0 🫧. The Software Identifier Length field says how many bytes are set aside for the Software Identifier field. The Software Identifier field holds a Software Identifier as described in Section 3.4.1 🏷️. When identifiers show up, the SWIMA-PV is flagging a targeted request, which means it only wants inventories or events about software matching those identifiers 🎀. The SWIMA-PC MUST only report software that matched the Software Identifiers in the SWIMA-PV's SWIMA Request attribute. No random extras, periodt 💖.
5.7. Software Identifier Inventory ✨
okay bestie 💅 so a SWIMA-PC uses this attribute to send a SWIMA-PV the inventory of the endpoint's Software Inventory Evidence Collection, but without the actual Software Inventory Evidence Records attached 🎀. The list could be the whole inventory or a targeted list, depending on what the SWIMA-PV asked for in its request. A SWIMA-PV MUST NOT send this attribute 🙈.
The SWIMA-PC only sends this one in two situations 🦋: (1) to fulfill an existing subscription whose establishing request has a Result Type of 1 and an Earliest EID of zero, or (2) as a direct response to a SWIMA Request attribute where the Result Type is 1 and the Earliest EID is zero.
1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Flags | Software Identifier Count |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Request ID Copy / Subscription ID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| EID Epoch |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Last EID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
| SUB-BLOCK (Repeated "Software Identifier Count" times) |
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Figure 8: Software Identifier Inventory Attribute
1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Record Identifier |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Data Model Type PEN |Data Model Type|
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Source Id Num | Reserved | Software Identifier Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Software Identifier (variable length) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Software Locator Length |Software Locator (variable len)|
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Figure 9: Software Identifier Inventory Attribute SUB-BLOCK
Here's the field breakdown, straight from the table 💖:
+----------------+--------------------------------------------------+
| Field | Description |
+----------------+--------------------------------------------------+
| Flags: Bit 0 - | In the case that this attribute is sent in |
| Subscription | fulfillment of a subscription, this bit MUST be |
| Fulfillment | set (1). In the case that this attribute is a |
| | direct response to a SWIMA Request, this bit |
| | MUST be unset (0). |
| | |
| Flags: Bits | Reserved for future use. This field MUST be set |
| 1-7 - Reserved | to zero on transmission and ignored upon |
| | reception. |
| | |
| Software | The number of Software Identifiers that follow. |
| Identifier | This field is an unsigned integer. The Record |
| Count | Identifier, Data Model Type PEN, Data Model |
| | Type, Source Identification Number, Reserved, |
| | Software Identifier Length, Software Identifier, |
| | Software Locator Length, and Software Locator |
| | fields are repeated, in order, the number of |
| | times indicated in this field. This field value |
| | MAY be 0, in which case there are no instances |
| | of these fields. |
| | |
| Request ID | In the case where this attribute is in direct |
| Copy / | response to a SWIMA Request attribute from a |
| Subscription | SWIMA-PV, this field MUST contain an exact copy |
| ID | of the Request ID field from that SWIMA Request. |
| | In the case where this attribute is sent in |
| | fulfillment of an active subscription, this |
| | field MUST contain the Subscription ID of the |
| | subscription being fulfilled by this attribute. |
| | |
| EID Epoch | The EID Epoch of the Last EID value. This field |
| | is a 4-byte unsigned integer. |
| | |
| Last EID | The EID of the last event recorded by the |
| | SWIMA-PC, or 0 if the SWIMA-PC has no recorded |
| | events. This field is a 4-byte unsigned |
| | integer. |
| | |
| Record | A 4-byte unsigned integer containing the Record |
| Identifier | Identifier value from a Software Inventory |
| | Evidence Record. |
| | |
| Data Model | A 3-byte unsigned integer containing the Private |
| Type PEN | Enterprise Number (PEN) of the organization that |
| | assigned the meaning of the Data Model Type |
| | value. |
| | |
| Data Model | A 1-byte unsigned integer containing an |
| Type | identifier number that identifies the data model |
| | of the reported record. |
| | |
| Source | The Source Identifier number associated with the |
| Identification | source from which this software installation |
| Number | inventory instance was reported. |
| | |
| Reserved | Reserved for future use. This field MUST be set |
| | to zero on transmission and ignored upon |
| | reception. |
| | |
| Software | A 2-byte unsigned integer indicating the length, |
| Identifier | in bytes, of the Software Identifier field. |
| Length | |
| | |
| Software | A string containing the Software Identifier |
| Identifier | value from a Software Inventory Evidence Record. |
| | This field value MUST be normalized to Network |
| | Unicode format, as described in Section 5.4. |
| | This string MUST NOT be null terminated. |
| | |
| Software | A 2-byte unsigned integer indicating the length, |
| Locator Length | in bytes, of the Software Locator field. |
| | |
| Software | A string containing the Software Locator value. |
| Locator | This field value MUST first be normalized to |
| | Network Unicode format, as described in |
| | Section 5.4, and then encoded as a URI |
| | [RFC3986]. This string MUST NOT be null |
| | terminated. |
+----------------+--------------------------------------------------+Table 3: Software Identifier Inventory Attribute Fields
Now the fun bits 🌈. When this attribute comes as a subscription fulfillment, the Subscription Fulfillment bit MUST be set (1) ✨. When it's a direct response to a SWIMA Request, that bit MUST be unset (0) 🌸. Heads up on a sneaky one: a SWIMA Response sent directly in response to the SWIMA Request that establishes a subscription MUST be treated as a direct response to that request, so the bit is unset there too 👀. A SWIMA Response only counts as being in fulfillment of a subscription (bit set) when it gets sent after a change event, like the one shown in Figure 3 🔥.
The Software Identifier Count field tells you how many Software Identifiers are in this inventory 🍓. Each one is made up of the Record Identifier, Data Model Type PEN, Data Model Type, Source Identification Number, Reserved, Software Identifier Length, Software Identifier, Software Locator Length, and Software Locator fields, and those show up once for every reported record 🧚.
When you're directly responding to a SWIMA Request, the Request ID Copy / Subscription ID field MUST contain an exact copy of the Request ID from that SWIMA Request 🫶. When this goes out to fulfill an existing subscription on this SWIMA-PC, that same field MUST contain the Subscription ID of the subscription being fulfilled 💜.
The EID Epoch field gives you the EID Epoch of the Last EID value 🌈. The Last EID field MUST contain the EID of the last recorded change event (see Section 3.7 for more about EIDs and recorded events) at the time this inventory was collected 🦋. If there were no recorded change events at that moment, the Last EID field MUST contain 0 🙈. Together, these two fields basically say "this inventory reflects the endpoint's state once every change up to and including this last event has been accounted for" ⭐.
The Data Model Type PEN and Data Model Type fields work together to identify the data model for each software record 🎀. You can read more about those in Section 3.4.2 💅.
The Source Identification Number field is how you figure out which source reported a given record, as described in Section 3.1 🫶.
5.8. Software Identifier Events ✨
Okay, so this one is the sibling attribute 👯♀️. A SWIMA-PC sends it to a SWIMA-PV to report events where the affected records are reported without Software Inventory Evidence Records 🦋. A SWIMA-PV MUST NOT send this attribute 🙈. The SWIMA-PC sends it either (1) to fulfill an existing subscription whose establishing request has a Result Type of 1 and a non-zero Earliest EID, or (2) as a direct response to a SWIMA Request attribute where the Result Type is 1 and the Earliest EID is non-zero 💖.
Okay bestie, this is the final bit of 5.8 💖 Figure 10 shows the whole Software Identifier Events attribute, and it's got that repeated SUB-BLOCK energy 🧚
1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Flags | Event Count |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Request ID Copy / Subscription ID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| EID Epoch |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Last EID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Last Consulted EID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
| SUB-BLOCK (Repeated "Event Count" times) |
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Figure 10: Software Identifier Events Attribute
Now the star of the show, the SUB-BLOCK itself 🌸 Figure 11 breaks it down field by field, so you can see exactly where each piece lives ✨
1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| EID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
+- -+
| |
+- -+
| Timestamp |
+- -+
| |
+- -+
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Record Identifier |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Data Model Type PEN |Data Model Type|
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Source Id Num | Action | Software Identifier Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Software Identifier (variable length) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Software Locator Length |Software Locator (variable len)|
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Figure 11: Software Identifier Events Attribute SUB-BLOCK
+----------------+--------------------------------------------------+
| Field | Description |
+----------------+--------------------------------------------------+
| Flags: Bit 0 - | In the case that this attribute is sent in |
| Subscription | fulfillment of a subscription, this bit MUST be |
| Fulfillment | set (1). In the case that this attribute is a |
| | direct response to a SWIMA Request, this bit |
| | MUST be unset (0). |
| | |
| Flags: Bits | Reserved for future use. This field MUST be set |
| 1-7 - Reserved | to zero on transmission and ignored upon |
| | reception. |
| | |
| Event Count | The number of events that are reported in this |
| | attribute. This field is a 3-byte unsigned |
| | integer. The EID, Timestamp, Record Identifier, |
| | Data Model Type PEN, Data Model Type, Source |
| | Identification Number, Action, Software |
| | Identifier Length, Software Identifier, Software |
| | Locator Length, and Software Locator fields are |
| | repeated, in order, the number of times |
| | indicated in this field. This field value MAY |
| | be 0, in which case there are no instances of |
| | these fields. |
| | |
| Request ID | In the case where this attribute is in direct |
| Copy / | response to a SWIMA Request attribute from a |
| Subscription | SWIMA-PV, this field MUST contain an exact copy |
| ID | of the Request ID field from that SWIMA Request. |
| | In the case where this attribute is sent in |
| | fulfillment of an active subscription, this |
| | field MUST contain the Subscription ID of the |
| | subscription being fulfilled by this attribute. |
| | |
| EID Epoch | The EID Epoch of the Last EID value. This field |
| | is a 4-byte unsigned integer. |
| | |
| Last EID | The EID of the last event recorded by the |
| | SWIMA-PC, or 0 if the SWIMA-PC has no recorded |
| | events. This field contains the EID of the |
| | SWIMA-PC's last recorded change event (which |
| | might or might not be included as an event |
| | record in this attribute). |
| | |
| Last Consulted | The EID of the last event record that was |
| EID | consulted when generating the event record list |
| | included in this attribute. This is different |
| | from the Last EID field value if and only if |
| | this attribute is conveying a partial list of |
| | event records. See Section 3.7.5 for more on |
| | partial lists of event records. |
| | |
| EID | The EID of the event in this event record. |
| | |
| Timestamp | The timestamp associated with the event in this |
| | event record. This timestamp is the SWIMA-PC's |
| | best understanding of when the given event |
| | occurred. Note that this timestamp might be an |
| | estimate. The Timestamp date and time MUST be |
| | represented as an ASCII string that is expressed |
| | in Coordinated Universal Time (UTC) and is |
| | compliant with RFC 3339 [RFC3339], with the |
| | additional restrictions that the 'T' delimiter |
| | and the 'Z' suffix MUST be capitalized and |
| | fractional seconds (time-secfrac) MUST NOT be |
| | included. This field conforms to the date-time |
| | ABNF production from Section 5.6 of RFC 3339, |
| | with the above restrictions. Leap seconds are |
| | permitted, and SWIMA-PVs MUST support them. The |
| | Timestamp string MUST NOT be null terminated or |
| | padded in any way. The length of this field is |
| | always 20 octets. |
| | |
| Record | A 4-byte unsigned integer containing the Record |
| Identifier | Identifier value from a Software Inventory |
| | Evidence Record. |
| | |
| Data Model | A 3-byte unsigned integer containing the PEN of |
| Type PEN | the organization that assigned the meaning of |
| | the Data Model Type value. |
| | |
| Data Model | A 1-byte unsigned integer containing an |
| Type | identifier number that identifies the data model |
| | of the reported record. |
| | |
| Source | The Source Identifier number associated with the |
| Identification | source for the software installation inventory |
| Number | instance that this event record reported. |
| | |
| Action | The type of event that is recorded in this event |
| | record. Possible values are as follows: 1 = |
| | CREATION - the addition of a record to the |
| | endpoint's Software Inventory Evidence |
| | Collection; 2 = DELETION - the removal of a |
| | record from the endpoint's Software Inventory |
| | Evidence Collection; 3 = ALTERATION - an |
| | alteration that was made to a record within the |
| | endpoint's Software Inventory Evidence |
| | Collection. All other values are reserved for |
| | future use and MUST NOT be used when sending |
| | attributes. In the case where a SWIMA-PV |
| | receives an event record that uses an action |
| | value other than the ones defined here, it MUST |
| | ignore that event record but SHOULD process |
| | other event records in this attribute as normal. |
| | |
| Software | A 2-byte unsigned integer indicating the length, |
| Identifier | in bytes, of the Software Identifier field. |
| Length | |
| | |
| Software | A string containing the Software Identifier |
| Identifier | value from a Software Inventory Evidence Record. |
| | This field value MUST first be normalized to |
| | Network Unicode format, as described in |
| | Section 5.4. This string MUST NOT be null |
| | terminated. |
| | |
| Software | A 2-byte unsigned integer indicating the length, |
| Locator Length | in bytes, of the Software Locator field. |
| | |
| Software | A string containing the Software Locator value. |
| Locator | This field value MUST first be normalized to |
| | Network Unicode format, as described in |
| | Section 5.4, and then encoded as a URI |
| | [RFC3986]. This string MUST NOT be null |
| | terminated. |
+----------------+--------------------------------------------------+Table 4: Software Identifier Events Attribute Fields 🧾✨
Okay so the first few fields in this attribute are basically the same as the Software Identifier Inventory attribute 💖 The big difference is that instead of handing over a whole inventory, it carries zero or more event records. Each one has the EID, Timestamp, Record Identifier, Data Model Type PEN, Data Model Type, Source Identification Number, Action, Software Identifier Length, Software Identifier, Software Locator Length, and Software Locator of the affected Software Inventory Evidence Record 🧚
Now the Timestamp drama 🕰️😭 Clock skew between the SWIMA-PC and SWIMA-PV (and between different SWIMA-PCs in an enterprise) can make lining up Timestamp values super hard. This spec doesn't try to fix clock skew, though other mechanisms (which are outside its scope) do exist to shrink the impact and make timestamps more useful for correlation. What SWIMA actually uses the Timestamp for is measuring the gap between two events on one endpoint 🦋 For example, if a record gets removed and then re-added later, the difference tells you how long the system was without that record (and the software tied to it). Since both timestamps come from the same system, clock skew between the SWIMA-PC and SWIMA-PV isn't an issue 🌸
Heads up bestie 👀 If the SWIMA-PC's clock got adjusted between two recorded events, that calculation can lead to misunderstandings about how far apart the events really were. Anyone using this field needs to be aware of that possibility.
And if the Timestamps of two events seem to contradict their EID ordering (the later EID has an earlier timestamp), the recipient MUST treat the EID ordering as correct. Ordering over vibes, always 👑
Last but not least, all events recorded in a Software Identifier Events attribute are required to be part of the same EID Epoch 🌈 Specifically, every reported event MUST have an EID from that same EID Epoch, matching the EID Epoch of the Last EID and Last Consulted EID values. The SWIMA-PC MUST NOT report events with EIDs from different EID Epochs. Not allowed, periodt 💅
Okay so the Last Consulted EID field is the EID of the last event record that got considered for this attribute 👀. If this attribute has a partial event set (see Section 3.7.5 💌), this value is lower than the Last EID value. If it has a complete event set, then Last EID and Last Consulted EID are the same number ✨.
If a bunch of events show up in one Software Identifier Events attribute, the order they sit in doesn't matter 🌸. The EIDs are what sort them into the right order, so you don't have to worry about it. Also, a single software record can totally show up more than once in the same attribute, like if several events involving that record are being reported 🦋 (no drama, that's just how it goes 💅).
5.9. Software Inventory 🎀
A SWIMA-PC sends this attribute to a SWIMA-PV to share a list of inventory records 📦. A SWIMA-PV MUST NOT send this attribute 🙅♀️. The SWIMA-PC sends it either (1) in fulfillment of an existing subscription where the establishing request has a Result Type of 0 and the Earliest EID is zero, or (2) in direct response to a SWIMA Request attribute where the Result Type is 0 and the Earliest EID is zero 💜.
1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Flags | Record Count |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Request ID Copy / Subscription ID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| EID Epoch |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Last EID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
| SUB-BLOCK (Repeated "Record Count" times) |
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Figure 12: Software Inventory AttributeHere's the sub-block, which is the part that repeats 🔁:
1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Record Identifier |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Data Model Type PEN |Data Model Type|
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Source Id Num | Reserved | Software Identifier Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Software Identifier (variable length) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Software Locator Length |Software Locator (variable len)|
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Record Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Record (variable length) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Figure 13: Software Inventory Attribute SUB-BLOCKAnd here's the field-by-field breakdown, the tea ☕:
+----------------+--------------------------------------------------+
| Field | Description |
+----------------+--------------------------------------------------+
| Flags: Bit 0 - | In the case that this attribute is sent in |
| Subscription | fulfillment of a subscription, this bit MUST be |
| Fulfillment | set (1). In the case that this attribute is a |
| | direct response to a SWIMA Request, this bit |
| | MUST be unset (0). |
| | |
| Flags: Bits | Reserved for future use. This field MUST be set |
| 1-7 - Reserved | to zero on transmission and ignored upon |
| | reception. |
| | |
| Record Count | The number of records that follow. This field |
| | is a 3-byte unsigned integer. The Record |
| | Identifier, Data Model Type PEN, Data Model |
| | Type, Source Identification Number, Reserved, |
| | Software Identifier Length, Software Identifier, |
| | Software Locator Length, Software Locator, |
| | Record Length, and Record fields are repeated, |
| | in order, the number of times indicated in this |
| | field. This field value MAY be 0, in which case |
| | there are no instances of these fields. |
| | |
| Request ID | In the case where this attribute is in direct |
| Copy / | response to a SWIMA Request attribute from a |
| Subscription | SWIMA-PV, this field MUST contain an exact copy |
| ID | of the Request ID field from that SWIMA Request. |
| | In the case where this attribute is sent in |
| | fulfillment of an active subscription, this |
| | field MUST contain the Subscription ID of the |
| | subscription being fulfilled by this attribute. |
| | |
| EID Epoch | The EID Epoch of the Last EID value. This field |
| | is a 4-byte unsigned integer. |
| | |
| Last EID | The EID of the last event recorded by the |
| | SWIMA-PC, or 0 if the SWIMA-PC has no recorded |
| | events. This field is a 4-byte unsigned |
| | integer. |
| | |
| Record | A 4-byte unsigned integer containing the Record |
| Identifier | Identifier value from a Software Inventory |
| | Evidence Record. |
| | |
| Data Model | A 3-byte unsigned integer containing the PEN of |
| Type PEN | the organization that assigned the meaning of |
| | the Data Model Type value. |
| | |
| Data Model | A 1-byte unsigned integer containing an |
| Type | identifier number that identifies the data model |
| | of the reported record. |
| | |
| Source | The Source Identifier number associated with the |
| Identification | source from which this software installation |
| Number | inventory instance was reported. |
| | |
| Reserved | Reserved for future use. This field MUST be set |
| | to zero on transmission and ignored upon |
| | reception. |
| | |
| Software | A 2-byte unsigned integer indicating the length, |
| Identifier | in bytes, of the Software Identifier field. |
| Length | |
| | |
| Software | A string containing the Software Identifier |
| Identifier | value from a Software Inventory Evidence Record. |
| | This field value MUST first be normalized to |
| | Network Unicode format, as described in |
| | Section 5.4. This string MUST NOT be null |
| | terminated. |
| | |
| Software | A 2-byte unsigned integer indicating the length, |
| Locator Length | in bytes, of the Software Locator field. |
| | |
| Software | A string containing the Software Locator value. |
| Locator | This field value MUST first be normalized to |
| | Network Unicode format, as described in |
| | Section 5.4, and then encoded as a URI |
| | [RFC3986]. This string MUST NOT be null |
| | terminated. |
| | |
| Record Length | A 4-byte unsigned integer indicating the length, |
| | in bytes, of the Record field. |
| | |
| Record | A Software Inventory Evidence Record expressed |
| | as a string. The record MUST be converted and |
| | normalized to Network Unicode format, as |
| | described in Section 5.4. This string MUST NOT |
| | be null terminated. |
+----------------+--------------------------------------------------+
Table 5: Software Inventory Attribute FieldsThe Software Inventory attribute holds a bunch of Software Inventory Evidence Records along with the core response attribute fields 🧚. Since records can be all different sizes, the length of this attribute is super variable, and if you're sending a complete inventory it can get HUGE 😭. To avoid overburdening the network, enterprises might wish to limit their use of Software Inventory attributes to targeted requests 🫶.
When copying a Software Inventory Evidence Record into the Record field, the record MUST be converted and normalized to use Network Unicode format prior to its inclusion in the Record field 💖.
5.10. Software Events 🦋
A SWIMA-PC sends this attribute to a SWIMA-PV to share a list of events that include Software Inventory Evidence Records 📣. A SWIMA-PV MUST NOT send this attribute 🙅♀️. The SWIMA-PC sends it either (1) in fulfillment of an existing subscription where the establishing request has a Result Type of 0 and the Earliest EID is non-zero, or (2) in direct response to a SWIMA Request attribute where the Result Type is 0 and the Earliest EID is non-zero 🌈.
Okay, bestie, here's the big Software Events diagram 💜 It's the packet layout for the whole attribute, with the repeating sub-block that gets stacked once per event 🦋
1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Flags | Event Count |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Request ID Copy / Subscription ID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| EID Epoch |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Last EID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Last Consulted EID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
| SUB-BLOCK (Repeated "Event Count" times) |
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Figure 14: Software Events Attribute
Now the sub-block, which is the thing that gets repeated 💅 Same ruler, same vibes:
1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| EID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
+- -+
| |
+- -+
| Timestamp |
+- -+
| |
+- -+
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Record Identifier |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Data Model Type PEN |Data Model Type|
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Source Id Num | Action | Software Identifier Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Software Identifier (variable length) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Software Locator Length |Software Locator (variable len)|
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Record Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Record (variable length) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Figure 15: Software Events Attribute SUB-BLOCK
that's the whole diagram set, and it's literally so pretty 🎀✨
The table shows every field of the Software Events attribute, with each one's size, meaning, and rules.
+----------------+--------------------------------------------------+
| Field | Description |
+----------------+--------------------------------------------------+
| Flags: Bit 0 - | In the case that this attribute is sent in |
| Subscription | fulfillment of a subscription, this bit MUST be |
| Fulfillment | set (1). In the case that this attribute is a |
| | direct response to a SWIMA Request, this bit |
| | MUST be unset (0). |
| | |
| Flags: Bits | Reserved for future use. This field MUST be set |
| 1-7 - Reserved | to zero on transmission and ignored upon |
| | reception. |
| | |
| Event Count | The number of events being reported in this |
| | attribute. This field is a 3-byte unsigned |
| | integer. The EID, Timestamp, Record Identifier, |
| | Data Model Type PEN, Data Model Type, Source |
| | Identification Number, Action, Software |
| | Identifier Length, Software Identifier, Software |
| | Locator Length, Software Locator, Record Length, |
| | and Record fields are repeated, in order, the |
| | number of times indicated in this field. This |
| | field value MAY be 0, in which case there are no |
| | instances of these fields. |
| | |
| Request ID | In the case where this attribute is in direct |
| Copy / | response to a SWIMA Request attribute from a |
| Subscription | SWIMA-PV, this field MUST contain an exact copy |
| ID | of the Request ID field from that SWIMA Request. |
| | In the case where this attribute is sent in |
| | fulfillment of an active subscription, this |
| | field MUST contain the Subscription ID of the |
| | subscription being fulfilled by this attribute. |
| | |
| EID Epoch | The EID Epoch of the Last EID value. This field |
| | is a 4-byte unsigned integer. |
| | |
| Last EID | The EID of the last event recorded by the |
| | SWIMA-PC, or 0 if the SWIMA-PC has no recorded |
| | events. This field contains the EID of the |
| | SWIMA-PC's last recorded change event (which |
| | might or might not be included as an event |
| | record in this attribute). |
| | |
| Last Consulted | The EID of the last event record that was |
| EID | consulted when generating the event record list |
| | included in this attribute. This is different |
| | from the Last EID field value if and only if |
| | this attribute is conveying a partial list of |
| | event records. See Section 3.7.5 for more on |
| | partial lists of event records. |
| | |
| EID | The EID of the event in this event record. |
| | |
| Timestamp | The timestamp associated with the event in this |
| | event record. This timestamp is the SWIMA-PC's |
| | best understanding of when the given event |
| | occurred. Note that this timestamp might be an |
| | estimate. The Timestamp date and time MUST be |
| | represented as an ASCII string that is expressed |
| | in Coordinated Universal Time (UTC) and is |
| | compliant with RFC 3339 [RFC3339], with the |
| | additional restrictions that the 'T' delimiter |
| | and the 'Z' suffix MUST be capitalized and |
| | fractional seconds (time-secfrac) MUST NOT be |
| | included. This field conforms to the date-time |
| | ABNF production from Section 5.6 of RFC 3339, |
| | with the above restrictions. Leap seconds are |
| | permitted, and SWIMA-PVs MUST support them. The |
| | Timestamp string MUST NOT be null terminated or |
| | padded in any way. The length of this field is |
| | always 20 octets. |
| | |
| Record | A 4-byte unsigned integer containing the Record |
| Identifier | Identifier value from a Software Inventory |
| | Evidence Record. |
| | |
| Data Model | A 3-byte unsigned integer containing the PEN of |
| Type PEN | the organization that assigned the meaning of |
| | the Data Model Type value. |
| | |
| Data Model | A 1-byte unsigned integer containing an |
| Type | identifier number that identifies the data model |
| | of the reported record. |
| | |
| Source | The Source Identifier number associated with the |
| Identification | source for the software installation inventory |
| Number | instance that this event record reported. |
| | |
| Action | The type of event that is recorded in this event |
| | record. Possible values are as follows: 1 = |
| | CREATION - the addition of a record to the |
| | endpoint's Software Inventory Evidence |
| | Collection; 2 = DELETION - the removal of a |
| | record from the endpoint's Software Inventory |
| | Evidence Collection; 3 = ALTERATION - an |
| | alteration that was made to a record within the |
| | endpoint's Software Inventory Evidence |
| | Collection. All other values are reserved for |
| | future use and MUST NOT be used when sending |
| | attributes. In the case where a SWIMA-PV |
| | receives an event record that uses an action |
| | value other than the ones defined here, it MUST |
| | ignore that event record but SHOULD process |
| | other event records in this attribute as normal. |
| | |
| Software | A 2-byte unsigned integer indicating the length, |
| Identifier | in bytes, of the Software Identifier field. |
| Length | |
| | |
| Software | A string containing the Software Identifier |
| Identifier | value from a Software Inventory Evidence Record. |
| | This field value MUST first be normalized to |
| | Network Unicode format, as described in |
| | Section 5.4. This string MUST NOT be null |
| | terminated. |
| | |
| Software | A 2-byte unsigned integer indicating the length, |
| Locator Length | in bytes, of the Software Locator field. |
| | |
| Software | A string containing the Software Locator value. |
| Locator | This field value MUST first be normalized to |
| | Network Unicode format, as described in |
| | Section 5.4, and then encoded as a URI |
| | [RFC3986]. This string MUST NOT be null |
| | terminated. |
| | |
| Record Length | A 4-byte unsigned integer indicating the length, |
| | in bytes, of the Record field. |
| | |
| Record | A Software Inventory Evidence Record expressed |
| | as a string. The record MUST be converted and |
| | normalized to Network Unicode format, as |
| | described in Section 5.4. This string MUST NOT |
| | be null terminated. |
+----------------+--------------------------------------------------+Table 6: Software Events Attribute Fields
Okay so these fields work exactly like the matching ones in the earlier attributes, no sneaky surprises 💅✨. Same vibe, same rules, bestie 🫶.
Also, ngl, a Software Events attribute can get huge 😭 if a bunch of stuff happens after the event that a request's Earliest EID points to, just like with the Software Inventory attribute. So the move is for SWIMA Request attributes to ask only for full records (Result Type set to zero) in a targeted request 🎯. That keeps the response limited to records matching a specific set of Software Identifiers, which is very much the main character move 🦋.
Heads up! ⚠️ This attribute MUST only contain event records with EIDs coming from the current EID Epoch of the SWIMA-PC. Same as the Software Identifier Events attribute, so no old-epoch EIDs allowed 🙅♀️.
And just like the Software Inventory attribute, the SWIMA-PC MUST do the conversion and normalization of each record 💖.
5.11. Subscription Status Request 🎀
Okay, this one is a SWIMA-PV asking a SWIMA-PC for its list of active subscriptions where the SWIMA-PV is the subscriber 📋🌸. Basically "hey, what am I signed up for?" 💅. A SWIMA-PC MUST NOT send this attribute 🚫, since it's the one asking, not answering.
This attribute has no fields, so there's nothing to fill in 🧚.
A SWIMA-PC MUST respond to this attribute by sending a Subscription Status Response attribute (or a PA-TNC Error attribute if it is unable to correctly provide a response) 💜. No ghosting allowed, periodt 💀.
5.12. Subscription Status Response 🦋
okay bestie, this one is the SWIMA-PC's little roll call 📋✨ It sends this attribute to a SWIMA-PV to report the list of active subscriptions where the receiving SWIMA-PV is the subscriber. And a SWIMA-PV MUST NOT send this attribute 🙅♀️ no cap, that one's strict.
1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Status Flags | Subscription Record Count |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
| SUB-BLOCK (Repeated "Subscription Record Count" times) |
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Figure 16: Subscription Status Response Attribute
1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Flags | Software Identifier Count |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Request ID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Earliest EID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
| SUB-SUB-BLOCK (Repeated "Software Identifier Count" times) |
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Figure 17: Subscription Status Response Attribute SUB-BLOCK
1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Software Identifier Length | Software Identifier (var len) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Figure 18: Subscription Status Response Attribute SUB-SUB-BLOCK
+--------------+----------------------------------------------------+
| Field | Description |
+--------------+----------------------------------------------------+
| Status | Reserved for future use. This field MUST be set |
| Flags: Bits | to zero on transmission and ignored upon |
| 0-7 - | reception. |
| Reserved | |
| | |
| Subscription | The number of subscription records that follow. |
| Record Count | This field is a 3-byte unsigned integer. The |
| | Flags, Software Identifier Count, Request ID, and |
| | Earliest EID fields, and zero or more instances of |
| | Software Identifier Length and Software |
| | Identifier, are repeated, in order, the number of |
| | times indicated in this field. (The Software |
| | Identifier Length and Software Identifier fields |
| | within each of these sets of fields are repeated a |
| | number of times equal to the preceding Software |
| | Identifier Count value.) The Subscription Record |
| | Count field value MAY be 0, in which case there |
| | are no instances of these fields. |
| | |
| Flags, | For each active subscription, these fields contain |
| Software | an exact copy of the fields with the corresponding |
| Identifier | name provided in the subscription's establishing |
| Count, | request. |
| Request ID, | |
| Earliest | |
| EID, | |
| Software | |
| Identifier | |
| Length, and | |
| Software | |
| Identifier | |
+--------------+----------------------------------------------------+Table 7: Subscription Status Response Fields
okay so a Subscription Status Response holds zero or more subscription records 💅 Specifically, it MUST contain one subscription record for each active subscription tied to the party that sent the Subscription Status Request this attribute is answering. Like Section 3.8.2 explains, the SWIMA-PC MUST use the requester's Connection ID and its Posture Validator Identifier to figure out which subscriptions belong to the requester 🔍🧚
A SWIMA-PC MUST send a Subscription Status Response attribute in response to a Subscription Status Request attribute 🫶, except when it hits an error condition that stops it from filling the response in correctly. In that case it MUST respond with a PA-TNC Error attribute that matches the type of error it ran into 🚨. If there are no active subscriptions for the requesting party, the attribute is just its Status Flags field plus a Subscription Record Count field set to 0, and nothing else 🫧
Each subscription record copies the fields of the SWIMA Request attribute that was the establishing request of a subscription. The Request ID field in the record holds the Subscription ID for that subscription 🎀, since the Subscription ID is the same as the Request ID of the establishing request. Also, if the establishing request is targeted, its Record Count field is non-zero, and inside that record the Software Identifier Length and Software Identifier fields repeat, in order, as many times as the Record Count field says. So each subscription record can come in a different size 📏 If the establishing request is not targeted (Record Count field is 0), the subscription record has no Software Identifier Length or Software Identifier fields at all 🌸
When a SWIMA-PV compares what it gets in a Subscription Status Response against its own records of active subscriptions, it should be aware that the SWIMA-PC might be unable to tell this SWIMA-PV apart from other SWIMA-PVs on the same NEA Server 👀 So the SWIMA-PC might report more subscription records than the SWIMA-PV recognizes. For that reason, SWIMA-PVs SHOULD NOT automatically assume that extra subscriptions in a Subscription Status Response mean something is wrong 🙈💜
5.13. Source Metadata Request 🌈
A SWIMA-PV sends this attribute to a SWIMA-PC to ask for metadata about the sources that the SWIMA-PC uses to collect software inventory information 🔎 And yep, a SWIMA-PC MUST NOT send this attribute 🙅♀️ (second time I'm saying it, it's that important bestie).
This attribute has no fields. Literally nothing to fill in, which is kinda iconic ✨
A SWIMA-PC MUST respond to this attribute by sending a Source Metadata Response attribute 💌, or a PA-TNC Error attribute if it is unable to correctly provide a response.
5.14. Source Metadata Response ✨
okay so this is the SWIMA-PC spilling the tea 🫖 about where its software inventory info comes from. Descriptive metadata for each source, served up nicely. A SWIMA-PV MUST NOT send this one, so the PC is the only one with the receipts 💅
1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Reserved | Source Count | |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| |
| SUB-BLOCK (Repeated "Source Count" times) |
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Figure 19: Source Metadata Response Attribute
1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Source Id Num | Metadata Length | Metadata (var)|
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Figure 20: Source Metadata Response Attribute SUB-BLOCK
+----------------+--------------------------------------------------+
| Field | Description |
+----------------+--------------------------------------------------+
| Reserved | Reserved for future use. This field MUST be set |
| | to zero on transmission and ignored upon |
| | reception. |
| | |
| Source Count | The number of source records that follow. The |
| | Source Identification Number, Metadata Length, |
| | and Metadata fields are repeated, in order, the |
| | number of times indicated by this field. This |
| | field MAY be 0, in which case no fields follow |
| | (but this would only be done to indicate that |
| | the SWIMA-PC has no active sources; this would |
| | not be a typical situation). |
| | |
| Source | The Source Identifier number associated with the |
| Identification | described source for any communications with the |
| Number | recipient SWIMA-PV. |
| | |
| Metadata | A 2-byte unsigned integer indicating the length, |
| Length | in bytes, of the Metadata field. |
| | |
| Metadata | A string containing descriptive metadata about |
| | the indicated data source. This string MUST NOT |
| | be null terminated. |
+----------------+--------------------------------------------------+Table 8: Source Metadata Response Fields
Each Source Metadata Response attribute holds zero or more records, and each one describes a data source the SWIMA-PC uses to collect software inventory information. Think of it as a little address book of all the places the PC gets its data from 🧚 The PC SHOULD include one metadata record for every source it uses. (Sometimes there's a good reason not to tell certain SWIMA-PVs about certain sources 🙈) The attribute MUST include a metadata record for every source that has shown up in inventory or event messages to that particular SWIMA-PV.
A SWIMA-PC MUST send a Source Metadata Response attribute in reply to a Source Metadata Request attribute 🫶 The only exception is when the PC hits an error that stops it from filling the response in properly. In that case it MUST respond with a PA-TNC Error attribute that matches the type of error it ran into 😭
The Source Count field tells you how many source metadata records are in the attribute. Each record is made up of a Source Identification Number field, a Metadata Length field, and a Metadata field, all in a neat little bundle 🎀
Now the Source Identification Number field. It lines up with the same field in inventory and event messages 🦋 If (1) the Source Identification Number here matches one in an inventory or event record, and (2) both the Source Metadata Response and that record went to the same SWIMA-PV, then the source described in the Metadata field MUST be the very same source that produced that record. Here's the twist: a SWIMA-PC MAY use different Source Identification Number associations with different SWIMA-PVs 👑 so the link between a number and its metadata only makes sense between that one sending SWIMA-PC and that one receiving SWIMA-PV. When the PC sends to a given SWIMA-PV, it MUST use that recipient's Source Identification Number associations. No mixing up your besties' info, periodt 💅
The Metadata Length field is the length of the Metadata field, in bytes 🍓 The Metadata field holds info about the data source. This spec doesn't tell you what format the Metadata field has to be in, so it's giving "anything goes." It MAY include machine-readable info. For the broadest usefulness, though, it SHOULD include human-readable, descriptive info about the data source ✨
5.15. PA-TNC Error as Used by SWIMA 🚨
The PA-TNC Error attribute is defined in the PA-TNC specification [RFC5792], and SWIMA uses it exactly the way that spec says to 🌸 A PA-TNC Error can show up because of any error in the PA-TNC exchange, and it can also be sent for errors that are specific to the SWIMA exchange. The SWIMA-specific ones use the error codes listed below.
A SWIMA-PC MUST send a PA-TNC Error in response to a SWIMA Request when it runs into a fatal error (meaning an error that stops any further processing of the exchange) related to the attribute exchange. A SWIMA-PV MUST NOT send this attribute 🙅♀️ If a SWIMA-PV hits a fatal error, it MUST handle that error without sending a PA-TNC Error attribute. The SWIMA-PV MAY still do other things about it, like logging the cause of the error or even isolating the endpoint 🛡️
A PA-TNC Error attribute gets sent instead of a SWIMA Response attribute when certain problems mean a reliable SWIMA Response can't be built. So a SWIMA-PC MUST NOT send both a PA-TNC Error attribute and a SWIMA Response attribute in response to a single SWIMA Request attribute. Pick one, bestie 💖
Table 9 lists the PA-TNC Error code values that are specific to the SWIMA exchange. Each code is shown in both hexadecimal and decimal, so you can read it either way 🧮 For all of these, the Error Code Vendor ID field MUST be set to 0x000000, which is the IETF SMI PEN. The error information structures for each code are covered in the subsections that follow.
+----------------+--------------------------------------------------+
| Error Code | Description |
| Value | |
+----------------+--------------------------------------------------+
| 0x00000004 (4) | SWIMA_ERROR. This indicates a fatal error |
| | (i.e., an error that precludes the creation of a |
| | suitable response attribute) other than the |
| | errors described below but still specific to the |
| | processing of SWIMA attributes. The Description |
| | field SHOULD contain additional diagnostic |
| | information. |
| | |
| 0x00000005 (5) | SWIMA_SUBSCRIPTION_DENIED_ERROR. This indicates |
| | that the SWIMA-PC denied the SWIMA-PV's request |
| | to establish a subscription. The Description |
| | field SHOULD contain additional diagnostic |
| | information. |
| | |
| 0x00000006 (6) | SWIMA_RESPONSE_TOO_LARGE_ERROR. This indicates |
| | that the SWIMA-PC's response to the SWIMA-PV's |
| | request was too large to be serviced. The error |
| | information structure indicates the largest |
| | possible size of a response supported by the |
| | SWIMA-PC (see Section 5.15.2). The Description |
| | field SHOULD contain additional diagnostic |
| | information. |
| | |
| 0x00000007 (7) | SWIMA_SUBSCRIPTION_FULFILLMENT_ERROR. This |
| | indicates that the SWIMA-PC experienced an error |
| | while fulfilling a given subscription. The |
| | error information includes the Subscription ID |
| | of the relevant subscription, as well as a |
| | sub-error that describes the nature of the error |
| | the SWIMA-PC experienced. The SWIMA-PC and |
| | SWIMA-PV MUST treat the identified subscription |
| | as cancelled. |
| | |
| 0x00000008 (8) | SWIMA_SUBSCRIPTION_ID_REUSE_ERROR. This |
| | indicates that the SWIMA-PC received a SWIMA |
| | Request from a given SWIMA-PV where the Request |
| | ID of that SWIMA Request is currently used as |
| | the Subscription ID of an active subscription |
| | with that SWIMA-PV. This error does not cancel |
| | the identified subscription. |
+----------------+--------------------------------------------------+Table 9: PA-TNC Error Codes for SWIMA
Quick heads up on the Table 9 codes: the error code is the same whether it's a SWIMA-specific one or a standard one 🌈 A message with a SWIMA attribute might also trip one of the IETF Standard PA-TNC Error Codes defined in Section 4.2.8 of [RFC5792]. Say a SWIMA attribute has an invalid parameter, so you get an error code of "Invalid Parameter." In that case, the SWIMA-PC MUST use the appropriate PA-TNC Error Code value as defined in Section 4.2.8 of [RFC5792]. Don't freestyle it 🙈
5.15.1. SWIMA_ERROR, SWIMA_SUBSCRIPTION_DENIED_ERROR, and SWIMA_SUBSCRIPTION_ID_REUSE_ERROR Information ✨
okay so bestie, this is where the error codes get their paperwork 📋💅 SWIMA_ERROR is the catch-all 🧺. It means the sender (the SWIMA-PC) hit a problem while processing a SWIMA Request attribute, and it's not covered by any of the more specific SWIMA error codes. Then there's SWIMA_SUBSCRIPTION_DENIED_ERROR 🚫, which shows up when the SWIMA-PV asks for a subscription (or asks to clear all of its subscriptions) and the SWIMA-PC is unable or unwilling to go along with it. And SWIMA_SUBSCRIPTION_ID_REUSE_ERROR 🙈 is for when a SWIMA Request comes in with a Request ID that's the same as a Subscription ID of an active subscription belonging to that same sender. Lowkey a very specific drama 💀
All three of these codes use the same error information structure 🦋
1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Copy of Request ID / Subscription ID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Description (variable length) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Figure 21: SWIMA_ERROR, SWIMA_SUBSCRIPTION_DENIED_ERROR, and SWIMA_SUBSCRIPTION_ID_REUSE_ERROR Information
+--------------+----------------------------------------------------+
| Field | Description |
+--------------+----------------------------------------------------+
| Copy of | In the case that this error condition is generated |
| Request ID / | in direct response to a SWIMA Request attribute, |
| Subscription | this field MUST contain an exact copy of the |
| ID | Request ID field in the SWIMA Request attribute |
| | that caused this error. In the case that the |
| | attribute in question is generated in fulfillment |
| | of an active subscription, this field MUST contain |
| | the Subscription ID of the subscription for which |
| | the attribute was generated. (This is only |
| | possible if the error code is SWIMA_ERROR, as the |
| | other errors are not generated by subscription |
| | fulfillment.) Note that in the case of failed |
| | subscription fulfillment, the indicated error |
| | appears as a sub-error for a |
| | SWIMA_SUBSCRIPTION_FULFILLMENT_ERROR, as described |
| | in Section 5.15.3. |
| | |
| Description | A UTF-8 [RFC3629] string describing the condition |
| | that caused this error. This field MAY be zero- |
| | length. However, senders SHOULD include some kind |
| | of description in all PA-TNC Error attributes with |
| | these error codes. This field MUST NOT be null |
| | terminated. |
+--------------+----------------------------------------------------+Table 10: SWIMA_ERROR, SWIMA_SUBSCRIPTION_DENIED_ERROR, and SWIMA_SUBSCRIPTION_ID_REUSE_ERROR Information Fields
so the vibe for this structure is: it tells you which SWIMA Request caused the drama 🎬 and describes what went wrong ✍️. The Description field holds the text. The SWIMA-PC MAY encode machine-interpretable information in there 🤖, but it SHOULD also include a human-readable description 🫶, because the receiving SWIMA-PV might not recognize the SWIMA-PC's encoded stuff. Literally, don't leave your bestie confused 😭
5.15.2. SWIMA_RESPONSE_TOO_LARGE_ERROR Information 🎀
the SWIMA_RESPONSE_TOO_LARGE_ERROR code is for when a SWIMA-PC's response to a SWIMA-PV's SWIMA Request attribute was too big to send 📦💥. Like, it literally couldn't fit 🙃
this one has its own little structure with an extra field 🌸
1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Copy of Request ID / Subscription ID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Maximum Allowed Size |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Description (variable length) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Figure 22: SWIMA_RESPONSE_TOO_LARGE_ERROR Information
+--------------+----------------------------------------------------+
| Field | Description |
+--------------+----------------------------------------------------+
| Copy of | In the case that the attribute in question is |
| Request ID / | generated in direct response to a SWIMA Request, |
| Subscription | this field MUST contain an exact copy of the |
| ID | Request ID field in the SWIMA Request attribute |
| | that caused this error. In the case that the |
| | attribute in question is generated in fulfillment |
| | of an active subscription, this field MUST contain |
| | the Subscription ID of the subscription for which |
| | the attribute was generated. Note that in the |
| | latter case, the SWIMA_RESPONSE_TOO_LARGE_ERROR |
| | appears as a sub-error for a |
| | SWIMA_SUBSCRIPTION_FULFILLMENT_ERROR, as described |
| | in Section 5.15.3. |
| | |
| Maximum | This field MUST contain an unsigned integer |
| Allowed Size | indicating the largest permissible size, in bytes, |
| | of the SWIMA attribute that the SWIMA-PC is |
| | currently willing to send in response to a SWIMA |
| | Request attribute. |
| | |
| Description | A UTF-8 [RFC3629] string describing the condition |
| | that caused this error. This field MAY be zero- |
| | length. However, senders SHOULD include some kind |
| | of description in all PA-TNC Error attributes with |
| | this error code. This field MUST NOT be null |
| | terminated. |
+--------------+----------------------------------------------------+Table 11: SWIMA_RESPONSE_TOO_LARGE_ERROR Information Fields
this structure is used with the SWIMA_RESPONSE_TOO_LARGE_ERROR status code to pin down the SWIMA Request attribute that caused the issue and describe the error 🕵️♀️. The Maximum Allowed Size field is the biggest attribute the SWIMA-PC is willing to send in response to a SWIMA Request under the current circumstances ⏳. Note that under other circumstances, the SWIMA-PC might be willing to return larger or smaller responses than that, like if the endpoint connects to the NEA Server using a different network protocol 🔌. The other fields work the same way as the matching fields in the SWIMA_ERROR and SWIMA_SUBSCRIPTION_DENIED_ERROR structures 🔁. ✨
Okay bestie, picking up right where we left off 💖
5.15.3. SWIMA_SUBSCRIPTION_FULFILLMENT_ERROR Information ✨
okay so this error code is for when the SWIMA-PC runs into trouble while it's busy fulfilling a subscription 😭 it's giving "I tried, but something went wrong while I was doing it" 💅 the bytes after the first 4 octets copy a PA-TNC Error attribute (check Section 4.2.8 of PA-TNC [RFC5792] if you want the full tea) and that copied bit tells you what actually went wrong 🫶
1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Subscription ID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Reserved | Sub-error Code Vendor ID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Sub-error Code |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Sub-error Information (variable length) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Figure 23: SWIMA_SUBSCRIPTION_FULFILLMENT_ERROR Information 🌸
+--------------+----------------------------------------------------+
| Field | Description |
+--------------+----------------------------------------------------+
| Subscription | This field MUST contain the Subscription ID of the |
| ID | subscription whose fulfillment caused this error. |
| | |
| Reserved | This field MUST contain the value of the Reserved |
| | field of a PA-TNC Error attribute that describes |
| | the error condition encountered during |
| | subscription processing. |
| | |
| Sub-error | This field MUST contain the value of the Error |
| Code Vendor | Code Vendor ID field of a PA-TNC Error attribute |
| ID | that describes the error condition encountered |
| | during subscription processing. |
| | |
| Sub-error | This field MUST contain the value of the Error |
| Code | Code field of a PA-TNC Error attribute that |
| | describes the error condition encountered during |
| | subscription processing. |
| | |
| Sub-error | This field MUST contain the value of the Error |
| Information | Information field of a PA-TNC Error attribute that |
| | describes the error condition encountered during |
| | subscription processing. |
+--------------+----------------------------------------------------+Table 12: SWIMA_SUBSCRIPTION_FULFILLMENT_ERROR Information Fields 🧚
this error structure goes with the SWIMA_SUBSCRIPTION_FULFILLMENT_ERROR status code 🦋 the first 4 octets hold the Subscription ID of the subscription that was being fulfilled when things went sideways, and the rest of the fields mirror a PA-TNC Error attribute, which the spec calls the "sub-error" 💜 the sub-error's error code matches the error the SWIMA-PC ran into while fulfilling that subscription 🙈 and here's the big rule: the sub-error MUST NOT have an error code of SWIMA_SUBSCRIPTION_FULFILLMENT_ERROR 🚫 no error-ception allowed, bestie 💀
⚠️ when the SWIMA-PC sends a PA-TNC Error attribute with this error code, the SWIMA-PV MUST treat the subscription named in the Subscription ID field as cancelled 🔥 MUST, no wiggle room! all the other subscriptions are totally unaffected 🌈
6. Supported Data Models 🍓
okay so SWIMA supports an extensible list of data models for representing and moving software inventory info 🦋 that list lives in the "Software Data Model Types" registry (see Section 10.5) ✨ this document gives guidance for an initial set of data models, and other documents might add guidance for new ones later and get referenced by extensions to that registry 💅
6.1. ISO 2015 SWID Tags Using XML 💖
the International Organization for Standardization and the International Electrotechnical Commission (ISO/IEC) put out the SWID tag spec (ISO/IEC 19770-2:2009) in 2009 [SWID09] 🌸 then a revised version (ISO/IEC 19770-2:2015) came out in 2015 [SWID15] ✨ ever since, more and more vendors have been putting SWID tags into their products 🎀 and honestly? SWID tags make identifying software so much easier 😭 instead of hunting for clues like particular files or registry keys, vendors can grab a ready-made list of SWID tags that gives simple, immediate evidence that a piece of software is there 🫶
SWIMA doesn't rely on whether SWID tags are present or managed on an endpoint, as described in the ISO 2015 SWID tag spec 🙈 BUT the data model for describing software in that spec is seriously robust and comprehensive, so SWIMA adopts it as a way to represent and transmit software info 👑 it's worth noting that using the ISO SWID tag data model makes no assumption about whether (1) the recorded info really came from an ISO SWID tag harvested from the endpoint, or (2) the info was made some other way and normalized into the SWID format 🧚
6.1.1. Guidance on Normalizing Source Data to ISO 2015 SWID Tags Using XML ✨
any record tied to this Software Data Model Type MUST conform to [SWID15] 💅
if you're generating a new ISO 2015 SWID tag, the software doing the generating MUST use a Tag Creator RegID associated with that generating software 🎀 unless that's impossible, in which case it MUST use the "http://invalid.unavailable" Tag Creator RegID value 🌈 (this matches the conventions for an unknown tag creator in the ISO 2015 SWID tag spec 🦋) do NOT use a RegID tied to any other party 🚫 it's flat-out incorrect to use a Tag Creator RegID belonging to the software being described, the enterprise using that software, or any other entity besides the party that built the tool generating the tag 💀 this is because the Tag Creator RegID is supposed to identify the party that created the tag 🫶 and also, any generated tags SHOULD conform to the tag creator guidance in NISTIR 8060 [NIST8060], which has extra recommendations for more interoperable SWID tag use 🙌
6.1.2. Guidance on Creation of Software Identifiers from ISO 2015 SWID Tags ✨
a Software Identifier generated from an ISO 2015 SWID tag is written as the Tag Creator RegID value joined with the Unique ID value 💖 specifically, (1) it MUST be of the form TAG_CREATOR_REGID "_" "_" UNIQUE_ID and (2) it's the Tag Creator RegID and the Unique ID from the tag stuck together with a double underscore (_), with no other connecting character or whitespace 🌸 no extra spaces, no extra characters, bestie 🙅♀️
TAG_CREATOR_REGID "_" "_" UNIQUE_ID6.2. ISO 2009 SWID Tags Using XML 🌈
like we said above, ISO's SWID tag spec gives a useful data model for representing software info 🦋 the ISO 2015 spec is considered more comprehensive and fixes some issues with the ISO 2009 spec, BUT as of writing this spec, 2009-format SWID tags are still way more common out in deployments 😭 so ISO 2009 SWID tags get included in the "Software Data Model Types" registry 💜
6.2.1. Guidance on Normalizing Source Data to ISO 2009 SWID Tags Using XML 💅
any record tied to this Software Data Model Type MUST conform to [SWID09] 🎀 any such tag SHOULD use UTF-8 encoding [RFC3629] 🌸 but it MUST NOT alter the existing encoding if doing so would invalidate digital signatures included in the tag 🔥
if you're generating a new ISO 2009 SWID tag, the generating software MUST use a Tag Creator RegID associated with that software 🫶 unless it's impossible, in which case it MUST use "unknown", which means the tag creator is unknown 🧚 (this matches the conventions for an unknown tag creator in the ISO 2009 SWID tag spec ✨) again, do NOT use a RegID tied to any other party 🚫 it's incorrect to use a Tag Creator RegID belonging to the software being described, the enterprise using it, or any other entity except the party that built the tool generating the tag 💀 because the Tag Creator RegID has to identify the party that created the tag 💖
6.2.2. Guidance on Creation of Software Identifiers from ISO 2009 SWID Tags ✨
a Software Identifier generated from an ISO 2009 SWID tag is written as the Tag Creator RegID value joined with the Unique ID value 🌸 specifically, (1) it MUST be of the form TAG_CREATOR_REGID "_" "_" UNIQUE_ID and (2) it's the Tag Creator RegID and the Unique ID from the tag connected with a double underscore (_), with no other connecting character or whitespace 🎀
TAG_CREATOR_REGID "_" "_" UNIQUE_IDthat's a wrap on this chunk, bestie!! 🌈💖
7. Relationship to Other Specifications 🔗
Okay so SWIMA doesn't live alone, bestie 🫶 This spec is expected to be part of a standard NEA architecture, which means it's meant to work alongside the other protocols in a NEA exchange. The big one: SWIMA attributes ride over PB-TNC [RFC5793], and PB-TNC rides over some flavor of PT (either PT-TLS [RFC6876] or PT-EAP [RFC7171]) 💅 These protocols are the unsung heroes, because they make sure the attributes defined here get delivered reliably, securely, and to the right party ✨
Now, the PA-TNC spec [RFC5792] has Product Information, Numeric Version, and String Version attributes that also tell you about installed apps and their versions. So yes, there's some overlap, ngl 🙈 But PA-TNC was built to answer very specific questions about specific classes of products, while SWIMA can ask a broader question and get a more comprehensive picture of an endpoint's installed software. So SWIMA brings capabilities that PA-TNC just doesn't have 🦋
NEA is meant for a whole range of activities, so other specs might use it too. For example, requirement T-001 in the SACM Requirements document [RFC8248] says NEA can support data collection from endpoints within the broader SACM architecture. (The other NEA parts that SWIMA uses cover the other SACM data transport requirements 🧚) In the SACM architecture, a SWIMA-PV corresponds to a "SACM Collector", and a SWIMA-PC corresponds to a "SACM Internal Collector". SWIMA can support software inventory collection in that world. Specifically, it supports the SACM "Endpoint Posture Attribute Value Collection" use case (Section 2.1.3 in [RFC7632]) by describing a collection mechanism that handles event-driven, scheduled, and ad hoc collection of software inventory info. SWIMA's flexibility about the format of inventory data records means it's compatible with virtually any data format that implements SACM's "Define, Publish, Query, and Retrieve Security Automation Data" use case (Section 2.1.1 in [RFC7632]). This is just one example of how SWIMA can support broader security solution standards 💖
Note though: while SWIMA can support these SACM use cases, it has no dependencies on the SACM architecture or any other context where NEA might reasonably be applied. Independent queen energy 👑
8. Security Considerations 🔐
Okay, this is the part where we get serious, so read carefully 💀 This section talks about some of the security threats facing SWIMA-PCs and SWIMA-PVs. It mostly points out potential issues for implementers to think about, although it does have a handful of normative requirements to deal with certain security issues. The issues below focus on capabilities specific to this document. Implementers are advised to check out the other relevant NEA specs, especially [RFC5209] (the NEA architecture) and [RFC5792] (PA-TNC), for security issues that apply to these components in general 📚
8.1. Evidentiary Value of Software Inventory Evidence Records
How accurately an endpoint's Software Inventory Evidence Collection reflects its actual software load (and any changes made to that load) depends on how accurate the tools are that populate and manage the Software Inventory Evidence Records in that collection. The SWIMA-PC is required to detect changes to the collection in near real time, but some tools might not be built to update their records in real time. That can leave the collection out of sync with the actual system state 😬 Tools might also inaccurately characterize software or fail to properly record its removal. And finally, there's likely to be software on the endpoint that isn't tracked by any source, so it won't show up in the collection. Tools that implement SWIMA ought to be aware of these issues and minimize them, but completely eliminating them is likely impossible. Users of collected Software Inventory Evidence Records need to understand that the info SWIMA provides can't be treated as completely accurate. Still, having endpoints report this info can give useful insight into the state of the endpoint's software load, and it can alert administrators and policy tools to situations that need remediation 🔥
8.2. Sensitivity of Collected Records
Collected software records can be sensitive. That includes both security sensitivities and privacy sensitivities (more on the privacy side in Section 9 🙈). On the security side, inventory records are a wealth of info about the endpoint. For an adversary who doesn't already have access to the endpoint, a collection of its inventory records might provide lots of details useful for mounting an attack. A list of the inventory records for an endpoint reveals a list of software installed on it. That list can be very detailed, noting specific versions and even patch levels, and an adversary can use that to identify vulnerable software and design effective attacks.
The following info might also be gleaned from a collection of software inventory records:
- An inventory record might include info about where the product was installed on a given endpoint. That can reveal details about the endpoint's file organization that an attacker can use.
- An inventory record might include info about how the software was provided to the endpoint, who in an organization signs off on the package release, and who packaged the product for installation. This info might be used as a starting point for developing supply chain attacks.
- Events affecting inventory records are reported with timestamps showing when each event occurred. That can give an attacker a sense of how quickly an organization distributes patches and updates, which helps them figure out how long an attack window might stay open ⏳
Any consolidated software inventory is a potential risk, because it can give an adversary insight into the enterprise's configuration and management process. It is recommended that a centralized software inventory record collection be protected against unauthorized access. Mechanisms to accomplish this can include encrypting the data at rest, making sure access to the data is limited only to authorized individuals and processes, and other basic security precautions 🔒
8.3. Integrity of Endpoint Records
SWIMA-PCs maintain records of detected changes to the endpoint's Software Inventory Evidence Collection. These records are used to respond to a SWIMA-PV's request for change events. The SWIMA-PV might use a list of reported events to update its understanding of the endpoint's Software Inventory Evidence Collection without needing to receive a full inventory report from the SWIMA-PC. For this reason, preserving the integrity of the SWIMA-PC's record of events is extremely important 🚨 If an attacker modifies the SWIMA-PC's record of changes to the collection, the SWIMA-PV's understanding of the collection might end up differing from its actual state. The results of such an attack might include leading the SWIMA-PV to believe that (1) absent software was present or, conversely, that present software was absent, or (2) patches have been installed even when they haven't. Such an attack could also leave the SWIMA-PV unaware of other changes to Software Inventory Evidence Records. So the SWIMA-PC MUST take steps to protect the integrity of its event records.
Records of established SWIMA-PV subscriptions also need protection against manipulation or corruption. If an attacker can modify or delete records of a SWIMA-PV's established subscription, the SWIMA-PC might fail to correctly fulfill that subscription. The SWIMA-PV wouldn't know its subscription wasn't being correctly fulfilled unless it received additional info that indicated a discrepancy. For example, the SWIMA-PV might collect a full inventory and realize from that info that certain events hadn't been correctly reported in accordance with an established subscription. For this reason, the SWIMA-PC MUST protect the integrity of subscription records 🫶
8.4. SWIMA-PC Access Permissions
A SWIMA-PC needs sufficient permissions to collect Software Inventory Evidence Records from all of its supported sources, as well as sufficient permissions to interact with the endpoint's Posture Broker Client. For the former, this might require permissions to read the contents of directories throughout the filesystem. Depending on the operating environment and on other activities undertaken by a SWIMA-PC (or by software that incorporates a SWIMA-PC as one of its capabilities), the SWIMA-PC software might require additional permissions. The SWIMA-PC SHOULD NOT be granted permissions beyond what it needs to fulfill its duties. Principle of least privilege, bestie 🧚
8.5. Sanitization of Record Fields
Not all sources of software inventory evidence are necessarily tightly controlled. For example, consider a source that gathers .swid files from the endpoint's filesystem. Any party could create a new .swid file that could then be collected and turned into a Software Inventory Evidence Record 👀 So it's important that the contents of source info not be automatically trusted. In particular, tools that read source info and the Software Inventory Evidence Records derived from it, including SWIMA-PCs, need to be careful to sanitize input to prevent buffer overflow attacks, encoding attacks, and other weaknesses that an adversary who controls the contents of a record might exploit 🧼
8.6. PA-TNC Security Threats
In addition to the considerations above, the SWIMA protocol is subject to the same security threats as other PA-TNC transactions; see Section 5.2 of PA-TNC [RFC5792]. These include, but aren't limited to, attribute theft, message fabrication, attribute modification, attribute replay, attribute insertion, and denial of service 💀 Implementers are advised to consult the PA-TNC specification to better understand these security issues 🩷
9. Privacy Considerations 🔒✨
okay bestie, this section is seriously important, so let's get into it 🫶
As noted in Section 8.2, if an adversary can gain an understanding of the software installed on an endpoint, they can utilize this to launch attacks and maintain footholds on this endpoint 😭💀. For this reason, the NEA Server needs to ensure that adequate safeguards are in place to prevent exposure of collected inventory records. For similar reasons, it is advisable that an endpoint only send records to a NEA Server that is authorized to receive this information and that can be trusted to safeguard this information after collection 🧚.
In addition, software inventory information can lead to insights about the endpoint's primary user if that user is able to install software. (Note that users might be "able" to install their own software even if they are not "allowed" to do so 🙈.) This is especially true on endpoints that support "apps", as individual apps can be closely tied to specific groups or activities 🌸. This could conceivably allow inferences about things such as a user's hobbies; the banks and other financial institutions that they use; and information about the user's race, sex, or sexual orientation. Yikes, that is a LOT of personal info 💜.
Organizations that collect software inventory information from endpoints ought to make sure the endpoints' users are aware of this collection 🦋. In addition, organizations should be aware that a software inventory associated with an individual, such as the inventory of the individual's primary endpoint, could expose sensitive personal information. For this reason, privacy safeguards are necessary for collected inventory information. Such safeguards would require not only protection of the inventory's confidentiality but also appropriate access controls so that only those trained in relevant privacy requirements are able to view the data 👑✨.
10. IANA Considerations 🎀
okay so this section is basically the registry paperwork 📋💅. It extends multiple existing IANA registries. Specifically, it extends the "PA-TNC Attribute Types" and "PA-TNC Error Codes" registries defined in the PA-TNC specification [RFC5792] and the "PA Subtypes" registry defined in the PB-TNC specification [RFC5793] and extended in PA-TNC. This specification only adds values to these registries and does not alter how these registries work or are maintained. Consult the appropriate specifications for details on the operations and maintenance of these registries 🌈.
This section also defines a new IANA registry for "Software Data Model Types". The structure and requirements for this registry are provided, as well as guidelines for reviewers adjudicating the addition of new entries to this registry 🍓.
10.1. Guidance for the Designated Experts
For the "Software Data Model Types" registry defined by this specification, new values are added to the registry using the "Specification Required" process defined in RFC 8126 [RFC8126].
This section provides guidance to designated experts so that they may make decisions using a philosophy appropriate for this registry 🧐.
Designated experts should focus on the following requirements. All values in this IANA registry MUST be documented in a specification that is permanently and publicly available. Values MUST also be useful, not harmful to the Internet, and defined in a manner that is clear and likely to ensure interoperability 💖.
Designated experts should encourage vendors to avoid defining similar but incompatible values and instead agree on a single value allocated via IETF standards. However, it is beneficial to document existing practice ✨.
There are several ways to ensure that a specification is permanently and publicly available. It may be published as an RFC. Alternatively, it may be published in another manner that makes it freely available to anyone. However, in this latter case, the vendor MUST supply a copy to IANA and authorize IANA to archive this copy and make it freely available to all, if at some point the document becomes no longer freely available to all through other channels 🦋.
Sections 10.2, 10.3, and 10.4 define a new PA Subtype, new PA-TNC Attribute Types, and new PA-TNC Error Codes, respectively. Section 10.5 provides guidance to IANA in creating and managing the new "Software Data Model Types" registry defined by this specification 🌸.
10.2. PA Subtypes
The following is an extension to the list of PA Subtypes provided in Section 7.2 of [RFC5792] and defined in the "PA Subtypes" registry in Section 6.3 of [RFC5793]. See <https://www.iana.org/assignments/pb-tnc-parameters/>.
+-----+---------+------------------+------------------------+
| PEN | Integer | Name | Defining Specification |
+-----+---------+------------------+------------------------+
| 0 | 9 | SWIMA Attributes | RFC 8412 |
+-----+---------+------------------+------------------------+10.3. PA-TNC Attribute Types
Section 5.2 of this specification defines several new PA-TNC attributes. The following values have been added to the "PA-TNC Attribute Types" registry defined in the PA-TNC specification. Note that Table 1 in Section 5.2 lists these attributes in both hexadecimal and decimal format. The decimal values given in that table are identical to those provided here. Note also that Table 1 includes an entry for the PA-TNC Error attribute, but the IANA information associated with the PA-TNC Error attribute is already defined in the PA-TNC specification and is not reproduced here 🎀.
+-----+---------+----------------------------+----------------------+
| PEN | Integer | Name | Defining |
| | | | Specification |
+-----+---------+----------------------------+----------------------+
| 0 | 13 | SWIMA Request | RFC 8412 |
| | | | |
| 0 | 14 | Software Identifier | RFC 8412 |
| | | Inventory | |
| | | | |
| 0 | 15 | Software Identifier Events | RFC 8412 |
| | | | |
| 0 | 16 | Software Inventory | RFC 8412 |
| | | | |
| 0 | 17 | Software Events | RFC 8412 |
| | | | |
| 0 | 18 | Subscription Status | RFC 8412 |
| | | Request | |
| | | | |
| 0 | 19 | Subscription Status | RFC 8412 |
| | | Response | |
| | | | |
| 0 | 20 | Source Metadata Request | RFC 8412 |
| | | | |
| 0 | 21 | Source Metadata Response | RFC 8412 |
+-----+---------+----------------------------+----------------------+10.4. PA-TNC Error Codes
Section 5.15 of this specification defines several new PA-TNC Error Codes. The following values have been added to the "PA-TNC Error Codes" registry defined in the PA-TNC specification. Note that Table 9 in Section 5.15 lists these codes in both hexadecimal and decimal format. The decimal values given in that table are identical to those provided here 💅.
+-----+---------+--------------------------------------+---------------+
| PEN | Integer | Name | Defining |
| | | | Specification |
+-----+---------+--------------------------------------+---------------+
| 0 | 4 | SWIMA_ERROR | RFC 8412 |
| | | | |
| 0 | 5 | SWIMA_SUBSCRIPTION_DENIED_ERROR | RFC 8412 |
| | | | |
| 0 | 6 | SWIMA_RESPONSE_TOO_LARGE_ERROR | RFC 8412 |
| | | | |
| 0 | 7 | SWIMA_SUBSCRIPTION_FULFILLMENT_ERROR | RFC 8412 |
| | | | |
| 0 | 8 | SWIMA_SUBSCRIPTION_ID_REUSE_ERROR | RFC 8412 |
+-----+---------+--------------------------------------+---------------+10.5. Software Data Model Types
For the "Software Data Model Types" registry (<https://www.iana.org/assignments/pa-tnc-parameters/#software-data-model-types>, each entry should include a human-readable name, an SMI PEN, a decimal integer value between 0 and 2^8-1 (inclusive), and a reference to the specification where the use of this data model is defined. This referenced specification needs to provide both a description of the format used by the data model and the procedures by which Software Identifiers are derived from a record expressed using this data model. Note that a specification that just defines the data model structure and its use is generally not sufficient, as it would likely lack the procedures for constructing a Software Identifier. This is why the table below uses the SWIMA standard for ISO SWID tags as the reference for the use of ISO SWID tags and does not reference the ISO SWID tag specification 🧠.
The following entries for this registry are defined in this document. They are the initial entries in the "Software Data Model Types" registry. Additional entries to this registry are added following the "Specification Required" policy defined in [RFC8126], following the guidelines in Section 10.1 💫.
+-----+---------+-----------------------------+---------------------+
| PEN | Integer | Name | Defining |
| | | | Specification |
+-----+---------+-----------------------------+---------------------+
| 0 | 0 | ISO 2015 SWID tags using | RFC 8412 |
| | | XML | |
| | | | |
| 0 | 1 | ISO 2009 SWID tags using | RFC 8412 |
| | | XML | |
| | | | |
| 0 | 192-255 | Reserved for local | N/A |
| | | enterprise use | |
+-----+---------+-----------------------------+---------------------+11. References 📚🌈
11.1. Normative References ✨
Okay bestie, these are the must-read docs the spec leans on, so here they are in full 📚
- [NIST8060] Waltermire, D., Cheikes, B., Feldman, L., and G. Witte, "Guidelines for the Creation of Interoperable Software Identification (SWID) Tags", DOI 10.6028/NIST.IR.8060, April 2016,
https://nvlpubs.nist.gov/nistpubs/ir/2016/NIST.IR.8060.pdf. - [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997,
https://www.rfc-editor.org/info/rfc2119. - [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002,
https://www.rfc-editor.org/info/rfc3339. - [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 2003,
https://www.rfc-editor.org/info/rfc3629. - [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005,
https://www.rfc-editor.org/info/rfc3986. - [RFC5198] Klensin, J. and M. Padlipsky, "Unicode Format for Network Interchange", RFC 5198, DOI 10.17487/RFC5198, March 2008,
https://www.rfc-editor.org/info/rfc5198. - [RFC5792] Sangster, P. and K. Narayan, "PA-TNC: A Posture Attribute (PA) Protocol Compatible with Trusted Network Connect (TNC)", RFC 5792, DOI 10.17487/RFC5792, March 2010,
https://www.rfc-editor.org/info/rfc5792. - [RFC8089] Kerwin, M., "The "file" URI Scheme", RFC 8089, DOI 10.17487/RFC8089, February 2017,
https://www.rfc-editor.org/info/rfc8089. - [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 8126, DOI 10.17487/RFC8126, June 2017,
https://www.rfc-editor.org/info/rfc8126. - [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017,
https://www.rfc-editor.org/info/rfc8174. - [SWID09] The International Organization for Standardization/International Electrotechnical Commission, "Information technology - Software asset management - Part 2: Software identification tag", ISO/IEC 19770-2:2009, November 2009,
https://www.iso.org/standard/53670.html. - [SWID15] The International Organization for Standardization/International Electrotechnical Commission, "Information technology - Software asset management - Part 2: Software identification tag", ISO/IEC 19770-2:2015, October 2015,
https://www.iso.org/standard/65666.html.
11.2. Informative References 📖
These ones are more like extra reading for the curious 🧚
- [RFC5209] Sangster, P., Khosravi, H., Mani, M., Narayan, K., and J. Tardo, "Network Endpoint Assessment (NEA): Overview and Requirements", RFC 5209, DOI 10.17487/RFC5209, June 2008,
https://www.rfc-editor.org/info/rfc5209. - [RFC5793] Sahita, R., Hanna, S., Hurst, R., and K. Narayan, "PB-TNC: A Posture Broker (PB) Protocol Compatible with Trusted Network Connect", RFC 5793, DOI 10.17487/RFC5793, March 2010,
https://www.rfc-editor.org/info/rfc5793. - [RFC6876] Sangster, P., Cam-Winget, N., and J. Salowey, "A Posture Transport Protocol over TLS (PT-TLS)", RFC 6876, DOI 10.17487/RFC6876, February 2013,
https://www.rfc-editor.org/info/rfc6876. - [RFC7171] Cam-Winget, N. and P. Sangster, "PT-EAP: Posture Transport (PT) Protocol for Extensible Authentication Protocol (EAP) Tunnel Methods", RFC 7171, DOI 10.17487/RFC7171, May 2014,
https://www.rfc-editor.org/info/rfc7171. - [RFC7632] Waltermire, D. and D. Harrington, "Endpoint Security Posture Assessment: Enterprise Use Cases", RFC 7632, DOI 10.17487/RFC7632, September 2015,
https://www.rfc-editor.org/info/rfc7632. - [RFC8248] Cam-Winget, N. and L. Lorenzin, "Security Automation and Continuous Monitoring (SACM) Requirements", RFC 8248, DOI 10.17487/RFC8248, September 2017,
https://www.rfc-editor.org/info/rfc8248.
Authors' Addresses 💖
Meet the squad who wrote this 🫶
Charles Schmidt
The MITRE Corporation
202 Burlington Road
Bedford, MA 01730
United States of America
Email: cmschmidt@mitre.orgDaniel Haynes
The MITRE Corporation
202 Burlington Road
Bedford, MA 01730
United States of America
Email: dhaynes@mitre.orgChris Coffin
The MITRE Corporation
202 Burlington Road
Bedford, MA 01730
United States of America
Email: ccoffin@mitre.orgDavid Waltermire
National Institute of Standards and Technology
100 Bureau Drive
Gaithersburg, Maryland
United States of America
Email: david.waltermire@nist.govJessica Fitzgerald-McKay
United States National Security Agency
9800 Savage Road
Ft. Meade, Maryland
United States of America
Email: jmfitz2@radium.ncsc.mil📦 where this page comes from
- ietf: rfc8412 2018-07
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms