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 the Create policies to protect your computers and other resources 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 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

# Modify the computer on Deep Security Manager
return computers_api.modify_computer(computer_id, computer, api_version)

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();
return computersApi.modifyComputer(computerID, computer, Boolean.FALSE, apiVersion);

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

Configure policy and default policy settings

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

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. Each class of settings has different scopes and purposes.

DefaultPolicySettings: Control certain behaviors of protection modules for top-level policies. Note that child policies inherit the settings of their parent policy unless they override them. Therefore, a DefaultPolicySettings setting is used by policies down the heirarchy until a policy overrides it.
PolicySettings: Control certain behaviors of protection modules at the policy level. These settings override the settings that are inherited from the parent policy or, for top-level policies, override the default policy settings.

The settings of the DefaultPolicySettings and PolicySettings classes are identical, with a few exceptions.

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

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.

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

Retrieve policy and default policy settings

The way you retrieve settings from Deep Security Manager depends on the setting class.

Default policy settings: Use aPoliciesApi object to get a DefaultPolicySettings object from the manager.
Policy settings: Use aPoliciesApi object to get a Policy object for a policy from the manager. Then, get aPolicySettings object from the Policy object.

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

Python

policy = policies_api.describe_policy(policy_id, api_version, overrides=False)
policy_settings = policy.policy_settings

# Get the setting value
network_engine_mode_value = policy_settings.firewall_setting_network_engine_mode

JavaScript

// Get the policy details from Deep Security Manager
const policiesApi = new api.PoliciesApi();
policiesApi.describePolicy(policyID, apiVersion, { overrides: false })
  .then(policy => {
    // Resolve the setting value
    resolve(policy.policySettings.firewallSettingNetworkEngineMode.value);
  })
  .catch(error => {
    reject(error);
  });

Java

PoliciesApi policiesApi = new PoliciesApi();
Policy policy = policiesApi.describePolicy(policyID, Boolean.FALSE, apiVersion);
PolicySettings policySettings = policy.getPolicySettings();
SettingValue networkEngineModeValue = policySettings.getFirewallSettingNetworkEngineMode();

Configure policy and default policy settings

For either class of settings, you create the settings object and set a value in the same way:

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.

You can configure as many settings as required in the same settings 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.

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.

Deep Security Manager validates setting values one by one without considering possible interdependencies of the settings.

The following example sets the value of the Firewall network engine mode setting for 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"
policies_api = api.PoliciesApi(api.ApiClient(configuration))

# Create a policy and add the setting value
policy = policies_api.describe_policy(policy_id, api_version)
policy_settings = policy.policy_settings
policy_settings.firewall_setting_network_engine_mode = network_engine_mode_value

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

JavaScript

// Setting value
const networkEngineModeValue = new api.SettingValue();
networkEngineModeValue.value = "Inline";

// Set the value of the setting
const policySettings = new api.PolicySettings();
policySettings.firewallSettingNetworkEngineMode = networkEngineModeValue;

// 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.firewallSettingNetworkEngineMode.value);
  })
  .catch(error => {
    reject(error);
  });

Java

// Set the value to either Inline or Tap
SettingValue networkEngineModeValue = new SettingValue();
networkEngineModeValue.setValue("Inline");

PolicySettings policySettings = new PolicySettings();
policySettings.setFirewallSettingNetworkEngineMode(networkEngineModeValue);

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

// Change the setting on Deep Security Manager
PoliciesApi policiesApi = new PoliciesApi();
policy = 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

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.

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