How can I do a custom check on endpoints?

As of January 09, 2018, MetaAccess provides administrators a way to do a custom check which OPSWAT does not offer in OPSWAT's granular policy, for example: whether a specific registry key/file exists, whether a specific process is running.

How does it work?

Administrators can write 189104195 to do a custom check on a device and apply it to a policy on their MetaAccess account. When the custom check is enabled in a policy, MetaAccess will push the script to the endpoints the policy applies to. The agent will then invoke the script on the endpoints with the configured privileges using the configured frequency.

To enable custom check,

  • Log into MetaAccess console

  • Navigate to Policies

  • Then select a policy you wish to enable the custom check on (e.g. "Default")

  • Click the "Laptops/Desktops" tab, then "Device Compliance", then click to enable the switch next to "Custom Check"

  • Select an operating system, you want to apply the custom check on

  • Check the box next to "Script returns FALSE"

  • Check on "Run the powershell/Shell script"... and select a privilege you would like OPSWAT Client run the script with. Notes

    • With the persistent client version 7.6.324/10.4.284 or earlier, OPSWAT Client will run the script with system/root privilege

    • With the on-demand client version 7.3.503.0/10.5.213.0 or earlier, OPSWAT Client will run the script with current user privilege.

  • Hit SAVE and enter your PIN to confirm the change.

images/download/attachments/5707550/custom-check-policy.png

  • Navigate to Settings > Global Settings > Device Agents

  • Set how often you would like the OPSWAT Client run the script in the Compliance Report section

images/download/attachments/5707550/custom-check-freq.png

Whenever an agent executes the script, it will report the script result to the MetaAccess cloud along with the compliance check report. If the script failed to run or timed out, the MetaAccess cloud will consider custom check on the device as PASSED. Administrators can view the script result on a device details page

images/download/attachments/5707550/custom-check-result.png

and also able to filter devices which the script returns FALSE on Devices page

images/download/attachments/5707550/custom-check-filter.png

What permission can we execute the script?

MetaAccess supports the script can be run as System/Administrator/Current User permission.

Run as

Windows

macOS

System

SUPPORTED

SUPPORTED

Administrator

SUPPORTED

NOT SUPPORTED

Current User

SUPPORTED

SUPPORTED


Note:

  • The privilege setting only applies for Persistent agent., not apply for On-demand agent

  • The on-demand agent runs the custom script as current On-demand process's permission.

    • If we run the On-demand agent (required admin permission), OPSWAT Client will run the script with admin privilege

    • If we run the limited On-demand agent, OPSWAT Client will run the script with current user privilege


What scripts does OPSWAT Client support?

OPSWAT Client supports PowerShell script for Windows devices and shell script for macOS /Linux devices. OPSWAT Client doesn't support inputs when executing a script.

Single script file MUST end with a ".ps1" extension for Windows devices or ".sh" for macOS/Linux devices

Multi script files MUST be packaged in a zip file with main.ps1 (or main.sh) in the root folder, subscripts could be located in root folder or subfolders. Multi script is only applicable on Windows and MacOS

Scripts MUST return an output as the below format. If the script returns wrong format or invalid value for "result" or "msg" parameter, the agent will treat it as failed to execute and MetaAccess cloud will consider the device pass the check.

[output]

result=0

msg=This is a script log

in which:

  • result only accepts 0/1 (0 is FALSE, 1 is TRUE)

  • msg limits 2048 bytes

Sample scripts

 

Windows

macOS

Whether a specific registry key exists

Win-CheckExistingRegistryKeyScript.ps1

 

Whether a specific registry key value contains certain regex string

Win-CheckRegistryKeyValueScript.ps1

 

Whether a specific process is running on the system

Win-CheckRunningProcessScript.ps1

MacOS-CheckRunningProcessScript.sh

Whether a specific service is running on the system

Win-CheckRunningServiceScript.ps1

MacOS-CheckRunningServiceScript.sh

Whether a specific file exists on a specific path in the system

Win-CheckExistingFileScript.ps1

MacOS-CheckExistingFileScript.sh

Multiple script check*

Win-multi-script.zip

MacOS-multi-script.zip

Note that only agent version listed below is able to execute a custom script.

  • Windows agent: 7.6.136.0+

  • macOS agent: 10.4.162.0+

*Agent version listed below is able to execute a multiple check

  • Windows agent: 7.6.366.0+

  • macOS agent : 10.4.300.0+