Create and Configure Policies

Use policies to protect computers using one or more Deep Security modules. This guide shows you how to create policies, configure the behavior of each protection module, and assign policies to computers.

For more information about Deep Security policies, see the Deep Security Help Center.

Create a policy

Create a policy that defines the behavior of the Deep Security modules that you are using, and that configures policy settings such as agent-manager communication, scanning behavior, logging, event retention, and network engine settings. After you create a policy you can assign it to one or more computers.

To create a policy you create a Policy object and then use the PoliciesApi class to add it to Deep Security Manager. Because policies are hierarchical, when creating a policy you need to indicate the ID of the parent policy. (Use an ID of 0 to create a top-level policy.)

The Policy object provides access to many policy properties:

  • The ID of the parent policy
  • The interfaces to which the policy applies rules
  • Whether to perform ongoing recommendation scans
  • Whether to automatically send policy changes to computers (AutoRequiresUpdate)
  • Policy settings

Tip: To see the available policy settings, get a policy and see its list of policy settings. (See the Describe a Policy operation.)

To create the policy, the PoliciesApi class uses the Create a Policy operation of the API.

Example: Create a policy below Base Policy

This example searches for the Base Policy, obtains its ID, and uses it as the parent of a new policy.

Python
def create_policy(client, configuration, api_version, api_exception, policy_name):
    """ Creates a policy that inherits from the base policy

    :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 policy_name: The name of the policy.
    :return: A PoliciesAPI object for the new policy.
    """

    # Create and configure a new policy
    new_policy = client.Policy()
    new_policy.name = policy_name
    new_policy.description = "Inherits from Base policy"
    new_policy.detection_engine_state = "off"
    new_policy.auto_requires_update = "on"

    # Create search criteria to retrieve the Base Policy
    search_criteria = client.SearchCriteria()
    search_criteria.field_name = "name"
    search_criteria.string_test = "equal"
    search_criteria.string_value = "%Base Policy%"
    search_criteria.max_results = 1

    # Create a search filter and pass the search criteria to it
    search_filter = client.SearchFilter(None, [search_criteria])

    try:
        # Search for the Base Policy
        policies_api = client.PoliciesApi(client.ApiClient(configuration))
        policy_search_results = policies_api.search_policies(api_version, search_filter=search_filter)

        # Set the parent ID of the new policy to the ID of the Base Policy
        new_policy.parent_id = policy_search_results.policies[0].id

        # Add the new policy to Deep Security Manager
        created_policy = policies_api.create_policy(new_policy, api_version)

        return created_policy

    except api_exception as e:
        return "Exception: " + str(e)
JavaScript
/*
 * Creates a policy that inherits from the Base Policy.
 * @param {Object} api The Deep Security API modules.
 * @param {String} policyName The name of the new policy.
 * @param {String} apiVersion The API version to use.
 * @returns {Promise} A promise object that resolves to the ID of the new policy.
*/
exports.createPolicy = function (api, policyName, apiVersion) {
  return new Promise((resolve, reject) => {
    const policiesApi = new api.PoliciesApi();

    // Create the policy object and set properties
    const newPolicy = new api.Policy();
    newPolicy.name = policyName;
    newPolicy.description = "Inherits from Base Policy";
    newPolicy.recommendationScanMode = api.Policy.RecommendationScanModeEnum.off;
    newPolicy.autoRequiresUpdate = api.Policy.AutoRequiresUpdateEnum.on;

    // Create a search criteria to find the Base Policy
    const searchCriteria = new api.SearchCriteria();
    searchCriteria.fieldName = "name";
    searchCriteria.stringValue = "Base Policy";
    searchCriteria.stringTest = "equal";

    // Create a search filter
    const searchFilter = new api.SearchFilter();
    searchFilter.searchCriteria = [searchCriteria];
    
    // Add the search filter  to a search options object
    const searchOptions = {
      searchFilter: searchFilter 
    };

    // Performs the search
    const searchPolicy = () => policiesApi.searchPolicies(apiVersion, searchOptions);
    // Add the policy to Deep Security Manager
    const createPolicy = data => {
      newPolicy.parentID = data.policies[0].ID;
      return policiesApi.createPolicy(newPolicy, apiVersion, { overrides: false });
    };

    searchPolicy()
      .then(createPolicy)
      .then(data => {
        resolve(data.ID);
      })
      .catch(error => {
        reject(error);
      });
  });
};
Java
/*
 * Creates a policy that inherits from the Base Policy
 * @param dsmClient An ApiClient for the Deep Security Manager
 * @return The created policy
 */
public static Policy createPolicy(String policyName){
    Policy newPolicy = null;
    //Create and configure policy object
    Policy policy = new Policy();
    policy.setName(policyName);
    policy.setDescription("Inherits from Base policy");
    policy.setRecommendationScanMode(Policy.RecommendationScanModeEnum.OFF);
    policy.setAutoRequiresUpdate(Policy.AutoRequiresUpdateEnum.ON);
    
    //Create search criteria to retrieve the Base Policy
    SearchCriteria searchCriteria = new SearchCriteria();
    searchCriteria.setFieldName("name");
    searchCriteria.setStringTest(SearchCriteria.StringTestEnum.EQUAL);
    searchCriteria.setStringValue("Base Policy");
            
    //Add the criteria to a search filter
    SearchFilter sf = new SearchFilter();
    sf.addSearchCriteriaItem(searchCriteria);

    //Perform the search
    PoliciesApi policiesApi = new PoliciesApi();
    try {
        Policies policies = policiesApi.searchPolicies(sf, false, "v1");
        
        //Get the ID and use it as the parent policy
        Integer id;
        if (policies.getPolicies().size() > 0) {
            id = policies.getPolicies().get(0).getID();
            policy.setParentID(id);
            
        //Create the policy
        newPolicy = policiesApi.createPolicy(policy, false, "v1");
        }
    } catch (ApiException e) {
        System.out.println(e.getMessage());
        e.printStackTrace();
    }
    return newPolicy;
}

The Policy object that is created contains no module configurations or setting values. When the configurations and settings are omitted, the values are inherited from the parent policy. Therefore, the policy that is created inherits almost all behavior from the Base Policy.

Also note that policy ID’s are immutable, so if you know the ID of the policy you can just use it instead of searching and getting it.

To use the API to interact with policies, use the policies endpoint. (See the Policies group of operations in the API Reference.)

For information about authenticating API calls, see Authenticate with Deep Security Manager.

Protection module and policy classes

The following types of classes enable you to configure protection modules, such as Firewall and Anti-Malware, and the policies that use them:

  • The PoliciesApi class provides access to policies with create, modify, delete, and search capabilities.
  • Policy-level configuration objects, such as FirewallPolicyExtension, control the behavior of protection modules for a policy.  Common properties that you can access are the state of the module (on or off) and some settings.
  • The PolicySettings class provides access to policy-level protection module settings.

Settings values and inheritance

When configuring policies, a setting with no value (or an empty string) inherits its value from the parent policy. If the policy is a top-level policy in the hierarchy, the setting inherits its value from default policy settings.

Configure Firewall

Generally, use the following steps to configure the Firewall module in a policy:

  1. Create or modify the firewall-related common objects to use in your policy: firewall rules, MAC lists, rule contexts, stateful configurations. See Create and Configure Common Objects for Policies and Computers.
  2. Create a FirewallPolicyExtension object and add the IDs of common objects. Also configure the running state (on or off).
  3. Create a PolicySettings object to configure runtime settings of the module.
  4. Create a Policy object and add the FirewallPolicyExtension and PolicySettings objects.
  5. Use a PoliciesApi object to add or update the policy on Deep Security Manager.

For more information about the Deep Security firewall, see the Deep Security Help Center.

Example: Configure Firewall

The following example code creates a Policy object, and modifies its FirewallPolicyExtension. The policy is then updated on Deep Security Manager according to the Policy object.

Python
def modify_firewall_policy(client, configuration, api_version, api_exception, policy_id):
    """ Modifies a policy to set the firewall state to on and disables reconnaissance 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 policy_id: The ID of the policy to modify.
    :return: A PoliciesApi object that contains the ID of the modified policy.
    """
    #
    policies_api = client.PoliciesApi(client.ApiClient(configuration))
    policy = client.Policy()
    firewall_policy_extension = client.FirewallPolicyExtension()

    # Turn on firewall
    firewall_policy_extension.state = "on"

    # Add the firewall state to the policy
    policy.firewall = firewall_policy_extension

    # Turn off reconnaissance scan
    policy_settings = client.PolicySettings()
    setting_value = client.SettingValue()
    setting_value.value = False
    policy_settings.firewall_setting_reconnaissance_enabled = setting_value

    # Add reconnaissance scan state to the policy
    policy.policy_settings = policy_settings

    try:
        # Modify the policy on Deep Security Manager
        policies = policies_api.modify_policy(policy_id, policy, api_version)
        return policies

    except api_exception as e:
        return "Exception: " + str(e)
JavaScript
/*
 * Modifies a policy to set the firewall state to ON and disables reconnassaince scan.
 * @param {ApiClient} api The Deep Security API exports.
 * @param {String} policyID The ID of the policy to modify.
 * @param {String} apiVersion The API version to use.
 * @returns {Promise} A promise object that resolves to the ID of the modified policy.
*/
exports.modifyFirewallPolicy = function (api, policyID, apiVersion) {
  return new Promise((resolve, reject) => {
    const policy = new api.Policy();
    const policiesApi = new api.PoliciesApi();
    const firewallPolicyExtension = new api.FirewallPolicyExtension();

    //Turn on firewall
    firewallPolicyExtension.state = api.FirewallPolicyExtension.StateEnum.on;

    //Add to the policy
    policy.firewall = firewallPolicyExtension;

    //Turn off reconnaisance scan
    const policySettings = new api.PolicySettings();
    const settingValue = new api.SettingValue();
    settingValue.value = "false";
    policySettings.firewallSettingReconnaissanceEnabled = settingValue;

    //Add to the policy
    policy.policySettings = policySettings;

    //Send the change to Deep Security Manager
    policiesApi
      .modifyPolicy(policyID, policy, apiVersion, { overrides: false })
      .then(modifiedPolicy => {
        resolve(modifiedPolicy);
      })
      .catch(error => {
        reject(error);
      });
  });
};
Java
/*
 * Modifies a policy to set the firewall state to ON and enable reconnaissance scan.
 * @param policyId The ID of the policy to modify.
 */
public static void ModifyFirewallPolicy(Integer policyId){
    PoliciesApi policiesApi = new PoliciesApi();
    Policy policy = new Policy();
    FirewallPolicyExtension firewallPolicyExtension = new FirewallPolicyExtension();

    //Turn on firewall
    firewallPolicyExtension.setState(FirewallPolicyExtension.StateEnum.ON);
    //Add to the policy
        policy.setFirewall(firewallPolicyExtension);
        
    //Turn off Reconnaissance Scan
    PolicySettings policySettings = new PolicySettings();
    SettingValue settingValue = new SettingValue();
    settingValue.setValue("false");
    policySettings.setFirewallSettingReconnaissanceEnabled(settingValue);
    //Add to the policy
    policy.setPolicySettings(policySettings);   
    
    //Send the changes to Deep Security Manager
    try{
        policiesApi.modifyPolicy(policyId, policy, false, "v1");
    } catch (ApiException e) {
        e.printStackTrace();
    }               
}
For information about authenticating API calls, see Authenticate with Deep Security Manager.

Configure Intrusion Prevention

Generally, use the following steps to configure Intrusion Prevention in a policy:

  1. Create or modify the Intrusion Prevention-related common objects to use in your policy: rules and application types. See Create and Configure Common Objects for Policies and Computers.
  2. Create an IntrusionPreventionPolicyExtension object and add the IDs of common objects. Also configure the running state (on or off).
  3. Create a PolicySettings object to configure runtime settings of the module.
  4. Create a Policy object and add the IntrusionPreventionPolicyExtension and PolicySettings objects.
  5. Use a PoliciesApi object to add or update the policy on Deep Security Manager.

For more information about Deep Security intrusion prevention, see the Deep Security Help Center.

Example: Configure intrusion prevention settings

The following example code creates a PolicySettings object and sets the value of the intrusionPreventionSettingAutoApplyRecommendationsEnables property to cause intrusion prevention to automatically apply rules found via recommendation scans. The object is added to a Policy object that is used to modify a policy.

Python
def modify_intrusion_prevention_policy(client, configuration, api_version, api_exception, policy_id):
    """ Turns on the automatic application of recommendation scans for intrusion prevention in a policy.

    :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 policy_id: The ID of the policy to modify.
    :return: A PoliciesApi object with the modified policy.
    """

    # Configure the setting
    policy_settings = client.PolicySettings()
    setting_value = client.SettingValue()
    setting_value.value = "yes"
    policy_settings.intrusion_prevention_setting_auto_apply_recommendations_enables = setting_value

    # Add the setting to a policy
    policy = client.Policy()
    policy.policy_settings = policy_settings

    try:
        # Modify the policy on Deep Security Manager
        policies_api = client.PoliciesApi(client.ApiClient(configuration))
        return policies_api.modify_policy(policy_id, policy, api_version)

    except api_exception as e:
        return "Exception: " + str(e)
JavaScript
/*
* Turns on the automatic application of recommendation scans for Intrusion Prevention in a policy.
* @param {Object} api The Deep Security API modules.
* @param {Number} policyId The ID of the policy to modify.
* @param {String} apiVersion The version of the api to use.
* @returns {Promise} A promise that contains the modified policy.
*/
exports.modifyIntrusionPreventionPolicy = function (api, policyID, apiVersion) {
  return new Promise((resolve, reject) => {
    // Configure the setting
    const policySettings = new api.PolicySettings();
    const settingValue = new api.SettingValue();
    settingValue.value = "yes";
    policySettings.intrusionPreventionSettingAutoApplyRecommendationsEnabled = settingValue;

    // Add to a policy
    const policy = new api.Policy();
    policy.policySettings = policySettings;

    // Modifies the policy on Deep Security Manager
    const modify = function() {
      const policiesApi = new api.PoliciesApi();
      return policiesApi.modifyPolicy(policyID, policy, apiVersion, { overrides: false });
    };

    modify()
      .then(policy => {
        resolve(policy);
      })
      .catch(error => {
        reject(error);
      });
  });
};
Java
/*
 * Turns on the automatic application of recommendation scans for Intrusion Prevention in a policy.
 * @param policyId The ID of the policy to modify.
 */
public static void modifyIntrusionPreventionPolicy(Integer policyId){
    //Create a setting object and turn on automatic application of recommendation scans
    PolicySettings policySettings = new PolicySettings();
    SettingValue settingValue = new SettingValue();
    settingValue.setValue("Yes");
    policySettings.setIntrusionPreventionSettingAutoApplyRecommendationsEnabled(settingValue);
    
    //Add to a policy
    Policy policy = new Policy();
    policy.setPolicySettings(policySettings);
    
    //Update the policy on Deep Security Manager
    PoliciesApi policiesApi = new PoliciesApi();    
    try {
        policiesApi.modifyPolicy(policyId, policy, false, "v1");
    } catch (ApiException e) {
        e.printStackTrace();
    }
}

For information about authenticating API calls, see Authenticate with Deep Security Manager.

Configure Anti-Malware

Generally, use the following steps to configure Anti-Malware in a policy:

  1. Create or modify the Anti-Malware-related common objects to use in your policy: directory lists, file and file extension lists, and malware scan configurations (real time, scheduled, and manual).  See Create and Configure Common Objects for Policies and Computers.
  2. Create an AntiMalwarePolicyExtension object and add the IDs of common objects. Also configure the running state (on or off)
  3. Create a PolicySettings object to configure runtime settings of the module.
  4. Create a Policy object and add the AntiMalwarePolicyExtension and PolicySettings objects.
  5. Use a PoliciesApi object to add or update the policy on Deep Security Manager.

Example: Set the real time Anti-Malware scan configuration

The following example creates an AntiMalwarePolicyExtension object and uses it to turn on the Anti-Malware module, set the real time scan configuration to use, and specify the scan schedule for real time scans.

Python
def modify_anti_malware_policy(client, configuration, api_version, api_exception, policy_id, real_time_scan_config_id, schedule_id):

    # Create and configure the Anti-maware policy
    anti_malware_policy_config = client.AntiMalwarePolicyExtension()
    anti_malware_policy_config.state = "on"
    anti_malware_policy_config.real_time_scan_configuration_id = real_time_scan_config_id
    anti_malware_policy_config.real_time_scan_schedule_id = schedule_id

    # Add the configuration to the policy
    policy = client.Policy()
    policy.anti_malware = anti_malware_policy_config

    # Modify the policy on Deep Security Manager
    try:
        policies_api = client.PoliciesApi(client.ApiClient(configuration))
        return policies_api.modify_policy(policy_id, policy, api_version)

    except api_exception as e:
        return "Exception: " + str(e)
JavaScript
/*
 * Modifies a policy to set the Anti-Malware state to ON and set the real time scan configuration.
 * @param {ApiClient} api The Deep Security API exports.
 * @param {Integer} policyID The ID of the policy to modify.
 * @param {Integer} realTimeScanConfigID The ID of the real time scan configuration to use.
 * @param {Integer} scheduleID The ID of the schedule to use for real time scans.
 * @param {String} apiVersion The API version to use.
 * @returns {Promise} A promise object that resolves to the ID of the modified policy.
*/
exports.modifyAntiMalwarePolicy = function (api, policyID, realTimeScanConfigID, scheduleID, apiVersion) {
  return new Promise((resolve, reject) => {
    const policy = new api.Policy();
    const policiesApi = new api.PoliciesApi();

    //Create and configure the AntiMalwarePolicyExtension object
    const antiMalwarePolicyExtension = new api.AntiMalwarePolicyExtension();
    antiMalwarePolicyExtension.state = api.AntiMalwarePolicyExtension.StateEnum.on;
    antiMalwarePolicyExtension.realTimeScanConfigurationID = realTimeScanConfigID;
    antiMalwarePolicyExtension.realTimeScanScheduleID = scheduleID;

    //Add to the policy
    policy.antiMalware = antiMalwarePolicyExtension;

    //Send the change to Deep Security Manager
    policiesApi.modifyPolicy(policyID, policy, apiVersion, { overrides: false })
      .then(data => {
        resolve(data);
      })
      .catch(error => {
        reject(error);
      });
  });
};
Java
/*
 * Turns on Anti-Malware for a policy and sets the real time scan configuration to use.
 * @param policyID The ID of the policy to configure.
 * @param realTimieScanConfigID The ID of the real time scan configuration.
 * @param scheduleID The ID fo the schedule to use for real time scans.
 * @return The modified policy.
 */
public static Policy configureAntiMalware(Integer policyID, Integer realTimeScanConfigID, Integer scheduleID) {
    //Create an AntiMalwarePolicyExtension object and configure
    AntiMalwarePolicyExtension antiMalwarePolicyExtension = new AntiMalwarePolicyExtension();
    antiMalwarePolicyExtension.setState(AntiMalwarePolicyExtension.StateEnum.ON);
    antiMalwarePolicyExtension.setRealTimeScanConfigurationID(realTimeScanConfigID);
    antiMalwarePolicyExtension.setRealTimeScanScheduleID(scheduleID);
    
    Policy policy = new Policy();
    PoliciesApi policiesApi = new PoliciesApi();
    try {
        //Modify the policy on Deep Security Manager
        policy = policiesApi.modifyPolicy(policyID, policy, false, "v1");
    } catch (ApiException e) {
        e.printStackTrace();
    }
    return policy;
}
For information about authenticating API calls, see Authenticate with Deep Security Manager.

For more information about Deep Security anti-malware, see the Deep Security Help Center.

Configure Web Reputation

Generally, use the following steps to configure Web Reputation in a policy:

  1. Create a WebReputationPolicyExtension object that configures the running state (on or off).
  2. Create a PolicySettings object to configure runtime settings of the module.
  3. Create a Policy object and add the WebReputationPolicyExtension and PolicySettings objects.
  4. Use a PoliciesApi object to add or update the policy on Deep Security Manager.

For more information about Deep Security web reputation, see the Deep Security Help Center.

Example: Turn on Web Reputation and configure settings

The following example code creates a WebReputationPolicyExtension object, then sets the web reputation state, security level, and enables Smart Protection Server. The object is then added to a Policy object which is used to modify a policy on Deep Security Manager.

Python
def configure_web_reputation(client, configuration, api_version, api_exception, policy_id, security_level):
    """ Turns on web reputation, sets the security level, and uses Smart Protection for a policy.

    :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 policy_id: The ID of the policy to modify.
    :param security_level: The security level to set for Web Reputation.
    :return:
    """

    # Enable Web Reputation
    policy_config_web_reputation = client.WebReputationPolicyExtension()
    policy_config_web_reputation.state = "on"

    # Add to a policy
    policy = client.Policy()
    policy.web_reputation = policy_config_web_reputation

    # Set the security level
    policy_settings = client.PolicySettings()
    security_level_setting = client.SettingValue()
    security_level_setting.value = security_level
    policy_settings.web_reputation_setting_security_level = security_level_setting

    # Enable Smart Protection
    smart_protection_allow_global = client.SettingValue()
    smart_protection_allow_global.value = True
    policy_settings.web_reputation_setting_smart_protection_local_server_allow_off_domain_global = smart_protection_allow_global

    # Add the settings
    policy.policy_settings = policy_settings

    try:
        # Modify the policy on Deep Security Manager
        policies_api = client.PoliciesApi(client.ApiClient(configuration))
        return policies_api.modify_policy(policy_id, policy, api_version)

    except api_exception as e:
        return "Exception: " + str(e)
JavaScript
/*
 * Turns on Web Reputation, sets the security level, and uses Smart Protection for a policy.
 * @param {Object} api The Deep Security API modules.
 * @param {Number} policyId The ID of the policy to modify.
 * @param {Number} securityLevel The security level to set for web reputation.
 * @param {String} apiVersion The version of the api to use.
 * @return {Promise} A promise that contains the modified policy
*/
exports.configureWebReputation = function (api, policyID, securityLevel, apiVersion) {
  return new Promise((resolve, reject) => {
    // Set the state
    const webReputationPolicyExtension = new api.WebReputationPolicyExtension();
    webReputationPolicyExtension.state =
      api.WebReputationPolicyExtension.StateEnum.on;

    // Add to a policy
    const policy = new api.Policy();
    policy.webReputation = webReputationPolicyExtension;

    // Setting for security level
    const policySettings = new api.PolicySettings();
    const securityLevelSetting = new api.SettingValue();
    securityLevelSetting.value = securityLevel;
    policySettings.webReputationSettingSecurityLevel = securityLevelSetting;

    // Setting for Smart Protection
    const smartProtectionAllowGlobal = new api.SettingValue();
    smartProtectionAllowGlobal.value = "true";
    policySettings.webReputationSettingSmartProtectionLocalServerAllowOffDomainGlobal = smartProtectionAllowGlobal;

    // Add the settings
    policy.policySettings = policySettings;

    // Modifies the policy on Deep Security
    const modify = () => {
      const policiesApi = new api.PoliciesApi();
      return policiesApi.modifyPolicy(policyID, policy, apiVersion, { overrides: false });
    };

    modify()
      .then(modifiedPolicy => {
        resolve(modifiedPolicy);
      })
      .catch(error => {
        reject(error);
      });
  });
};
Java
/*
 * Sets the Web Reputation module state to ON, sets the security level, and enables
 * Smart Protection Server for a policy.
 * @param policyId The ID of the policy to configure.
 * @param dsmClient The ApiClient for the Deep Security Manager.
 * @param securityLevel The security level to set for web reputation.
 */
public static void setSecurityLevel(Integer policyId, String securityLevel){
    Policy policy = new Policy();
    //Set the state, security level, and Smart Protection Server
    WebReputationPolicyExtension webReputationPolicyExtension = new WebReputationPolicyExtension();
    webReputationPolicyExtension.setState(WebReputationPolicyExtension.StateEnum.ON);
    
    SettingValue securityLevelValue = new SettingValue();
    securityLevelValue.setValue(securityLevel);
    
    PolicySettings policySettings = new PolicySettings();
    policySettings.setWebReputationSettingSecurityLevel(securityLevelValue);
    
    SettingValue allowGlobalValue = new SettingValue();
    allowGlobalValue.setValue("true");
    
    policySettings.setWebReputationSettingSmartProtectionLocalServerAllowOffDomainGlobal(allowGlobalValue);

    //Update the policy object
    policy.setWebReputation(webReputationPolicyExtension);
    policy.setPolicySettings(policySettings);
    
    //Send the policy to Deep Security Manager
    PoliciesApi policiesApi = new PoliciesApi();
    try {
        policiesApi.modifyPolicy(policyId, policy, false, "v1");
    } catch (ApiException e) {
        e.printStackTrace();
    }
}
For information about authenticating API calls, see Authenticate with Deep Security Manager.

Configure Integrity Monitoring

Generally, use the following steps to configure Integrity Monitoring in a policy:

  1. Create or modify the Integrity Monitoring rules that you want to use in your policy. See Create and Configure Common Objects for Policies and Computers.
  2. Create an IntegrityMonitoringPolicyExtension object and add the IDs of the rules to use. Also configure the running state (on or off).
  3. Create a PolicySettings object to configure runtime settings of the module.
  4. Create a Policy object and add the IntegrityMonitoringPolicyExtension and PolicySettings objects.
  5. Use a PoliciesApi object to add or update the policy on Deep Security Manager.

For more information about Deep Security integrity monitoring, see the Deep Security Help Center.

Example: Add Integrity Monitoring rules to a policy

The following example code adds rule IDs to an IntegrityMonitoringPolicyExtension object. The object is added to a Policy object which is used to update a policy on Deep Security Manager.

Python
def configure_integrity_monitoring(client, configuration, api_version, api_exception, policy_id, im_rule_ids):
    """ Adds integrity monitoring rules to a policy.

    :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 policy_id: The ID of the policy to modify.
    :param im_rule_ids: A list of integrity monitoring rule IDs.
    :return: A PoliciesApi object containing a policy containing the added integrity monitoring rules.
    """

    # Get the rule ID
    policy_config_integrity_monitoring = client.IntegrityMonitoringPolicyExtension()
    policy_config_integrity_monitoring.rule_ids = im_rule_ids

    # Add the rule IDs a policy
    policy = client.Policy()
    policy.integrity_monitoring = policy_config_integrity_monitoring

    try:
        # Modify the policy on Deep Security Manager
        policies_api = client.PoliciesApi(client.ApiClient(configuration))
        return policies_api.modify_policy(policy_id, policy, api_version)

    except api_exception as e:
        return "Exception: " + str(e)
JavaScript
/*
 * Adds Integrity Monitoring rules to a policy.
 * @param {Object} api The Deep Security API modules.
 * @param {Number} policyId The ID of the policy to modify.
 * @param {[Number]} imRules An array of integrity monitoring rule IDs.
 * @param {String} apiVersion The version of the api to use.
 * @returns {Promise} A promise that contains the modified policy
*/
exports.configureIntegrityMonitoring = function (api, policyID, imRules, apiVersion) {
  return new Promise((resolve, reject) => {
    // Add rule IDs to a PolicyLevelConfigurationForTheIntegrityMonitoringModule object
    const integrityMonitoringPolicyExtension = new api.IntegrityMonitoringPolicyExtension();
    integrityMonitoringPolicyExtension.ruleIDs = imRules;

    // Add to a policy
    const policy = new api.Policy();
    policy.integrityMonitoring = integrityMonitoringPolicyExtension;

    //Modifies the policy on Deep Security Manager
    const modify = () => {
      const policiesApi = new api.PoliciesApi();
      return policiesApi.modifyPolicy(policyID, policy, apiVersion, { overrides: false });
    };

    return modify()
      .then(data => {
        resolve(data);
      })
      .catch(error => {
        reject(error);
      });
  });
};
Java
/*
 * Adds Integrity Monitoring rules to a policy.
 * @param policyID The ID of the policy to modify.
 * @param dsmClient The API client for the Deep Security Manager.
 * @param ruleIds An ArrayList of rule IDs to add.
 */
public static void configureIntegrityMonitoring(Integer policyId, ArrayList<Integer> ruleIds){
    //Get the policy to modify
    PoliciesApi policiesApi = new PoliciesApi();
    Policy policy = new Policy();
    //Add the rule ID's
    IntegrityMonitoringPolicyExtension integrityMonitoringPolicyExtension = new IntegrityMonitoringPolicyExtension();
    for (Integer ruleId : ruleIds){
        integrityMonitoringPolicyExtension.addRuleIDsItem(ruleId);
    }
    policy.setIntegrityMonitoring(integrityMonitoringPolicyExtension);
    //Send the policy to Deep Security Manager
    try {
        policiesApi.modifyPolicy(policyId, policy, false, "v1");
    } catch (ApiException e) {
        e.printStackTrace();
    }
}
For information about authenticating API calls, see Authenticate with Deep Security Manager.

Configure Log Inspection

Generally, use the following steps to configure Log Inspection in a policy:

  1. Create or modify the Log Inspection rules that you want to use in your policy. See Create and Configure Common Objects for Policies and Computers.
  2. Create a LogInspectionPolicyExtension object and add the IDs of the rules to use. Also configure the running state (on or off).
  3. Create a PolicySettings object to configure runtime settings of the module.
  4. Create a Policy object and add the LogInspectionPolicyExtension and PolicySettings objects.
  5. Use a PoliciesApi object to add or update the policy on Deep Security Manager.

For more information about Deep Security log inspection, see the Deep Security Help Center.

Example: Add a log inspection rule to a policy

Python
def configure_log_inspection(client, configuration, api_version, api_exception, policy_id, li_rules):
    """ Adds a log inspection rule to a policy.

    :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 policy_id: The ID of the policy to modify.
    :param li_rules: A list of log inspection rule IDs to add.
    :return: A PoliciesApi object containing a policy containing the added log inspection rules.
    """

    # Add log inspection rules to the policy from li_rules
    policies_api = client.PoliciesApi(client.ApiClient(configuration))
    policy_config_log_inspection = client.LogInspectionPolicyExtension()
    policy_config_log_inspection.rule_ids = li_rules

    # Update the policy with the log inspection rules
    policy = client.Policy()
    policy.log_inspection = policy_config_log_inspection

    try:
        # Modify the policy on Deep Security Manager
        return policies_api.modify_policy(policy_id, policy, api_version)

    except api_exception as e:
        return "Exception: " + str(e)
JavaScript
/*
 * Adds a Log Inspection rule to a policy.
 * @param {Object} api The Deep Security API modules.
 * @param {Number} policyId The ID of the policy to modify.
 * @param {Number} liRules An array of Log Inspection rule IDs to add.
 * @param {String} apiVersion The version of the api to use.
 * @returns {Promise} A promise that contains the modified policy.
*/
exports.configureLogInspection = function (api, policyID, liRules, apiVersion) {
  return new Promise((resolve, reject) => {

    const logInspectionPolicyExtension = new api.LogInspectionPolicyExtension();
    logInspectionPolicyExtension.ruleIDs = liRules;
    //Add to a policy
    const policy = new api.Policy();
    policy.logInspection = logInspectionPolicyExtension;

    //Modifies the policy on Deep Security Manager
    const modify = () => {
      const policiesApi = new api.PoliciesApi();
      return policiesApi.modifyPolicy(policyID, policy, apiVersion, { overrides: false });
    };

    return modify()
      .then(data => {
        resolve(data);
      })
      .catch(error => {
        reject(error);
      });
  });
};
Java
/*
 * Adds a Log Inspection rule to a policy.
 * @param policyId The ID of the policy to modify.
 * @param liRule The rule ID to add.
 */
public static void addLogInspectionRule(Integer policyId, Integer liRule){
    //Create a policy and add the rule ID
    Policy policy = new Policy();

    LogInspectionPolicyExtension logInspectionPolicyExtension = new LogInspectionPolicyExtension();
    logInspectionPolicyExtension.addRuleIDsItem(liRule);
    policy.setLogInspection(logInspectionPolicyExtension);
    
    //Update the policy on Deep Security Manager
    PoliciesApi policiesApi = new PoliciesApi();
    try {
        policiesApi.modifyPolicy(policyId, policy, false, "v1");
    } catch (ApiException e) {
        e.printStackTrace();
    }
}

For information about authenticating API calls, see Authenticate with Deep Security Manager.

Configure Application Control

Generally, use the following steps to configure Application Control in a policy:

  1. Create an ApplicationControlPolicyExtension object and add the Ruleset IDs to use. Also configure the running state (on or off).
  2. Create an PolicySettings object to configure runtime settings of the module.
  3. Create a Policy object and add the ApplicationControlPolicyExtension and PolicySettings objects.
  4. Use a PoliciesApi object to add or update the policy on Deep Security Manager.

For more information about Deep Security application control, see Deep Security Help Center.

Example: Turn on application control

The following example code creates an ApplicationControlPolicyExtension object and turns on application control. The object is added to a Policy object which is used to modify a policy on Deep Security Manager.

Python
def configure_application_control(client, configuration, api_version, api_exception, policy_id):
    """ Modifies a policy to set the application control state to on.

    :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 policy_id: The ID of the policy to modify.
    :return: A PoliciesApi object that contains the ID of the modified policy.
    """

    # Get the policy
    policies_api = client.PoliciesApi(client.ApiClient(configuration))

    # Turn on Application Control
    application_control_policy_extension = client.ApplicationControlPolicyExtension()
    application_control_policy_extension.state = "on"

    # Update the policy
    update_policy = client.Policy()
    update_policy.application_control = application_control_policy_extension

    try:
        # Modify the policy on Deep Security Manager
        app_control_policy = policies_api.modify_policy(policy_id, update_policy, api_version, overrides=False)
        return app_control_policy

    except api_exception as e:
        return "Exception: " + str(e)
JavaScript
/*
 * Modifies a policy to set the Application Control state to ON.
 * @param {ApiClient} api The Deep Security API exports.
 * @param {String} policyID The ID of the policy to modify.
 * @param {String} apiVersion The API version to use.
 * @returns {Promise} A promise object that resolves to the ID of the modified policy.
*/
exports.configureApplicationControl = function (api, policyID, apiVersion) {
  return new Promise((resolve, reject) => {
    const policy = new api.Policy();
    const policiesApi = new api.PoliciesApi();
    const appControlPolicyExtension = new api.ApplicationControlPolicyExtension();

    //Turn on application control
    appControlPolicyExtension.state =
      api.ApplicationControlPolicyExtension.StateEnum.on;

    //Add to the policy
    policy.applicationControl = appControlPolicyExtension;

    //Send the change to Deep Security Manager
    policiesApi.modifyPolicy(policyID, policy, apiVersion, { overrides: false })
      .then(data => {
        resolve(data);
      })
      .catch(error => {
        reject(error);
      });
  });
};
Java
/*
 * Turns on the Application Control module for a policy.
 * @param policyId The ID of the policy to modify.
 * @param dsmClient The ApiClient for the Deep Security Manager.
 */
public static void configureApplicationControl(Integer policyId){
    //Get the policy to modify
    PoliciesApi policiesApi = new PoliciesApi(); 
    
    //Turn on ApplicationControl
    ApplicationControlPolicyExtension appControlPolicyExtension = new ApplicationControlPolicyExtension();
    appControlPolicyExtension.setState(ApplicationControlPolicyExtension.StateEnum.ON);
    
    //Update the policy
    Policy updatePolicy = new Policy();
    updatePolicy.setApplicationControl(appControlPolicyExtension);
    try {
        //Update the policy on Deep Security Manager
        policiesApi.modifyPolicy(policyId, updatePolicy, false, "v1");
    } catch (ApiException e) {
        e.printStackTrace();
    }
}
For information about authenticating API calls, see Authenticate with Deep Security Manager.

Assign a policy to a computer

Assign a policy to a computer to protect the compter according to the policy settings and the configuration of the security modules:

  1. Create a Computer object.
  2. Set the policy ID to use on the object.
  3. Use a ComputersApi object to update the computer on Deep Security Manager.

Example: Search for a policy and add it to a computer

Python
def assign_linux_server_policy(client, configuration, api_version, api_exception, computer_id):
    """ Assigns a Linux server policy to 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 to assign the policy to.
    :return: A ComputersApi object that contains the Linux server policy.
    """

    # Create search criteria to retrieve the Base Policy
    search_criteria = client.SearchCriteria()
    search_criteria.field_name = "name"
    search_criteria.string_test = "equal"
    search_criteria.string_value = "%Linux Server%"

    # Create a search filter
    search_filter = client.SearchFilter(None, [search_criteria])
    policies_api = client.PoliciesApi(client.ApiClient(configuration))
    computers_api = client.ComputersApi(client.ApiClient(configuration))
    computer = client.Computer()

    try:
        # Perform the search
        policy_search_results = policies_api.search_policies(api_version, search_filter=search_filter)

        # Assign the policy to the computer
        computer.policy_id = policy_search_results.policies[0].id

        return computers_api.modify_computer(computer_id, computer, api_version)

    except api_exception as e:
        return "Exception: " + str(e)
JavaScript
/*
 * Assign a Linux server policy to a computer.
 * @param {Object} api The Deep Security API modules.
 * @param {Number} computerID The ID of the computer to assign the policy.
 * @param {String} apiVersion The API version to use.
 * @returns {Promise} A promise object that resolves to the modified computer object.
 */
exports.assignLinuxServerPolicy = function (api, computerID, apiVersion) {
  return new Promise((resolve, reject) => {
    // Create the search criteria
    const searchCriteria = new api.SearchCriteria();
    searchCriteria.fieldName = "name";
    searchCriteria.stringValue = "%Linux Server%";
    searchCriteria.stringTest = "equal";
    searchCriteria.stringWildcards = "true";

    // Create a search filter
    const searchFilter = new api.SearchFilter();
    searchFilter.searchCriteria = [searchCriteria];

    const policiesApi = new api.PoliciesApi();

    // Searches for the policy
    const searchPolicy = () =>
      policiesApi.searchPolicies(apiVersion, searchFilter);

    const computersApi = new api.ComputersApi();

    // Assigns the found policy to the computer
    const assignPolicy = searchResults => {
      const computer = new api.Computer();
      computer.policyID = searchResults.policies[0].ID;
      return computersApi.modifyComputer(computerID, computer, apiVersion, { overrides: false });
    };

    searchPolicy()
      .then(assignPolicy)
      .then(data => {
        resolve(data);
      })
      .catch(error => {
        reject(error);
      });
  });
};
Java
/*
 * Assign a Linux server policy to a computer.
 * @param computerID The ID of the computer to assign the policy.
 */
public static void assignLinuxServerPolicy(Integer computerID) {
    //Create a search criteria to retrieve the Web Server policy
    SearchCriteria searchCriteria = new SearchCriteria();
    searchCriteria.setFieldName("name");
    searchCriteria.setStringTest(SearchCriteria.StringTestEnum.EQUAL);
    searchCriteria.setStringValue("%Linux Server%");        
    
    //Add the criteria to a search filter
    SearchFilter sf = new SearchFilter();
    sf.addSearchCriteriaItem(searchCriteria);

    PoliciesApi policiesApi = new PoliciesApi();
    ComputersApi computersApi = new ComputersApi();
    try {
        //Search for the policy
        Policies policies = policiesApi.searchPolicies("sf, true, "v1");
        
        //Retrieve the computer
        Computer computer = new Computer();
        
        //Set the policy for the computer
        computer.setPolicyID(policies.getPolicies().get(0).getID());
        computersApi.modifyComputer(computerID, computer, true, "v1");
    } catch (ApiException e) {
        e.printStackTrace();
    }
}

For information about authenticating API calls, see Authenticate with Deep Security Manager.

Reset policy overrides

Reset policy overrides so that the policy inherits the property or setting value of the parent policy (or, for top-level policies, the default policy settings). The way you reset a policy override depends on the type of property or setting.

Generally, the information in this section also applies to computers. Where some situations use policy-specific classes, you use computer-specific classes. For example, instead of PoliciesApi and PolicySettings, you use ComputersApi and ComputerSettings.

Reset an ID reference

To reset an ID reference override to inherit the value, modify the policy and set the value of the property to 0. An ID reference is a property that uses the ID of another item as a value.

For example, the Set the real time Anti-Malware scan configuration example overrides the realTimeScanConfigurationID for a policy. To reset the property to inherit the value from the parent policy, set realTimeScanConfigurationID to 0.

Reset a setting

To reset policy settings, set the value of the setting in a PolicySettings object to an empty string.

For example, the Configure Firewall example overrides the value of the FirewallSettingReconnaissanceEnabled setting for a policy. To reset the setting to inherit the value from the parent policy, you set the value to "".

Reset the status of a security module

To reset the status of a security module, modify the policy and set the value of the module’s state to inherited.

For example, the Turn on Application Control example overrides the status property of the Application Control module to on for a policy. To reset the setting to inherit the value from the parent policy, you set the status value to inherited.

Reset a rule

A rule override is achieved when the rule that is added to a policy is changed from the original rule. You can either reset all overrides of a rule, or reset the overrides selectively.

When a rule is assigned to a policy it is not considered an override, whether the parent policy is assigned the rule or not.

Reset all overrides of a rule

Each module-specific policy rules details class (FirewallRulesDetailsApi, PolicyIntegrityMonitoringRulesDetailsApi, PolicyIntrusionPreventionRuleDetailsApi, and PolicyLogInspectionRulesDetailsApi) provide a method for resetting all of the overrides of a rule that is assigned to a specific policy.

To see a code example, go to the Reset firewall rule overrides operation of Policy Firewall Rule Details in the API Reference, and see the code example for the operation.

Selectively reset overrides of a rule

Use the following procedure to reset only some properties of a rule.

  1. Obtain all of the overrides for the policy’s rule. Use the describe method of a module-specific rules details class with the overrides parameter set to true. Save the results.
  2. Reset all of the overrides of the rule.
  3. Restore the overrides that you want to keep in a new rule.
  4. Modify the policy rule with the overrides.
Python
Coming soon…
Javascript
Coming soon…
Java
/*
 * Resets all but the Alert Minimum Severity and Recommendation Options overrides
 * of a Log Inspection rule that is assigned to a policy. 
 * @param policyID The ID of the policy that is assigned the rule.
 * @param ruleID The ID of the Log Inspection rule.
 */
public static void selectiveResetForLogInspectionRuleOnPolicy(Integer policyID, Integer ruleID) {
    PolicyLogInspectionRuleDetailsApi policyLogInspectionRuleDetailsApi = new PolicyLogInspectionRuleDetailsApi();
    Boolean overrides = true;
    try {
        //Get the rule overrides
        LogInspectionRule ruleOverrides = 
                policyLogInspectionRuleDetailsApi.describeLogInspectionRuleOnPolicy(policyID, ruleID, overrides, "v1");
                    
        //Reset the rule
        policyLogInspectionRuleDetailsApi.resetLogInspectionRuleOnPolicy(policyID, ruleID, false, "v1");
        
        //Add the desired overrides to a new rule
        LogInspectionRule liRuleOverridesRestored = new LogInspectionRule();
        
        if (ruleOverrides.getAlertMinimumSeverity() != null) {
            liRuleOverridesRestored.setAlertMinimumSeverity(ruleOverrides.getAlertMinimumSeverity());;
        }
        if (ruleOverrides.getRecommendationsMode() != null) {
            liRuleOverridesRestored.setRecommendationsMode(ruleOverrides.getRecommendationsMode());
        }
        
        //Modify the rule on Deep Security Manager
        policyLogInspectionRuleDetailsApi.modifyLogInspectionRuleOnPolicy(policyID, ruleID, liRuleOverridesRestored, false, "v1");
        
    } catch (ApiException e) {
        System.out.println(e.getMessage());
        e.printStackTrace();
    }
}