Configure Container Control

This feature is being rolled out to Deep Security as a Service customers. If it’s not available in your account yet, it will be soon. Container Control requires that you upgrade to Deep Security Agent Feature Releases (version 12.5 or higher), which will be available soon.

The Container Control module controls whether a container can run on a Docker host that is protected by a Deep Security Agent, based on parameters that you configure. You can block privileged containers from running, or allow them to run but log an event. If you have Deep Security Smart Check running in your environment, you can also block containers where Smart Check has found malware or vulnerabilities.

If you are using Deep Security Smart Check, connect Smart Check to Deep Security Manager before using Container Control.

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

General steps

Use the following steps to configure the Container Control module to define its behavior for a policy:

  1. Create a ContainerControlPolicyExtension object and configure the running state (on or off).
    Python
    # Get the policy
    policies_api = api.PoliciesApi(api.ApiClient(configuration))
     
    # Turn on Container Control
    container_control_policy_extension = api.ContainerControlPolicyExtension()
    container_control_policy_extension.state = "on"
    
    JavaScript
    const policy = new api.Policy();
    const policiesApi = new api.PoliciesApi();
    const containerControlPolicyExtension = new api.ContainerControlPolicyExtension();containerControlPolicyExtension.state =
    api.ContainerControlPolicyExtension.StateEnum.on;
    
    Java
    //Get the policy to modify
    PoliciesApi policiesApi = new PoliciesApi();= new ContainerControlPolicyExtension();
    containerControlPolicyExtension.state(ContainerControlPolicyExtension.StateEnum.ON);
    }
    
  2. Configure the action for privileged containers.
    Python
    container_control_policy_extension.privileged_container_action = "detect"
    
    JavaScript
    containerControlPolicyExtension.privilegedContainerAction = api.ContainerControlPolicyExtension.PrivilegedContainerActionEnum.detect;
    
    Java
    containerControlPolicyExtension.privilegedContainerAction(ContainerControlPolicyExtension.PrivilegedContainerActionEnum.DETECT);
    
  3. Configure the action for images that haven’t been scanned.
    Python
    container_control_policy_extension.unscanned_images_action = "allow"
    JavaScript
    containerControlPolicyExtension.unscannedImagesAction = api.ContainerControlPolicyExtension.UnscannedImagesActionEnum.allow;
    
    Java
    containerControlPolicyExtension.unscannedImagesAction(ContainerControlPolicyExtension.UnscannedImagesActionEnum.ALLOW);
    
  4. Configure the action for the images with malware detected.
    Python
    container_control_policy_extension.malware_detected_action = "block"
    
    JavaScript
    containerControlPolicyExtension.malwareDetectedAction = api.ContainerControlPolicyExtension.MalwareDetectedActionEnum.block;
    
    Java
    containerControlPolicyExtension.malwareDetectedAction(ContainerControlPolicyExtension.MalwareDetectedActionEnum.BLOCK);
    
  5. Create a ContainerControlVulnerabilityThreshold object and adjust the threshold of vulnerabilities (the severity level and number of vulnerabilities that will trigger a detect or block action).
  6. Add the ContainerControlVulnerabilityThreshold to ContainerControlPolicyExtension.
  7. Configure the action for images that exceed the threshold.
    Python
    # Adjust the threshold of vulnerabilities and configure the action for images that exceed vulnerability threshold
    container_control_vulnerability_threshold = api.ContainerControlVulnerabilityThreshold()
    container_control_vulnerability_threshold.defcon1_count = 0
    container_control_vulnerability_threshold.critical_count = 0
    container_control_vulnerability_threshold.high_count = 0
    container_control_vulnerability_threshold.medium_count = 10
    container_control_vulnerability_threshold.low_count = -1
    container_control_vulnerability_threshold.negligible_count = -1
    container_control_vulnerability_threshold.unknown_count = -1
    container_control_policy_extension.vulnerability_threshold = container_control_vulnerability_threshold
    container_control_policy_extension.vulnerability_exceed_threshold_action = "block"
    JavaScript
    // Adjust the threshold of vulnerabilities and configure the action for images that exceed vulnerability threshold
    const containerControlVulnerabilityThreshold = new api.ContainerControlVulnerabilityThreshold();
    containerControlVulnerabilityThreshold.defcon1Count = 0;
    containerControlVulnerabilityThreshold.criticalCount = 0;
    containerControlVulnerabilityThreshold.highCount = 0;
    containerControlVulnerabilityThreshold.mediumCount = 10;
    containerControlVulnerabilityThreshold.lowCount = -1;
    containerControlVulnerabilityThreshold.negligibleCount = -1;
    containerControlVulnerabilityThreshold.unknownCount = -1;
    containerControlPolicyExtension.vulnerabilityThreshold = containerControlVulnerabilityThreshold;
    containerControlPolicyExtension.vulnerabilityExceedThresholdAction =
                api.ContainerControlPolicyExtension.VulnerabilityExceedThresholdActionEnum.block;
    Java
    // Adjust the threshold of vulnerabilities and configure the action for images that exceed vulnerability threshold
    ContainerControlVulnerabilityThreshold containerControlVulnerabilityThreshold = new ContainerControlVulnerabilityThreshold();
    containerControlVulnerabilityThreshold.defcon1Count(0);
    containerControlVulnerabilityThreshold.criticalCount(0);
    containerControlVulnerabilityThreshold.highCount(0);
    containerControlVulnerabilityThreshold.mediumCount(10);
    containerControlVulnerabilityThreshold.lowCount(-1);
    containerControlVulnerabilityThreshold.negligibleCount(-1);
    containerControlVulnerabilityThreshold.unknownCount(-1);
     containerControlPolicyExtension.vulnerabilityThreshold(containerControlVulnerabilityThreshold);
    containerControlPolicyExtension.vulnerabilityExceedThresholdAction(ContainerControlPolicyExtension.VulnerabilityExceedThresholdActionEnum.BLOCK);
    
  8. Create a Policy object and add the ContainerControlPolicyExtension.
  9. Use a PoliciesApi object to add or update the policy in Deep Security Manager.
    Python
    # Update the policy
    update_policy = api.Policy()
    update_policy.container_control = container_control_policy_extension
     
    try:
        # Modify the policy on Deep Security Manager
        container_control_policy = policies_api.modify_policy(policy_id, update_policy, api_version, overrides=False)
        return container_control_policy
     
    except api_exception as e:
        return "Exception: " + str(e)
    
    JavaScript
    //Add to the policy
    policy.containerControl = containerControlPolicyExtension;policiesApi.modifyPolicy(policyID, policy, apiVersion, { overrides: false })
        .then(data => {
            resolve(data);
        })
        .catch(function(error) {
            reject(error);
        });
    
    Java
    //Get the policy to modify
    PoliciesApi policiesApi = new PoliciesApi();= new Policy();
    updatePolicy.setContainerControl(containerControlPolicyExtension);policiesApi.modifyPolicy(policyId, updatePolicy, false, apiVersion);
    

Example

The following example code creates a ContainerControlPolicyExtension object and turns on Container Control. The object is added to a Policy object, which is used to modify a policy in Deep Security Manager.

Python
def configure_container_control(api , configuration, api_version, api_exception, policy_id):
    """ Modifies a policy to set the Container Control state to on.
 
    :param api: The Deep Security API modules.
    :param configuration: Configuration object to pass to the api 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 = api.PoliciesApi(api.ApiClient(configuration))
 
    # Turn on Container Control
    container_control_policy_extension = api.ContainerControlPolicyExtension()
    container_control_policy_extension.state = "on"
 
    # Configure action for privileged container
    container_control_policy_extension.privileged_container_action = "detect"
 
    # Configure action for unscanned images
    container_control_policy_extension.unscanned_images_action = "allow"
 
    # Configure action for images with malware detected
    container_control_policy_extension.malware_detected_action = "block"
 
    # Adjust the threshold of vulnerabilities and configure the action for images that exceed vulnerability threshold
    container_control_vulnerability_threshold = api.ContainerControlVulnerabilityThreshold()
    container_control_vulnerability_threshold.defcon1_count = 0
    container_control_vulnerability_threshold.critical_count = 0
    container_control_vulnerability_threshold.high_count = 0
    container_control_vulnerability_threshold.medium_count = 10
    container_control_vulnerability_threshold.low_count = -1
    container_control_vulnerability_threshold.negligible_count = -1
    container_control_vulnerability_threshold.unknown_count = -1
    container_control_policy_extension.vulnerability_threshold = container_control_vulnerability_threshold
    container_control_policy_extension.vulnerability_exceed_threshold_action = "block"
 
    # Update the policy
    update_policy = api.Policy()
    update_policy.container_control = container_control_policy_extension
 
    try:
        # Modify the policy on Deep Security Manager
        container_control_policy = policies_api.modify_policy(policy_id, update_policy, api_version, overrides=False)
        return container_control_policy
 
    except api_exception as e:
        return "Exception: " + str(e)
JavaScript
/*
 * Modifies a policy to set the Container 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.configureContainerControl = function (api, policyID, apiVersion) {
    return new Promise((resolve, reject) => {
        const policy = new api.Policy();
        const policiesApi = new api.PoliciesApi();
        const containerControlPolicyExtension = new api.ContainerControlPolicyExtension();
        // Turn on container control
        containerControlPolicyExtension.state =
            api.ContainerControlPolicyExtension.StateEnum.on;
        
        // Configure Action for privileged container
        containerControlPolicyExtension.privilegedContainerAction = 
            api.ContainerControlPolicyExtension.PrivilegedContainerActionEnum.detect;
        // Configure Action for unscanned images
        containerControlPolicyExtension.unscannedImagesAction = 
            api.ContainerControlPolicyExtension.UnscannedImagesActionEnum.allow;
        // Configure Action for images with malware detected
        containerControlPolicyExtension.malwareDetectedAction = 
            api.ContainerControlPolicyExtension.MalwareDetectedActionEnum.block;
        // Adjust the threshold of vulnerabilities and configure action for the images that exceed vulnerability threshold
        const containerControlVulnerabilityThreshold = new api.ContainerControlVulnerabilityThreshold();
        containerControlVulnerabilityThreshold.defcon1Count = 0;
        containerControlVulnerabilityThreshold.criticalCount = 0;
        containerControlVulnerabilityThreshold.highCount = 0;
        containerControlVulnerabilityThreshold.mediumCount = 10;
        containerControlVulnerabilityThreshold.lowCount = -1;
        containerControlVulnerabilityThreshold.negligibleCount = -1;
        containerControlVulnerabilityThreshold.unknownCount = -1;
        containerControlPolicyExtension.vulnerabilityThreshold = containerControlVulnerabilityThreshold;
        containerControlPolicyExtension.vulnerabilityExceedThresholdAction = 
            api.ContainerControlPolicyExtension.VulnerabilityExceedThresholdActionEnum.block;
        // Add to the policy
        policy.containerControl = containerControlPolicyExtension;
        // Send the change to Deep Security Manager
        policiesApi.modifyPolicy(policyID, policy, apiVersion, { overrides: false })
            .then(data => {
                resolve(data);
            })
            .catch(function(error) {
                reject(error);
            });
    });
};
Java
package com.trendmicro.deepsecurity.docs;
import com.trendmicro.deepsecurity.ApiException;
import com.trendmicro.deepsecurity.api.PoliciesApi;
import com.trendmicro.deepsecurity.model.ContainerControlPolicyExtension;
import com.trendmicro.deepsecurity.model.ContainerControlVulnerabilityThreshold;
import com.trendmicro.deepsecurity.model.Policy;
public class ContainerControlExamples {
	/*
	 * Turns on the Container 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 Policy configureContainerControl(Integer policyId, String apiVersion) throws ApiException{
	    // Get the policy to modify
	    PoliciesApi policiesApi = new PoliciesApi(); 
	    // Turn on Container Control
	    ContainerControlPolicyExtension containerControlPolicyExtension = new ContainerControlPolicyExtension();
	    containerControlPolicyExtension.state(ContainerControlPolicyExtension.StateEnum.ON);
	    // Configure Action for privileged container
	    containerControlPolicyExtension.privilegedContainerAction(ContainerControlPolicyExtension.PrivilegedContainerActionEnum.DETECT);
	    // Configure Action for unscanned images
	    containerControlPolicyExtension.unscannedImagesAction(ContainerControlPolicyExtension.UnscannedImagesActionEnum.ALLOW);
	    // Configure Action for images with malware detected
	    containerControlPolicyExtension.malwareDetectedAction(ContainerControlPolicyExtension.MalwareDetectedActionEnum.BLOCK);
	    // Adjust the threshold of vulnerabilities and configure action for the images that exceed vulnerability threshold
	    ContainerControlVulnerabilityThreshold containerControlVulnerabilityThreshold = new ContainerControlVulnerabilityThreshold();
	    containerControlVulnerabilityThreshold.defcon1Count(0);
	    containerControlVulnerabilityThreshold.criticalCount(0);
	    containerControlVulnerabilityThreshold.highCount(0);
	    containerControlVulnerabilityThreshold.mediumCount(10);
	    containerControlVulnerabilityThreshold.lowCount(-1);
	    containerControlVulnerabilityThreshold.negligibleCount(-1);
	    containerControlVulnerabilityThreshold.unknownCount(-1);
	    containerControlPolicyExtension.vulnerabilityThreshold(containerControlVulnerabilityThreshold);
	    containerControlPolicyExtension.vulnerabilityExceedThresholdAction(ContainerControlPolicyExtension.VulnerabilityExceedThresholdActionEnum.BLOCK);
	    // Update the policy
	    Policy updatePolicy = new Policy();
	    updatePolicy.setContainerControl(containerControlPolicyExtension);
        // Update the policy on Deep Security Manager
        return policiesApi.modifyPolicy(policyId, updatePolicy, false, apiVersion);
	}
}
For information about authenticating API calls, see Authenticate with Deep Security Manager.