Assign rules with recommendation scans

Recommendation scans identify Intrusion Prevention, Integrity Monitoring, and Log Inspection rules that should be assigned or removed for a computer or policy. The API provides access to the results of recommendation scans for each of these protection modules at the computer and policy levels via the following classes:

• ComputerIntrusionPreventionAssignmentsRecommendationsApi
• ComputerIntegrityMonitoringAssignmentsRecommendationsApi
• ComputerLogInspectionAssignmentsRecommendationsApi
• PolicyIntrusionPreventionAssignmentsRecommendationsApi
• PolicyIntegrityMonitoringAssignmentsRecommendationsApi
• PolicyLogInspectionAssignmentsRecommendationsApi

The methods and functions of these classes return objects that include the latest recommendations and scan information. The following JSON represents the data structure of the returned objects:

{
    "assignedRuleIDs": [],
    "recommendationScanStatus": "valid",
    "lastRecommendationScanDate": "1562702362438",
    "recommendedToAssignRuleIDs": [],
    "recommendedToUnassignRuleIDs": []
}

To run a recommendation scan using the API, you use scheduled tasks. See the Maintain Protection Using Scheduled Tasks guide.

For more information about recommendation scans, see Manage and run recommendation scans.

Obtain the date of the last recommendation scan

Obtain the date of the last recommendation scan when you want to make sure your computers have been recently scanned. For example, a computer is not scanned if it is offline when the recommendation scan is scheduled to run. You can run a script that discovers, for each computer in your environment, when a scan last ran. Depending on the results, you can run a recommendation scan as needed.

Use the following general steps to get the date of the last recommendation scan for one or more computers:

1. Create a ComputersApi object to obtain the ID of the computers to check.
2. Create a ComputerIntrusionPreventionAssignmentsRecommendationsApi object and use it to list the Intrusion Prevention rule assignments and recommendations.
3. Obtain the date of the last scan from the returned IntrusionPreventionAssignments object.

When a recommendation scan runs, it determines recommendations for the Intrusion Prevention, Integrity Monitoring, and Log Inspection security modules. Therefore, the methods and functions of the ComputerIntrusionPreventionAssignmentsRecommendationsApi, ComputerIntegrityMonitoringAssignmentsRecommendationsApi, and ComputerLogInspectionAssignmentsRecommendationsApi return the same value for the date and status of the last scan.

For example, obtain a list of all computers in your environment (you only need the ID so set the expand parameter to none to return the minimal information):

expand = api.Expand(api.Expand.none)
computers_api = api.ComputersApi(api.ApiClient(configuration))
computers = computers_api.list_computers(api_version, expand=expand.list(), overrides=False)

For each computer, obtain the applied rules and recommendation scan results:

computer_ips_assignments_recommendations_api = (
    api.ComputerIntrusionPreventionRuleAssignmentsRecommendationsApi(api.ApiClient(configuration)))
intrusion_prevention_assignments = (
    computer_ips_assignments_recommendations_api.list_intrusion_prevention_rule_ids_on_computer(
        computer.id,
        api_version,
        overrides=False)

Finally, extract the date of the last scan. Note that when no recommendation scan has run, the property is None:

reco_scan_info = list()
if intrusion_prevention_assignments.last_recommendation_scan_date is not None:
    d = datetime.datetime.utcfromtimestamp(intrusion_prevention_assignments.last_recommendation_scan_date/1000)
    reco_scan_info.append(d.strftime('%Y-%m-%d %H:%M:%S'))
else:
    reco_scan_info.append("No scan on record")

Also see the List Intrusion Prevention Rule IDs operation in the API Reference.

Example: Get the date of the last recommendation scan for all computers

The following example retrieves a list of all computers and determines the date and status of the last recommendation scan. The information, along with the computer hostnames, are returned in comma separated value (CSV) format that can be opened as a spreadsheet.

View source

# Include minimal information in the returned Computer objects
expand = api.Expand(api.Expand.none)

# Get the list of computers and iterate over it
computers_api = api.ComputersApi(api.ApiClient(configuration))
computers = computers_api.list_computers(api_version, expand=expand.list(), overrides=False)

computer_ips_assignments_recommendations_api = (
    api.ComputerIntrusionPreventionRuleAssignmentsRecommendationsApi(api.ApiClient(configuration)))

for computer in computers.computers:
    # Get the recommendation scan information
    intrusion_prevention_assignments = (
        computer_ips_assignments_recommendations_api.list_intrusion_prevention_rule_ids_on_computer(
            computer.id,
            api_version,
            overrides=False))
    reco_scan_info = list()

    # Computer name
    reco_scan_info.append(computer.host_name)

    # Scan date
    if intrusion_prevention_assignments.last_recommendation_scan_date is not None:
        d = datetime.datetime.utcfromtimestamp(intrusion_prevention_assignments.last_recommendation_scan_date/1000)
        reco_scan_info.append(d.strftime('%Y-%m-%d %H:%M:%S'))
    else:
        reco_scan_info.append("No scan on record")

    # Scan status
    reco_scan_info.append(intrusion_prevention_assignments.recommendation_scan_status)

    # Add to the CSV string
    csv += format_for_csv(reco_scan_info)

return csv

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 Intrusion Prevention 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

The following example obtains the recommendations for Intrusion Prevention for a computer.

View source

ip_recommendations_api = api.ComputerIntrusionPreventionRuleAssignmentsRecommendationsApi(api.ApiClient(configuration))
ip_assignments = None

ip_assignments = ip_recommendations_api.list_intrusion_prevention_rule_ids_on_computer(computer_id, api_version, overrides=False)
return ip_assignments.recommended_to_assign_rule_ids

Also see the List Intrusion Prevention Rule IDs operation in the API Reference. For information about authenticating API calls, see Authenticate with Workload Security.