Create and Configure Common Objects for Policies and Computers

Common objects are items that are used to configure certain aspects of the security modules, and can be used with multiple policies and computers. For example, you can create a malware scan configuration and use it to configure Anti-Malware in multiple policies.

Use the API to create and configure the following common objects:

  • Rules (Firewall, Intrusion Prevention, Integrity Monitoring, Log Inspection, and Application Control rulesets)
  • Lists (directory lists, file extension lists, file lists, IP lists, MAC lists, and port lists)
  • Contexts
  • Firewall stateful configurations
  • Malware scan configurations
  • Schedules

Create and configure rules

Generally, to create rules for the different protection modules you perform the following steps:

  1. Create the rule object.
  2. Set the rule properties. Each type of rule has different properties.
  3. Use the API object that is associated with the rule object to add the rule to Deep Security Manager. For example, to add a Firewall rule you use a FirewallRulesApi object.

The sections that follow provide information that is specfic to each type of rule.

Use XML to define rules

You can use XML to define the content of the following types of rules:

  • Integrity Monitoring
  • Log Inspection

These rules have a Template property that controls whether you use XML to define the rule, or whether you use object properties or methods to define the rule. To use XML, you set the template type to Custom, and then set the CustomXML property.

The XML that you provide must be base64-encoded.

Firewall rules

To create a Firewall rule, create a FirewallRule object and then use a FirewallRulesApi object to create the rule on Deep Security Manager. The properties that you need to set on the FirewallRule object are as described in the core Deep Security help.

To use the API to create a Firewall rule, send a POST request to the firewallrules endpoint. (See the Create a Firewall Rule operation in the API Reference.)

Intrusion Prevention rules

To create an Intrusion Prevention rule, create an IntrusionPreventionRule object and use an IntrusionPreventionRulesApi object to create it on Deep Security Manager.

For background information about Intrusion Prevention rules, see the core Deep Security help.

To use the API to create an Intrusion Prevention rule, send a POST request to the intrusionpreventionrules endpoint. (See the Create an Intrusion Prevention Rule operation in the API Reference.)

Integrity Monitoring rules

To create an Integrity Monitoring rule you create an IntegrityMonitoringRule object and use an IntegrityMonitoringRulesApi object to create the rule on Deep Security Manager.

Set the template type to indicate how you are defining the rule:

  • File: Set properties that describe how to monitor changes to files.
  • Registry: Set properties that describe how to monitor changes to Windows registry values.
  • Custom: Provide XML (base64-encoded) that describes how to monitor changes to directories, registry values, registry keys, services, processes, installed software, ports and files.

For background information about Integrity Monitoring rules and the rules language, see the core Deep Security documentation.

To use the API to create an Integrity Monitoring rule, send a POST request to the integritymonitoringrules endpoint. (See the Create an Integrity Monitoring Rule operation in the API Reference.)

Log Inspection rules

To create a Log Inspection rule you create a LogInspectionRule object and set the name, description, and the log file to inspect. Use a LogInspectionRulesApi object to create the rule on Deep Security Manager.

Set the template type to indicate how you are defining the content of the rule:

  • Basic: A single Log Inspection rule under a single rule group. You provide values for each property of the rule.
  • Custom: A single or mutliple rules under a single group or multiple groups. You provide XML (base64-encoded) that defines the rule or rules.

For background information about Log Inspection rules, see the core Deep Security documentation.

To use the API to create a Log Inspection rule, send a POST request to the loginspectionrules endpoint. (See the Create a Log Inspection Rule operation in the API Reference.)

Example: Create a basic Log Inspection rule

Python
def create_log_inspection_rule(client, configuration, api_version, api_exception, name, path, pattern, group):
    """ Creates a basic log inspection rule that monitors a log file for errors.

    :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 name: The name for the rule.
    :param path: The path of the log file to monitor.
    :param pattern: The pattern in the file to match.
    :param group: The rule group.
    :return: A LogInspectionRulesApi object with the new rule.
    """

    # Create the rule object
    li_rule = client.LogInspectionRule()
    li_rule.name = name
    li_rule.description = "A log inspection rule"

    # Create a log file and add it to the rule
    log_file = client.LogFile()
    log_file.location = "C/logfile.log"
    log_file.format = "eventlog"
    log_files = client.LogFiles()
    log_files.log_files = [log_file]
    li_rule.log_files = log_files

    # Define the rule
    li_rule.template ="basic-rule"
    li_rule.pattern = pattern
    li_rule.pattern_type = "string"
    li_rule.rule_description = "Rule for " + path + " and pattern " + pattern
    li_rule.groups = [group]

    try:
        # Add the rule to Deep Security Manager
        log_inspection_rules_api = client.LogInspectionRulesApi(client.ApiClient(configuration))
        return log_inspection_rules_api.create_log_inspection_rule(li_rule, api_version)

    except api_exception as e:
        return "Exception: " + str(e)
JavaScript
/*
 * Creates a basic log inspection rule that monitors a log file for errors.
 * @param {Object} api The Deep Security API modules.
 * @param {String} name The name for the rule.
 * @param {String} path The path of the log file to monitor.
 * @param {String} pattern The pattern in the file to match.
 * @param {String} group The rule group.
 * @param {String} apiVersion The version of the API to use.
 * @return {Promise} A promise that contains the rule.
*/
exports.createLogInspectionRule = function(api, name, path, pattern, group, apiVersion) {
  return new Promise((resolve, reject) => {
    // Create the rule object and set name
    const liRule = new api.LogInspectionRule();
    liRule.name = name;

    // Create the LogFile and add to rule
    const logFile = new api.LogFile();
    logFile.location = path;
    logFile.format = "eventlog";
    const logFiles = new api.LogFiles();
    logFiles.logFiles = [logFile];
    liRule.logFiles = logFiles;

    // Define the rule
    liRule.template = "basic-rule";
    liRule.pattern = pattern;
    liRule.patternType = "string";
    liRule.ruleDescription = "Rule for " + path + " and pattern " + pattern;
    liRule.groups = [group];

    // Creates on Deep Security Manager
    const createRule = () => {
      const logInspectionRulesApi = new api.LogInspectionRulesApi();
      return logInspectionRulesApi.createLogInspectionRule(liRule, apiVersion);
    };

    createRule()
    .then(data => {
      resolve(data);
    })
    .catch(error => {
      reject(error);
    });
  });
};
Java
/*
* Creates a basic log inspection rule that monitors a log file for errors.
*/
public static void createLogInspectionRule() {
    //Create the rule and add basic information
    LogInspectionRule liRule = new LogInspectionRule();
    liRule.setName("Inspect Log for Error");
    liRule.setDescription("A simple rule.");
    
    //Log files to inpsect
    LogFile logFile = new LogFile();
    logFile.setLocation("C/logfile.log");
    logFile.setFormat(LogFile.FormatEnum.EVENTLOG);
    LogFiles logFiles = new LogFiles();
    logFiles.addLogFilesItem(logFile);
    liRule.setLogFiles(logFiles);
    
    //Template type is Basic Rule
    liRule.setTemplate(LogInspectionRule.TemplateEnum.BASIC_RULE);
    
    //Set the pattern
    liRule.setPattern("^ERROR");
    liRule.setPatternType(LogInspectionRule.PatternTypeEnum.STRING);
    
    //Description and group
    liRule.setRuleDescription("Test Rule Description");
    List<String> groups = new ArrayList<String>();
    groups.add("Windows Rules");
    liRule.setGroups(groups);
    
    //Add the rule to Deep Security Manager
    LogInspectionRulesApi liRulesApi = new LogInspectionRulesApi();
    try {
        liRule = liRulesApi.createLogInspectionRule(liRule, "v1");
    } catch (ApiException e) {
        e.printStackTrace();
    }
}
For information about authenticating API calls, see Authenticate with Deep Security Manager.

Example: Create a log inspection rule using XML

Python
def create_log_inspection_rule_xml(client, configuration, api_version, api_exception, name, xml):
    """ Creates a log inspection rule from XML that monitors a log file for errors.

    :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 name: The name for the rule.
    :param path: The path of the log file to monitor.
    :param xml: The rule in XML format (base64-encoded).
    :return:
    """

    # Create the rule object
    li_rule = client.LogInspectionRule()
    li_rule.name = name
    li_rule.description = "A log inspection rule"

    # Create a log file and add it to the rule
    log_file = client.LogFile()
    log_file.location = "C/logfile.log"
    log_file.format = "eventlog"
    log_files = client.LogFiles()
    log_files.log_files = [log_file]
    li_rule.log_files = log_files

    # Define the rule
    li_rule.template ="custom"
    li_rule.XML = xml

    try:
        # Add the rule to Deep Security Manager
        log_inspection_rules_api = client.LogInspectionRulesApi(client.ApiClient(configuration))
        return log_inspection_rules_api.create_log_inspection_rule(li_rule, api_version)

    except api_exception as e:
        return "Exception: " + str(e)
JavaScript
/*
 * Creates a log inspection rule from XML that monitors a log file for errors.
 * @param {Object} api The Deep Security API modules.
 * @param {String} name The name for the rule.
 * @param {String} path The path of the log file to monitor.
 * @param {String} xml  The rule in XML format (base64-encoded).
 * @param {String} apiVersion The version of the API to use.
 * @return {Promise} A promise that contains the rule.
*/
exports.createLogInspectionRuleXML = function(api, name, path, xml, apiVersion) {
  return new Promise(function(resolve, reject) {
    // Create the rule object and set name
    const liRule = new api.LogInspectionRule();
    liRule.name = name;

    // Create the LogFile and add to rule
    const logFile = new api.LogFile();
    logFile.location = path;
    logFile.format = "eventlog";
    const logFiles = new api.LogFiles();
    logFiles.logFiles = [logFile];
    liRule.logFiles = logFiles;

    // Define the rule
    liRule.template = "custom";
    liRule.ruleXML = xml;

    // Creates the rule on Deep Security Manager
    const createRule = function() {
      const logInspectionRulesApi = new api.LogInspectionRulesApi();
      return logInspectionRulesApi.createLogInspectionRule(liRule, apiVersion);
    };

    createRule()
      .then(data => {
        resolve(data);
      })
      .catch(error => {
        reject(error);
      });
  });
};
Java
/*
 * Creates a log inspection rule using XML.
 * @param xml The base-64-encoded XML (contains patterns and groups)
 */
public static void createLogInspectionRuleXML(String xml) {
    //Create the rule and add basic information
    LogInspectionRule liRule = new LogInspectionRule();
    liRule.setName("Inspect Log for Error XML");
    liRule.setDescription("A simple rule.");

    //Log files to inpsect
    LogFile logFile = new LogFile();
    logFile.setLocation("C/logfile.log");
    logFile.setFormat(LogFile.FormatEnum.EVENTLOG);
    LogFiles logFiles = new LogFiles();
    logFiles.addLogFilesItem(logFile);
    liRule.setLogFiles(logFiles);

    //Template type is Custom
    liRule.setTemplate(LogInspectionRule.TemplateEnum.CUSTOM);
    
    //Set the XML
    liRule.setRuleXML(xml);
    
    //Add the rule to Deep Security Manager
    LogInspectionRulesApi liRulesApi = new LogInspectionRulesApi();
    try {
        liRule = liRulesApi.createLogInspectionRule(liRule, "v1");
    } catch (ApiException e) {
        e.printStackTrace();
    }
}
For information about authenticating API calls, see Authenticate with Deep Security Manager.

Create and modify lists

Several common objects are lists of items that are used to configure protection modules: directory lists, file extension lists, file lists, IP lists, MAC lists, and port lists. The way that you create each list is very similar:

  1. Create the list object.
  2. Set general properties such as the name and description.
  3. Add items to the list. The type of list determines the nature of the item that you add.
  4. Use the API object that is associated with the list object to add the list to Deep Security Manager. For example, you use a DirectoryListsApi object to add a directory list.

To modify a list, you obtain the list, modify it, then update the list. Like any other object, to obtain the list you can search, get the list by ID, or get all lists and cycle through them to find a particular list.

Example: Add a directory to a directory list

Python
def add_item_to_directory_list(client, configuration, api_version, api_exception, dir_list_name, dir_path):
    """ Adds a directory to a directory list. If the list does not exist, it is created.

    :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 dir_list_name: The name of the directory list.
    :param dir_path: The path to add to the directory list.
    :return: A DirectoryListsApi object that contains the added directory list.
    """

    dir_list = client.DirectoryList()
    dir_lists_api = client.DirectoryListsApi(client.ApiClient(configuration))

    try:
        dir_lists = dir_lists_api.list_directory_lists(api_version)

        for dir in dir_lists.directory_lists:
            if dir.name == dir_list_name:
                dir_list.dir_list = dir

        # Create the directory list if dir_list_name was not found
        if dir_list.name == None:
            dir_list.name = dir_list_name
            dir_list = dir_lists_api.create_directory_list(dir_list, api_version)

        dir_list_with_directory = client.DirectoryList()
        dir_list_with_directory.items = dir_path

        return dir_lists_api.modify_directory_list(dir_list.id, dir_list_with_directory, api_version)

    except api_exception as e:
        return "Exception: " + str(e)
JavaScript
/*
* Adds a directory to a directory list.
* @param {object} api The api module.
* @param {String} dirListID The ID of the directory list.
* @param {String} dirPath The path to add to the directory list.
* @param {String} apiVersion The api version to use.
* @return {Promise} A Promise that contains the directory list.
*/
exports.addItemToDirectoryList = function(api, dirListID, dirPath, apiVersion) {
  return new Promise((resolve, reject) => {
    getDirList(api, dirListID, apiVersion) // Get the list
      .then(dirList => addDirPath(api, dirList, dirPath, apiVersion)) // Add the path to the list
      .then(data => {
        resolve(data); // Return the response from the addDirPath call
      })
      .catch(error => {
            reject(error);
      });
  });
};

// PRIVATE METHODS //
// Gets a directory list
function getDirList(api, dirListID, apiVersion) {
    const directoryListsApi = new api.DirectoryListsApi();
    return directoryListsApi.describeDirectoryList(dirListID, apiVersion);
}

// Adds a path to a directory list
function addDirPath(api, list, dirPath, apiVersion) {
  // Verify that we have the listID
  try {
    if (!list.ID) {
      throw { error: true, message: "Directory list ID is required" };
    }
  } catch (error) {
    return error;
  }

  // Add the path to the list object
  const dirList = new api.DirectoryList();
  dirList.items = list.items;
  dirList.items.push(dirPath);

  // Add the path to the list on Deep Security Manager
  const directoryListsApi = new api.DirectoryListsApi();
  return directoryListsApi.modifyDirectoryList(list.ID, dirList, apiVersion);
}
Java
/*
 * Adds a directory to an existing directory list.
 * @param dirListID The ID of the directory list.
 * @param dirPath The path of the directory to add to the list.
 * @Return The modified directory list.
 */
public static DirectoryList addItemToDirectoryList(Integer dirListID, String dirPath) {
    DirectoryList dirList = new DirectoryList();

    DirectoryListsApi dirListsApi = new DirectoryListsApi();
    try {
        //Obtain the directory list if it exists
        dirList = dirListsApi.describeDirectoryList(dirListID, "v1");

        //Create a DirectoryList object and add the existing and additional directory
        DirectoryList dirListWithDirectory = new DirectoryList();
        dirListWithDirectory.setItems(dirList.getItems());
        dirListWithDirectory.addItemsItem(dirPath);
        //Modify the list and update on Deep Security Manager   
        dirList = dirListsApi.modifyDirectoryList(dirList.getID(), dirListWithDirectory, "v1");

    }catch (ApiException e) {
        System.out.println(e.getMessage());
        e.printStackTrace();
    }
    return dirList;
}
For information about authenticating API calls, see Authenticate with Deep Security Manager.

Create and modify malware scan configurations

Malware scan configurations determine how the Anti-Malware module performs scans to detect malware. To create a malware scan configuration, perform the following general steps:

  1. Create an AntiMalwareConfiguration object.
  2. Set the property values of the object.
  3. Use an AntiMalwareConfigurationsApi object to update Deep Security Manager.

For background information about malware scan configurations, see the core Deep Security help.

To use the API to interact with a malware scan configuration, use the antimalwareconfigurations endpoint. (See the Anti Malware Configurations operations in the API Reference.)

Example: Configure directory exclusions for a malware scan configuration

Python
def set_exclusion_dir_real_time_scan(client, configuration, api_version, api_exception, scan_config_id, dir_list_id):
    """ Configures a Malware Scan Configuration to exclude a directory list from scans.

    :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 scan_config_id: The ID of the scan configuration.
    :param dir_list_id: The ID of the directory list to exclude from scans.
    :return: An AntiMalwareConfigurationsApi object with the modified scan configuration.
    """

    # Create an anti-malware scan configuration
    real_time_config = client.AntiMalwareConfiguration()

    # Set the exclusion
    real_time_config.excluded_directory_list_id = dir_list_id

    try:
        # Modify the anti-malware scan configuration on Deep Security Manager
        am_configurations_api = client.AntiMalwareConfigurationsApi(client.ApiClient(configuration))
        return am_configurations_api.modify_anti_malware(scan_config_id, real_time_config, api_version)

    except api_exception as e:
        return "Exception: " + str(e)
JavaScript
/* 
* Configures a Malware Scan Configuration to exclude a directory list from scans.
* @param {object} api The API module.
* @param {Number} dirListID The ID of the directory list to exclude from scans.
* @param {Number} scanConfigID The ID of the scan configuration.
* @param {String} apiVersion The version of the API to use.
* @return {Promise} A promise that contains the malware scan configuration ID.
*/
exports.setExclusionDirRealTimeScan = function(api, dirListID, scanConfigID, apiVersion) {
  return new Promise((resolve, reject) => {
    // Create a malware scan configuration
    const realtimeConfig = new api.AntiMalwareConfiguration();

    // Set the exclusion
    realtimeConfig.excludedDirectoryListID = dirListID;

    // Modify the scan configuration on Deep Security Manager
    const amConfigurationsApi = new api.AntiMalwareConfigurationsApi();
    amConfigurationsApi.modifyAntiMalware(scanConfigID, realtimeConfig, apiVersion)
      .then(scanConfig => {
        resolve(scanConfig.ID);
      })
      .catch(error => {
        reject(error);
      });
  });
};
Java
/*
 * Sets the exclusion directory list for a policy's anti-malware real-time scan configuration.
 * @param scanConfigID The ID of the scan configuration.
 * @param dirListName The name of the exclusion directory list to use.
 */
public static void setExclusionDirRealTimeScan(Integer scanConfigID, Integer dirListId){

        //create a real time scan configuration object
        AntiMalwareConfiguration realtimeConfig = new AntiMalwareConfiguration();
        
        //Set the ID of the directory exclusion list
        realtimeConfig.setExcludedDirectoryListID(dirListId);
        
        //Update Deep Security Manager
        AntiMalwareConfigurationsApi amConfigsApi = new AntiMalwareConfigurationsApi();
        try {   
        amConfigsApi.modifyAntiMalware(scanConfigID, realtimeConfig, "v1");
    } catch (ApiException e) {
        System.out.println(e.getMessage());
        e.printStackTrace();
    }
}
For information about authenticating API calls, see Authenticate with Deep Security Manager.

Create and configure schedules

Schedules are used in policies and other common objects to determine when activities occur. For example, you use schedules to configure when scheduled malware scans run and when Firewall rules are active.

To create a schedule, perform these general steps:

  1. Create a Schedule object.
  2. Set general properties such as name and description.
  3. Create a list of 168 boolean values that indicate which hours of the week the scheduled activity is active (true) and inactive (false). Each value corresponds with the consecutive hours of the week starting at 00:00 on Sunday and ending at 23:00 on Saturday.
  4. Use a SchedulesApi object to add the schedule to Deep Security Manager.

To use the API to create a schedule, send a POST request to the schedules endpoint. (See the Create a Schedule operation in the API Reference.)

Example: Create a schedule for business hours only

Python
def create_business_hours_schedule(client, configuration, api_version, api_exception):
    """ Creates a schedule for an activity that occurs during normal business hours.

    :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.
    :return: A SchedulesApi object with the business hours schedule.
    """

    hours = []

    for day in range(0, 7):
        if day != 0 or day != 6:
            for hour in range(0, 24):
                if hour > 8 or hour > 17:
                    hours.append(True)
                else:
                    hours.append(False)
        else:
            for hour in range(0, 24):
                hours.append(False)

    # Create the schedule
    schedule = client.Schedule()
    schedule.name = "Normal Business Hours"
    schedule.hours_of_week = hours

    try:
        # Add the schedule to Deep Security Manager
        schedules_api = client.SchedulesApi(client.ApiClient(configuration))
        return schedules_api.create_schedule(schedule, api_version)

    except api_exception as e:
        return "Exception: " + str(e)
JavaScript
/* 
* Creates a schedule for an activity that occurs during normal business hours.
* @param {object} api The API module.
* @param {String} apiVersion The version of the API to use.
* @return {Promise} A promise that contains the schedule ID.
*/
exports.createBusinessHoursSchedule = function(api, apiVersion) {
  return new Promise((resolve, reject) => {
    // Create the array of boolean values that represent hours of the week
    const hours = [];
    for (let i = 0; i < 7; i++) {
      if (i !== 0 && i !== 6) {
        //true from Monday - Friday
        for (let j = 0; j < 24; j++) {
          if (j > 8 && j < 17) {
            //true from 9AM to 5PM
            hours.push(true);
          } else {
            hours.push(false);
          }
        }
      } else {
        //false for weekends
        for (let k = 0; k < 24; k++) {
          hours.push(false);
        }
      }
    }

    // Create the schedule
    const schedule = new api.Schedule();
    schedule.name = "Normal Business Hours";
    schedule.hoursOfWeek = hours;

    // Add to Deep Security Manager
    const schedulesApi = new api.SchedulesApi();
    schedulesApi
      .createSchedule(schedule, apiVersion)
      .then(newSchedule => {
        resolve(newSchedule.ID);
      })
      .catch(error => {
        reject(error);
      });
  });
};
Java
/*
 * Creates a schedule for an activity that occurs during business hours.
 * @returns The ID of the created schedule.
 */
public static Integer createBusinessHoursSchedule() {
    Schedule schedule = new Schedule();
    schedule.setName("Normal business hours");
    List<Boolean> hours = new ArrayList<Boolean>();
    for (int i=0;i<7;i++) {
        if (i != 0 && i != 6) {
            //true from Monday - Friday
            for (int j=0; j<24; j++) {
                if (j>8 && j<17) {
                    //true from 9AM to 5PM
                    hours.add(true);
                }else {
                    hours.add(false);
                }
            }
        } else {
            for (int k=0; k<24; k++) {
                hours.add(false);
            }
        }
    }
    //Add hours to schedule
    schedule.setHoursOfWeek(hours);
    //Add to Deep Security Manager
    SchedulesApi schedulesApi = new SchedulesApi();
    try {
        schedule = schedulesApi.createSchedule(schedule, "v1");
    } catch (ApiException e) {
        e.printStackTrace();
    }
    return schedule.getID();
}

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