[RFC] New device fields - Stage 0 #2521

ricardo-estc · 2025-09-03T10:01:25Z

1. What does this PR do?

This PR proposes adding new fields to the existing device field set in ECS to provide more comprehensive device identification and classification capabilities. It enhances device tracking, inventory management, and security monitoring by adding vendor, product, and device type information.

2. Which ECS fields are affected/introduced?

device.vendor_name (keyword)
device.vendor_id (keyword)
device.product_name (keyword)
device.product_id (keyword)
device.device_type (keyword)

3. Why is this change necessary?

4. Have you added/updated documentation?

YES / NO / N/A

5. Have you built ECS and committed any newly generated files?

YES / NO

6. Have you run the ECS validation tests locally?

YES / NO

7. Anything else for the reviewers?

Commit Message

cla-checker-service · 2025-09-03T10:01:29Z

💚 CLA has been signed

github-actions · 2025-09-03T10:01:33Z

🤖 GitHub comments

Expand to view the GitHub comments

Just comment with:

run docs-build : Re-trigger the docs validation. (use unformatted text in the comment!)

ricardo-estc · 2025-09-03T14:07:15Z

run docs-build

kgeller · 2025-09-03T17:56:34Z

Hey @ricardo-estc !

I think the issue with the CLA is because the git user associated with the commit is not the same as the one associated with the PR (and presumably your elastic account).

I think if you modify the commits to have your estc email (stack overflow), or possibly even switch the user this should make CI happy.

trisch-me · 2025-09-05T10:57:20Z

rfcs/text/0053-new-device-fields.md

+
+Field | Type | Description
+-- | -- | --
+device.vendor_name | keyword | Vendor name of the device. Example: "SanDisk"


As we are still try to make it as close to semconv as possible, I suggest we would use dot notation i.e. vendor.name, product.id but device_type as a multiword representation.

trisch-me · 2025-09-05T10:57:52Z

rfcs/text/0053-new-device-fields.md

+
+The following are the people that consulted on the contents of this RFC.
+
+* TBD | author


could you please fill this section?

trisch-me · 2025-09-05T10:58:52Z

rfcs/text/0053-new-device-fields.md

+Field | Type | Description
+-- | -- | --
+device.vendor_name | keyword | Vendor name of the device. Example: "SanDisk"
+device.vendor_id | keyword | VendorID of the device. Example: "0x1234"


how ids (both vendor and product) are getting generated? could you please link here specification or add description?

Vendor and product IDs are embedded into the device from the manufacturer.
Each manufacturer has to first request a vendor id from usb.org. List of approved vendors is listed here
https://www.usb.org/sites/default/files/vendor_ids072325_1.pdf

https://learn.microsoft.com/en-us/windows-hardware/drivers/install/standard-usb-identifiers

Should I add these 2 links to the RFC?

Added them in the reference section

trisch-me · 2025-09-05T10:59:11Z

rfcs/text/0053-new-device-fields.md

+
+<!-- Insert any links appropriate to this RFC in this section. -->
+
+* https://www.usb.org/defined-class-codes


where this link is getting used?

trisch-me

Please update according to the comments

trisch-me · 2025-09-08T13:58:10Z

rfcs/text/0053-new-device-fields.md

+device.vendor.id | keyword | VendorID of the device. Example: "0x1234". See [1][2]
+device.product.name | keyword | Product name of the device. Example: "Extreme V2 SSD"
+device.product.id | keyword | ProductID Example: "0xABCD".  See [1][2]
+device.type | keyword | Device type classification. Example: "Storage Device", "HID", "Audio". Ideally one of the USB defined class codes. See [3]


do we need here also class ID according to the link? 07h etc
I am not sure how unique it should be and if it adds any value.

I don't think we need it as the hexadecimal code (0x07) is uniquely defined for USBs. I think device type as string is more versatile and it can be used for numerous usecases, such as virtual devices or non-USB devices

Are there other fields that you think would be good to also add? Looking at lsusb and lspci output, there are additional fields available for many devices. Would any of these be useful to have?

For example, lsusb:

Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub Device Descriptor: bLength 18 bDescriptorType 1 bcdUSB 2.00 bDeviceClass 9 Hub bDeviceSubClass 0 [unknown] bDeviceProtocol 1 Single TT bMaxPacketSize0 64 idVendor 0x1d6b Linux Foundation idProduct 0x0002 2.0 root hub bcdDevice 6.15 iManufacturer 3 Linux 6.15.6-100.fc41.aarch64 xhci-hcd iProduct 2 xHCI Host Controller iSerial 1 0000:00:04.0 bNumConfigurations 1 Configuration Descriptor: bLength 9 bDescriptorType 2 wTotalLength 0x0019 bNumInterfaces 1 bConfigurationValue 1 iConfiguration 0 bmAttributes 0xe0 Self Powered Remote Wakeup MaxPower 0mA Interface Descriptor: bLength 9 bDescriptorType 4 bInterfaceNumber 0 bAlternateSetting 0 bNumEndpoints 1 bInterfaceClass 9 Hub bInterfaceSubClass 0 [unknown] bInterfaceProtocol 0 Full speed (or root) hub iInterface 0 Endpoint Descriptor: bLength 7 bDescriptorType 5 bEndpointAddress 0x81 EP 1 IN bmAttributes 3 Transfer Type Interrupt Synch Type None Usage Type Data wMaxPacketSize 0x0004 1x 4 bytes bInterval 12 Hub Descriptor: bLength 9 bDescriptorType 41 nNbrPorts 4 wHubCharacteristic 0x000a No power switching (usb 1.0) Per-port overcurrent protection TT think time 8 FS bits bPwrOn2PwrGood 10 * 2 milli seconds bHubContrCurrent 0 milli Ampere DeviceRemovable 0x00 PortPwrCtrlMask 0xff Hub Port Status: Port 1: 0000.0100 power Port 2: 0000.0100 power Port 3: 0000.0100 power Port 4: 0000.0100 power can't get device qualifier: Resource temporarily unavailable can't get debug descriptor: Resource temporarily unavailable Device Status: 0x0001 Self Powered

lspci:

00:06.0 Communication controller: Red Hat, Inc. Virtio console Subsystem: Red Hat, Inc. Device 0003 Control: I/O+ Mem+ BusMaster+ SpecCycle- MemWINV- VGASnoop- ParErr- Stepping- SERR- FastB2B- DisINTx+ Status: Cap+ 66MHz- UDF- FastB2B- ParErr- DEVSEL=fast >TAbort- <TAbort- <MAbort- >SERR- <PERR- INTx- Latency: 0 Interrupt: pin A routed to IRQ 47 Region 0: I/O ports at 1080 [size=64] Region 1: Memory at 10043000 (32-bit, non-prefetchable) [size=4K] Region 4: Memory at 8000014000 (64-bit, prefetchable) [size=16K] Capabilities: <access denied> Kernel driver in use: virtio-pci

@mjwolf I don't think other fields are relevant. Configuration Descriptor refers to the internal transfer bus of the USB device and protocol description, there is no value in adding these.
There are for sure additional hub/filesystem fields that are related to mass storage devices, but these fields are already present under volume and can be used from there.

Here is a sample of an event

"device": { "product": { "id": "007A", "name": "USB 2.0 FD" }, "serial_number": "0416KK00000066840018", "type": "Disk File System", "vendor": { "id": "154B", "name": "PNY" } }, ... "volume": { "bus_type": "Usb", "device_name": "\\Device\\HarddiskVolume5", "file_system_type": "NTFS", "mount_name": "F:", "removable": true, "size": 16356593664, "writeable": true } ...

mjwolf · 2025-09-09T22:07:21Z

rfcs/text/0053-new-device-fields.md

+Stage 1: Provide a high-level description of example sources of data. This does not yet need to be a concrete example of a source document, but instead can simply describe a potential source (e.g. nginx access log). This will ultimately be fleshed out to include literal source examples in a future stage. The goal here is to identify practical sources for these fields in the real world. ~1-3 sentences or unordered list.
+-->
+
+* Elastic Defend


I think this could potentially be used by many other sources of peripheral device, so you could expand this to include other system software monitoring tools that might send device events

I don't really know any kind specific software that could send device events, but I would assume that any Data loss prevention software does monitor external devices and read/writes to them.
Compliance and auditing software might also leverage those to ensure data integrity

mjwolf · 2025-09-09T22:14:57Z

rfcs/text/0053-new-device-fields.md

+device.vendor.id | keyword | VendorID of the device. Example: "0x1234". See [1][2]
+device.product.name | keyword | Product name of the device. Example: "Extreme V2 SSD"
+device.product.id | keyword | ProductID Example: "0xABCD".  See [1][2]
+device.type | keyword | Device type classification. Example: "Storage Device", "HID", "Audio". Ideally one of the USB defined class codes. See [3]


Are there other fields that you think would be good to also add? Looking at lsusb and lspci output, there are additional fields available for many devices. Would any of these be useful to have?

For example, lsusb:

Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub Device Descriptor: bLength 18 bDescriptorType 1 bcdUSB 2.00 bDeviceClass 9 Hub bDeviceSubClass 0 [unknown] bDeviceProtocol 1 Single TT bMaxPacketSize0 64 idVendor 0x1d6b Linux Foundation idProduct 0x0002 2.0 root hub bcdDevice 6.15 iManufacturer 3 Linux 6.15.6-100.fc41.aarch64 xhci-hcd iProduct 2 xHCI Host Controller iSerial 1 0000:00:04.0 bNumConfigurations 1 Configuration Descriptor: bLength 9 bDescriptorType 2 wTotalLength 0x0019 bNumInterfaces 1 bConfigurationValue 1 iConfiguration 0 bmAttributes 0xe0 Self Powered Remote Wakeup MaxPower 0mA Interface Descriptor: bLength 9 bDescriptorType 4 bInterfaceNumber 0 bAlternateSetting 0 bNumEndpoints 1 bInterfaceClass 9 Hub bInterfaceSubClass 0 [unknown] bInterfaceProtocol 0 Full speed (or root) hub iInterface 0 Endpoint Descriptor: bLength 7 bDescriptorType 5 bEndpointAddress 0x81 EP 1 IN bmAttributes 3 Transfer Type Interrupt Synch Type None Usage Type Data wMaxPacketSize 0x0004 1x 4 bytes bInterval 12 Hub Descriptor: bLength 9 bDescriptorType 41 nNbrPorts 4 wHubCharacteristic 0x000a No power switching (usb 1.0) Per-port overcurrent protection TT think time 8 FS bits bPwrOn2PwrGood 10 * 2 milli seconds bHubContrCurrent 0 milli Ampere DeviceRemovable 0x00 PortPwrCtrlMask 0xff Hub Port Status: Port 1: 0000.0100 power Port 2: 0000.0100 power Port 3: 0000.0100 power Port 4: 0000.0100 power can't get device qualifier: Resource temporarily unavailable can't get debug descriptor: Resource temporarily unavailable Device Status: 0x0001 Self Powered

lspci:

00:06.0 Communication controller: Red Hat, Inc. Virtio console Subsystem: Red Hat, Inc. Device 0003 Control: I/O+ Mem+ BusMaster+ SpecCycle- MemWINV- VGASnoop- ParErr- Stepping- SERR- FastB2B- DisINTx+ Status: Cap+ 66MHz- UDF- FastB2B- ParErr- DEVSEL=fast >TAbort- <TAbort- <MAbort- >SERR- <PERR- INTx- Latency: 0 Interrupt: pin A routed to IRQ 47 Region 0: I/O ports at 1080 [size=64] Region 1: Memory at 10043000 (32-bit, non-prefetchable) [size=4K] Region 4: Memory at 8000014000 (64-bit, prefetchable) [size=16K] Capabilities: <access denied> Kernel driver in use: virtio-pci

trisch-me · 2025-09-12T10:05:32Z

@ricardo-estc you can proceed with next stage and create a final PR to update real yaml files

Awaits elastic/ecs#2521 Updated trusted device field mappings and added new field options. Changed: **Device ID** to use `device.serial_number`, **Manufacturer** to `device.vendor.name`, **Product ID** to `device.product.id`, and added: **Device Type** (`device.type`), **Manufacturer ID** (`device.vendor.id`) **Product Name** (`device.product.name`) with alphabetical sorting and Windows-only Username field support. Q: should fields be removed that are not part of this list? https://github.com/elastic/ecs/pull/2521/files/e22e09f1f5614987779c9ce27568108d836a8781#diff-def0f07e87941747d6f2f97751729e80661451188c943007cadf0946ab8bc509R31-R35 --------- Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com> Co-authored-by: Gergő Ábrahám <gergo.abraham@elastic.co>

ricardo-estc requested a review from a team as a code owner September 3, 2025 10:01

ricardo-estc mentioned this pull request Sep 3, 2025

New event.category for device events #2522

Closed

ricardo-estc force-pushed the endpoint_device_control_fields branch from 33117db to e740734 Compare September 4, 2025 06:13

ricardo-estc added 3 commits September 4, 2025 09:21

Add new proposal

23bca2c

PR

6006629

fix

b5f0dfb

ricardo-estc force-pushed the endpoint_device_control_fields branch from e740734 to b5f0dfb Compare September 4, 2025 06:22

trisch-me reviewed Sep 5, 2025

View reviewed changes

trisch-me requested changes Sep 5, 2025

View reviewed changes

ricardo-estc added 4 commits September 5, 2025 15:09

addressing feedback

addd499

author fix

169f059

links

1deeddb

new link

e22e09f

ricardo-estc requested a review from trisch-me September 5, 2025 12:15

trisch-me reviewed Sep 8, 2025

View reviewed changes

szwarckonrad mentioned this pull request Sep 8, 2025

[EDR Workflows][Device Control] Final fields and values elastic/kibana#234139

Merged

mjwolf reviewed Sep 9, 2025

View reviewed changes

mjwolf approved these changes Sep 11, 2025

View reviewed changes

Merge branch 'main' into endpoint_device_control_fields

6f9de2d

trisch-me approved these changes Sep 12, 2025

View reviewed changes

trisch-me merged commit 561a89d into main Sep 12, 2025
7 checks passed

ricardo-estc mentioned this pull request Sep 12, 2025

[RFC 0053][Update] Stage2: New device fields #2530

Merged


		The following are the people that consulted on the contents of this RFC.

		* TBD \| author


		<!-- Insert any links appropriate to this RFC in this section. -->

		* https://www.usb.org/defined-class-codes

[RFC] New device fields - Stage 0 #2521

[RFC] New device fields - Stage 0 #2521

Uh oh!

Conversation

ricardo-estc commented Sep 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

1. What does this PR do?

2. Which ECS fields are affected/introduced?

3. Why is this change necessary?

4. Have you added/updated documentation?

5. Have you built ECS and committed any newly generated files?

6. Have you run the ECS validation tests locally?

7. Anything else for the reviewers?

Commit Message

Uh oh!

cla-checker-service bot commented Sep 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Sep 3, 2025

🤖 GitHub comments

Uh oh!

ricardo-estc commented Sep 3, 2025

Uh oh!

kgeller commented Sep 3, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

trisch-me left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

trisch-me commented Sep 12, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

ricardo-estc commented Sep 3, 2025 •

edited

Loading

cla-checker-service bot commented Sep 3, 2025 •

edited

Loading