About the connector
FortiClient Enterprise Management Server (FortiClient EMS) is a security management solution that enables scalable and centralized management of multiple endpoints (computers). FortiClient EMS provides efficient and effective administration of endpoints running FortiClient.
This document provides information about the Fortinet FortiClient EMS connector, which facilitates automated interactions, with the Fortinet FortiClient EMS server using FortiSOAR™ playbooks. Add the Fortinet FortiClient EMS connector as a step in FortiSOAR™ playbooks and perform automated operations, such as quarantining or unquarantining an endpoint ticket in Fortinet FortiClient EMS or retrieving details for endpoints, zero trust rule sets, etc. from Fortinet FortiClient EMS.
Version information
Connector Version: 1.1.0
FortiSOAR™ Version Tested on: 7.3.1-2105
FortiClient EMS version Tested on: 7.0.2 build 0123
Authored By: Fortinet
Certified: Yes
Release Notes for version 1.1.0
The following enhancements have been made to the Fortinet FortiClient EMS connector in version 1.1.0:
- Added the following new actions and playbooks
- Get Zero Trust Rule Sets List
- Get Zero Trust Rule Tags List
- Deprecated the following actions since the API for these actions is not available from FortiClient EMS version 7.0.7:
- Get Events For Endpoint
- Get Verification Rules
- Get Host Verification Tags
- Get Profile Details
- Get All Profiles
- Fixed a bug that cause the 'Get Endpoint Details' action to fail even when valid input details were provided.
- Added the following input parameters to the 'Get All Endpoints' action:
- Device ID
- Group ID
- Client ID
- Client OS
- Client Version
- Activity
- Connection
- Event Type
- Management
- Status
- View Type
- Verification
- Filters
- Order By
- Sort Order
- Custom Properties
Installing the connector
Use the Content Hub to install the connector. For the detailed procedure to install a connector, click here.
You can also use the following yum command as a root user to install connectors from an SSH session:
yum install cyops-connector-fortinet-forticlient-ems
Prerequisites to configuring the connector
- You must have the URL of the Fortinet FortiClient EMS server to which you will connect and perform automated operations and credentials (username-password pair) to access that server.
- The FortiSOAR™ server should have outbound connectivity to port 443 on the FortiClient EMS server.
Minimum Permissions Required
To run actions using the Fortinet FortiClient connector users must be assigned appropriate "Roles". Roles are associated with different permissions. To view the various roles that can be assigned to a user, in the Fortinet FortiClient EMS server, navigate to Administration >> Admin Roles.
For example, if you have assigned a role with only "Read" permissions to a user, then that user can run actions such as Get All Endpoints, Get Endpoint Details, etc, but cannot run actions such as Quarantine Endpoints, Unquarantine Endpoints, etc
Configuring the connector
For the procedure to configure a connector, click here.
Configuration parameters
In FortiSOAR™, on the Content Hub (or Connector Store) page, click the Manage tab, and then click the Fortinet FortiClient EMS connector card. On the connector popup, click the Configurations tab to enter the required configuration details.
| Parameter |
Description |
| Server URL |
The URL of the FortiClient EMS server to which you will connect and perform automated operations. |
| Username |
The username used to access the FortiClient EMS server to which you will connect and perform the automated operations. |
| Password |
The Password used to access the FortiClient EMS server to which you will connect and perform the automated operations. |
| Verify SSL |
Specifies whether the SSL certificate for the server is to be verified or not. |
Actions supported by the connector
The following automated operations can be included in playbooks and you can also use the annotations to access operations from FortiSOAR™:
| Function |
Description |
Annotation and Category |
| Quarantine Endpoints |
Quarantines the specified endpoints on the Fortinet FortiClient EMS server based on the endpoint IDs you have specified. |
quarantine_endpoints
Investigation |
| Unquarantine Endpoints |
Unquarantines the specified endpoints on the Fortinet FortiClient EMS server based on the endpoint IDs you have specified. |
unquarantine_endpoints
Investigation |
| Get All Endpoints |
Retrieves a list of all the endpoints or the specific endpoints connected to the specified Fortinet FortiClient EMS server based on the input parameters you have specified. |
get_endpoints
Investigation |
| Get Endpoint Details |
Retrieves details for a specific endpoint from the Fortinet FortiClient EMS server based on the device ID you have specified. |
get_endpoints
Investigation |
| Get Zero Trust Rule Sets List |
Retrieves a list of all zero trust rule sets or specific zero trust rule sets from the FortiClient EMS server based on the input parameters you have specified. |
get_zero_trust_rule_sets
Investigation |
| Get Zero Trust Rule Tags List |
Retrieves a list of all zero trust rule tags from the FortiClient EMS server. |
get_zero_trust_rule_tags
Investigation |
operation: Quarantine Endpoints
Input parameters
| Parameter |
Description |
| Endpoint IDs |
Specify the IDs of the endpoints to quarantine on the Fortinet FortiClient EMS server. |
Output
The output contains the following populated JSON schema:
{
"result": {
"retval": "",
"message": ""
},
"data": [
{
"id": "",
"name": "",
"full_host": "",
"host": "",
"ip_addr": "",
"uid": "",
"retval": "",
"message": ""
}
]
}
operation: Unquarantine Endpoints
Input parameters
| Parameter |
Description |
| Endpoint IDs |
Specify the IDs of the endpoints to unquarantine on the Fortinet FortiClient EMS server. |
Output
The output contains the following populated JSON schema:
{
"result": {
"retval": "",
"message": ""
},
"data": [
{
"id": "",
"name": "",
"full_host": "",
"host": "",
"ip_addr": "",
"uid": "",
"retval": "",
"message": ""
}
]
}
operation: Get All Endpoints
Input parameters
Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied, and an unfiltered list (of endpoints) is returned.
| Parameter |
Description |
| Device ID |
Specify the ID of the device for which you want to retrieve endpoints from FortiClient EMS. |
| Group ID |
Specify the ID of the group for which you want to retrieve endpoints from FortiClient EMS. |
| Client ID |
Specify the ID of the client for which you want to retrieve endpoints from FortiClient EMS. |
| Client OS |
Specify the OS of the client for which you want to retrieve endpoints from FortiClient EMS. |
| Client Version |
Specify the version of the client for which you want to retrieve endpoints from FortiClient EMS. |
| Activity |
Select the activity based on which you want to filter the endpoints retrieved from FortiClient EMS. You can choose from the following options: EMS On Net, EMS Off Net, or Total. |
| Connection |
Select the connection based on which you want to filter the endpoints retrieved from FortiClient EMS. You can choose from the following options: Online, OfflineLong, OfflineNominal, OfflineRecent, or Total. |
| Event Type |
Select the type of event based on which you want to filter the endpoints retrieved from FortiClient EMS. You can choose from the options such as Antivirus, AntiRansomware, AntiExploit, CloudScan, RemovableMedia, etc. |
| Management |
Select the management based on which you want to filter the endpoints retrieved from FortiClient EMS. You can choose from the following options: Managed, Unmanaged, or Total. |
| Status |
Select the status based on which you want to filter the endpoints retrieved from FortiClient EMS. You can choose from the options such as Not Installed, Unregistered, OutOfSync, SecurityRisk, etc. |
| View Type |
Select the view type based on which you want to filter the endpoints retrieved from FortiClient EMS. You can choose from the following options: ALL, Device, or User. |
| Verification |
Specify the verification, in the JSON format, based on which you want to filter the endpoints retrieved from FortiClient EMS. |
| Filters |
Specify the filters, in the JSON format, using which you want to filter the endpoints retrieved from FortiClient EMS. |
| Order By |
Specify the option based on which you want to order the endpoints retrieved from FortiClient EMS. |
| Sort Order |
Select the checkbox (by default it is selected) to sort the endpoints retrieved from FortiClient EMS in an 'ascending' order. |
| Count |
Specify the maximum number of results, per page, that this operation should return in its response. |
| Offset |
Specify the index of the first item to be returned by this operation. This parameter is useful if you want to get a subset of records, say endpoints starting from the 10th endpoint. By default, this is set as 0. |
| Custom Properties |
Additional properties (fields), in the JSON format, that you want to associate with the endpoint retrieved from FortiClient EMS. |
Output
The output contains the following populated JSON schema:
{
"result": {
"retval": "",
"message": ""
},
"data": {
"endpoints": [
{
"device_id": "",
"name": "",
"ip_addr": "",
"os_version": "",
"group_id": "",
"group_name": "",
"group_path": "",
"orig_group_name": "",
"domain_id": "",
"installer_name": "",
"deployment_state": "",
"fgt_sn": "",
"forticlient_id": "",
"uid": "",
"fct_version": "",
"diskenc": "",
"av_product": "",
"is_installed": "",
"is_managed": "",
"is_migrating": "",
"is_ems_registered": "",
"is_ems_online": "",
"is_ems_onnet": "",
"is_excluded": "",
"is_quarantined": "",
"quarantine_access_code": "",
"comparable_fct_version": "",
"last_seen": "",
"last_seen_fct_user_id": "",
"endpoint_policy_name": "",
"endpoint_policy_id": "",
"ip_list_name": "",
"av_enabled": "",
"rtp_enabled": "",
"ae_enabled": "",
"cs_enabled": "",
"rm_enabled": "",
"fw_enabled": "",
"wf_enabled": "",
"vpn_enabled": "",
"vuln_enabled": "",
"ssoma_enabled": "",
"sb_enabled": "",
"sb_cloud_enabled": "",
"rs_enabled": "",
"onboarding_supported": "",
"client_version_up_to_date": "",
"client_av_sig_version_up_to_date": "",
"client_policy_synced": "",
"client_policy_primary_synced": "",
"client_policy_offnet_synced": "",
"client_policy_iplist_synced": "",
"client_policy_onnet_rule_synced": "",
"client_policy_verification_rule_synced": "",
"client_policy_certs_synced": "",
"av_events_count": "",
"wf_events_count": "",
"fw_events_count": "",
"sb_events_count": "",
"ae_events_count": "",
"rm_events_count": "",
"cs_events_count": "",
"unreg_events_count": "",
"rs_events_count": "",
"vuln_events_count": "",
"vuln_events_max_severity": "",
"profile_components": {
"vpn": {
"id": "",
"name": ""
},
"ztna": {
"id": "",
"name": ""
},
"webfilter": {
"id": "",
"name": "",
"fp_name": ""
},
"vulnerability_scan": {
"id": "",
"name": ""
},
"malware": {
"id": "",
"name": ""
},
"sandbox": {
"id": "",
"name": ""
},
"firewall": {
"id": "",
"name": ""
},
"system": {
"id": "",
"name": ""
}
},
"off_net_profile_components": {
"vpn": {
"id": "",
"name": ""
},
"ztna": {
"id": "",
"name": ""
},
"webfilter": {
"id": "",
"name": "",
"fp_name": ""
},
"vulnerability_scan": {
"id": "",
"name": ""
},
"malware": {
"id": "",
"name": ""
},
"sandbox": {
"id": "",
"name": ""
},
"firewall": {
"id": "",
"name": ""
},
"system": {
"id": "",
"name": ""
}
},
"fct_users": [
{
"auth_user_name": "",
"machine_user_name": "",
"auth_user_id": "",
"machine_user_id": "",
"auth_domain": "",
"machine_domain": "",
"avatar": "",
"fct_user_id": "",
"client_id": "",
"last_seen": "",
"is_authenticated": "",
"user_email": "",
"user_phone": "",
"row_no": ""
}
]
}
],
"total": ""
}
}
operation: Get Endpoint Details
Input parameters
| Parameter |
Description |
| Device ID |
Specify the ID of the device whose details you want to retrieve from the Fortinet FortiClient EMS server. |
Output
The output contains the following populated JSON schema:
{
"result": {
"retval": "",
"message": ""
},
"data": {
"endpoints": [
{
"device_id": "",
"name": "",
"ip_addr": "",
"os_version": "",
"group_id": "",
"group_name": "",
"group_path": "",
"orig_group_name": "",
"domain_id": "",
"installer_name": "",
"deployment_state": "",
"fgt_sn": "",
"forticlient_id": "",
"uid": "",
"fct_version": "",
"diskenc": "",
"av_product": "",
"is_installed": "",
"is_managed": "",
"is_migrating": "",
"is_ems_registered": "",
"is_ems_online": "",
"is_ems_onnet": "",
"is_excluded": "",
"is_quarantined": "",
"quarantine_access_code": "",
"comparable_fct_version": "",
"last_seen": "",
"last_seen_fct_user_id": "",
"endpoint_policy_name": "",
"endpoint_policy_id": "",
"ip_list_name": "",
"av_enabled": "",
"rtp_enabled": "",
"ae_enabled": "",
"cs_enabled": "",
"rm_enabled": "",
"fw_enabled": "",
"wf_enabled": "",
"vpn_enabled": "",
"vuln_enabled": "",
"ssoma_enabled": "",
"sb_enabled": "",
"sb_cloud_enabled": "",
"rs_enabled": "",
"onboarding_supported": "",
"client_version_up_to_date": "",
"client_av_sig_version_up_to_date": "",
"client_policy_synced": "",
"client_policy_primary_synced": "",
"client_policy_offnet_synced": "",
"client_policy_iplist_synced": "",
"client_policy_onnet_rule_synced": "",
"client_policy_verification_rule_synced": "",
"client_policy_certs_synced": "",
"av_events_count": "",
"wf_events_count": "",
"fw_events_count": "",
"sb_events_count": "",
"ae_events_count": "",
"rm_events_count": "",
"cs_events_count": "",
"unreg_events_count": "",
"rs_events_count": "",
"vuln_events_count": "",
"vuln_events_max_severity": "",
"profile_components": {
"vpn": {
"id": "",
"name": ""
},
"ztna": {
"id": "",
"name": ""
},
"webfilter": {
"id": "",
"name": "",
"fp_name": ""
},
"vulnerability_scan": {
"id": "",
"name": ""
},
"malware": {
"id": "",
"name": ""
},
"sandbox": {
"id": "",
"name": ""
},
"firewall": {
"id": "",
"name": ""
},
"system": {
"id": "",
"name": ""
}
},
"off_net_profile_components": {
"vpn": {
"id": "",
"name": ""
},
"ztna": {
"id": "",
"name": ""
},
"webfilter": {
"id": "",
"name": "",
"fp_name": ""
},
"vulnerability_scan": {
"id": "",
"name": ""
},
"malware": {
"id": "",
"name": ""
},
"sandbox": {
"id": "",
"name": ""
},
"firewall": {
"id": "",
"name": ""
},
"system": {
"id": "",
"name": ""
}
},
"fct_users": [
{
"auth_user_name": "",
"machine_user_name": "",
"auth_user_id": "",
"machine_user_id": "",
"auth_domain": "",
"machine_domain": "",
"avatar": "",
"fct_user_id": "",
"client_id": "",
"last_seen": "",
"is_authenticated": "",
"user_email": "",
"user_phone": "",
"row_no": ""
}
]
}
],
"total": ""
}
}
operation: Get Zero Trust Rule Sets List
Input parameters
Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied, and an unfiltered list (of zero trust rule sets) is returned.
| Parameter |
Description |
| Filters |
Specify the filters, in the JSON format, using which you want to filter the zero trust rule sets retrieved from FortiClient EMS |
| Order By |
Specify the field based on which you want to order the zero trust rule sets retrieved from FortiClient EMS. You can choose from Name or Priority. |
| Sort Order |
Select the order based on which you want to sort the zero trust rule sets retrieved from FortiClient EMS. You can choose from Ascending or Descending. |
| Count |
Specify the maximum number of results, per page, that this operation should return in its response. |
| Offset |
Specify the index of the first item to be returned by this operation. This parameter is useful if you want to get a subset of records, say zero trust rule sets starting from the 10th zero trust rule set. By default, this is set as 0 |
| Custom Properties |
Additional properties (fields), in the JSON format, that you want to associate with the zero trust rule sets retrieved from FortiClient EMS. |
Output
The output contains the following populated JSON schema:
{
"result": {
"retval": "",
"message": ""
},
"data": {
"rule_sets": [
{
"id": "",
"name": "",
"status": "",
"comments": "",
"tag_name": "",
"tag": "",
"tag_detection_type": ""
}
],
"total": ""
}
}
operation: Get Zero Trust Rule Tags List
Input parameters
None.
Output
The output contains the following populated JSON schema:
{
"result": {
"retval": "",
"message": ""
},
"data": [
{
"id": "",
"name": "",
"description": "",
"rule_sets": [
{
"name": ""
}
]
}
]
}
Included playbooks
The Sample - Fortinet FortiClient EMS - 1.1.0 playbook collection comes bundled with the Fortinet FortiClient EMS connector. These playbooks contain steps using which you can perform all supported actions. You can see bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the Fortinet FortiClient EMS connector.
- Get All Endpoints
- Get Endpoint Details
- Get Zero Trust Rule Sets List
- Get Zero Trust Rule Tags List
- Quarantine Endpoints
- Unquarantine Endpoints
Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection since the sample playbook collection gets deleted during the connector upgrade and delete.
