Create and Configure a Policy

Use policies to protect computers using one or more Deep Security modules.

For information about configuring specific protection modules for a policy, see the following guides:

Before you use the API, you should understand the essential concepts about policies. For background information, see Create policies in 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, set its properties to define behaviors, 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

To see the available policy properties, expand the 200 response to the [Describe a Policy](../api-reference/#operation/describePolicy) operation in the API Reference.

This example creates a policy below Base Policy. A search obtains Base Policy to obtain its ID, which is used as the parent of a new policy. (The creation of the search criteria and search filter is not shown.)

Python

# Search for the Base Policy
policies_api = api.PoliciesApi(api.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)

JavaScript

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

// Perform the search
PoliciesApi policiesApi = new PoliciesApi();
Policies policies = policiesApi.searchPolicies(sf, Boolean.FALSE, apiVersion);

// 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);

// Set the ID of the parent policy
if (!policies.getPolicies().isEmpty()) {
    Integer id = policies.getPolicies().get(0).getID();
    policy.setParentID(id);

    // Create the policy
    return policiesApi.createPolicy(policy, Boolean.FALSE, apiVersion);
}

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.

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

For information about searching, see Search for Resources. 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 computer according to the policy settings and the configuration of the security modules:

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

The following example assigns a policy to a computer. A search obtains the policy to obtain its ID, which is assigned to a computer. (The creation of the search criteria and search filter is not shown.)

Python

# 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

JavaScript

const policiesApi = new api.PoliciesApi();

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

// Assigns the found policy to the computer
const assignPolicy = searchResults => {
  const computer = new api.Computer();
  computer.policyID = searchResults.policies[0].ID;

  const computersApi = new api.ComputersApi();
  return computersApi.modifyComputer(computerID, computer, apiVersion, { overrides: false });
};

searchPolicy()
  .then(assignPolicy)
  .then(data => {
    resolve(data);
  })
  .catch(error => {
    reject(error);
  });

Java

// Search for the policy
PoliciesApi policiesApi = new PoliciesApi();
Policies policies = policiesApi.searchPolicies(sf, Boolean.FALSE, apiVersion);

if (policies.getPolicies().isEmpty())
    return null;

// Set the policy for the computer
Computer computer = new Computer();
computer.setPolicyID(policies.getPolicies().get(0).getID());

// Update on Deep Security Manager
ComputersApi computersApi = new ComputersApi();
Expand expand = new Expand();
return computersApi.modifyComputer(computerID, computer, expand.list(), Boolean.FALSE, apiVersion);

Also see the Modify a Policy operation in the API Reference.

You can override a policy at the computer level. See Configure Computers to Override Policies.

Configure policy and default policy settings

Policy Settings control many of the behaviors of the protection modules and the Deep Security Manager platform. Therefore, many tasks that you automate using the API require you to configure policy settings.

For a list of policy and default policy settings, see Default policy, policy, and computer settings in the Settings Reference.

Default setting values and overrides

Deep Security Manager policies are hierarchical. A policy's location in the hierarchy determines the default values of their settings:

Top-level policies: A set of default policy settings defines the default values for all top-level policies.
Child policies: Default values are inherited from their parent policy.

You can configure any setting for a policy to override the default. Therefore, a default policy setting is inherited by policies down the hierarchy until a policy overrides it.

For more information about the policy hierarchy and inheritance, see Policies, inheritance, and overrides in the Deep Security Help Center.

Policy setting and default policy setting classes

The Deep Security SDKs provide the following classes for storing policy and default policy settings. These classes are used to pass setting values between Deep Security Manager and SDK or API clients.

DefaultPolicySettings: Stores the values of all default policy settings.
PolicySettings: Stores setting values for a specific policy.

The settings of the DefaultPolicySettings and PolicySettings classes are identical, with a few exceptions. (See Default policy, policy, and computer settings in the Settings Reference.)

Retrieve the value of a policy setting or default policy setting

The PoliciesApi class enables you to retrieve the value of a single setting for a policy or for the default policy settings. For a policy, you can either retrieve the effective value of the setting or the override value:

Effective setting: The value that is being used for the policy. This value is either inherited or has been set specifically for this policy (overridden).
Override: The value that has been set specifically for this policy. No value indicates that the setting value is inherited.

Retrieve a default setting when you want to know the default value for top-level policies.

When you retrieve a setting value, identify the setting by name. The value is returned as a SettingValue object. For a list of policy and default policy settings, see Default policy, policy, and computer settings in the Settings Reference.

The following example retrieves the firewall network engine mode of a policy.

Python

# Get the policy details from Deep Security Manager
policies_api = api.PoliciesApi(api.ApiClient(configuration))
return policies_api.describe_policy_setting(policy_id, api.PolicySettings.firewall_setting_network_engine_mode, api_version, overrides=False)

To get the value for the default policy setting, use the describe_default_setting method.

JavaScript

const policiesApi = new api.PoliciesApi();
const settingName = "firewallSettingNetworkEngineMode";

return policiesApi.describePolicySetting(policyID, settingName, apiVersion, { overrides: false });

To get the value for the default policy setting, use the describeDefaultSetting function.

Java

PoliciesApi policiesApi = new PoliciesApi();
String settingName = "firewallSettingNetworkEngineMode";
Boolean overrides = Boolean.FALSE;
SettingValue networkEngineModeValue = policiesApi.describePolicySetting(policyID, settingName, overrides, apiVersion);

return networkEngineModeValue.getValue();

To get the value for the default policy setting, use the describeDefaultSetting method.

List all policy or default policy settings

You can retrieve all policy and default policy settings in a single call. The way you retrieve settings from Deep Security Manager depends on the setting class.

Default policy settings: Use a PoliciesApi object to get a DefaultPolicySettings object from the manager.
Policy settings: Use a PoliciesApi object to get a policy from Deep Security Manager as a Policy object. Then, get the PolicySettings object from the Policy object.

For examples, see the List default policy settings and Describe a policy operations in the Policies section of the API Reference.

Configure a single policy or default policy setting

The PoliciesApi class enables you to set the value of a single setting for a policy or for the default policy settings.

Create a SettingValue object and set the value (all values are strings). When settings accept one value from a list of choices, you can either use the ID of the choice or the exact wording of the choice as it appears in the Deep Security Manager console.
Create a PoliciesApi object and use it with the SettingValue object to modify either the policy setting or default setting. When modifying a policy setting, you also provide the policy ID.

The following example sets the value of the firewall network engine mode of a policy

Python

# Create a SettingValue object and set the value to either "Inline" or "Tap"
network_engine_mode_value = api.SettingValue()
network_engine_mode_value.value = "Inline"

# Modify the setting on Deep Security Manager
policies_api = api.PoliciesApi(api.ApiClient(configuration))
return policies_api.modify_policy_setting(policy_id, api.PolicySettings.firewall_setting_network_engine_mode, network_engine_mode_value, api_version, overrides=False)

To set the value for the default policy setting, use the modify_default_setting method.

JavaScript

// Setting name and value
const settingName = "firewallSettingNetworkEngineMode";
const networkEngineModeValue = new api.SettingValue();
networkEngineModeValue.value = "Inline";

// Modify the policy setting on Deep Security Manager
const policiesApi = new api.PoliciesApi();
policiesApi
  .modifyPolicySetting(policyID, settingName, networkEngineModeValue, apiVersion, { overrides: false })
  .then(returnedPolicySetting => {
    resolve(returnedPolicySetting.value);
  })
  .catch(error => {
    reject(error);
  });

To set the value for the default policy setting, use the modifyDefaultSetting function.

Java

PoliciesApi policiesApi = new PoliciesApi();
String settingName = "firewallSettingNetworkEngineMode";
Boolean overrides = Boolean.FALSE;
SettingValue networkEngineModeValue = policiesApi.describePolicySetting(policyID, settingName, overrides, apiVersion);

return networkEngineModeValue.getValue()

To set the value for the default policy setting, use the modifyDefaultSetting method.

Also see the Modify a Policy Setting operation in the API Reference.

Configure multiple policy and default policy settings

To configure multiple policy or default policy settings, you first create a settings object for each setting and set the values:

Create a SettingValue object and set the value (all values are strings). When settings accept one value from a list of choices, you can either use the ID of the choice or the exact wording of the choice as it appears in the Deep Security Manager console.
Create an object from the settings class (DefaultPolicySettings or PolicySettings).
Set the value of the setting to the SettingValue object.

Set the value of as many settings as required in the same DefaultPolicySettings or PolicySettings object.

For either class of settings, the way you modify the setting on Deep Security Manager is slightly different:

Default policy settings: Use a PoliciesApi object to modify the DefaultPolicySettings object on the manager.
Policy settings: Add the PolicySettings object to a Policy object. Then, use the PoliciesApi class to modify the policy on the manager.

Settings in the DefaultPolicySettings or PolicySettings object that have no values are unchanged on Deep Security Manager.

Deep Security Manager validates all modified settings before persisting the values. If one or more settings in the object is invalid, none of the modified settings are persisted. The error response includes the reason for each failure.

When Deep Security Manager validates setting values, it does not check that interdependent settings are concordant.

The following example configures two settings for a policy to enable either fail open or fail closed mode of operation.

Python

# Create the SettingValue objects
failure_response_engine_system = api.SettingValue()
failure_response_packet_sanity_check = api.SettingValue()

# Set the values
if fail_open:
    failure_response_engine_system.value = failure_response_packet_sanity_check.value = "Fail open"
else:
    failure_response_engine_system.value = failure_response_packet_sanity_check.value = "Fail closed"

# Set the setting values and add to a policy
policy_settings = api.PolicySettings()
policy_settings.firewall_setting_failure_response_engine_system = failure_response_engine_system
policy_settings.firewall_setting_failure_response_packet_sanity_check = failure_response_packet_sanity_check

policy = api.Policy()
policy.policy_settings = policy_settings

# Modify the policy on the Deep Security Manager.
policies_api = api.PoliciesApi(api.ApiClient(configuration))
return policies_api.modify_policy(policy_id, policy, api_version, overrides=False)

JavaScript

const modes = {
  failOpen: "Fail open",
  failClosed: "Fail closed"
};

// Create the SettingValue objects
const failureResponseEngineSystem = new api.SettingValue();
const failureResponsePacketSanityCheck = new api.SettingValue();

// Set the values
if (failOpen) {
  failureResponseEngineSystem.value = modes.failOpen;
  failureResponsePacketSanityCheck.value = modes.failOpen;
} else {
  failureResponseEngineSystem.value = modes.failClosed;
  failureResponsePacketSanityCheck.value = modes.failClosed;
}

// Set the value of the setting
const policySettings = new api.PolicySettings();
policySettings.firewallSettingFailureResponseEngineSystem = failureResponseEngineSystem;
policySettings.firewallSettingFailureResponsePacketSanityCheck = failureResponsePacketSanityCheck;

// Create a policy and add the setting values
const policy = new api.Policy();
policy.policySettings = policySettings;

// Modify the policy on Deep Security Manager.
const policiesApi = new api.PoliciesApi();
policiesApi
  .modifyPolicy(policyID, policy, apiVersion, { overrides: false })
  .then(returnedPolicy => {
    resolve(returnedPolicy.policySettings);
  })
  .catch(error => {
    reject(error);
  });

Java

final String FAIL_OPEN = "Fail open";
final String FAIL_CLOSED = "Fail closed";

// Create the SettingValue objects
SettingValue failureResponseEngineSystem = new SettingValue();
SettingValue failureResponsePacketSanityCheck = new SettingValue();

// Set the values
if (failOpen) {
    failureResponseEngineSystem.setValue(FAIL_OPEN);
    failureResponsePacketSanityCheck.setValue(FAIL_OPEN);
} else {
    failureResponseEngineSystem.setValue(FAIL_CLOSED);
    failureResponsePacketSanityCheck.setValue(FAIL_CLOSED);
}

// Set the setting values and add to a policy
PolicySettings policySettings = new PolicySettings();
policySettings.setFirewallSettingFailureResponseEngineSystem(failureResponseEngineSystem);
policySettings.setFirewallSettingFailureResponsePacketSanityCheck(failureResponsePacketSanityCheck);

Policy policy = new Policy();
policy.setPolicySettings(policySettings);

// Change the setting on Deep Security Manager
PoliciesApi policiesApi = new PoliciesApi();
return policiesApi.modifyPolicy(policyID, policy, Boolean.FALSE, apiVersion);

For an example of configuring a system setting, see Configure Deep Security Manager System Settings.

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

The PoliciesApi class provides methods for resetting a single policy setting. For an example, see the Reset the Value of a Policy Setting operation in the Policies section of the Api Reference.

To reset several policy settings at the same time, use a PolicySettings object with PoliciesApi to set the value of the settings 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.

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. (See [About the Overrides Parameter](../overrides-parameter).)
Reset all of the overrides of the rule.
Restore the overrides that you want to keep in a new rule.
Modify the policy rule with the overrides.

The following example resets a subset of Log Inspection rule overrides for a policy.

Python

policy_log_inspection_rule_details_api = api.PolicyLogInspectionRuleDetailsApi(api.ApiClient(configuration))

# Get the rule overrides
rule_overrides = policy_log_inspection_rule_details_api.describe_log_inspection_rule_on_policy(policy_id, rule_id, api_version, overrides=True)

# Reset the rule
policy_log_inspection_rule_details_api.reset_log_inspection_rule_on_policy(policy_id, rule_id, api_version, overrides=False)

# Add the desired overrides to a new rule
li_rule_overrides_restored = api.LogInspectionRule()

if rule_overrides.alert_minimum_severity:
    li_rule_overrides_restored.alert_minimum_severity = rule_overrides.alert_minimum_severity

if rule_overrides.recommendations_mode:
    li_rule_overrides_restored.recommendations_mode = rule_overrides.recommendations_mode

# Modify the rule on Deep Security Manager
return policy_log_inspection_rule_details_api.modify_log_inspection_rule_on_policy(policy_id, rule_id, li_rule_overrides_restored, api_version, overrides=False)

JavaScript

let ruleWithOverrides; // Stores the rule with overrides

// Retrieves the overridden properties of the Log Inspection rule that is assigned the policy
const getRule = () => {
  const policyLogInspectionRuleDetailsApi = new api.PolicyLogInspectionRuleDetailsApi();
  return policyLogInspectionRuleDetailsApi.describeLogInspectionRuleOnPolicy(policyID, ruleID, apiVersion, {
    overrides: true
  });
};

// Resets the overridden properties of the rule that is assigned to the policy
const resetRule = () => {
  const policyLogInspectionRuleDetailsApi = new api.PolicyLogInspectionRuleDetailsApi();
  return policyLogInspectionRuleDetailsApi.resetLogInspectionRuleOnPolicy(policyID, ruleID, apiVersion, {
    overrides: false
  });
};

// Overrides the rule that is assigned to the policy according to the given rule's properties
const updateRule = rule => {
  const policyLogInspectionRuleDetailsApi = new api.PolicyLogInspectionRuleDetailsApi();
  return policyLogInspectionRuleDetailsApi.modifyLogInspectionRuleOnPolicy(policyID, ruleID, rule, apiVersion, {
    overrides: false
  });
};

// Get the Log Inspection rule (overridden properties only) that is assigned to the policy
getRule()
  .then(liRule => {
    // Store the rule
    ruleWithOverrides = liRule;
    // Reset the rule on the policy
    return resetRule();
  })
  .then(() => {
    // Create a Log Inpsection rule
    let liRuleWithOverridesRestored = new api.LogInspectionRule();

    // Set the properties of the new rule to restore the desired overrides
    if (ruleWithOverrides.alertMinimumSeverity !== undefined) {
      liRuleWithOverridesRestored.alertMinimumSeverity = ruleWithOverrides.alertMinimumSeverity;
    }
    if (ruleWithOverrides.recommendationsMode !== undefined) {
      liRuleWithOverridesRestored.recommendationsMode = ruleWithOverrides.recommendationsMode;
    }
    // Update the rule for the policy with the desired overrides
    return updateRule(liRuleWithOverridesRestored);
  })

Java

// Get the rule overrides
LogInspectionRule ruleOverrides = policyLogInspectionRuleDetailsApi.describeLogInspectionRuleOnPolicy(policyID, ruleID, overrides, apiVersion);

// Reset the rule
policyLogInspectionRuleDetailsApi.resetLogInspectionRuleOnPolicy(policyID, ruleID, Boolean.FALSE, apiVersion);

// 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
return policyLogInspectionRuleDetailsApi.modifyLogInspectionRuleOnPolicy(policyID, ruleID, liRuleOverridesRestored, Boolean.FALSE, apiVersion);