DEX check definitions for Mac

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

    • Check definitions for Mac are predetermined sets of rules and criteria that assess the performance, security, and compliance of Mac devices. These checks can cover various aspects such as CPU usage, memory usage, battery details, and firewall status.

    For macOS systems, to retrieve the entire data, include subsequent content to /etc/sudoers.

    For Agent version 3.4.0 or earlier:
    _servicenow ALL=NOPASSWD: SETENV: /Library/Caches/servicenow/agent-client-collector/osquery/bin/osqueryi *, /usr/bin/mdls, /usr/bin/log, /bin/kill, /bin/launchctl
Defaults:_servicenow !requiretty
    For Agent version 3.4.1 or later:
    _servicenow ALL=NOPASSWD: SETENV: /Library/Application\ Support/servicenow/agent-client-collector/cache/osquery/bin/osqueryi *, /usr/bin/mdls, /usr/bin/log, /bin/kill, /bin/launchctl
 Defaults:_servicenow !requiretty
    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.mac.check-app-version, os.mac.check-app-is-installed, os.mac.check-app-last-access-time, and os.mac.check-app-last-updated check definitions, which are accessible even when the application is not running. In the check definition parameters:
    • appName = application name. Example, Webex.
    • 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: Webex.app. Example 2: Microsoft Teams.app | Microsoft Teams Classic.app.
      Note:
      If the primary process for the Teams application is Microsoft Teams.app on one end-point device, while on another end-point device, it is Microsoft Teams classic.app, 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, Cisco WebEx Start.app | webexmtaV2.app.
    Check definition name Check definition parameters Description
    os.mac.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.mac.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 resources being used by the application.
    os.mac.check-app-listening-ports
    • --appName=<application name>
    • --primaryProcess=<primary process name>
    • --secondaryProcesses=<list of secondary processes separated by a pipe symbol>
    • --appSysId=<sys id of the application>
    		 Retrieves the port numbers that are open and through which incoming network traffic can reach the application.
    os.mac.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.
    Note:
    This check definition does not require the application to be in a running state.
    os.mac.check-app-version
    • --appName=<application name>
    • --primaryProcess=<primary process name>
    • --secondaryProcesses=<list of secondary processes separated by a pipe symbol>
    • --appSysId=<sys id of the application>
    		 Retrieves the version number of the application.
    Note:
    • This check definition does not require the application to be in a running state.
    • If an application does not have a version, the check definition returns the string "unversioned" for that application.
    os.mac.check-app-is-installed
    • --appName=<application name>
    • --primaryProcess=<primary process name>
    • --secondaryProcesses=<list of secondary processes separated by a pipe symbol>
    • --appSysId=<sys id of the application>
    		 Checks if the application is installed or not on the device.
    Note:
    This check definition does not require the application to be in a running state.
    os.mac.check-app-is-running
    • --appName=<application name>
    • --primaryProcess=<primary process name>
    • --secondaryProcesses=<list of secondary processes separated by a pipe symbol>
    • --appSysId=<sys id of the application>
    		 Checks whether the application is currently in a running state or not.
    os.mac.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.mac.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 does not require the application to be in a running state.
    • If the application has not been run by the user within the last 7 days, the last access time will be empty.
    os.mac.check-app-io-usage-read
    • --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 application's usage of Read I/O (Input/Output) operations.
    os.mac.check-app-io-usage-write
    • --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 application's usage of Write I/O (Input/Output) operations.
    os.mac.check-app-domain-network-latency
    • --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>
    		 Fetches network latency of the application domain.
    os.mac.check-app-crashes
    • --appName=<application name>
    • --primaryProcess=<primary process name>
    • --secondaryProcesses=<list of secondary processes separated by a pipe symbol>
    • --appSysId=<sys id of the application>
    		 Fetches number of crashes and crash details of the application.
    Check definition name Description
    os.mac.check-system-cpu-usage Checks the CPU utilization.
    os.mac.check-system-cpu-details Retrieves the CPU name, number of physical and logical cores, and architecture information.
    os.mac.check-system-memory-usage Checks system memory utilization.
    os.mac.check-system-last-access-time Checks the last time the current device was accessed.
    Note:
    This check definition works on locked and unlocked devices.
    os.mac.check-system-uptime Checks the amount of time elapsed since the system was last booted.
    os.mac.check-system-time Checks the current time in Coordinated Universal Time (UTC) using Unix timestamp.
    os.mac.check-system-device-crashes Retrieves details of different crashes on your device.
    Note:
    This check fetches Kernel Panics present in the device logs in the last five minutes.
    os.mac.check-system-device-details Retrieves the type, model, and serial number of the chassis.
    os.mac.check-system-device-events Retrieves the details of events that occurred on the device during the specified time interval. Events for Mac include: last boot, logged-in users, installed software, updated software, added users, and reset passwords.
    os.mac.check-system-disk-details Retrieves disk details such as total space, used space, and free space in bytes.
    os.mac.check-system-disk-io-usage-read Retrieves disk bytes read per second.
    os.mac.check-system-disk-io-usage-write Retrieves disk bytes written per second.
    os.mac.check-system-disk-usage Retrieves the disk used space as a percentage of the total space.
    os.mac.check-system-os-details Retrieves the name, version, platform, architecture, and installation date of the operating system.
    os.mac.check-system-net-bytes-incoming Retrieves the incoming network bytes per second across all network devices.
    os.mac.check-system-net-bytes-outgoing Retrieves the outgoing network bytes per second across all network devices.
    os.mac.check-system-logged-in-users Retrieves the detail of users currently logged in to the device.
    os.mac.check-system-session-details Retrieves the session time of currently logged in users in minutes.
    os.mac.check-system-network-details Retrieves the network details, including Ethernet, Wi-Fi, and other relevant information.
    os.mac.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.mac.check-system-battery-charge-percentage Retrieves the charge percentage of batteries present on the device.
    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.mac.check-system-firewall-enabled Checks if the operating system firewall is active and enabled.
    os.mac.check-system-pending-updates Checks the status of pending software updates.
    os.mac.check-system-admin-users Retrieves all user accounts with local administrative privileges.
    os.mac.check-system-reboot-details Retrieves the reboot details for the device.
    os.mac.check-system-os-setup-details Retrieves the approximate OS age for the device.

    os.mac.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.mac.check-system-vpn-details Get the VPN details for your device.
    os.mac.check-system-energy-consumption Gets Energy consumed by Mac machine in coming 5minutess.
    Note:
    The important details of this check defintion is listed below:
    • /usr/bin/powermetrics needs to be added to sudo Permissions.
    • The check will take approximately five minutes to get completed as it is calculating energy consumed in the coming five minutes
    • This check defintion will not work if agent is installed with rosetta enabled on M1, M2, M3 machines.
    os.mac.check-system-power-consumption Gets Power consumption for mac device.

    Check definitions — Diagnostic Actions

    DEX provides the following types of check definitions for Diagnostic actions.
    Check definition name Check definition parameters Description
    os.mac.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.mac.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.mac.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.mac.check-process-data N/A Retrieves the CPU usage, memory usage, and disk usage of all currently running processes.
    os.mac.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.mac.check-traceroute

    --url=<url>

    --max_hops = <default value is 65>

    --timeout = <default value is 5>

    		 Retrieves the IP address, domain name and round-trip time (RTT) for each network hop.
    os.mac.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.

    Check definitions — Remedial Actions

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

    --pid=<process id>

    OR

    --process_name=<executable file name>

    Note:
    The process ID takes priority over the application name.
    		 Terminates a running process or multiple processes specified by their Process ID (PID) or executable (.app) file name.
    os.mac.action-restart-service --service_name=<service name> Restarts logged user services that take a service name as input to the system.