3.1.8.5. Agent Payloads

Once the Agent is properly installed and established communication with the ON Core, it will start sending messages to the ON Core. These messages are called payloads and they are compressed and stored in the database. You can visualize these messages in the Agent payload section:

The API retrieves the last authentication status on each Agent response. It also sends, saves and displays the user ID of the person who performed the authentication.

When you enter text in the Search field, it will search for that specific text within the JSON file. This feature allows you to filter by software, hostname, IP addresses, processes, and any other data contained in an agent’s JSON.

3.1.8.5.1. Filters

The filter capability provides a way to narrow down your payloads based on specific criteria within each category:

../../../_images/agent_payload_filters.png

You can filter the payloads based on Hostname, MAC, IP, Agent version, OS, User, Process type and Date.

For each filter type, you can apply different conditions according to the parameters you are applying. For example, contains, less than, starts with, is not, etc.

Refer to the table on Process type for a comprehensive list of processes. For optimal results, use the “contains” filter condition along with any keyword associated with the desired process. For example: “Contains + scan”.

The Agent payload section displays the Hostname, the MAC, the IP, the Agent version (operating system), the User, and the Date of every corresponding payload. Apart from that, it displays the following information:

3.1.8.5.2. Process type

There are various Process types for Agent payloads, each represented by an icon. Hover over the icons to see their meanings. Here are the available Process types:

Note

The “Stop agent service” process type displays payloads for Windows and Linux operating systems, but not for MacOS.

Since the payloads are triggered by events, you may occasionally notice a wait time between payload retries to reduce server overload.

3.1.8.5.3. Data (Payload types)

There are different Payload types and they are also represented by icons. The following table indicate their meaning:

3.1.8.5.4. View payloads

Administrators can see the content of the payload by clicking on the View payload viewpayload_img icon.

The payloads are organized in different sections to facilitate their readability.

In the ACCOUNT INFORMATION module, we can find the key name and the key value.

In the OPENNAC DATA module, we can find the identifier, the timestamp, the data type, the platform, the agent version, the event, the IP used to send the payload, if the service is stopped, if the service is installed, if the system is updated, if there are script modifications, and if PowerShell is disabled.

In the PAYLOAD PROCESSING TIME module, we can find the payloads process ID and the start and end time of the payload.

In the TRIGGER TYPE module, we can find the number corresponding to the trigger type.

In the TRIGGER DATE AND TIME module, we can find the date and time the trigger is finished.

In the HARDWARE module, we can find the system architecture, the name of the system where the agent is, the OS name, the OS version, the OS VM, the OS volume, the serial number, the hardware unique identifier, and if the device is using random MAC. If the Random mac switch is set to true, the HDT_MACRANDOM tag is added to the device.

Note

If the ON Agent is soluble and is not executed as sudo, the machine UUID and OS_VM flags won’t be returned in the Hardware section.

In the CERTIFICATES module, we can find a list of the certificates found on the host. We can find the end date, the issuer, the start date, and the subject from each certificate in the list.

In the ESTABLISHED CONNECTIONS module we can find a list of the host connections: the family number, the local address, the local port, the process ID, the protocol, the remote address, the remote port, and the state from each connection in the list.

In the NETWORKS module, we can find a list of the interfaces of the host machine. We can find the description, if the DHCP is enabled, the default gateway, the interface type, the IP of the interface, the MAC address, the name, the status, if it has a random MAC, and the type from each interface in the list.

In the OPEN PORTS module we can find a list of all the open ports of the host. We can find the family number, the local address, the local port, the process ID, the protocol, the remote address, the remote port and the state from each open port in the list.

In the SECURITY CENTER module for Windows devices, we can see a list of the security instances running on the host, like firewalls and antivirus. We can find the category, the company, if it is enabled, the product, if the security center is enabled, and if it is up to date from each security center in the list:

In the case of macOS devices, the SECURITY CENTER module displays the following columns:

In the USER ACTIVE module, we can see a list of the active users running on the host. We can find the domain and the name of the active user. When an OSQuery fails, this field will display the following error message: “A problem occurred when obtaining information about this entity”.

../../../_images/agent_active_admin_users.png

The ACTIVE ADMIN USERS section will display the Group name and name of the active admin user found in the query.

In the SCRIPT EXECUTION RESULTS module, we can find the corresponding script executing in the host, the result, the start time and end time. These scripts are configured in the ON Agent > Agent scripts section. The SCRIPT MODIFICATIONS module displays the test create dir field.

../../../_images/agent_payload_recover.png

In the RECOVER module, you will see the recovered payloads displayed with their timestamp. These payloads will be sent in the event of a loss of connectivity with the server.

../../../_images/agent_payload_iptables.png

The IPTABLES module provides details about the iptables configuration, facilitating analysis of network traffic filtering.

The ARP module displays the IP address, the interface, the MAC address, and ARP entries.

The WIFI module displays in its wether the WiFi is connectable, the interface GUID, the connection status, security, security activated, signal quality, and SSID.

../../../_images/agent_payload_bluetooth.png

The BLUETOOTH module displays the name of the device connected via bluetooth, the device ID, its connection status, type, serial number and address.

The USB Device module displays the ID of the device connected via USB, the hardware ID, and the manufacturer.

../../../_images/agent_payload_scanned_networks.png

The SCANNED NETWORKS section includes the display of broadcast address, netmask, and IP address information, providing enhanced network details.

../../../_images/agent_payload_bitlocker.png

In the BITLOCKER query, you can see the details of this feature when it is enabled in Windows operating systems. It ill add tags for each drive individually (ISS_BITLOCKER_DRIVE_C, NCS_BITLOCKER_DRIVE_D) and global tags for the drivers set (ISS_BITLOCKER, NCS_BITLOCKER). The table displays the following fields:

Conversion status: The bitlocker conversion status of the drive.
Device ID:ID of the encrypted drive.
Drive letter: Drive letter of the encrypted drive.
Encryption method: The encryption type of the device.
Lock status: The accessibility status of the drive from Windows.
Percentage encrypted: The percentage of the driver that is encrypted.
Persistent volume ID: Persistent ID of the device.
Protection status: The bitlocker protection status of the device.
Version: The FVE metadata version of the drive.

../../../_images/agent_payload_firefox.png

The FIREFOX EXTENSIONS section displays if the extension is currently active, its ID, the installation URL, the name of the extension, its path, its publisher, the username, user ID, version and description.

../../../_images/agent_payload_chrome.png

The CHROME EXTENSIONS section displays if the extension ID and name, its path, the username, user ID, version and description.

../../../_images/agent_payload_explorer.png

The INTERNET EXPLORER EXTENSIONS section displays if the extension ID and name, its path and version.

../../../_images/agent_payload_system.png

The AGENT OAUTH WIREGUARD CONFIG module, displaying key parameters such as creation details, client information, and authentication settings like ClientID, ClientSecret, RedirectURI, and Scope.

The SYSTEM UPDATES section displays installed updates with a description and date of the event.

../../../_images/agent_payload_installed_system_updates.png

The INSTALLED SYSTEM UPDATES section will report only Windows operating systems updates. The table displays the update ID, title and description, the release date, its client applicationID.

../../../_images/agent_payload_pending.png

The PENDING SYSTEM UPDATES section will report only Windows operating systems updates. The table displays pending uninstalled updates awaiting execution. For example, Security Intelligence Update for Microsoft Defender Antivirus.

Note

When the Windows Update is disabled, the SYSTEM_UPDATES_ACTIVE field in the OPENNAC DATA section will return false, while the INSTALLED_SYSTEM_UPDATED and PENDING_SYSTEM_UPDATES fields will be set as “”null” making it impossible to accurately determine the machine’s update status.

Regarding System Update tags, note that drivers may be present in the update payload but are usually ignored for tagging purposes. Understand three possible scenarios:

Disabled Updates

Scenario: When System Updates are disabled, the system enters a state where updates are not actively managed or applied.
Tags: The ISS_SYSTEM_UPDATES_DISABLED tag will be added to indicate that System Updates are disabled.

Enabled Updates & Not Updated

Scenario: In cases where System Updates are enabled, but some updates are pending installation or the system is not yet updated.
Tags: The ISS_SYSTEM_UPDATES_ENABLED tag indicates that System Updates are enabled. Additionally, the ISS_WINDOWS_PENDING_UPDATES tag is added, and UIP_KBxx tags are included for each pending update. Note that drivers may be present in the update payload but are usually ignored for tagging purposes.

Enabled Updates & Updated

Scenario: When System Updates are enabled and the system is up-to-date with all available updates.
Tags:
- ISS_WINDOWS_PENDING_UPDATES will be added.
- UIS_AMOUNT_UPDATES_PENDING_X will be added with the number of pending updates.
- The UIS_OLDEST_UPDATE_PENDING_X tag could be added if it is possible to determine the oldest update (in days).
- The UIS_SEVERITY_UPDATES_PENDING_UNKNOWN tag will be added if it is not possible to determine the severity of the updates.
- The UIS_SEVERITY_UPDATES_PENDING_XXXXX tag will be added if it is possible to determine the severity of the updates (CRITICAL, IMPORTANT, MODERATE, or LOW)
- UIP_KBxx tags will be added for each pending update.

Unknown

Scenario: When the Agent cannot obtain information, either because the device does not have internet access or access to the corresponding Windows servers, or because the antivirus has blocked the query, etc.
Tags: The ISS_SYSTEM_UPDATES_UNKNOWN tag will be added indicating that the Agent could not obtain information.

By clicking on View Payload at the upper-right corner of the Agent Payload window, it will display the following view:

Note

All invalid payloads will be stored in the file located at /usr/share/opennac/api/data/payloads-unprocessed/.

3.1.8.5.5. Download payload

The Download Payload downloadpayload_img icon, located next to the View Payload icon, allows you to download the payload file.

3.1.8.5.6. View tags simulator

You can perform a tag simulation from the View tags simulator tags_sim_img icon.

Consult the OpenNAC Agent section for a comprehensive list of tags generated from the data collected by the Agent.

3.1.8.5.7. View server response

The View server response server_response_img icon, allows you to see the Agent server response:

../../../_images/agent_payload_response.png

In the GENERAL CONFIGURATION module, you can find the periodicity of the script execution in seconds, the periodicity of the full scan in seconds, the waiting time before a script execution before initialization, the waiting time ignoring sc events before windows initialization, the interval between user session events, the visibility, the debug mode, the secure mode, the number of logs sent to the server, the max log file size in MB, the max number of old logs saved, if the event product changed, if the event firewall changed, if the security center changed, if the network changed, if the user session changed, if there is an event when closing and if there is an event when uninstalling.

../../../_images/agent_payload_response1.png

In the CONNECTION PROPERTIES module, you can find the connection protocol, the connection endpoint, the endpoint to discover the IP that the agent uses to make requests, the connection IP or domain, and the taf identifier.

In the UI CONFIGURATION module, you can find if the UI is enabled, if the debug mode is enabled, if the client authentication is enabled, , if the SAML for WireGuard is enabled, if an URL is going to be open when connecting using WireGuard, if Wireguard is enabled, the UI language, and MUI.

../../../_images/agent_payload_response2.png

In the AGENT QUERY module, you can find details about each query such as its type, key, impersonation requirements, processors and script executed.

../../../_images/agent_payload_response2a.png

There are modules for MINIMUM VERSION REQUIRED and AGENT HASH QUERY display.

../../../_images/agent_payload_response2b.png

In the AGENT OAUTH2 WIREGUARD CONFIG module, you will find information about the OAuth2authentication configuration within WireGuard such as timestamp, id, realm, response time, client id, client secret, scope, redirect URI and timeout.

../../../_images/agent_payload_response2c.png

The AGENT VPN WIREGUARD FARM module, displays the farm to which the VPN connection belongs.

../../../_images/agent_payload_response2d.png

In the Wireguard CONFIGURATIONS module, you can find the configuration of the Wireguard server.

../../../_images/agent_payload_response2e.png

In the AGENT OSQUERIES module, you will find details you can find details about each OSQuery such as the entity, available platforms, available processors, SQL query, and impersonation requirements.

../../../_images/agent_payload_response3.png

In the POLICY module, you can find the policy into which the host has matched.

In the VLAN module, you can find the VLAN name and the VLAN ID.

The SESSIONID displays the MAC address and in the AGENT USER AUTHENTICATED section, you can see if the user has been authenticated.

In the RECOVER module, you will see the recovered payloads displayed with their timestamp. These payloads will be sent in the event of a loss of connectivity with the server.

3.1.8.5.8. View logs

By clicking on the View logs view_logs_img icon, it will display the Agent logs.

3.1.8.5.9. Agent service stopped

The Agent service stopped agent_stopped_img icon will be displayed whenever the service is interrupted. It will display payloads for Windows and Linux operating systems, but not for MacOS.

3.1.8.5.10. View scripts

By clicking on the View scripts view_scripts_img icon, it will display the scripts execution results.

../../../_images/agent_payload_scripts.png

3.1.8.5.11. Update status

By clicking on the Update status update_status_img icon, it will display a payload with the Agent update result.

../../../_images/payload_agent_update.png

The Agent update result might display:

Success
Unknown Error
Failed downloading new agent version
Exit code

You can also call the agentpayload using the API key.

See more details about the data exchange process in the Agent Doc section, which showcases examples of data extracted from devices by the Agent and transmitted between OpenNAC Enterprise and the Agent.