DEX check definitions for Windows

  • Release version: Washingtondc
  • Updated February 1, 2024
  • 9 minutes to read

    • Check definitions for Windows are predetermined sets of rules and criteria that assess the performance, security, and compliance of Windows devices. These checks can cover various aspects such as CPU usage, memory usage, IO usage, firewall status, network tests, network bytes, and logged-in users.

    To fetch the complete playbook data for a Windows device, the Agent Client Collector (ACC) must run as a local system account. For more details on how to set up the ACC service as a local system account, see Run Agent Client Collector as local system account.

    Note:
    You have the ability to configure the check definitions and associated retrievable data. Some of the listed check definitions may retrieve data that contains or is considered personal information.

    Check definitions — Application (Metrics)

    DEX offers the following check definitions that are accessible solely when the application is running, with the exception of os.win.check-app-crash-rate and os.win.check-app-last-access-time check definitions, which are accessible even when the application is not running. In the check definition parameters:
    • appName = application name. Example, Zoom.
    • appSysId= sys id of the application.
    • primaryProcess = list of primary process for the application separated by a pipe symbol (|). The first process which exists on the endpoint device will be given priority. Example1: chrome.exe. Example 2: teams.exe|msteams.exe.
      Note:
      If the primary process for the Teams application in Windows 10 is teams.exe, while in Windows 11, it is msteams.exe, then when determining priority based on process availability on the endpoint device, the process that is present first on the endpoint device is given precedence.
    • secondaryProcesses = list of secondary processes for the application separated by a pipe symbol (|). Example, cpthost.exe|cptservice.exe.
    Check definition name Check definition parameters Description
    os.win.check-app-cpu-usage
    • --appName=<application name>
    • --primaryProcess=<primary process name>
    • --secondaryProcesses=<list of secondary processes separated by a pipe symbol>
    • --appSysId=<sys id of the application>
    		 Checks the amount of CPU resources being used by the application.
    os.win.check-app-memory-usage
    • --appName=<application name>
    • --primaryProcess=<primary process name>
    • --secondaryProcesses=<list of secondary processes separated by a pipe symbol>
    • --appSysId=<sys id of the application>
    		 Checks the amount of memory used by the application.
    os.win.check-app-last-access-time
    • --appName=<application name>
    • --primaryProcess=<primary process name>
    • --secondaryProcesses=<list of secondary processes separated by a pipe symbol>
    • --appSysId=<sys id of the application>
    		 Checks the most recent time when the application was executed or run.
    Note:
    • This check definition doesn't require the application to be in a running state.
    • If the application hasn't been run within the last 7 days, the last access time is empty.
    • If the application's process path changes within 7 days (which can occur during app updates), the last access time is empty until you run the app again.
    • To modify the 7-day retention policy, you can change the registry path in the following way:
      • Registry Key: "HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\BAM"
      • Registry Name: "UserSettingsLifetimeMs"
      • Registry Type: REG_DWORD (32-bit value)
      • Registry Value: Duration in milliseconds
    os.win.check-app-last-updated
    • --appName=<application name>
    • --primaryProcess=<primary process name>
    • --secondaryProcesses=<list of secondary processes separated by a pipe symbol>
    • --appSysId=<sys id of the application>
    		 Checks the time and date of the latest application update installation.
    os.win.check-app-crash-rate
    • --appName=<application name>
    • --primaryProcess=<primary process name>
    • --secondaryProcesses=<list of secondary processes separated by a pipe symbol>
    • --appSysId=<sys id of the application>

    Retrieves crash rate of the application.

    This check definition supports:
    • Applications that emit a window app crash event (event id = 1000) on crashing such as Microsoft OneDrive, Microsoft Teams, Microsoft Excel, Microsoft OneNote, Microsoft PowerPoint, Microsoft Outlook, Microsoft Word.
    • Other supported applications include Zoom and Slack. Crash rate is fetched based on crash logs inside the respective app folders. These crash rates are susceptible to changes in application’s log path in future versions of these apps
    Note:
    This check definition doesn't require the application to be running.
    os.win.check-app-uptime
    • --appName=<application name>
    • --primaryProcess=<primary process name>
    • --secondaryProcesses=<list of secondary processes separated by a pipe symbol>
    • --appSysId=<sys id of the application>
    		 Checks the uptime of the given application.
    os.win.check-app-incoming-network-bytes
    • --appName=<application name>
    • --primaryProcess=<primary process name>
    • --secondaryProcesses=<list of secondary processes separated by a pipe symbol>
    • --appSysId=<sys id of the application>
    • sleep_time =<Duration of time from now for which you need to calculate the average incoming network byte/sec>
    		 Retrieves the incoming network bytes of an application for IPv4 and IPv6 networks.
    os.win.check-app-outgoing-network-bytes
    • --appName=<application name>
    • --primaryProcess=<primary process name>
    • --secondaryProcesses=<list of secondary processes separated by a pipe symbol>
    • --appSysId=<sys id of the application>
    • sleep_time =<Duration of time from now for which you need to calculate the average incoming network byte/sec>
    		 Retrieves the outgoing network bytes of an application for IPv4 and IPv6 networks.
    os.win.check-app-domain-network-details
    • --appName=<application name>
    • --primaryProcess=<primary process name>
    • --secondaryProcesses=<list of secondary processes separated by a pipe symbol>
    • --appSysId=<sys id of the application>
    • domain=<Domain of the application>
    		 Retrieves the network latency, packet loss, and jitter for installed application domain.
    os.win.check-app-domain-network-route-details
    • --appName=<application name>
    • --primaryProcess=<primary process name>
    • --secondaryProcesses=<list of secondary processes separated by a pipe symbol>
    • --appSysId=<sys id of the application>
    • domain=<Domain of the application>
    		 Retrieves the complete network route details for application domain.
    os.win.check-app-sccm N/A Fetches application specific metrics for the App - Microsoft System Center Configuration Manager.

    Check definitions — Device (Metrics)

    DEX provides the following types of check definitions for device.
    Check definition name Description
    os.win.check-system-cpu-usage Checks the current CPU utilization.
    os.win.check-system-cpu-details Retrieves the CPU id, CPU name, number of physical and logical cores, and architecture information.
    os.win.check-system-memory-usage Checks the current system memory utilization.
    os.win.check-system-last-access-time Checks the last time the current device was accessed.
    Note:
    This check definition works on locked and unlocked devices. The first time this check definition runs, the events are captured and an error message is produced due to no data.
    os.win.check-system-uptime Checks the time elapsed since the last boot of the system.
    os.win.check-system-disk-io-usage-read Retrieves disk bytes read per second.
    os.win.check-system-disk-io-usage-write Retrieves disk bytes written according to second.
    os.win.check-system-energy-consumption Retrieves the energy consumption values for CPU, SoC, display, disk, network, MBB, EMI, other, total, and loss of a Windows device in milliwatt-hours.
    Note:
    This check definition isn't compatible with virtual machines that don't have energy sensors.

    Unlike other check definitions that retrieve latest data, this check definition retrieves the sum of last 5 minutes of data.
    os.win.check-system-time Checks the current time in Coordinated Universal Time (UTC) using UNIX timestamp.
    os.win.check-system-power-plan Retrieves the name of the active power plan.
    os.win.check-system-os-details Retrieves the name, version, platform, architecture, and installation date of the operating system.
    os.win.check-system-device-crashes Retrieves details of different crashes on your device.
    Note:
    This check definition supports BSOD that emits system events with event ids = 41,1001.
    os.win.check-system-device-events Retrieves the details of events that occurred on the device during the specified time interval. Events for Windows include: last boot and logged-in users.
    os.win.check-system-disk-usage Retrieves the disk used space as a percentage of the total space.
    os.win.check-system-battery-details Retrieves battery-related data, including the remaining battery percentage, the designed voltage, the estimated run time, and the battery's maximum capacity.
    Note:
    • This check definition doesn't apply to virtual machines (VMs) or desktops because they don't have batteries.
    • If current capacity is greater than designed capacity, the battery is rounded off to 100%.
    os.win.check-system-network-details Retrieves the network details, including Ethernet, Wi-Fi, and other relevant information.
    os.win.check-system-logged-in-users Checks the login user ID of the users who are currently logged in to the device.
    os.win.check-system-power-consumption Retrieves the power consumption of the device in milliwatt.
    Note:
    This check definition is exclusively compatible with physical machines and doesn't support virtual machines (VMs).
    os.win.check-system-admin-users Retrieves all user accounts with local administrative privileges.
    os.win.check-system-bsod Retrieves the count, message, ID, level, and time of Blue Screen of Death (BSOD) occurrences.
    Note:
    This check definition supports BSOD that emits system events with event ids = 1001.
    os.win.check-system-firewall-enabled Checks if the operating system firewall is active and enabled.
    os.win.check-system-antimalware-details Retrieves the details of the anti-malware software on the device.
    os.win.check-system-reboot-details Retrieves the reboot duration in seconds and the last reboot timestamp (in UNIX epoch time).
    Note:
    The displayed values might not accurately reflect cases where system reboots were interrupted, such as during system updates, power loss, or manual intervention.
    os.win.check-system-os-setup-details Retrieves the approximate OS age for the device.
    os.win.check-system-network-adapter-details Retrieves the network adapter details for the device.
    os.win.check-system-network-connection-profiles Retrieves the network connection profile details for the device.
    Note:
    This check definition retrieves the network type which can be used to check the vpn status.
    os.win.check-system-compliance-details Retrieves the system’s compliance details. This includes the list of all configured apps and metric values that are non-compliant, and calculates a compliance rating based on that.
    Note:
    • This check definition provides the following details:
      • Condition for app to be said as compliant: Every process mentioned in primary process should be running.
      • Condition for metric value to be said as compliant: Value should be matching with the configured expected value.
    • The score is then calculated using this formula: Score = ( Complaint Application + Compliant metric value) / (Total Applications and metric value - Failed Ones) *100
    os.win.check-system-battery-charge-percentage Retrieves the battery charge percentage on windows device.
    Note:
    If current capacity is greater than designed capacity, the battery is rounded off to 100%.
    os.win.check-system-windows-registry Retrieves the windows registry data.
    os.win.check-system-memory-details Retrieves the system memory details like and virtual memory details.
    os.win.check-system-bios-details Retrieves the System Bios details.
    os.win.check-system-executables Fetches all the executables (*.exe) present on windows machine.

    Check definitions — Diagnostic Actions

    DEX provides the following types of check definitions for Diagnostic actions.
    Check definition name Check definition parameters Description
    Diagnostic action
    os.win.check-app-process-ids --process_name=<process name> Retrieves the Process IDs (PIDs) of both the parent and all the child processes associated with the application.
    os.win.check-dns-lookup-test --url=<url> Conducts a DNS lookup test on the provided URL and returns the IP address.
    os.win.check-http-test --url=<http url> Conducts an HTTP test on the provided URL and returns the status code of the response.
    os.win.check-ping-test --url=<url> Sends a ping request to the provided URL and returns the connectivity status, indicating whether the URL is currently reachable or not.
    os.win.check-process-cpu N/A Retrieves a list of all running processes along with their CPU usage percentage, CPU time, Process ID (PID), Parent Process ID (PPID), and name.
    os.win.check-process-memory N/A Retrieves a list of all running processes along with their memory usage in kilobytes (KB), Process ID (PID), Parent Process ID (PPID), and name.
    os.win.check-process-data N/A Retrieves the CPU usage, memory usage, and disk usage of all currently running processes.
    os.win.check-process-disk N/A Retrieves a list of all running processes along with their disk usage in Bytes, Process ID (PID), Parent Process ID (PPID), and name.
    os.win.check-rssi-value N/A Retrieves the Received Signal Strength Indicator (RSSI) value for the currently connected WiFi interface.

    RSSI indicates the signal strength between the wireless access point (AP) and the device, with higher RSSI values indicating stronger signal strength.

    Note:
    This check definition cannot be applied to a virtual machine.
    os.win.check-traceroute

    --url=<url>

    --max_hops = <default value is 30>

    --timeout = <default value is 4>

    		 Retrieves the IP address, domain name and round-trip time (RTT) for each network hop.

    Check definitions — Remedial Actions

    DEX provides the following types of check definitions for Remedial actions.
    Check definition name Check definition parameters Description
    os.win.action-kill-process

    --pid=<process id>

    OR

    --process_name=<list of comma separated executable file names>

    Note:
    The process ID takes priority over the application name.
    		 Terminates a running process or multiple processes specified by their Process ID (PID) or a list of executable (.exe) file names.
    os.win.action-restart-service --service_name=<service name> Restarts logged user services that take a service name as input to the system.
    os.win.action-flush-dns-cache N/A Flushes DNS cache on a Windows device.
    os.win.action-clear-browser-cache

    --auto_close = <true/false>

    Note:
    When auto close is enabled, while clearing the browser cache, the browser is closed and vice versa.

    --browsers = <List of comma separated browsers>

    		 Clears cache of the supported browsers such as Google Chrome,Mozilla Firefox, and Microsoft Edge.
    Note:
    Before executing this definition check, ensure that you save your browser work.