Report custom inventory attributes

  5 minute read  

You may have a scenario where the standard inventory data collected by the TrustEdge agent isn’t enough. Maybe you need to track a device’s GPS location, hardware model, or custom serial number. That’s where custom inventory attributes come in.

With custom attributes, you can define and report additional device data to DigiCert® Device Trust Manager. These attributes either extend the default data collected by TrustEdge, or override the existing values.

In this tutorial, you’ll learn how to configure custom attributes on a device using TrustEdge, so that the data is automatically sent to Device Trust Manager.

Before you begin

Ensure your device is registered with Device Trust Manager. If not, follow the steps mentioned in the Device creator guide. The Device creator guide walks you through:

  • Creating your device in Device Trust Manager
  • Securely register the device, so it can connect and exchange messages with the platform.

Once registration is complete, you’ll be ready to configure the attributes.json file included with the TrustEdge agent GitHub repository package. This file also has the required attributes to collect the data.

You can view the default attributes automatically collected by the TrustEdge agent on Ubuntu 22.04 and later on Device Trust Manager by navigating to Device management > Devices > select a device > Attributes.

You can begin reporting device-specific attributes as explained below.

How it works

Custom attributes are pushed from TrustEdge to the Device Trust Manager and can be triggered manually using the TrustEdge command.

  • You define the custom keys and values in an attributes.json file.
  • TrustEdge reads the values from either environment variables or executable scripts, or programs.
  • You can change the reporting interval by updating the attributes_refresh_hours settings in /etc/digicert/trustedge.json.

Get the sample attributes.json file

Download the sample configuration file provided by DigiCert:

sudo wget -P /etc/digicert/conf/ https://raw.githubusercontent.com/digicert/trustedge/master/examples/samples/attributes.json

This command saves the file to the default TrustEdge agent keystore at /etc/digicert/keystore/conf

Understand the two reporting methods

In the attributes.json file, you can define custom attributes in one of two ways:

  • ENV: Use this method when you want TrustEdge to read a value directly from an OS environment variable specified in the variable_name field.
  • Program: Use this method when you want TrustEdge to launch the program specified by the path field. By default, the output of the program is used as the value. If the output_format is specified, then an array of attributes must be specified. The program is expected to output the values in the specified format.

Report custom attributes through environment variables

The simplest way to report a device’s custom attributes to Device Trust Manager on a Linux-based system is by using environment variables.

  1. Define custom attributes Ensure your custom attributes file is saved at /etc/digicert/conf/attributes.json In this file, list the attributes you want the system to report. For example, to report a device’s serial number, include a key like SERIAL_NUMBER in the JSON.
  2. Set environment variables Define the corresponding environment variables in your Linux system. These can be configured either system-wide (recommended for consistency) or under a specific user account that belongs to the TrustEdgegroup.
    • Set a system-wide variable by running the following command: sudo nano /etc/environment
    • Add your attribute definition. For example: SERIAL_NUMBER=SN1234562025
    • Run the following command: sudo trustedge agent
    • Save and close this file. Alterntively, for testing, attribute value can be pushed directly from the CLI. Ensure the same environment variable is captured in /etc/digicert/conf/attributes.json file. Run the following command:
    sudo SERIAL_NUMBER=SN123456_2025 trustedge agent
  3. Verify the environment variable in Device Trust Manager The new attribute appears in the Attributes section of Device Trust Manager. For more advanced usage of attributes, see Attributes.

Start by saving your custom attributes file at /etc/digicert/conf/attributes.json. Once the file is in place, define the specific attributes you want to report within that JSON file.

For example, if you want to report the SERIAL_NUMBER, ensure:

  • The SERIAL_NUMBER key is defined in the /etc/digicert/conf/attributes.json file.
  • A corresponding environment variable exists in the Linux system.

These environment variables can be set system-wide or configured under a user account that belongs to the TrustEdge group.

Report custom attributes programmatically

In addition to using environment variables, you can report device attributes to Device Trust Manager by executing scripts that return attribute values. This method gives you flexibility to generate values dynamically at runtime.

  1. Configure the attributes.json file
  2. Make the script executable
    sudo chmod +x /usr/local/bin/serial_number.sh
  3. Report the attribute to Device Trust Manager
    sudo trustedge agent

Examples of various attribute reports

For more complex use cases—where you need to report multiple attributes to Device Trust Manager, you can use a script that outputs key-value pairs.

You can download a sample script by running the following command. It’ll be saved to /usr/local/bin/

sudo wget -P /usr/local/bin/ https://raw.githubusercontent.com/digicert/trustedge/refs/heads/master/examples/samples/attributes/get_attributes.sh

The file is saved at /usr/local/bin/get_attributes.sh. You can make it executable by running the following command:

sudo chmod +x /usr/local/bin/get_attributes.sh

Report hardware model:

Run the following command:

sudo wget -P /usr/local/bin/ https://raw.githubusercontent.com/digicert/trustedge/refs/heads/master/examples/samples/attributes/hardware_model.sh

Make the script executable

sudo chmod +x /usr/local/bin/hardware_model.sh

Upon successful execution, the following command attributes are reported to Device Trust Manager.

sudo trustedge agent

Debug and verify custom attributes

Run the following command

sudo trustedge agent
  • Check the logs to confirm the agent is reading from /etc/digicert/conf/attributes.json.
  • Go to the Attributes section in Device Trust Manager to confirm the values have been reported.
  • Upon success, the system generates a file called metrics.pb in /etc/digicert/conf/.
  • Decode metrics.pb
    • Install the protobuf compiler for Ubuntu or Debian by running the following commands:
      sudo apt update
sudo apt install protobuf-compiler
    • To decode metrics.pb, run the following command:
      protoc --decode_raw < metrics.pb
    • Similarly, to read the desired attributes (key-value pairs), run the following command:
      protoc --decode_raw < desired_attributes.pb

Sample attributes.json

{
    "attributes": [
        {
            "attribute_name": "serial_number",
            "attribute_value": {
                "type": "ENV",
                "variable_name": "SERIAL_NUMBER"
            }
        },
        {
            "attribute_name": "serial_number",
            "attribute_value": {
                "type": "program",
                "path": "/usr/local/bin/serial_number.sh"
            }
        },
        {
            "attribute_names": [
                "location",
                "ip_address"
            ],
            "attribute_value": {
                "type": "program",
                "path": "/usr/local/bin/get_attributes.sh",
                "argument": "location ip_address",
                "output_format": "JSON"
            }
        },
        {
            "attribute_names": [
                "hardware_model"
            ],
            "attribute_value": {
                "type": "program",
                "path": "<path-to-hardware_model.sh>",
                "output_format": "JSON"
            }
        }
    ]
}