Discover Vulnerabilities and Computer Security Statuses

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.

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 = deepsecurity.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 = deepsecurity.AntiMalwareConfigurationsApi(deepsecurity.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(client, configuration, api_version, api_exception, computer_id):
    """ Obtains certain anti-malware properties for a computer.

    :param client: The Deep Security API modules.
    :param configuration: Configuration object to pass to the 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 = client.ComputersApi(client.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 = client.AntiMalwareConfigurationsApi(client.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_prevevention_rules(client, configuration, api_version, api_exception):
    """ Retrieves the intrusion prevention rules that are applied to all computers.

    :param client: The Deep Security API modules.
    :param configuration: Configuration object to pass to the 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 = client.ComputersApi(client.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(client, configuration, api_version, api_exception, cve_id):
    """ Finds the intrusion prevention rules for a CVE.

    :param client: The Deep Security API modules.
    :param configuration: Configuration object to pass to the 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 = client.SearchCriteria()
    search_criteria.field_name = "CVE"
    search_criteria.string_value = "%" + cve_id + "%"
    search_criteria.string_test = "equal"

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

    try:
        # Search for all intrusion prevention rules for the CVE
        ip_rules_api = client.IntrusionPreventionRulesApi(client.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(client, configuration, api_version, api_exception, rule_id):
    """ Finds computers that do not have a specific intrusion prevention rule applied.

    :param client: The Deep Security API modules.
    :param configuration: Configuration object to pass to the 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 = client.ComputersApi(client.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(client, configuration, api_version, api_exception, computers, rule_id):
    """ Adds an Intrusion Prevention rule to the policies of a list of computers.

    :param client: The Deep Security API modules.
    :param configuration: Configuration object to pass to the 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 = client.PoliciesApi(client.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 = client.IntrusionPreventionPolicyExtension()
            intrusion_prevention_policy_extension.rule_ids = current_rules.intrusion_prevention.rule_ids
            policy = client.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(client, 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 client: The Deep Security API modules.
    :param configuration: Configuration object to pass to the 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 = client.ComputerIntrusionPreventionRuleAssignmentsRecommendationsApi(client.ApiClient(configuration))
    ip_assignments = None

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.