RFC 8412
Software Inventory Message and Attributes (SWIMA) for PA-TNC
Pages: 101
Proposed Standard
Proposed Standard
Part 3 of 6 – Pages 26 to 45
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 the SWIMA-PC is operational, and a given SWIMA-PC MUST be able to account for any net change to the endpoint's Software Inventory Evidence Collection that occurs when the SWIMA-PC is not operational. However, to be of use to the enterprise, the NEA Server needs to be able to receive these events and be able to understand how new changes relate to earlier changes. In SWIMA, this is facilitated 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
To be useful, change events need to be correctly ordered. The ordering of events is facilitated by two pieces of information: an Event Identifier (EID) value and an EID Epoch value. An EID is a 4-byte unsigned integer that the SWIMA-PC assigns sequentially to each observed event (whether detected in real time or deduced by looking for net changes over a period of SWIMA-PC inactivity). All EIDs exist within the context of some "EID Epoch", which is also represented as a 4-byte unsigned integer. EID Epochs are used to ensure synchronization between the SWIMA-PC and any SWIMA-PVs with which it communicates. EID Epoch values MUST be generated in such a way as to minimize the chance that an EID Epoch will be reused, even in the case where the SWIMA-PC reverts to an earlier state. For this reason, sequential EID Epochs are discouraged, since loss of state could result in value reuse. There are multiple reasons that a SWIMA-PC might need to deliberately reset its EID counter, including exhaustion of available EID values, the need to purge entries from the event log to recover memory, or corruption of the event log. In all cases where a SWIMA-PC needs to reset its EID counter, a new EID Epoch MUST be selected. Within an Epoch, EIDs MUST be assigned sequentially, so that if a particular event is assigned an EID of N, the next observed event is given an EID of N+1. In some cases, events might occur simultaneously, or the SWIMA-PC might not otherwise be able to determine an ordering for events. In these cases, the SWIMA-PC creates an arbitrary ordering of the events and assigns EIDs according to this ordering. Two change events MUST NOT ever be assigned the same EID within the same EID Epoch. No meaningful comparison can be made between EID values of different Epochs. The EID value of 0 is reserved and MUST NOT be associated with any event. Specifically, an EID of 0 in a SWIMA Request attribute indicates that a SWIMA-PV wants an inventory response rather than an event response, while an EID of 0 in a SWIMA Response is used to indicate the initial state of the endpoint's Software Inventory Evidence Collection prior to the observation of any events. Thus, the very first recorded event in a SWIMA-PC's records within an EID Epoch MUST be assigned a value of 1. Note that EID and EID Epoch values are assigned by the SWIMA-PC without regard to whether events are being reported to one or more SWIMA-PVs. The SWIMA-PC records events and assigns EIDs during its operation. All SWIMA-PVs that request event information from the SWIMA-PC will have those requests served from the same event records and thus will see the same EIDs and EID Epochs for the same events.
If a SWIMA-PC uses multiple sources, a SWIMA-PC's assignment of EIDs MUST reflect the presence and order of all events on the endpoint (at least for supported sources), regardless of the source. This means that if source A experiences an event and then source B experiences two events, and then source A experiences another two events, the SWIMA-PC is required to capture five events with consecutive EID values reflecting the order in which the events occurred. The SWIMA-PC MUST ensure that there is no coverage gap (i.e., change events that are not recorded in the SWIMA-PC's records) in its change event records. This is necessary because a coverage gap might give a SWIMA-PV a false impression of the endpoint's state. For example, if a SWIMA-PV saw an event indicating that a particular record had been added to the endpoint's Software Inventory Evidence Collection but did not see any subsequent events indicating that the record in question had been deleted, it might reasonably assume that this record was still present and thus that the indicated software was still installed (assuming that the Epoch has not changed). If there is a coverage gap in the SWIMA-PC's event records, however, this assumption could be false. For this reason, the SWIMA-PC's event records MUST NOT contain gaps. In the case where there are periods where it is possible that changes occurred without the SWIMA-PC detecting or recording them, the SWIMA-PC MUST either (1) compute a net change and update its event records appropriately or (2) pick a new EID Epoch to indicate a discontinuity with previous event records. Within a given Epoch, once a particular event has been assigned an EID, this association MUST NOT be changed. That is, within an Epoch, once an EID is assigned to an event, that EID cannot be reassigned to a different event, and the event cannot be assigned a different EID. When the SWIMA-PC's Epoch changes, all of these associations between EIDs and events are cancelled, and EID values once again become free for assignment.3.7.2. Core Event-Tracking Information
Whether reporting events or full inventories, it is important to know how the reported information fits into the overall timeline of change events. This is why all SWIMA Response attributes include fields to place that response within the sequence of detected events. Specifically, all SWIMA Responses include a Last EID field and an EID Epoch field. The EID Epoch field identifies the EID Epoch in which the SWIMA Response was sent. If the SWIMA Response is reporting events, all reported events occurred within the named EID Epoch. The Last EID (which is also always from the named EID Epoch) indicates the EID of the last recorded change event at the time that the SWIMA
Response was sent. These two fields allow any response to be placed in the context of the complete set of detected change events within a given EID Epoch.3.7.3. Updating Inventory Knowledge Based on Events
Modern endpoints can have hundreds of software products installed, most of which are unlikely to change from one day to the next. As such, instead of exchanging a complete list of an endpoint's inventory on a regular basis, one might wish to only identify changes since some earlier known state of this inventory. This is readily facilitated by the use of EIDs to place change events in a context relative to the earlier state. As noted above, every SWIMA Response sent by a SWIMA-PC to a SWIMA-PV (as described in Sections 3.3 through 3.5) includes the EID Epoch and EID of the last event recorded prior to that response being compiled. This allows the SWIMA-PV to place all subsequently received event records in context relative to this SWIMA Response attribute (since the EIDs represent a total ordering of all changes to the endpoint's Software Inventory Evidence Collection). Specifically, a SWIMA-PV (or, more likely, a database that collects and records its findings) can record an endpoint's full inventory and also the EID and Epoch of the most recent event reflected at the time of that inventory. From that point on, if change events are observed, the attribute describing these events indicates the nature of the change, the affected records, and the order in which these events occurred (as indicated by the sequential EIDs). Using this information, any remote record of the endpoint's Software Inventory Evidence Collection can be updated appropriately.3.7.4. Using Event Records in SWIMA Attributes
A SWIMA-PV MUST be able to request a list of event records instead of an inventory. The attribute flow in such an exchange looks the same as the basic flow shown in Figure 2. The only difference is that in the SWIMA Request attribute the SWIMA-PV provides an EID other than 0. (An EID value of 0 in a SWIMA Request represents a request for an inventory.) When the SWIMA-PC receives such a request, instead of identifying records from the endpoint's Software Inventory Evidence Collection, it consults its list of detected changes. The SWIMA-PC MUST add an event record to the SWIMA Response attribute for each recorded change event with an EID greater than or equal to the EID in the SWIMA Request attribute (although the targeting of requests, as described in the next paragraph, might limit this list). A list of event records MUST only contain events with EIDs that all come from the current Epoch.
SWIMA-PVs can target requests for event records by including one or more Software Identifiers, as described in Section 3.5, in the SWIMA Request that requests an event record list. A targeted request for event records is used to indicate that only events affecting software that matches one of the provided Software Identifiers are to be returned. Specifically, in response to a targeted request for event records, the SWIMA-PC MUST exclude any event records that are less than the indicated EID (within the current EID Epoch) and exclude any event records where the affected software does not match one of the provided Software Identifiers. This might mean that the resulting list of event records sent in the response attribute does not provide a continuous sequence of EIDs. 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
Over time, a SWIMA-PC might record a large number of change events. If a SWIMA-PV requests all change events covering a long period of time, the resulting SWIMA Response attribute might be extremely large, especially if the SWIMA-PV requests the inclusion of Software Inventory Evidence Records in the response. In the case that the resulting attribute is too large to send (because it exceeds either (1) the 4 GB attribute size limit imposed by the PA-TNC specification or (2) some smaller size limit imposed on the SWIMA-PC), the SWIMA-PC MAY send a partial list of event records back to the SWIMA-PV. The generation of a partial list of events in a SWIMA Response attribute requires the SWIMA-PC to identify a "consulted range" of EIDs. A consulted range is the set of event records that are examined for inclusion in the SWIMA Response attribute and that are included in that attribute if applicable. Recall that if a SWIMA Request is targeted, only event records that involve the indicated software would be applicable. (See Section 3.5 for more on targeted requests.) If a request is not targeted, all event records in the consulted range are applicable and are included in the SWIMA Response attribute. The lower bound of the consulted range MUST be the EID provided in the SWIMA Request. (Recall that a SWIMA-PV indicates a request for event records by providing a non-zero EID value in the SWIMA Request. See Section 3.7.4.) The upper bound of the consulted range is the EID of the latest event record (as ordered by EID values) that is included in the SWIMA Response attribute if it is applicable to the request. The EID of this last event record is called the "Last Consulted EID". The SWIMA-PC chooses this Last Consulted EID based on the size of the event record list it is willing to provide to the SWIMA-PV.
A partial result list MUST include all applicable event records within the consulted range. This means that for any applicable event record (i.e., any event record in a non-targeted request or any event record associated with software matching a requested Software Identifier in a targeted request) whose EID is greater than or equal to the EID provided in the SWIMA Request and whose EID is less than or equal to the Last Consulted EID, that event record MUST be included in the SWIMA Response conveying this partial list of event records. This ensures that every partial list of event records is always complete within its indicated range. Remember that for targeted requests, "complete" doesn't mean that all EIDs between the range endpoints are present -- only that every matching EID between the range endpoints is included. In addition to the EID Epoch and Last EID fields that are present in all SWIMA Responses, all SWIMA Response attributes that convey event records include a Last Consulted EID field. Note that if responding to a targeted SWIMA Request, the SWIMA Response attribute might not contain the event record whose EID matches the Last Consulted EID value. For example, that record might have been deemed inapplicable because it did not match the specified list of Software Identifiers in the SWIMA Request. If a SWIMA-PV receives a SWIMA Response attribute where the Last EID and Last Consulted EID fields are identical, the SWIMA-PV knows that it has received a result list that is complete, given the parameters of the request, up to the present time. On the other hand, if the Last EID is greater than the Last Consulted EID, the SWIMA-PV has received a partial result list. (The Last Consulted EID MUST NOT exceed the Last EID.) In this case, if the SWIMA-PV wishes to try to collect the rest of the partially delivered result list, it then sends a new SWIMA Request whose EID is one greater than the Last Consulted EID in the preceding response. Doing this causes the SWIMA-PC to generate another SWIMA Response attribute containing event records where the earliest reported event record is the one immediately after the event record with the Last Consulted EID (since EIDs are assigned sequentially). By repeating this process until it receives a SWIMA Response where the Last EID and Last Consulted EID are equal, the SWIMA-PV is able to collect all event records over a given range, even if the complete set of event records would be too large to deliver via a single attribute. Implementers need to be aware that a SWIMA Request might specify an EID that is greater than the EID of the last event recorded by a SWIMA-PC. In accordance with the behaviors described in Section 3.7.4, a SWIMA-PC MUST respond to such a request with a SWIMA Response attribute that contains zero event records. This is because
the SWIMA-PC has recorded no event records with EIDs greater than or equal to the EID in the SWIMA Request. In such a case, the Last Consulted EID field MUST be set to the same value as the Last EID field in this SWIMA Response attribute. This case is called out because the consulted range on a SWIMA-PC in such a situation is a negative range, where the "first" EID in the range (provided in the SWIMA Request) is greater than the "last" EID in the range (this being the EID of the last recorded event on the SWIMA-PC). Implementers need to ensure that SWIMA-PCs do not experience problems in such a circumstance. Note that this specification only supports the returning of partial results when returning event records. There is no way to return a partial inventory list under this specification.3.7.6. Synchronizing Event Identifiers and Epochs
Since EIDs are sequential within an Epoch, if a SWIMA-PV's list of event records contains gaps in the EID values within a single Epoch, the SWIMA-PV knows that there are events that it has not accounted for. The SWIMA-PV can request either (1) a new event list to collect the missing events or (2) a full inventory to resync its understanding of the state of the endpoint's Software Inventory Evidence Collection. In either case, after the SWIMA-PV's record of the endpoint's Software Inventory Evidence Collection has been updated, the SWIMA-PV can record the new latest EID value and track events normally from that point on. If the SWIMA-PV receives any attribute from a SWIMA-PC where the EID Epoch differs from the EID Epoch that was used previously, then the SWIMA-PV or any entity using this information to track the endpoint's Software Inventory Evidence Collection knows that there is a discontinuity in its understanding of the endpoint's state. To move past this discontinuity and reestablish a current understanding of the state of the endpoint's Software Inventory Evidence Collection, the SWIMA-PV needs to receive a full inventory from the endpoint. The SWIMA-PV cannot be brought in sync with the endpoint's state through the collection of any set of event records in this situation. This is because it is not possible to account for all events on the SWIMA-PC since the previous Epoch was used: there is no way to query for EIDs from a previous Epoch. Once the SWIMA-PV has received a full inventory for the new Epoch, the SWIMA-PV records the latest EID reported in this new Epoch and can track further events normally. A SWIMA-PC MUST NOT report events with EIDs from any Epoch other than the current EID Epoch. The SWIMA-PC MAY choose to purge all event records from a previous Epoch from memory after an Epoch change. Alternately, the SWIMA-PC MAY choose to retain some event records
from a previous EID Epoch and assign them new EIDs in the current Epoch. However, in the case where a SWIMA-PC chooses the latter option it MUST ensure that the order of events according to their EIDs is unchanged and that there is no coverage gap between the first retained event recorded during the previous Epoch (now reassigned with an EID in the current Epoch) and the first event recorded during the current Epoch. In particular, the SWIMA-PC MUST ensure that all change events that occurred after the last recorded event from the previous Epoch are known and recorded. (This might not be possible if the Epoch change is due to state corruption on the SWIMA-PC.) A SWIMA-PC might choose to reassign EIDs to records from a preceding Epoch to create a "sliding window" of events, where each Epoch change represents a shift in the window of available events. In the case where a SWIMA-PC suffers a crash and loses track of its current EID Epoch or current EID, then it MUST generate a new EID Epoch value and begin assigning EIDs within that Epoch. In this case, the SWIMA-PC MUST purge all event records from before the crash, as it cannot ensure that there is not a gap between the last of those records and the next detected event. The process for generating a new EID Epoch MUST minimize the possibility that the newly generated EID Epoch is the same as a previously used EID Epoch. The SWIMA-PV will normally never receive an attribute indicating that the latest EID is less than the latest EID reported in a previous attribute within the same EID Epoch. If this occurs, the SWIMA-PC has suffered an error of some kind, possibly indicative of at least partial corruption of its event log. In this 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 being out of sync until a full inventory can be reported by the SWIMA-PC. The SWIMA-PV SHOULD log the occurrence so the SWIMA-PC can be examined to ensure that it is now operating properly.3.8. Subscriptions
Thus far, all attribute exchanges discussed assume that a SWIMA-PV sent a SWIMA Request attribute and the SWIMA-PC is providing a direct response to that request. SWIMA also supports the ability of a SWIMA-PC to send a SWIMA Response to the SWIMA-PV in response to observed changes in the endpoint's Software Inventory Evidence Collection, instead of in direct response to a SWIMA Request. An agreement by a SWIMA-PC to send content when certain changes to the endpoint's Software Inventory Evidence Collection are detected is referred to in this specification as a "subscription", and the SWIMA-PV that receives this content is said to be "subscribed to" the given SWIMA-PC. All SWIMA-PCs and SWIMA-PVs MUST support the use of subscriptions.
3.8.1. Establishing Subscriptions
A SWIMA-PV establishes a subscription on a particular SWIMA-PC by sending a SWIMA Request attribute with the Subscribe flag set. The SWIMA Request attribute is otherwise identical to the SWIMA Requests discussed in previous sections. Specifically, such a SWIMA Request might or might not request the inclusion of Software Inventory Evidence Records, might or might not be targeted, and might request change event records or endpoint inventory. Assuming that no error is encountered, a SWIMA-PC MUST send a SWIMA Response attribute in direct response to this SWIMA Request attribute, just as if the Subscribe flag was not set. As such, the attribute exchange that establishes a new subscription in a SWIMA-PC has the same flow as the flow seen in the previous attribute exchanges, as depicted in Figure 2. If the SWIMA-PV does not receive a PA-TNC Error attribute (as described in Sections 3.9 and 5.15) in response to its subscription request, the subscription has been successfully established on the SWIMA-PC. The SWIMA Request attribute that establishes a new subscription is referred to as the "establishing request" for that subscription. When a subscription is established, it is assigned 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 this. These subscriptions might all come from a single SWIMA-PV, might all be from different SWIMA-PVs (residing on the same or different NEA Servers), or might be a mix. In the case that a SWIMA-PC receives a subscription request but is unable to support an additional subscription, it MUST respond to the request with a PA-TNC Error attribute with 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 this. Any number of these subscriptions might be to the same SWIMA-PC, and any number of these subscriptions might be to different SWIMA-PCs. In the latter case, some of these SWIMA-PCs might share a single endpoint, while others might be on different endpoints.
3.8.2. Managing Subscriptions
The SWIMA-PC MUST record each accepted subscription along with the identity of the party to whom attributes are to be pushed. This identity includes two parts: o 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" o The Posture Validator Identifier for the SWIMA-PV that made the subscription request The Posture Validator Identifier is provided in the field of the same name in the PB-PA message that encapsulates the subscription request attribute (Section 4.5 of [RFC5793]), and this information is passed along to NEA Posture Collectors (Section 3.3 of [RFC5792]). The Connection ID is a value local to a particular endpoint's Posture Broker Client that identifies an ongoing session between a specific Posture Broker Client and a specific Posture Broker Server. Posture Broker Clients and Posture Broker Servers need to be capable of supporting multiple simultaneous sessions, so they already need a way to locally distinguish each ongoing session. (See Section 3.1 of [RFC5793].) A Posture Broker Client needs to assign each session at a given time its own Connection ID that lasts for the life of that session. Connection IDs only need to be unique among the Connection IDs of simultaneously occurring sessions on that endpoint. This Connection ID needs to be exposed to the SWIMA-PC, and the SWIMA-PC needs to be informed when the Connection ID is unbound due to the closure of that connection. Likewise, SWIMA-PVs MUST record each accepted subscription for which they are the subscribing party, including the parameters of the establishing request, along with the associated Subscription ID and the identity of the SWIMA-PC that will be fulfilling the subscription. The SWIMA-PV needs to retain this information in order to 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] of the PB-PA message header in all messages from that SWIMA-PC. The SWIMA-PV has no need to record the associated connection ID of the subscription as the SWIMA-PV is only receiving, not sending, attributes once a subscription is established.
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. (See Section 5.6 for more on using this flag.) In the case that a SWIMA Request with the Clear Subscriptions flag set is received, 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 MUST clear all such subscriptions. This specification does not give the SWIMA-PV the ability to terminate subscriptions individually -- all subscriptions to the SWIMA-PV are cleared when the Clear Subscriptions flag is set. This specification does not give the SWIMA-PC the ability to unilaterally terminate a subscription. However, if the SWIMA-PC experiences a fatal error while fulfilling a subscription, resulting in sending a PA-TNC Error attribute with error code SWIMA_SUBSCRIPTION_FULFILLMENT_ERROR, then the subscription whose fulfillment led to the error MUST be treated as terminated by both the SWIMA-PC and the SWIMA-PV. Only the subscription experiencing the error is cancelled; other subscriptions are unaffected. See Section 3.9 for more on this error condition. Finally, a subscription is terminated if the connection between the SWIMA-PC and SWIMA-PV is closed. This occurs when the Connection ID used in the messages between the SWIMA-PC and the SWIMA-PV becomes unbound. Loss of this Connection ID would prevent the SWIMA-PC from sending messages in fulfillment of this subscription. As such, loss of the Connection ID necessarily forces subscription termination between the affected parties.3.8.4. Subscription Status
A SWIMA-PV can request that a SWIMA-PC report the list of active subscriptions for which the SWIMA-PV is the subscriber. A SWIMA-PV can use this capability to recover lost information about active subscriptions. A SWIMA-PV can also use this capability to verify that a SWIMA-PC has not forgotten any of its subscriptions. The latter is especially useful in cases where a SWIMA-PC does not send any attributes in fulfillment of a given subscription for a long period of time. The SWIMA-PV can check the list of active subscriptions on the SWIMA-PC and verify whether the inactivity is due to (1) a lack of reportable events or (2) the SWIMA-PC forgetting its obligations to fulfill a given subscription.
A SWIMA-PV requests a list of its subscriptions on a given SWIMA-PC 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 an error condition is experienced). The Subscription Status Response MUST contain one subscription record for each of the active subscriptions for which 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 a change to relevant records is detected within the endpoint's Software Inventory Evidence Collection. Such an attribute 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 provided in that establishing request are considered relevant. Otherwise (i.e., for non-targeted requests), any record is considered relevant for this purpose. Figure 3 shows a sample attribute exchange where a subscription is established and then attributes are sent from the SWIMA-PC in fulfillment of the established subscription. +-------------+ +--------------+ | SWIMA-PC | | SWIMA-PV | Time +-------------+ +--------------+ | | | | |<----------SWIMA Request-----------| | | | | |-----------SWIMA Response--------->| | | | | . . . . . . . . . <Change Event>| | | |----------SWIMA Response---------->| | | | | . . . . . . . . . <Change Event>| | | |----------SWIMA Response---------->| | | | V Figure 3: Subscription Establishment and Fulfillment
The contents of an attribute sent in fulfillment of a subscription depend on the parameters provided in the establishing request for that subscription. Specifically, the attribute sent in fulfillment of a subscription has the same attribute type as would a direct response to the establishing request. For example, if the establishing request stipulated a response that contained an event record list that included Software Inventory Evidence Records, all attributes sent in fulfillment of this subscription will also consist of event record lists with Software Inventory Evidence Records. As such, all SWIMA Responses displayed in the exchange depicted in Figure 3 are the same attribute type. A SWIMA Response generated in fulfillment of an active subscription MUST be a valid SWIMA Response attribute according to all the rules outlined in the preceding sections. In other words, an attribute constructed in fulfillment of a subscription will look the same as an attribute sent in direct response to an explicit request from a SWIMA-PV that had the same request parameters and that arrived immediately after the given change event. There are a few special rules that expand on this guideline, as discussed in Sections 3.8.5.1 through 3.8.5.5.3.8.5.1. Subscriptions That Report Inventories
In the case that a SWIMA-PV subscribes to a SWIMA-PC and requests an inventory attribute whenever changes are detected (i.e., the EID in the establishing request is 0), then the SWIMA-PC MUST send the requested inventory whenever 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.) Upon detection of a relevant change for an active subscription, the SWIMA-PC sends the appropriate inventory information as if it had just received the establishing request. Inventory attributes sent in fulfillment of this subscription will probably have a large amount of redundancy, as the same records are likely to be present in each of these SWIMA attributes. The role of an inventory subscription is not to report records just for the items that changed -- that is the role of a subscription that reports events (see Section 3.8.5.2). A SWIMA-PC MUST NOT exclude a record from an attribute sent in fulfillment of an inventory subscription simply because that record was not involved in the triggering event (although a record might be excluded for other reasons, such as if the subscription is targeted; see Section 3.8.5.3).3.8.5.2. Subscriptions That Report Events
A SWIMA-PV indicates that it wishes to establish a subscription requesting event records by providing a non-zero EID in the SWIMA Request establishing the subscription (see Section 3.7.1). However, when the SWIMA-PC constructs an attribute in fulfillment of the
subscription (other than the direct response to the establishing request), it MUST only include event records for the detected change(s) that precipitated this response attribute. In other words, it MUST NOT send a complete list of all changes starting with the establishing request's EID, up through the latest change, every time a new event is detected. In effect, the EID in the establishing request is treated as being updated every time an attribute is sent in fulfillment of this subscription, such that a single event is not reported twice in fulfillment of a single subscription. As such, every SWIMA-PC MUST track the EID of the last event that triggered an attribute for the given subscription. When the next event (or set of events) is detected, the SWIMA-PC MUST only report events with EIDs after the last reported event. In the case that the EID Epoch of the SWIMA-PC changes, the SWIMA-PC MUST reset this EID tracker to zero (if the event log is completely purged) or to the new EID of the last reported retained event (if the event log is partially purged to create a "sliding window"). Doing this ensures that the SWIMA-PC continues to only send events that have not been previously reported. Note that while a subscription is active, the subscribing SWIMA-PV MAY make other requests for event records that overlap with events that are reported in fulfillment of a subscription. Such requests are not affected by the presence of the subscription, nor is the subscription affected by such requests. In other words, a given request will get the same results back whether or not there was a subscription. Likewise, an attribute sent in fulfillment of a subscription will contain the same information whether or not other requests had been received from the SWIMA-PV. A SWIMA-PV needs to pay attention to the EID Epoch in these attributes, as changes in the Epoch might create discontinuities in the SWIMA-PV's understanding of the endpoint's Software Inventory Evidence Collection state, as discussed in Section 3.7.6. In particular, once the EID Epoch changes, a SWIMA-PV is unable to have confidence that it has a correct understanding of the state of an endpoint's Software Inventory Evidence Collection until after the SWIMA-PV collects a complete inventory. 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.) In the case that a SWIMA-PC sends a partial list of event records in fulfillment of a subscription, it MUST immediately send the next consecutive partial list and continue doing so until it has sent the equivalent of the complete list of event records. In other words, if the SWIMA-PC sends a partial list, it does not wait for another change event to send another SWIMA Response; rather, it continues sending SWIMA Responses until it has sent all event records that would have been included in a complete fulfillment of the
subscription. Note that the direct response to the establishing request is not considered to be sent in fulfillment of a subscription. However, in this case the SWIMA-PC MUST treat the presence of unreported events as a triggering event for pushing additional messages in fulfillment of the newly established subscription. As such, the net effect is that if the direct response to the establishing request (i.e., the Subscription Fulfillment flag is unset) is partial, the SWIMA-PC will immediately follow this with additional attributes (with the Subscription Fulfillment flag set) until the complete set of events has been sent to the SWIMA-PV.3.8.5.3. Targeted Subscriptions
Subscriptions MAY be targeted to only apply to records that match a given set of Software Identifiers. In the case where changes that affect multiple records are detected -- some matching the establishing request's Software Identifiers and some not -- the attribute sent in fulfillment of the subscription MUST only include inventory or events (as appropriate) for records that match the establishing request's Software Identifiers. The SWIMA-PC MUST NOT include non-matching records in the attribute, even if those non-matching records experienced change events that were simultaneous with change events on the matching records. In addition, a SWIMA-PC MUST send an attribute in fulfillment of a targeted subscription only when changes to the endpoint's Software Inventory Evidence Collection impact one or more records matching the subscription's establishing request's Software Identifiers. A SWIMA-PC MUST NOT send any attribute in fulfillment of a targeted subscription based on detected changes to the endpoint's Software Inventory Evidence Collection that did not involve any of the records targeted by that subscription.3.8.5.4. No Subscription Consolidation
A SWIMA-PV MAY establish multiple subscriptions to a given SWIMA-PC. If this is the case, it is possible that a single change event on the endpoint might require fulfillment by multiple subscriptions and that the information included in attributes that fulfill each of these subscriptions might overlap. The SWIMA-PC MUST send separate attributes for each established subscription that requires a response due to the given event. Each of these attributes MUST contain all information required to fulfill that individual subscription, even if that information is also sent in other attributes sent in fulfillment of other subscriptions at the same time. In other words, SWIMA-PCs MUST NOT attempt to combine information when fulfilling multiple subscriptions simultaneously, even if this results in some redundancy in the attributes sent to the SWIMA-PV.
3.8.5.5. Delayed Subscription Fulfillment
A SWIMA-PC MAY delay the fulfillment of a subscription following a change event in the interest of waiting to see if additional change events are forthcoming and, if so, conveying the relevant records back to the SWIMA-PV in a single SWIMA Response attribute. This can help reduce network bandwidth consumption between the SWIMA-PC and the SWIMA-PV. For example, consider a situation where 10 changes occur a tenth of a second apart. If the SWIMA-PC does not delay in assembling and sending SWIMA Response attributes, the SWIMA-PV will receive 10 separate SWIMA Response attributes over a period of 1 second. However, if the SWIMA-PC waits half a second after the initial event before assembling a SWIMA Response, the SWIMA-PV only receives two SWIMA Response attributes over the same period of time. Note that the ability to consolidate events for a single subscription over a given period of time does not contradict the rules in Section 3.8.5.4 prohibiting consolidation across multiple subscriptions. When delaying fulfillment of subscriptions, SWIMA-PCs are still required to fulfill each individual subscription separately. Moreover, in the case that change events within the delay window cancel each other out (e.g., a record is deleted and then re-added), the SWIMA-PC MUST still report each change event, rather than just report the net effect of changes over the delay period. In other words, delayed fulfillment can decrease the number of attributes sent by the SWIMA-PC, but it does not reduce the total number of change events reported. SWIMA-PCs are not required to support delayed fulfillment of subscriptions. However, in the case that the SWIMA-PC does support delayed subscription fulfillment, it MUST be possible to configure the SWIMA-PC to disable delayed fulfillment. In other words, parties deploying SWIMA-PCs need to be allowed to disable delayed subscription fulfillment in their SWIMA-PCs. The manner in which such configuration occurs is left to the discretion of implementers, although implementers MUST protect the configuration procedure from unauthorized tampering. In other words, there needs to be some assurance that unauthorized individuals are not able to introduce long delays in subscription fulfillment.3.9. Error Handling
In the case where the SWIMA-PC detects an error in a SWIMA Request attribute that it receives, it MUST respond with a PA-TNC Error attribute with an error code appropriate to the nature of the error. (See Section 4.2.8 of PA-TNC [RFC5792] for more details about PA-TNC Error attributes and error codes, and see Section 5.15 in this specification for error codes specific to SWIMA attributes.) In the
case that an error is detected in a SWIMA Request, the SWIMA-PC MUST NOT take any action requested by this SWIMA Request, even if partial completion of the request is possible. In other words, a SWIMA Request that contains an error will be completely ignored by the SWIMA-PC (beyond sending a PA-TNC Error attribute and possibly logging the error locally); no attempt at partial completion of the request will be made. In the case where the SWIMA-PC receives a valid SWIMA Request attribute but experiences an error during the process of responding to that attribute's instructions where that error prevents the SWIMA-PC from properly or completely fulfilling that request, the SWIMA-PC MUST send a PA-TNC Error attribute with an error code appropriate to the nature of the error. In the case where a PA-TNC Error attribute is sent, the SWIMA-PC MUST NOT take any of the actions requested by the SWIMA Request attribute that led to the detected error. This is the case even if some actions could have been completed successfully and might even require the SWIMA-PC to reverse some successful actions already taken before the error condition was detected. In other words, either (1) all aspects of a SWIMA Request complete fully and successfully (in which case the SWIMA-PC sends a SWIMA Response attribute) or (2) no aspects of the SWIMA Request occur (in which case the SWIMA-PC sends a PA-TNC Error attribute). In the case that a SWIMA-PC sends a PA-TNC Error attribute in response to a SWIMA Request, then the SWIMA-PC MUST NOT also send any SWIMA Response attribute in response to the same SWIMA Request. For this reason, the sending of a SWIMA Response attribute MUST be the last action taken by a SWIMA-PC in response to a SWIMA Request, to avoid the possibility of a processing error occurring after that SWIMA Response attribute is sent. In the case that the SWIMA-PC detects an error that prevents it from properly or completely fulfilling its obligations under an active subscription, the SWIMA-PC 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 cannot be adequately honored due to the error condition and also identifies an error "subtype". The error subtype indicates the error code of the error condition the SWIMA-PC experienced that prevented it from honoring the given subscription. In the case that the error condition cannot be identified or does not align with any of the defined error codes, the SWIMA_ERROR error code SHOULD be used in the subtype. In the case that 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. In the case that a SWIMA-PV detects an error condition, it SHOULD log this error, but the SWIMA-PV 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 that administrators can trace the causes of errors. Log entries SHOULD include the code of the error, the time it was detected, and additional descriptive information to aid in understanding the nature and cause of the error. Logs are an 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. These message exchanges are described in the following subsections, along with implementation requirements for supporting them. The SWIMA protocol also supports 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). As these exchanges are straightforward, no additional information on the exchanges is provided.
4.1. Direct Response to a SWIMA Request
The first type of software information exchange is used to provide the SWIMA-PV with 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 indicates to the SWIMA-PC, via a SWIMA Request, the nature of the information it wishes to receive (inventory vs. events, full or targeted) and how it wishes the returned inventory to be expressed (with or without Software Inventory Evidence Records). The SWIMA-PC responds 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. Such an exchange is shown in Figure 5. +-------------+ +--------------+ | 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 precipitate 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 providing multiple SWIMA Responses in this way, the initial responses contain partial lists of event records and the last of those SWIMA Responses conveys the remainder of the relevant event records, completing the delivery of all relevant events in response to the 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.
(next page on part 4)