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.

/*
 * 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.

/*
 * 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.

/*
 * 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.

/*
 * 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.

/*
 * 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.

/*
 * 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

/*
 * 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.

/*
 * 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

/*
 * 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 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.
/*
 * 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();
    }
}