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

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

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

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

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

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