Asset Telemetry

Asset Telemetry is a set of events representing the state changes of identifiable, active source devices for any normalized device attribute that qualifies for change tracking.

📘
Italicized terms are important definitions of key system concepts. We recommend reading Unified Asset Inventory to understand these terms.

Asset Telemetry Overview

Asset Telemetry operates on identifiable, active source devices. It occurs after source device preprocessing, but before correlation.

After fetching a batch of source device observations, the identifiable, active source devices are sent to the telemetry engine. The telemetry engine compares the currently reported device with the previously reported device and, for every change on a change-tracked attribute, creates a change event.

Event Types

There are two categories of events currently reported:

Inventory Change Events: An event reported each time a device is either added to or removed from a given source.
Attribute Change Events: An event reported each time the value of a change-tracked attribute changes from the previous observation.

Inventory Change Events

For direct sources, there are two types of Inventory Change Events:

SourceMembershipAdd: This event is generated when a device is added to a source.
SourceMembershipRemove: This event is generated when a device is removed from a source.

These events are not generated for inferred sources that report device activity observations.

Attribute Change Events

There are two types of Attribute Change Events:

AttributeValueAdded: This event is generated when a new attribute value is observed.
AttributeValueRemoved: This event is generated when a previously seen attribute is removed.

Changes are not tracked on every attribute, but only a subset, including but not limited to:

Device Attributes	User Attributes
`Active Directory Domain`	`Created Timestamp`
`Agent Version`	`Emails`
`Asset Classification Category`	`First Name`
`Fully Qualified Domain Name`	`Full Name`
`Hostnames`	`Groups`
`IP Addresses`	`Last Name`
`MAC Addresses`	`Names`
`Operating System`	`Phone Numbers`
	`Roles`
	`Status`
	`Usernames`

See your events page for a full list of tracked attributes. If there is an attribute you need tracked, please bring it to our attention!

Key Event Fields

Field	Description
`org_id`	The ID of the Sevco Organization to which this event belongs.
`source`	The ID of the Source from which this event was generated.
`config_id`	The ID of the Source config this event was generated from (this is in cases where there are multiple live instances of the same source, like multiple Active Directory sources).
`object_id`	The ID of this object as reported by the source. For example, for Active Directory, this would be the machine SID.
`object_version`	A Sevco-internal version number of this object.
`asset_type`	`device`
`event_type`	One of the above event types; for example, `SourceMembershipAdd`.
`event_timestamp`	The time this event was observed.
`valid_until_timestamp`	For `AttributeValueAdd` events, the time when the attribute was removed.
`attribute`	For `AttributeValueAdd` or `AttributeValueRemove` events, the name of the attribute.
`value`	For `AttributeValueAdd` or `AttributeValueRemove` events, the value of the attribute.

Event Examples

Attribute Value Add

{
    "org_id": "2719ac2e-8d52-4dac-958d-b928c79f0fdc",
    "source": "microsoft-ad",
    "config_id": "7bb1789a-5ec3-45ad-ae36-5ffe3afc9c1d",
    "object_id": "S-1-5-21-625934469-701448264-3900219089-55180",
    "object_version": "2021-03-17T16:47:37.854Z",
    "asset_type": "device",
    "event_type": "AttributeValueAdded",
    "event_time": "2021-03-17T16:47:37.854Z",
    "valid_until": null,
    "attribute": "hostnames",
    "value": "baylissbob"
}

Attribute Value Remove

Note that this event is from the same system as the above, but also includes the valid_until_timestamp referencing the previous events event_time.

{
    "org_id": "2719ac2e-8d52-4dac-958d-b928c79f0fdc",
    "source": "microsoft-ad",
    "config_id": "7bb1789a-5ec3-45ad-ae36-5ffe3afc9c1d",
    "object_id": "S-1-5-21-625934469-701448264-3900219089-55180",
    "object_version": "2021-03-17T16:47:37.854Z",
    "asset_type": "device",
    "event_type": "AttributeValueAdded",
    "event_time": "2021-03-17T16:47:37.854Z",
    "valid_until": "2021-03-18T16:47:37.854Z",
    "attribute": "hostnames",
    "value": "baylissbob"
}

Source Membership Add

{
    "org_id": "2719ac2e-8d52-4dac-958d-b928c79f0fdc",
    "source": "microsoft-ad",
    "config_id": "7bb1789a-5ec3-45ad-ae36-5ffe3afc9c1d",
    "object_id": "S-1-5-21-625934469-701448264-3900219089-55180",
    "object_version": "2021-03-17T16:47:37.854Z",
    "asset_type": "device",
    "event_type": "AttributeValueAdded",
    "event_time": "2021-03-17T16:47:37.854Z",
    "valid_until": "2021-03-18T16:47:37.854Z",
    "attribute": "hostnames",
    "value": "baylissbob"
}

Source Membership Remove

{
    "org_id": "2719ac2e-8d52-4dac-958d-b928c79f0fdc",
    "source": "microsoft-ad",
    "config_id": "7bb1789a-5ec3-45ad-ae36-5ffe3afc9c1d",
    "object_id": "S-1-5-21-625934469-701448264-3900219089-55180",
    "object_version": null,
    "asset_type": "device",
    "event_type": "SourceMembershipRemove",
    "event_time": "2021-03-17T16:47:37.854Z",
    "valid_until": null,
    "attribute": null,
    "value": null
}