Discover Computer Security Statuses and Patch Vulnerabilities

Use the API to gather information about the security status of the computers that Deep Security is protecting. For example, to create a monthly report of your security status, you gather information about security modules, such as their running state (on or off), and whether the latest rules are assigned.

You can also discover whether you are protected against a specific threat. For example when a CVE is released for a zero-day vulnerability, you can find the intrusion prevention rule for that CVE and apply it to your computers.

Discover unprotected computers

Discover unprotected computers based on the real-time status of the agent or appliance, or on the status of a protection module:

  • The computer has no agent or appliance installed, or the agent or appliance is not active
  • The protection module is not on, or it is on and not active

For virtual machines, you can also obtain the machine state which can be useful for troubleshooting, as well as other information.

For background information about computer statuses, see Computer and agent statuses in the Deep Security Help Center.

Find computers based on agent status

Computers that have no agent or appliance installed are not protected by Deep Security. Computers could also be unprotected when problems exist with their agent or appliance.

To determine whether an agent or appliance is installed, check for the agent and appliance fingerprint. No fingerprint indicates that no agent or appliance is installed and therefore the computer is unprotected. When an agent or appliance is installed, also check their status. For example, a status of active indicates that the agent or appliance is running correctly. Other statuses, such as error or inactive, indicate a problem that you should investigate.

The following example JSON represents the data structure of a Computer object (some items are omitted to make the example more concise). The agentFingerPrint shows that an agent is installed and the computerStatus shows that it is active.

{
    "hostName": "laptop_adaggs",
    ...
    "policyID": 34,
    "agentFingerPrint": "71:3E:81:64:65:EB:34:78:FC:72:C2:CB:37:6B:1D:F0:8C:D1:9B:1E",
    "agentVersion": "11.3.2.883",
    "computerStatus": {
        "agentStatus": "active",
        "agentStatusMessages": [
            "Managed (Online)"
        ]
    },
    "computerSettings": {...},
    "ID": 48,
    "antiMalware": {...},
    ...
}
An offline status can indicate that Deep Security Manager cannot communicate with the computer. With this status, the agent or appliance can be running normally and providing protection. However, the manager cannot send security updates to the agent or appliance.

Use the following general procedure to discover unprotected computers:

  1. Use ComputersApi to obtain a Computer object.
  2. Check the AgentFingerPrint and ApplianceFingerPrint property of the computer.
  3. Obtain the ComputerStatus object from the Computer object and check the AgentStatus property. Any value other than ACTIVE can indicate a problem.
  4. Optionally, obtain the AgentStatusMessages of the ComputerStatus object and the AgentTasks property of the Computer object for useful information.
Because the value of the computerStatus field of a computer is an object (ComputerStatus), you cannot search on this field.

Example: Report on agent status

The following example finds computers that have neither an agent or appliance installed, or the status of the agent and/or appliance is not active. The results are returned in a format that can be saved as a CSV file to open as a spreadsheet.

Python
def get_computer_statuses(api, configuration, api_version, api_exception):
    """Obtains agent and appliance status for all computers and provides the results as comma-separated values.

    :param api: The Deep Security API modules.
    :param configuration: Configuration object to pass to the api client.
    :param api_version: The version of the API to use.
    :param api_exception: The Deep Security API exception module.
    :return: A string that can be saved as a CSV file.
    """

    # Add column titles to comma-separated values string
    csv = "Host Name,Agent or Appliance,Status,Status Messages,Tasks\r\n"

    try:
        computers_api = api.ComputersApi(api.ApiClient(configuration))
        computers = computers_api.list_computers(api_version, overrides=False)

        for computer in computers.computers:
            computer_info = []

            # Report on computers with no agent or appliance
            if computer.agent_finger_print == None and computer.appliance_finger_print == None:
                # Hostname and protection type
                computer_info.append(computer.host_name)
                computer_info.append("None")

                # Agent/appliance status and status messages
                computer_info.append("No agent/appliance")
                status_messages = ""
                if computer.computer_status != None and computer.computer_status.agent_status != None:
                    status_messages = str(computer.computer_status.agent_status_messages)
                computer_info.append(status_messages)

                # Add the computer info to the CSV string
                csv_line = ""
                for num, item in enumerate(computer_info):
                    csv_line += item
                    if num != (len(computer_info) - 1):
                        csv_line += ","
                    else:
                        csv_line += "\r\n"
                csv += csv_line

            else:
                # Report on problem agents and appliances
                agent_status = computer.computer_status.agent_status
                appliance_status = computer.computer_status.appliance_status

                # Agent is installed but is not active
                if computer.agent_finger_print != None and agent_status != "active":
                    # Hostname and protection type
                    computer_info.append(computer.host_name)
                    computer_info.append("Agent")

                    # Agent status, status messages, and tasks
                    if computer.computer_status.agent_status != None:
                        computer_info.append(computer.computer_status.agent_status)
                    else:
                        computer_info.append("")

                    if computer.computer_status.agent_status_messages != None:
                        computer_info.append(str(computer.computer_status.agent_status_messages))
                    else:
                        computer_info.append("")

                    if computer.tasks != None:
                        computer_info.append(str(computer.tasks.agent_tasks))
                    else:
                        computer_info.append("")

                    # Add the computer info to the CSV string
                    csv_line = ""
                    for num, item in enumerate(computer_info):
                        csv_line += item
                        if num != (len(computer_info) - 1):
                            csv_line += ","
                        else:
                            csv_line += "\r\n"
                    csv += csv_line

                # Appliance is installed but is not active
                if computer.appliance_finger_print != None and appliance_status != "active":
                    # Hostname and protection type
                    computer_info.append(computer.host_name)
                    computer_info.append("Appliance")

                    # Appliance status, status messages, and tasks
                    if computer.computer_status.appliance_status != None:
                        computer_info.append(computer.computer_status.appliance_status)
                    else:
                        computer_info.append("")

                    if computer.computer_status.appliance_status_messages != None:
                        computer_info.append(str(computer.computer_status.appliance_status_messages))
                    else:
                        computer_info.append("")

                    if computer.tasks != None:
                        computer_info.append(str(computer.tasks.appliance_tasks))
                    else:
                        computer_info.append("")

                    # Add the computer info to the CSV string
                    csv_line = ""
                    for num, item in enumerate(computer_info):
                        csv_line += item
                        if num != (len(computer_info) - 1):
                            csv_line += ","
                        else:
                            csv_line += "\r\n"
                    csv += csv_line

        return csv

    except api_exception as e:
        return "Exception: " + str(e)
JavaScript
/*
* Obtains agent and appliance status for all comptuters
* and provides the results as comma-separated values.
* @param {object} api The api module.
* @param {String} apiVersion The api version to use.
* @return {Promise} A promise that contains a string of values in CSV format.
*/
exports.getComputerStatuses = function (api, apiVersion) {
  return new Promise((resolve, reject) => {

    // Obtains a list of all computers
    const getListOfComputers = () => {
      const computersApi = new api.ComputersApi();
      return computersApi.listComputers(apiVersion, { overrides: false });
    };
    // Add column titles to comma-separated values string
    let csv = "Host Name, Agent or Appliance, Status, Status Messages, Tasks\r\n";
    // Get the computers and iterate them
    getListOfComputers()
      .then(computers => {
        for (const computer of computers.computers) {
          const computerInfo = []; // Stores computer status information
          // Report on computers with no agent or appliance
          if (computer.agentFingerPrint === undefined & computer.applianceFingerPrint === undefined) {
            // Hostname and protection type
            computerInfo.push(computer.hostName);
            computerInfo.push("None");
            // Agent/appliance status and status message
            computerInfo.push("No agent/appliance");
            computerInfo.push((computer.computerStatus.agentStatus !== undefined)
              ? computer.computerStatus.agentStatusMessages
              : "");
            // Add to CSV string
            csv += formatForCSV(computerInfo);
          } else {
            // Report on problem agents and appliances
            const agentIsActive = computer.computerStatus.agentStatus == api.ComputerStatus.AgentStatusEnum.active;
            const applianceIsActive = computer.computerStatus.applianceStatus == api.ComputerStatus.ApplianceStatusEnum.active;
            if (computer.agentFingerPrint !== undefined && !agentIsActive) {
              // Agent is installed but not active
              computerInfo.push(computer.hostName);
              computerInfo.push("Agent");
              computerInfo.push(computer.computerStatus.agentStatus !== undefined
                ? computer.computerStatus.agentStatus
                : "");
              computerInfo.push(computer.computerStatus.agentStatusMessages !== undefined
                ? computer.computerStatus.agentStatusMessages
                : "");
              computerInfo.push(computer.tasks !== undefined
                ? computer.tasks
                : "");
              // Add to CSV string
              csv += formatForCSV(computerInfo);
              computerInfo.lenght = 0;
            }
            if (computer.applianceFingerPrint !== undefined && !applianceIsActive) {
              // Appliance is installed but not active
              computerInfo.push(computer.hostName);
              computerInfo.push("Appliance");
              computerInfo.push(computer.computerStatus.applianceStatus !== undefined
                ? computer.computerStatus.applianceStatus
                : "");
              computerInfo.push(computer.computerStatus.applianceStatusMessages !== undefined
                ? computer.computerStatus.applianceStatusMessages
                : "");
              computerInfo.push(computer.tasks !== undefined
                ? computer.tasks
                : "");
              // Add to CSV string
              csv += formatForCSV(computerInfo);
            }
          }
        }
        resolve(csv);
      })
      .catch(error => {
        reject(error);
      });
  });
};

// PRIVATE METHODS //

/*
* Converts an array of string values into a string of comma-separated values.
* @param {Array} values The array of values.
* @return {String} The string of comma-separated values.
*/
function formatForCSV(values) {
  let csvLine = "";
  for (let i = 0; i < values.length; i++) {
    csvLine += '"' + values[i] + '"';
    if (i != values.length - 1) {
      csvLine += ',';
    } else {
      csvLine += '\r\n';
    }
  }
  return csvLine;
}
Java
/*
 * Obtains agent and appliance status for all computers 
 * and provides the results as comma-separated values.
 * @return A String value that can be saved as a CSV file.
 */
public static String getComputerStatuses() {
	//Add column titles to comma-separated values string
	String csv = "Host Name, Agent or Appliance, Status, Status Messages, Tasks\r\n";

	ComputersApi computersApi = new ComputersApi();
	Computers computers = new Computers();

	try {
		computers = computersApi.listComputers(false, "v1");
	} catch (ApiException e) {
		System.out.println(e.getMessage());
		e.printStackTrace();
	}
	
	for (Computer computer : computers.getComputers()) {
		ArrayList<String > computerInfo = new ArrayList<String>();
		//Report on computers with no agent or appliance
		if (computer.getAgentFingerPrint() == null && computer.getApplianceFingerPrint() == null) {
			//Hostname and protection type
			computerInfo.add(computer.getHostName());
			computerInfo.add("None");
			//Agent/appliance status and status messages
			computerInfo.add("No agent/appliance");
			String statusMessages = (computer.getComputerStatus().getAgentStatus() != null) 
				?	computer.getComputerStatus().getAgentStatusMessages().toString()
				: "";
			computerInfo.add(statusMessages);
			//Add to CSV string
			csv += formatForCSV(computerInfo);

		} else {
			//Report on problem agents and appliances
			boolean agentIsActive = computer.getComputerStatus().getAgentStatus() == ComputerStatus.AgentStatusEnum.ACTIVE;
			boolean applianceIsActive = computer.getComputerStatus().getApplianceStatus() == ComputerStatus.ApplianceStatusEnum.ACTIVE;

			//Agent is installed but is not active
			if (computer.getAgentFingerPrint() != null && !agentIsActive) {
				//Hostname and protection type
				computerInfo.add(computer.getHostName());
				computerInfo.add("Agent");
				//Agent status, status messages, and tasks
				String agentStatus = (computer.getComputerStatus().getAgentStatus() != null)
					? computer.getComputerStatus().getAgentStatus().getValue()
					: "";
				computerInfo.add(agentStatus);
				String statusMessages = (computer.getComputerStatus().getAgentStatusMessages() != null) 
					?	computer.getComputerStatus().getAgentStatusMessages().toString() 
					: "";
				computerInfo.add(statusMessages);
				String agentTasks = (computer.getTasks() != null) 
					? computer.getTasks().getAgentTasks().toString()
					: "";
				computerInfo.add(agentTasks);
				//Add to CSV string
				csv += formatForCSV(computerInfo);
				computerInfo.clear();
			} 
			//Appliance is installed but is not active
			if (computer.getApplianceFingerPrint() != null && !applianceIsActive) {
				//Hostname and protection type
				computerInfo.add(computer.getHostName());
				computerInfo.add("Appliance");
				//Applicance status, messages, and tasks
				String applianceStatus = (computer.getComputerStatus().getApplianceStatus() != null)
					? computer.getComputerStatus().getApplianceStatus().getValue()
					: "";
				computerInfo.add(applianceStatus);
				String applianceStatusMessages = computer.getComputerStatus().getApplianceStatusMessages() != null 
					? computer.getComputerStatus().getApplianceStatusMessages().toString() 
					: "";
				computerInfo.add(applianceStatusMessages);
				String applianceTasks = (computer.getTasks() != null) 
					? computer.getTasks().getApplianceTasks().toString()
					: "";
				computerInfo.add(applianceTasks);
				computerInfo.trimToSize();
				//Add to CSV string
				csv += formatForCSV(computerInfo);
			}
		}
	}
	return csv;
}

/*
 * Converts a List of strings into a String of comma-separated values.
 * @return A String that contains the comma-separated values.
 */
private static String formatForCSV(ArrayList<String> values) {
	String csvLine = "";
	for (int i=0; i<values.size();i++) {
		csvLine += "\"" + values.get(i) + "\"";
		if (i != values.size()-1) {
			csvLine += ","; 
		} else {
			csvLine += "\r\n"; 
		}
	}
	return csvLine;
}

Find computers based on module status

Computers are vulnerable when a protection module is turned off or a problem prevents the agent or appliance from running the module correctly. To check if a computer is protected by a protection module, check the module state (on or off ). When the state is on, also check the module status which indicates the ability of the agent and/or appliance to run the module. Any status other than active can indicate a problem that requires your attention. You can also obtain status messages that can provide insight into the status.

The following example JSON represents the data structure of a Computer object (some items are omitted to make the example more concise). The Anti-Malware module is on, however the agent status for the module shows a warning.

{
    "hostName": "192.168.60.128",
    ...
    "policyID": 9,
    "agentFingerPrint": "76:C8:CE:B3:70:61:A3:BE:84:A2:2A:5D:1F:3A:29:8A:DC:7A:70:6C",
    "agentVersion": "11.2.0.147",
    "computerStatus": {...},
    "computerSettings": {...},
    ...
    "ID": 2,
    "antiMalware": {
        "state": "on",
        "moduleStatus": {
            "agentStatus": "warning",
            "agentStatusMessage": "Software Update: Anti-Malware Module Installation Failed"
        },
        "realTimeScanConfigurationID": 1,
        "realTimeScanScheduleID": 4,
        "manualScanConfigurationID": 2,
        "scheduledScanConfigurationID": 3
    },
    "webReputation": {...},
    "firewall": {...},
    "intrusionPrevention": {...},
    "integrityMonitoring": {...},
    "logInspection": {...},
    "applicationControl": {...}
}

Use the following general procedure to use module statuses to discover unprotected computers:

  1. Use ComputersApi to obtain a Computer object.
  2. Obtain the computer extension object for the protection module in which you are interested, such as AntiMalwareComputerExtension or IntrusonPreventionComputerExtension.
  3. From the computer extension object, get the value of the module state to see if the module is on or off.
  4. Also from the computer extension object, get the ModuleStatus object and obtain the agent and appliance status and status messages.
Because the value of the moduleStatus field of a computer extension is an object (ModuleStatus), you cannot search on this field.

Example: Report on module status

The following example finds computers that have the Anti-Malware module turned off, or where the status of the module is not active. The results are returned in a format that can be saved as a CSV file to open as a spreadsheet.

Python
def get_anti_malware_status_for_computers(api, configuration, api_version, api_exception):
    """Obtains agent and appliance status for the Anti-Malware module of all computers.

    Returns the status information of all computers that have the Anti-Malware module turned off,
    or where the status of the module is not active as comma-separated values.

    :param api: The Deep Security API modules.
    :param configuration: Configuration object to pass to the api client.
    :param api_version: The version of the API to use.
    :param api_exception: The Deep Security API exception module.
    :return: A string that can be saved as a CSV file.
    """

    # Add column titles to comma-separated values string
    csv = "Host Name,Module State,Agent or Appliance,Status,Status Message\r\n"

    try:
        computers_api = api.ComputersApi(api.ApiClient(configuration))
        computers = computers_api.list_computers(api_version, overrides=False)

        # Get the list of computers and iterate over it
        for computer in computers.computers:
            # Module information to add to the CSV string
            module_info = []

            # Check that the computer has a an agent or appliance status
            if computer.anti_malware.module_status:
                agent_status = computer.anti_malware.module_status.agent_status
                appliance_status = computer.anti_malware.module_status.appliance_status
            else:
                agent_status = None
                appliance_status = None

            # Agents that are not active for the module
            if agent_status and agent_status != "active":
                # Host name
                module_info.append(computer.host_name)

                # Module state
                module_info.append(computer.anti_malware.state)

                # Agent status and status message
                module_info.append("Agent")
                module_info.append(agent_status)
                module_info.append(computer.anti_malware.module_status.agent_status_message)

                # Add the module info to the CSV string
                csv_line = ""
                for num, item in enumerate(module_info):
                    csv_line += item
                    if num != (len(module_info) - 1):
                        csv_line += ","
                    else:
                        csv_line += "\r\n"
                csv += csv_line

            # Appliances that are not active for the module
            if appliance_status and appliance_status != "active":
                # Host name
                module_info.append(computer.host_name)
        
                # Module state
                module_info.append(computer.anti_malware.state)
        
                # Appliance status and status message
                module_info.append("Appliance")
                module_info.append(appliance_status)
                module_info.append(computer.anti_malware.module_status.appliance_status_message)
        
                # Add the module info to the CSV string
                csv_line = ""
                for num, item in enumerate(module_info):
                    csv_line += item
                    if num != (len(module_info) - 1):
                        csv_line += ","
                    else:
                        csv_line += "\r\n"
                csv += csv_line

        return csv

    except api_exception as e:
        return "Exception: " + str(e)
JavaScript
exports.getAntiMalwareStatusForComputers = function (api, apiVersion) {
  return new Promise((resolve, reject) => {
    // Obtains a list of all computers
    const getListOfComputers = () => {
      const computersApi = new api.ComputersApi();
      return computersApi.listComputers(apiVersion, { overrides: false });
    };
    // Add column titles to comma-separated values string
    let csv = "Host Name, Module State, Agent or Appliance, Status, Status Message\r\n";
    // Get the computers and iterate them
    getListOfComputers()
      .then(computers => {
        for (const computer of computers.computers) {
          let moduleInfo = [];
          const agentStatus = computer.antiMalware.moduleStatus.agentStatus;
          const applianceStatus = computer.antiMalware.moduleStatus.applianceStatus;

          // Agents that are not active for the module
          if (agentStatus !== undefined && agentStatus !== api.ComputerModuleStatus.AgentStatusEnum.active) {
            // Hostname
            moduleInfo.push(computer.hostName);
            // Module state
            moduleInfo.push(computer.antiMalware.state);
            // Agent status and status message
            moduleInfo.push("Agent");
            moduleInfo.push(agentStatus);
            moduleInfo.push(computer.antiMalware.moduleStatus.agentStatusMessages);

            // Add to the CSV string
            csv += formatForCSV(moduleInfo);
            moduleInfo.length = 0;
          }
          // Appliances that are not active for the module
          if (applianceStatus !== undefined && agentStatus !== api.ComputerModuleStatus.ApplianceStatusEnum.active) {
            // Hostname
            moduleInfo.push(computer.hostName);
            // Module state
            moduleInfo.push(computer.antiMalware.state);
            // Agent status and status message
            moduleInfo.push("Appliance");
            moduleInfo.push(applianceStatus);
            moduleInfo.push(computer.antiMalware.moduleStatus.applianceStatusMessages);

            // Add to the CSV string
            csv += formatForCSV(moduleInfo);
          }
        }
        resolve(csv);
      })
      .catch(error => {
        reject(error);
      });
  });
};
Java
	/*
	 * Obtains agent and appliance status for the Anti-Malware module
	 * of all computers and provides the results as comma-separated values.
	 * @return A String value that can be saved as a CSV file.
	 */
	public static String getAntiMalwareStatusForComputers() {
		//Add titles to comma-separated values string
		String csv = "Host Name, Module State, Agent or Appliance, Status, Status Message\r\n ";
		
		ComputersApi computersApi = new ComputersApi();
		Computers computers = new Computers();

		//Get a list of computers
		try {
			computers = computersApi.listComputers(false, "v1");
		} catch (ApiException e) {
			System.out.println(e.getMessage());
			e.printStackTrace();
		}
		
		for (Computer computer : computers.getComputers()) {
			//Module information to add to the CSV string
			ArrayList moduleInfo = new ArrayList();
			
			AgentStatusEnum agentStatus = computer.getAntiMalware().getModuleStatus().getAgentStatus();
			ApplianceStatusEnum applianceStatus = computer.getAntiMalware().getModuleStatus().getApplianceStatus();
			
			//Agents that are not active for the module
			if (agentStatus != null && agentStatus != AgentStatusEnum.ACTIVE) {
				//Hostname
				moduleInfo.add(computer.getHostName());
				//Module state
				moduleInfo.add(computer.getAntiMalware().getState().getValue());
				//Agent status and status message
				moduleInfo.add("Agent");
				moduleInfo.add(agentStatus.getValue());
				moduleInfo.add(computer.getAntiMalware().getModuleStatus().getAgentStatusMessage());
				
				//Add to the CSV string
				csv += formatForCSV(moduleInfo);
				moduleInfo.clear();
			}
			
			//Appliances that are not active for the module
			if (applianceStatus != null && applianceStatus != ApplianceStatusEnum.ACTIVE) {
				//Hostname
				moduleInfo.add(computer.getHostName());
				//Module state
				moduleInfo.add(computer.getAntiMalware().getState().getValue());
				//Appliance status and status messages
				moduleInfo.add("Appliance");
				moduleInfo.add(computer.getAntiMalware().getModuleStatus().getApplianceStatus().getValue());
				moduleInfo.add(computer.getAntiMalware().getModuleStatus().getApplianceStatusMessage());
				
				//Add to the CSV string
				csv += formatForCSV(moduleInfo);
			}
		}
		return csv;
	}

See the state of a virtual machine

When a computer is a virtual machine, you can obtain several properties of the virtual machine, including the state (as defined by the virtual machine vendor). The Computer class provides access to several virtual machine summary objects, such as azureARMVirtualMachineSummaryec2VirtualMachineSummary, and vmwareVMVirtualMachineSummary. (For a complete list, see the API Reference.)

You can obtain the virtual machine summary for your computer and use it to check the properties of the virtual machine, such as the state.

Get computer configurations

Computer objects contain the configuration information for a computer. To obtain Computer objects, create a ComputersApi object and then either get a specific computer by ID, search by some other property, or list all computers and iterate over them.

When you obtain a computer, you indicate whether to include all properties or only the overrides that are set on that computer:

  • All properties: Includes those inherited from the computer’s assigned policy as well as overrides.
  • Only overrides: Includes only the properties that have been overridden on that computer. All inherited properties are null.

To access the current configuration of a computer, you use the Computer object to obtain a computer extension object for a protection module. For example, to get information about the anti-malware configuration or state for a computer, you get the AntiMalwareComputerExtension object.

Python
computers_api = api.ComputersApi()
computer = computers_api.describe_computer(computer_id, api_version)
real_time_scan_configuration_id = computer.anti_malware.real_time_scan_configuration_id
am_configs_api = api.AntiMalwareConfigurationsApi(api.ApiClient())
am_description = am_configs_api.describe_anti_malware(real_time_scan_configuration_id, api_version)
JavaScript
const getMalwareScanConfig = computerObj => {
  const realTimeScanConfigID = computerObj.antiMalware.realTimeScanConfigurationID;
  const amConfigsApi = new api.AntiMalwareConfigurationsApi();
  return amConfigsApi.describeAntiMalware(realTimeScanConfigID, apiVersion);
    };
Java
ComputersApi computersApi = new ComputersApi();
try {
  Computers computers = computersApi.listComputers(false, "v1");
  for (Computer computer : computers.getComputers()) {
    AntiMalwareComputerExtension antiMalware = computer.getAntiMalware();
    //Perform operations on antiMalware
  } 
} catch (ApiException e) {
  e.printStackTrace();
}

Discover the Anti-Malware configuration of a computer

AntiMalwareComputerExtension objects provide access to the Anti-malware configuration for a computer, including the:

  • Anti-Malware module running state (on or off)
  • Malware scan configurations

Use the following general steps to obtain the Anti-Malware configuration for your computers:

  1. Use a ComputersApi object to obtain the Computer object.
  2. Use the Computer object to obtain the AntiMalwareComputerExtension object.
  3. Obtain the Anti-Malware module state.
  4. Obtain the scan configurations.

Example: Obtain Anti-Malware configurations of computers

Python
def check_anti_malware(api, configuration, api_version, api_exception, computer_id):
    """ Obtains certain anti-malware properties for a computer.

    :param api: The Deep Security API modules.
    :param configuration: Configuration object to pass to the api client.
    :param api_version: The version of the API to use.
    :param api_exception: The Deep Security API exception module.
    :param computer_id: The ID of the computer.
    :return: An AntiMalwareConfigurationsApi object that contains the anti-malware properties of the computer.
    """

    # Get the computer object from Deep Security Manager
    computers_api = api.ComputersApi(api.ApiClient(configuration))
    computer = computers_api.describe_computer(computer_id, api_version)

    # Get the anti-malware scan configuration id for the computer
    real_time_scan_configuration_id = computer.anti_malware.real_time_scan_configuration_id

    try:
        # Get the anti-malware properties for the computer
        am_configs_api = api.AntiMalwareConfigurationsApi(api.ApiClient(configuration))
        return am_configs_api.describe_anti_malware(real_time_scan_configuration_id, api_version)

    except api_exception as e:
        return "Exception: " + str(e)
JavaScript
/*
* Obtains certain Anti-Malware properties for a computer.
* @param {object} api The api module.
* @param {Number} computerID The ID of the computer.
* @param {String} apiVersion The api version to use.
* @return {Promise} A promise that contains on object of Anti-Malware properties.
*/

exports.checkAntiMalware = function (api, computerID, apiVersion) {
  return new Promise((resolve, reject) => {
    let amStatus, computer;

    // Gets the computer object from Deep Security Manager
    const getComputer = () => {
      const computersApi = new api.ComputersApi();
      return computersApi.describeComputer(computerID, apiVersion, { overrides: false });
    };

    // Gets the malware scan configuration for a computer
    const getMalwareScanConfig = computerObj => {
  const realTimeScanConfigID = computerObj.antiMalware.realTimeScanConfigurationID;
  const amConfigsApi = new api.AntiMalwareConfigurationsApi();
  return amConfigsApi.describeAntiMalware(realTimeScanConfigID, apiVersion);
    };

    getComputer()
      .then(computerObj => {
  computer = computerObj;
  amStatus = getAntiMalwareInfo(computerObj);
  if ( computerObj.antiMalware.realTimeScanConfigurationID !== 0 ) {
    getMalwareScanConfig(computerObj)
    .then(scanConfig => {
      amStatus.directoriesToScan = scanConfig.directoriesToScan;
      resolve(amStatus);
    })
    .catch(error => {
      reject(error);
    });
    
  } else {
    resolve(amStatus);
  }
      })
      .catch(error => {
      reject(error);
      });
  });
};

// PRIVATE METHODS //

// Retrieves certain Anti-Malware properties from a computer object
function getAntiMalwareInfo(computer) {
  const status = {};
  status.name = computer.hostName;
  status.state = computer.antiMalware.state;
  status.smartScanErrorEnabled = computer.computerSettings.antiMalwareSettingSmartScanState;
  return status;
}
Java
/*
 * Obtains certain properties of the Anti-Malware module for all computers
 * @return A HashMap of computer hostnames (the key) and the a list of properties (the value).
 */
public static ArrayList<HashMap<String, Object>> checkAntiMalware() {
  //Stores the properties
  ArrayList<HashMap<String, Object>> amStatuses = new ArrayList<HashMap<String, Object>>();
  //Stores the computer host names and the properties
  HashMap<String, Object> amStatus = null;
  
  ComputersApi computersApi = new ComputersApi();
  AntiMalwareConfigurationsApi amConfigApi = new AntiMalwareConfigurationsApi();
  try {
    //Get all computers
    Computers computers = computersApi.listComputers(false, "v1");
    for (Computer computer : computers.getComputers()) {
      //Get properties for each computer
      amStatus = new HashMap<String, Object>();
      amStatus.put("hostname", computer.getHostName());
      AntiMalwareComputerExtension antiMalware = computer.getAntiMalware();
      
      //Get anti malware state
      String state = antiMalware.getState().getValue();
      amStatus.put("state", state);
      
      //Smart Scan enabled?
      amStatus.put("AntiMalwareSettingSmartScanState", computer.getComputerSettings().getAntiMalwareSettingSmartScanState().getValue());
      
      //Scanned directories
      Integer realTimeScanConfigID = antiMalware.getRealTimeScanConfigurationID();
      if (realTimeScanConfigID != null && realTimeScanConfigID.intValue()>0) {
        AntiMalwareConfiguration amc = amConfigApi.describeAntiMalware(realTimeScanConfigID, "v1");
        amStatus.put("directories", amc.getDirectoriesToScan());
        if (amc.getDirectoriesToScan() == AntiMalwareConfiguration.DirectoriesToScanEnum.DIRECTORY_LIST) {
          amStatus.put("scan-dirs", amc.getDirectoryListID());
        }
      }
      amStatuses.add(amStatus);
    }
  } catch (ApiException e) {
    e.printStackTrace();
  }
  return amStatuses;
}
For information about authenticating API calls, see Authenticate with Deep Security Manager.

Get applied intrusion prevention rules

Determine the Intrusion Prevention rules that are applied to your computers to ensure that the required protections are in place.

  1. Use a ComputersApi object to obtain the Computer objects.
  2. For each Computer object, obtain the IntrusionPreventionComputerExtension object.
  3. Obtain the list of Intrusion Prevention rules.

Example: Retrieve applied Intrusion Prevention rules for all computers

Python
def get_assigned_intrusion_prevention_rules(api, configuration, api_version, api_exception):
    """ Retrieves the intrusion prevention rules that are applied to all computers.

    :param api: The Deep Security API modules.
    :param configuration: Configuration object to pass to the api client.
    :param api_version: The version of the API to use.
    :param api_exception: The Deep Security API exception module.
    :return: A dictionary of objects that contain the computer host name and their assigned rules or None if no rules.
    """

    try:
        # Retrieve computers from Deep Security Manager
        computers_api = api.ComputersApi(api.ApiClient(configuration))
        computers_list = computers_api.list_computers(api_version)

        # Extract intrusion prevention rules from the computers
        im_rules = {}
        for computer in computers_list.computers:
            im_rules[computer.host_name] = computer.intrusion_prevention.rule_ids
        return im_rules

    except api_exception as e:
        return "Exception: " + str(e)
JavaScript
/*
 * Retrieves the Intrusion Prevention rules that are applied to all computers.
 * @param {Object} api The Deep Security API modules.
 * @param {String} apiVersion The version of the api to use.
 * @return {Promise} A promise that contains an array of objects that contain
 * the computer host name and their assigned rules or undefined if no rules.
*/
exports.getAssignedIntrusionPreventionRules = function (api, apiVersion) {
  return new Promise((resolve, reject) => {
    // Retreives computers from Deep Security Manager
    const getComputers = function() {
      const computersApi = new api.ComputersApi();
      return computersApi.listComputers(apiVersion, { overrides: false });
    };

    // Extracts intrusion prevention rules from computers
    const getRules = computers => {
      const rules = {};
      for (let i = 0; i < computers.computers.length; i++) {
        rules[computers.computers[i].hostName] = computers.computers[i].intrusionPrevention.ruleIDs;
      }
      return rules;
    };

    getComputers()
      .then(computerList => {
        resolve(getRules(computerList));
      })
      .catch(error => {
        reject(error);
      });
  });
};
Java
/*
 * Compiles a list of intrusion prevention rules that are applied to each computer.
 * @return A HashMap that has computer IDs as keys and a list of rules (or null if no rules) as values.
 */
public static HashMap<Integer, List<Integer>> getIntrusionPreventionRules(){
  HashMap<Integer, List<Integer>> computerRules = new HashMap<Integer, List<Integer>>();
  ComputersApi computersApi = new ComputersApi();
  try {
    //Get all computer IDs
    Computers computers = computersApi.listComputers(false, "v1");
    //For each computer, get the IDs for the assigned rules
    for (Computer computer : computers.getComputers()) {
      IntrusionPreventionComputerExtension ipce = computer.getIntrusionPrevention();
      computerRules.put(computer.getID(), ipce.getRuleIDs());
    }
  } catch (ApiException e) {
    e.printStackTrace();
  }
  return computerRules;
}
For information about authenticating API calls, see Authenticate with Deep Security Manager.

Patch unprotected computers

Deep Security creates Intrusion Prevention rules that patch your computers against CVE’s. You can use the API to determine which Intrusion Prevention rule protects against a specific CVE, determine if the rule is applied to your computers, and apply the rule if required.

  1. Use an IntrusionPreventionRulesApi object to obtain the intrusion prevention rules via search.
  2. For each computer, obtain an IntrusionPreventionComputerExtension object and determine if the rule is applied to the computer.
  3. For each vulnerable computer, determine the policy that it uses, add the rule to the policy, and update the computers with the change.

Example: Find the Intrusion Prevention rule for a CVE

Python
def find_rules_for_cve(api, configuration, api_version, api_exception, cve_id):
    """ Finds the intrusion prevention rules for a CVE.

    :param api: The Deep Security API modules.
    :param configuration: Configuration object to pass to the api client.
    :param api_version: The version of the API to use.
    :param api_exception: The Deep Security API exception module.
    :param cve_id: The ID of the CVE.
    :return: The intrusion prevention rule ID, or None if no rule is found.
    """

    rule_id_s = []

    # Set search criteria
    search_criteria = api.SearchCriteria()
    search_criteria.field_name = "CVE"
    search_criteria.string_value = "%" + cve_id + "%"
    search_criteria.string_test = "equal"

    # Create a search filter
    search_filter = api.SearchFilter()
    search_filter.search_criteria = [search_criteria]

    try:
        # Search for all intrusion prevention rules for the CVE
        ip_rules_api = api.IntrusionPreventionRulesApi(api.ApiClient(configuration))
        ip_rules_search_results = ip_rules_api.search_intrusion_prevention_rules(api_version, search_filter=search_filter)

        # Get the intrusion prevention rule IDs for the CVE from the results
        for rule in ip_rules_search_results.intrusion_prevention_rules:
            rule_id_s.append(rule.id)

        return rule_id_s

    except api_exception as e:
        return "Exception: " + str(e)
JavaScript
/*
* Finds the Intrusion Prevention rules that protect against a CVE.
* @param {object} api The api module.
* @param {Number} cveID The ID of the CVE (for example CVE-2016-7214) or 
*    part of the ID (for example CVE-2016 or 7214).
* @param {String} apiVersion The api version to use.
* @return {Promise} A promise that contains the rule IDs.
*/
exports.findRulesForCVE = function(api, cveID, apiVersion) {
  const ruleIDs = [];

  // Search for Intrusion Prevention rules
  return new Promise((resolve, reject) => {
    const getIpRules = () => {
      
      // Search criteria
      const cveCriteria = new api.SearchCriteria();
      cveCriteria.fieldName = "CVE";
      cveCriteria.stringValue = "%" + cveID +  "%";
      cveCriteria.stringTest = api.SearchCriteria.StringTestEnum.equal;
      
      // Add criteria to a search filter
      const searchFilter = new api.SearchFilter();
      searchFilter.searchCriteria = [cveCriteria];
      
      // Add the search filter to a search options object
      const searchOptions = {
        searchFilter: searchFilter,
        overrides: false
      };
      
      // Perform the search
      const ipRulesApi = new api.IntrusionPreventionRulesApi();
      return ipRulesApi.searchIntrusionPreventionRules(apiVersion, searchOptions);
    };

    getIpRules()
      .then(ipRules => {
        // Iterate the rules and get the IDs
        for (let i = 0; i < ipRules.intrusionPreventionRules.length; i++) {
           ruleIDs.push(ipRules.intrusionPreventionRules[i].ID);
        }
        resolve(ruleIDs);
      })
      .catch(error => {
        reject(error);
      });
  });
};
Java
/*
 * Finds the intrusion prevention rules for a CVE.
 * @param cve The CVE ID.
 * @return A list of the intrusion prevention rule ID. The  list is empty if no rule is found.
 */
public static List<Integer> findRuleForCVE(String cve) {

  List<Integer> ruleIDs = new ArrayList<Integer>();

  IntrusionPreventionRulesApi intrusionPreventionRulesApi = new IntrusionPreventionRulesApi();

  //Create a search filter to find the rules
  SearchFilter searchFilter = new SearchFilter();

  SearchCriteria searchCriteria = new SearchCriteria();
  searchCriteria.fieldName("CVE");
  searchCriteria.setStringValue("%" + cve + "%");
  searchCriteria.setStringTest(StringTestEnum.EQUAL);

  searchFilter.addSearchCriteriaItem(searchCriteria);
  try {
    //Perform the searcch
    IntrusionPreventionRules intrusionPreventionRules = intrusionPreventionRulesApi.searchIntrusionPreventionRules(searchFilter,
        "v1");
    //Get the rule IDs from the results
    for (IntrusionPreventionRule rule : intrusionPreventionRules.getIntrusionPreventionRules()) {
      ruleIDs.add(rule.getID());
    }

  } catch (ApiException e) {
    System.out.println(e.getMessage());
    e.printStackTrace();
  }
  return ruleIDs;
}

Example: Find computers that are not protected against a CVE

Python
def check_computers_for_ip_rule(api, configuration, api_version, api_exception, rule_id):
    """ Finds computers that do not have a specific intrusion prevention rule applied.

    :param api: The Deep Security API modules.
    :param configuration: Configuration object to pass to the api client.
    :param api_version: The version of the API to use.
    :param api_exception: The Deep Security API exception module.
    :param rule_id: The ID of the rule.
    :return: A list of computers that do not have the rule applied.
    """

    unprotected_computers = []

    try:
        # Create a list of computers
        computers_api = api.ComputersApi(api.ApiClient(configuration))
        computers_list = computers_api.list_computers(api_version, overrides=False)

        # Search the list of computers for those that do not have the IP rule
        for computer in computers_list.computers:
            computer_ip_list = computer.intrusion_prevention
            if computer_ip_list.rule_ids:
                if rule_id in computer_ip_list.rule_ids:
                    unprotected_computers.append(computer)
        return unprotected_computers

    except api_exception as e:
        return "Exception: " + str(e)
JavaScript
/*
* Finds computers that are not assigned a specific Intrusion Prevention rule.
* @param {object} api The api module.
* @param {Number} ruleID The ID of the rule.
* @param {String} apiVersion The api version to use.
* @return {Promise} A promise that contains an array of IDs of unprotected computers.
*/
exports.checkComputersForIPRule = function (api, ruleID, apiVersion) {
  return new Promise((resolve, reject) => {
    // Retreives computers from Deep Security Manager
    const getComputers = () => {
      const computersApi = new api.ComputersApi();
      return computersApi.listComputers(apiVersion, { overrides: false });
    };

    //Finds computers that are not assigned the rule
    const checkForRule = function (computers) {
      let unprotected = [];
      for (let i = 0; i < computers.computers.length; i++) {
  if (computers.computers[i].intrusionPrevention !== undefined) {
    const IDs = computers.computers[i].intrusionPrevention.ruleIDs;
    let found = false;
    if (IDs !== undefined) {
      for (let j = 0; j < IDs.length; j++) {
        if (IDs[j] === ruleID) {
    found = true;
    break;
        }
      }
    }
    if (!found) {
      unprotected.push(computers.computers[i]);
    }
  }
      }
      return unprotected;
    };
    
    getComputers()
      .then(computerlist => {
        resolve(checkForRule(computerlist));
      })
      .catch(error => {
        reject(error);
      });
  });
};
Java
/*
 * Finds computers that do not have a specific intrusion prevention rule applied.
 * @param ruleID The rule ID.
 * @return A Computers object that contains the computers that do not have the rule applied.
 */
public static Computers checkComputersForIPRule(Integer ruleID){
  Computers needsRule = new Computers();
  ComputersApi computersApi = new ComputersApi();
  try {
    Computers computers = computersApi.listComputers(false, "v1");
    for (Computer computer : computers.getComputers()) {
      IntrusionPreventionComputerExtension ipExt = computer.getIntrusionPrevention();
      if (ipExt.getRuleIDs() == null || !ipExt.getRuleIDs().contains(ruleID)) {
        needsRule.addComputersItem(computer);
      }
    }
  } catch (ApiException e) {
    e.printStackTrace();
  }
  return needsRule;
}

Example: Add intrusion prevention rules to computers’ policies

Python
def apply_rule_to_policies(api, configuration, api_version, api_exception, computers, rule_id):
    """ Adds an Intrusion Prevention rule to the policies of a list of computers.

    :param api: The Deep Security API modules.
    :param configuration: Configuration object to pass to the api client.
    :param api_version: The version of the API to use.
    :param api_exception: The Deep Security API exception module.
    :param computer: The Computer that is assigned the policy.
    :param rule_id: The ID of the Intrusion Prevention rule to add.
    :return: A list of PoliciesApi objects that were updated with the rule.
    """


    # Store IDs of policies to modify
    policy_ids = []
    for computer in computers:
        if computer.policy_id:
            policy_ids.append(computer.policy_id)

    # Store modified policies
    modified_policies = []

    for policy_id in policy_ids:
        try:
            # Get the current list of rules from the policy
            policies_api = api.PoliciesApi(api.ApiClient(configuration))
            current_rules = policies_api.describe_policy(policy_id, api_version, overrides=False)

            # Add the rule_id if it doesn't already exist in current_rules
            if current_rules.intrusion_prevention.rule_ids == None:
                current_rules.intrusion_prevention.rule_ids = rule_id

            elif rule_id not in current_rules.intrusion_prevention.rule_ids:
                current_rules.intrusion_prevention.rule_ids.append(rule_id)


            # Add the new and existing intrusion prevention rules to a policy
            intrusion_prevention_policy_extension = api.IntrusionPreventionPolicyExtension()
            intrusion_prevention_policy_extension.rule_ids = current_rules.intrusion_prevention.rule_ids
            policy = api.Policy()
            policy.intrusion_prevention = intrusion_prevention_policy_extension

            # Configure sending policy updates when the policy changes
            policy.auto_requires_update = "on"

            # Modify the policy on Deep Security Manager
            modified_policies.append(policies_api.modify_policy(policy_id, policy, api_version))

        except api_exception as e:
            return "Exception: " + str(e)

    return modified_policies
JavaScript
/*
* Assigns an Intrusion Prevention rule to the policy that is assigned to a computer.
* @param {object} api The api module.
* @param {Computer} computer The Computer that is assigned a policy.
* @param {number} ruleID The ID of the Intrusion Prevention rule to add.
* @param {String} apiVersion The api version to use.
* @return {Promise} A promise that contains the modified policy.
*/

exports.applyRuleToPolicy = function (api, computer, ruleID, apiVersion) {
  return new Promise((resolve, reject) => {
    // Retrieves the policy that we are modifying
    const getPolicy = policyID => {
      const policiesApi = new api.PoliciesApi();
      return policiesApi.describePolicy(policyID, apiVersion, { overrides: false });
    };

    // Creates a policy that includes the Intrusion Prevention rules
    // Rule is added to the currently assigned rules so they are not overwritten
    const addRulesToPolicyObject = currentRules => {
      if (currentRules !== undefined) {
        currentRules.push(ruleID);
      } else {
        currentRules = [ruleID];
      }
      const intrusionPreventionPolicyExtension = new api.IntrusionPreventionPolicyExtension();
      intrusionPreventionPolicyExtension.ruleIDs = currentRules;

      const policy = new api.Policy();
      policy.intrusionPrevention = intrusionPreventionPolicyExtension;
      policy.autoRequiresUpdate = api.Policy.AutoRequiresUpdateEnum.on;
      return policy;
    };

    // Updates the policy on Deep Security Manager
    const sendPolicyToManager = (policyID, policy) => {
      const policiesApi = new api.PoliciesApi();
      return policiesApi.modifyPolicy(policyID, policy, apiVersion, { overrides: false });
    };
    
    // Check that the computer is assigned a policy
    if(computer.policyID === undefined) {
      reject("Computer has no policy");
      return;
    } 
    getPolicy(computer.policyID)
      .then(policy => {
        const newPolicy = addRulesToPolicyObject(policy.intrusionPrevention.ruleIDs);
        resolve(sendPolicyToManager(computer.policyID, newPolicy));
      })
      .catch(error => {
        reject(error);
      });
  });
};
Java
/*
 * Adds an Intrusion Prevention rule to the policies of a list of computers.
 * @param needsRule A Computers object that contains computers that require the protection of the rule.
 * @param ruleID The ID of the rule to add to the policies
 */
public static void applyRuleToPolicies(Computers needsRule, Integer ruleID) {
  //Stores IDs of policies to modify (HashSet ensures no duplicates)
  HashSet<Integer> policyIDs = new HashSet<Integer>();
  
  //Get the policy IDs of each computer 
  ArrayList<Computer> computers = (ArrayList<Computer>) needsRule.getComputers();
  for (Computer computer : computers) {
    if (computer.getPolicyID() != null) {
      policyIDs.add(computer.getPolicyID());
    }
  }
    
  PoliciesApi policiesApi = new PoliciesApi();

  for (Integer policyID : policyIDs) {
    try {
      //Get the current list of rules from the policy
      ArrayList<Integer> currentRules = (ArrayList<Integer>) policiesApi.describePolicy(policyID, false, "v1").getIntrusionPrevention().getRuleIDs();

      //Add the new and existing intrusion prevention rules to a policy 
      IntrusionPreventionPolicyExtension intrusionPreventionPolicyExtension = new IntrusionPreventionPolicyExtension();
      intrusionPreventionPolicyExtension.setRuleIDs(currentRules);
      intrusionPreventionPolicyExtension.addRuleIDsItem(ruleID);
      Policy policy = new Policy();
      policy.setIntrusionPrevention(intrusionPreventionPolicyExtension);
      
      //Configure sending policy updates when the policy changes
      policy.setAutoRequiresUpdate(Policy.AutoRequiresUpdateEnum.ON);
      
      //Modify the policy on Deep Security Manager
      policiesApi.modifyPolicy(policyID, policy, false, "v1");
    } catch (ApiException e) {
      e.printStackTrace();
    }
  }
}
For information about authenticating API calls, see Authenticate with Deep Security Manager.

Apply recommendations

The API provides access to the recommendation scan results that have been made for a computer for the integrity monitoring, intrusion prevention, and log inspection modules. Use a ComputerIntrusionPreventionAssignmentsRecommendationsApi object to obtain an IntrusionPreventionAssignments object for a computer. The IntrusionPreventionAssignments object contains and provides access to the recommendations for that computer:

  • Recommended rules to assign and unassign
  • Scan status
  • When the last scan occurred

After you obtain the rule recommendations, you can apply them to computer policies, as illustrated in the Add intrusion prevention rules to computers’ policies example.

When there has been no recommendation scan performed on a computer, ComputerIntrusionPreventionAssignmentsRecommendationsApi returns null for rule IDs and the last scan occurrence.

Similar classes are provided for the integrity monitoring and log inspection modules:

  • ComputerIntegrityMonitoringAssignmentsRecommendationsApi and IntegrityMonitoringAssignments
  • ComputerLogInspectionAssignmentsRecommendationsApi and LogInspectionAssignments

Example: Obtain recommendations for intrusion prevention

Python
def get_intrusion_prevention_recommendations(api, configuration, api_version, api_exception, computer_id):
    """Obtains the list of recommended intrusion prevention rules to apply to a computer, according to the results of the last recommendation scan.

    :param api: The Deep Security API modules.
    :param configuration: Configuration object to pass to the api client.
    :param api_version: The version of the API to use.
    :param api_exception: The Deep Security API exception module.
    :param computer_id: The ID of the computer that was scanned.
    :return: A list of recommended Intrusion Prevention rules to apply to a computer,
    according to the results of the last recommendation scan or None if no scan was performed.
    """

    ip_recommendations_api = api.ComputerIntrusionPreventionRuleAssignmentsRecommendationsApi(api.ApiClient(configuration))
    ip_assignments = None

    try:
        ip_assignments = ip_recommendations_api.list_intrusion_prevention_rule_ids_on_computer(computer_id, api_version, overrides=False)
        return ip_assignments.recommended_to_assign_rule_ids

    except api_exception as e:
JavaScript
/*
* Obtains the list of recommended Intrusion Prevention rules to apply to a computer,
* according to the results of the last recommendation scan.* @param {object} api The api module.
* @param {object} api The api module.
* @param {Computer} computer The Computer that was scanned.
* @param {String} apiVersion The api version to use.
* @return {Promise} A promise that contains the recommended rules.
*/
exports.getRecommendedIPRules = function (api, computerID, apiVersion) {
  return new Promise((resolve, reject) => {
    // Obtains the results of the recommendation scan
    const getRecommendations = () => {
      const ipRecosApi = new api.ComputerIntrusionPreventionRuleAssignmentsRecommendationsApi();
      return ipRecosApi.listIntrusionPreventionRuleIDsOnComputer(
        computerID,
        apiVersion,
        { overrides: false }
      );
    };

    getRecommendations()
      .then(ipAssignments => {
        // Resolve the recommended rules
        resolve(ipAssignments.assignedRuleIDs);
      })
      .catch(error => {
        reject(error);
      });
  });
};
Java
/*
 * Obtains the list of recommended intrusion prevention rules to apply to a computer, 
 * according to the results of the last recommendation scan.
 * @param computerID The ID of the computer that was scanned.
 * @return A list of rule IDs, or null if no scan was performed.
 */
public static ArrayList<Integer> getIntrusionPreventionRecommendations(Integer computerID){
  ComputerIntrusionPreventionRuleAssignmentsRecommendationsApi ipRecosApi = new ComputerIntrusionPreventionRuleAssignmentsRecommendationsApi();
  IntrusionPreventionAssignments ipAssignments = null;
  try {
    ipAssignments = ipRecosApi.listIntrusionPreventionRuleIDsOnComputer(computerID, false, "v1");
  } catch (ApiException e) {
    e.printStackTrace();
  }
  return (ArrayList<Integer>) ipAssignments.getRecommendedToAssignRuleIDs();
}
For information about authenticating API calls, see Authenticate with Deep Security Manager.