Discover Vulnerabilities and Computer Security Statuses

Use the API to gather information about the security status of the computers that Deep Security is protecting. For example, to create a monthly report of your security status, you gather information about security modules, such as their running state (on or off), and whether the latest rules are assigned.

You can also discover whether you are protected against a specific threat. For example when a CVE is released for a zero-day vulnerability, you can find the intrusion prevention rule for that CVE and apply it to your computers.

Get computer configurations

Computer objects contain the configuration information for a computer. To obtain Computer objects, create a ComputersApi object and then either get a specific computer by ID, search by some other property, or list all computers and iterate over them.

When you obtain a computer, you indicate whether to include all properties or only the overrides that are set on that computer:

  • All properties: Includes those inherited from the computer’s assigned policy as well as overrides.
  • Only overrides: Includes only the properties that have been overridden on that computer. All inherited properties are null.

To access the current configuration of a computer, you use the Computer object to obtain a computer extension object for a protection module. For example, to get information about the anti-malware configuration or state for a computer, you get the AntiMalwareComputerExtension object.

ComputersApi computersApi = new ComputersApi();
try {
	Computers computers = computersApi.listComputers(false, "v1");
	for (Computer computer : computers.getComputers()) {
		AntiMalwareComputerExtension antiMalware = computer.getAntiMalware();
		//Perform operations on antiMalware
	}	
} catch (ApiException e) {
	e.printStackTrace();
}

Discover the Anti-Malware configuration of a computer

AntiMalwareComputerExtension objects provide access to the Anti-malware configuration for a computer, including the:

  • Anti-Malware module running state (on or off)
  • Malware scan configurations

Use the following general steps to obtain the Anti-Malware configuration for your computers:

  1. Use a ComputersApi object to obtain the Computer object.
  2. Use the Computer object to obtain the AntiMalwareComputerExtension object.
  3. Obtain the Anti-Malware module state.
  4. Obtain the scan configurations.

Example: Obtain Anti-Malware configurations of all computers

/*
 * Obtains certain properties of the Anti-Malware module for all computers
 * @return A HashMap of computer hostnames (the key) and the a list of properties (the value).
 */
public static ArrayList<HashMap<String, Object>> checkAntiMalware() {
	//Stores the properties
	ArrayList<HashMap<String, Object>> amStatuses = new ArrayList<HashMap<String, Object>>();
	//Stores the computer host names and the properties
	HashMap<String, Object> amStatus = null;
	
	ComputersApi computersApi = new ComputersApi();
	AntiMalwareConfigurationsApi amConfigApi = new AntiMalwareConfigurationsApi();
	try {
		//Get all computers
		Computers computers = computersApi.listComputers(false, "v1");
		for (Computer computer : computers.getComputers()) {
			//Get properties for each computer
			amStatus = new HashMap<String, Object>();
			amStatus.put("hostname", computer.getHostName());
			AntiMalwareComputerExtension antiMalware = computer.getAntiMalware();
			
			//Get anti malware state
			String state = antiMalware.getState().getValue();
			amStatus.put("state", state);
			
			//Smart Scan enabled?
			amStatus.put("AntiMalwareSettingSmartScanState", computer.getComputerSettings().getAntiMalwareSettingSmartScanState().getValue());
			
			//Scanned directories
			Integer realTimeScanConfigID = antiMalware.getRealTimeScanConfigurationID();
			if (realTimeScanConfigID != null && realTimeScanConfigID.intValue()>0) {
				AntiMalwareConfiguration amc = amConfigApi.describeAntiMalware(realTimeScanConfigID, "v1");
				amStatus.put("directories", amc.getDirectoriesToScan());
				if (amc.getDirectoriesToScan() == AntiMalwareConfiguration.DirectoriesToScanEnum.DIRECTORY_LIST) {
					amStatus.put("scan-dirs", amc.getDirectoryListID());
				}
			}
			amStatuses.add(amStatus);
		}
	} catch (ApiException e) {
		e.printStackTrace();
	}
	return amStatuses;
}

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

Get applied intrusion prevention rules

Determine the Intrusion Prevention rules that are applied to your computers to ensure that the required protections are in place.

  1. Use a ComputersApi object to obtain the Computer objects.
  2. For each Computer object, obtain the IntrusionPreventionComputerExtension object.
  3. Obtain the list of Intrusion Prevention rules.

Example: Retrieve applied Intrusion Prevention rules for all computers

/*
 * Compiles a list of intrusion prevention rules that are applied to each computer.
 * @return A HashMap that has computer IDs as keys and a list of rules (or null if no rules) as values.
 */
public static HashMap<Integer, List<Integer>> getIntrusionPreventionRules(){
	HashMap<Integer, List<Integer>> computerRules = new HashMap<Integer, List<Integer>>();
	ComputersApi computersApi = new ComputersApi();
	try {
		//Get all computer IDs
		Computers computers = computersApi.listComputers(false, "v1");
		//For each computer, get the IDs for the assigned rules
		for (Computer computer : computers.getComputers()) {
			IntrusionPreventionComputerExtension ipce = computer.getIntrusionPrevention();
			computerRules.put(computer.getID(), ipce.getRuleIDs());
		}
	} catch (ApiException e) {
		e.printStackTrace();
	}
	return computerRules;
}

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

Patch unprotected computers

Deep Security creates Intrusion Prevention rules that patch your computers against CVE’s. You can use the API to determine which Intrusion Prevention rule protects against a specific CVE, determine if the rule is applied to your computers, and apply the rule if required.

  1. Use an IntrusionPreventionRulesApi object to obtain the intrusion prevention rules via search.
  2. For each computer, obtain an IntrusionPreventionComputerExtension object and determine if the rule is applied to the computer.
  3. For each vulnerable computer, determine the policy that it uses, add the rule to the policy, and update the computers with the change.

Example: Find the Intrusion Prevention rule for a CVE

/*
 * Finds the intrusion prevention rules for a CVE.
 * @param cve The CVE ID.
 * @return A list of the intrusion prevention rule ID. The  list is empty if no rule is found.
 */
public static List<Integer> findRuleForCVE(String cve) {

	List<Integer> ruleIDs = new ArrayList<Integer>();

	IntrusionPreventionRulesApi intrusionPreventionRulesApi = new IntrusionPreventionRulesApi();

	//Create a search filter to find the rules
	SearchFilter searchFilter = new SearchFilter();

	SearchCriteria searchCriteria = new SearchCriteria();
	searchCriteria.fieldName("CVE");
	searchCriteria.setStringValue("%" + cve + "%");
	searchCriteria.setStringTest(StringTestEnum.EQUAL);

	searchFilter.addSearchCriteriaItem(searchCriteria);
	try {
		//Perform the searcch
		IntrusionPreventionRules intrusionPreventionRules = intrusionPreventionRulesApi.searchIntrusionPreventionRules(searchFilter,
				"v1");
		//Get the rule IDs from the results
		for (IntrusionPreventionRule rule : intrusionPreventionRules.getIntrusionPreventionRules()) {
			ruleIDs.add(rule.getID());
		}

	} catch (ApiException e) {
		System.out.println(e.getMessage());
		e.printStackTrace();
	}
	return ruleIDs;
}

Example: Find computers that are not protected against a CVE

/*
 * Finds computers that do not have a specific intrusion prevention rule applied.
 * @param ruleID The rule ID.
 * @return A Computers object that contains the computers that do not have the rule applied.
 */
public static Computers checkComputersForIPRule(Integer ruleID){
	Computers needsRule = new Computers();
	ComputersApi computersApi = new ComputersApi();
	try {
		Computers computers = computersApi.listComputers(false, "v1");
		for (Computer computer : computers.getComputers()) {
			IntrusionPreventionComputerExtension ipExt = computer.getIntrusionPrevention();
			if (ipExt.getRuleIDs() == null || !ipExt.getRuleIDs().contains(ruleID)) {
				needsRule.addComputersItem(computer);
			}
		}
	} catch (ApiException e) {
		e.printStackTrace();
	}
	return needsRule;
}

Example: Add intrusion prevention rules to computers’ policies

/*
 * Adds an Intrusion Prevention rule to the policies of a list of computers.
 * @param needsRule A Computers object that contains computers that require the protection of the rule.
 * @param ruleID The ID of the rule to add to the policies
 */
public static void applyRuleToPolicies(Computers needsRule, Integer ruleID) {
	//Stores IDs of policies to modify (HashSet ensures no duplicates)
	HashSet<Integer> policyIDs = new HashSet<Integer>();
	
	//Get the policy IDs of each computer 
	ArrayList<Computer> computers = (ArrayList<Computer>) needsRule.getComputers();
	for (Computer computer : computers) {
		if (computer.getPolicyID() != null) {
			policyIDs.add(computer.getPolicyID());
		}
	}
		
	PoliciesApi policiesApi = new PoliciesApi();

	for (Integer policyID : policyIDs) {
		try {
			//Get the current list of rules from the policy
			ArrayList<Integer> currentRules = (ArrayList<Integer>) policiesApi.describePolicy(policyID, false, "v1").getIntrusionPrevention().getRuleIDs();

			//Add the new and existing intrusion prevention rules to a policy 
			IntrusionPreventionPolicyExtension intrusionPreventionPolicyExtension = new IntrusionPreventionPolicyExtension();
			intrusionPreventionPolicyExtension.setRuleIDs(currentRules);
			intrusionPreventionPolicyExtension.addRuleIDsItem(ruleID);
			Policy policy = new Policy();
			policy.setIntrusionPrevention(intrusionPreventionPolicyExtension);
			
			//Configure sending policy updates when the policy changes
			policy.setAutoRequiresUpdate(Policy.AutoRequiresUpdateEnum.ON);
			
			//Modify the policy on Deep Security Manager
			policiesApi.modifyPolicy(policyID, policy, false, "v1");
		} catch (ApiException e) {
			e.printStackTrace();
		}
	}
}

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

Apply recommendations

The API provides access to the recommendation scan results that have been made for a computer for the integrity monitoring, intrusion prevention, and log inspection modules. Use a ComputerIntrusionPreventionAssignmentsRecommendationsApi object to obtain an IntrusionPreventionAssignments object for a computer. The IntrusionPreventionAssignments object contains and provides access to the recommendations for that computer:

  • Recommended rules to assign and unassign
  • Scan status
  • When the last scan occurred

After you obtain the rule recommendations, you can apply them to computer policies, as illustrated in the Add intrusion prevention rules to computers’ policies example.

When there has been no recommendation scan performed on a computer, ComputerIntrusionPreventionAssignmentsRecommendationsApi returns null for rule IDs and the last scan occurrence.

Similar classes are provided for the integrity monitoring and log inspection modules:

  • ComputerIntegrityMonitoringAssignmentsRecommendationsApi and IntegrityMonitoringAssignments
  • ComputerLogInspectionAssignmentsRecommendationsApi and LogInspectionAssignments

Example: Obtain recommendations for intrusion prevention

/*
 * Obtains the list of recommended intrusion prevention rules to apply to a computer, 
 * according to the results of the last recommendation scan.
 * @param computerID The ID of the computer that was scanned.
 * @return A list of rule IDs, or null if no scan was performed.
 */
public static ArrayList<Integer> getIntrusionPreventionRecommendations(Integer computerID){
	ComputerIntrusionPreventionRuleAssignmentsRecommendationsApi ipRecosApi = new ComputerIntrusionPreventionRuleAssignmentsRecommendationsApi();
	IntrusionPreventionAssignments ipAssignments = null;
	try {
		ipAssignments = ipRecosApi.listIntrusionPreventionRuleIDsOnComputer(computerID, false, "v1");
	} catch (ApiException e) {
		e.printStackTrace();
	}
	return (ArrayList<Integer>) ipAssignments.getRecommendedToAssignRuleIDs();
}

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