Skip to content

Agent Metadata Controls

Choose which optional fields a commercial Windows, Linux, FreeBSD, or macOS agent collects and reports when generating its payload, then adjust them while it runs. These settings affect collection and reporting; they do not erase metadata already stored by the server.

Network interface metadata

Tuoni groups network addresses by interface. Default Windows agents report MAC and IPv4 data for active interfaces. Commercial agents additionally support optional IPv6 addresses and interface names across Windows, Linux, FreeBSD, and macOS.

The REST metadata field netInterfaces contains records with name, macAddress, ipv4Addresses, and ipv6Addresses. A name or MAC address can be absent, and address arrays can be empty. Interface names are limited to 16 Unicode code points.

Payload-generation settings

The commercial payload configuration accepts a metadataFields object. With the standard templates, MAC and IPv4 collection are enabled; IPv6 and interface names require opt-in.

Settings Default when a metadataFields object is supplied
username, hostname, workingDirectory true
processName, processId, processArchitecture true
operatingSystem, osMajorVersion, osMinorVersion, operatingSystemArchitecture true
ansiCodePage, integrity true
macAddress, ipv4Addresses true
ipv6Addresses, interfaceName false

For example, add this object to a commercial payload configuration to include IPv6 addresses and interface names:

1
2
3
4
5
6
{
  "metadataFields": {
    "ipv6Addresses": true,
    "interfaceName": true
  }
}

Omitting metadataFields preserves the template's embedded settings, including those in a custom template. Fields that do not apply to a platform do not create information that the platform cannot report.

Runtime commands

Command Purpose Parameters
metadata-fields-report Report supported and enabled metadata fields None
metadata-fields-enable Enable selected optional fields Nonempty selectors array
metadata-fields-disable Disable selected optional fields Nonempty selectors array

Run metadata-fields-report first to inspect support on the connected agent. Selectors include USERNAME, PROCESS_NAME, PROCESS_ID, WORKING_DIRECTORY, OPERATING_SYSTEM, OS_MAJOR_VERSION, OS_MINOR_VERSION, HOSTNAME, PROCESS_ARCHITECTURE, OS_ARCHITECTURE, ANSI_CODE_PAGE, and INTEGRITY.

Network selectors use NETWORK_INTERFACES followed by : and +-joined components: MAC, IPV4, IPV6, and NAME.

1
2
metadata-fields-report
metadata-fields-enable --selectors NETWORK_INTERFACES:IPV6+NAME

The equivalent configuration for the enable command is:

1
2
3
{
  "selectors": ["NETWORK_INTERFACES:IPV6+NAME"]
}

Required identity, encryption, and capability fields cannot be disabled. Runtime changes apply to the running agent and reset to the generated payload's settings after a restart. Support also depends on the connected agent's version and reported capabilities; default Windows agents do not expose these controls.