Views:
Use the API to gather information about the security status of the computers that Server & Workload Protection 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.

Discover unprotected computers Parent topic

Discover unprotected computers based on the real-time status of the agent or appliance, or on the status of a protection module:
  • The computer has no agent or appliance installed, or the agent or appliance is not active
  • The protection module is not on, or it is on and not active
For virtual machines, you can also obtain the machine state and other information, which can be useful for troubleshooting.
For background information about computer statuses, see Computer and agent statuses

Find computers based on agent status Parent topic

Computers that have no agent installed are not protected by Server & Workload Protection. Computers could also be unprotected when problems exist with their agent or appliance.
To determine whether an agent or appliance is installed, check for the agent and appliance fingerprint. No fingerprint indicates that no agent or appliance is installed and therefore the computer is unprotected. When an agent or appliance is installed, also check their status. For example, a status of active indicates that the agent or appliance is running correctly. Other statuses, such as error or inactive, indicate a problem that you should investigate.
The following example JSON represents the data structure of a Computer object (some items are omitted to make the example more concise). The agentFingerPrint shows that an agent is installed and the computerStatus shows that it is active.
{
    "hostName": "laptop_adaggs",
    ...
    "policyID": 34,
    "agentFingerPrint": "71:3E:81:64:65:EB:34:78:FC:72:C2:CB:37:6B:1D:F0:8C:D1:9B:1E",
    "agentVersion": "11.3.2.883",
    "computerStatus": {
        "agentStatus": "active",
        "agentStatusMessages": [
            "Managed (Online)"
        ]
    },
    "computerSettings": {...},
    "ID": 48,
    "antiMalware": {...},
    ...
}
Tip
Tip
An offline status can indicate that Server & Workload Protection cannot communicate with the computer. With this status, the agent or appliance can be running normally and providing protection. However, Server & Workload Protection cannot send security updates to the agent or appliance.
Use the following general procedure to discover unprotected computers:

Procedure

  1. Use ComputersApi to obtain a Computer object.
  2. Check the AgentFingerPrint and ApplianceFingerPrint property of the computer.
  3. Obtain the ComputerStatus object from the Computer object and check the AgentStatus property. Any value other than ACTIVE can indicate a problem.
  4. Optionally, obtain the AgentStatusMessages of the ComputerStatus object and the AgentTasks property of the Computer object for useful information.

What to do next

Tip
Tip
Because the value of the computerStatus field of a computer is an object (ComputerStatus), you cannot search on this field.
To check the status of all computers, first use the ComputersApi class to list all computers:
computers_api = api.ComputersApi(api.ApiClient(configuration))
computers = computers_api.list_computers(api_version, expand=expand.list(), overrides=False)
For each computer, check for the agent and appliance fingerprint. No fingerprint indicates that no agent or appliance is installed and the computer is not protected. Note that a computer can have both an agent and an appliance installed. You need to check the value of both fingerprints.
if computer.agent_finger_print == None and computer.appliance_finger_print == None:
If a fingerprint is found, get the agent or appliance status to determine if it is active. Any status other than active can indicate a problem with the agent or appliance.
agent_status = computer.computer_status.agent_status
if computer.agent_finger_print != None and agent_status != "active":
    ...
appliance_status = computer.computer_status.appliance_status
if computer.appliance_finger_print != None and appliance_status != "active":
    ...
When the status is not active, obtain the status message and tasks of the agent or appliance. The following example shows how to obtain the information for an agent.
if computer.computer_status.agent_status_messages != None:
    computer_info.append(str(computer.computer_status.agent_status_messages))
else:
    computer_info.append("")

if computer.tasks != None:
    computer_info.append(str(computer.tasks.agent_tasks))
else:
computer_info.append("")
The following example finds computers that have neither an agent or appliance installed, or the status of the agent and/or appliance is not active. In the full source code sample, the results are compiled in a format that can be saved as a CSV file to open as a spreadsheet.
View source
# Include computer status information in the returned Computer objects
expand = api.Expand(api.Expand.computer_status)

# Get all computers
computers_api = api.ComputersApi(api.ApiClient(configuration))
computers = computers_api.list_computers(api_version, expand=expand.list(), overrides=False)

for computer in computers.computers:
    computer_info = []

    # Report on computers with no agent or appliance
    if computer.agent_finger_print is None and computer.appliance_finger_print is None:
        # Hostname and protection type
        computer_info.append(computer.host_name)
        computer_info.append("None")

        # Agent/appliance status and status messages
        computer_info.append("No agent/appliance")
        status_messages = ""
        if computer.computer_status is not None and computer.computer_status.agent_status is not None:
            status_messages = str(computer.computer_status.agent_status_messages)
        computer_info.append(status_messages)

    else:
        # Report on problem agents and appliances
        agent_status = computer.computer_status.agent_status
        appliance_status = computer.computer_status.appliance_status

        # Agent is installed but is not active
        if computer.agent_finger_print is not None and agent_status != "active":
            # Hostname and protection type
            computer_info.append(computer.host_name)
            computer_info.append("Agent")

            # Agent status, status messages, and tasks
            if computer.computer_status.agent_status is not None:
                computer_info.append(computer.computer_status.agent_status)
            else:
                computer_info.append("")

            if computer.computer_status.agent_status_messages is not None:
                computer_info.append(str(computer.computer_status.agent_status_messages))
            else:
                computer_info.append("")

            if computer.tasks is not None:
                computer_info.append(str(computer.tasks.agent_tasks))
            else:
                computer_info.append("")

        # Appliance is installed but is not active
        if computer.appliance_finger_print is not None and appliance_status != "active":
            # Hostname and protection type
            computer_info.append(computer.host_name)
            computer_info.append("Appliance")

            # Appliance status, status messages, and tasks
            if computer.computer_status.appliance_status is not None:
                computer_info.append(computer.computer_status.appliance_status)
            else:
                computer_info.append("")

            if computer.computer_status.appliance_status_messages is not None:
                computer_info.append(str(computer.computer_status.appliance_status_messages))
            else:
                computer_info.append("")

            if computer.tasks is not None:
                computer_info.append(str(computer.tasks.appliance_tasks))
            else:
                computer_info.append("")
Also see the List Computers, Describe a Computer, and Search Computers operations in the API Reference.

Find computers based on module status Parent topic

Computers are vulnerable when a protection module is turned off or a problem prevents the agent or appliance from running the module correctly. To check if a computer is protected by a protection module, check the module state (on or off ). When the state is on, also check the module status which indicates the ability of the agent and/or appliance to run the module. Any status other than active can indicate a problem that requires your attention. You can also obtain status messages that can provide insight into the status.
The following example JSON represents the data structure of a Computer object (some items are omitted to make the example more concise). The Anti-Malware module is on, however the agent status for the module shows a warning.
{
    "hostName": "192.168.60.128",
    ...
    "policyID": 9,
    "agentFingerPrint": "76:C8:CE:B3:70:61:A3:BE:84:A2:2A:5D:1F:3A:29:8A:DC:7A:70:6C",
    "agentVersion": "11.2.0.147",
    "computerStatus": {...},
    "computerSettings": {...},
    ...
    "ID": 2,
    "antiMalware": {
        "state": "on",
        "moduleStatus": {
            "agentStatus": "warning",
            "agentStatusMessage": "Software Update: Anti-Malware Module Installation Failed"
        },
        "realTimeScanConfigurationID": 1,
        "realTimeScanScheduleID": 4,
        "manualScanConfigurationID": 2,
        "scheduledScanConfigurationID": 3
    },
    "webReputation": {...},
    "firewall": {...},
    "intrusionPrevention": {...},
    "integrityMonitoring": {...},
    "logInspection": {...},
    "applicationControl": {...}
}
Use the following general procedure to use module statuses to discover unprotected computers:

Procedure

  1. Use ComputersApi to obtain a Computer object.
  2. Obtain the computer extension object for the protection module in which you are interested, such as AntiMalwareComputerExtension or IntrusonPreventionComputerExtension.
  3. From the computer extension object, get the value of the module state to see if the module is on or off.
  4. Also from the computer extension object, get the ModuleStatus object and obtain the agent and appliance status and status messages.

What to do next

Tip
Tip
Because the value of the moduleStatus field of a computer extension is an object (ModuleStatus), you cannot search on this field.
To check the module status of all computers, first use the  ComputersApi class to list all computers:
computers_api = api.ComputersApi(api.ApiClient(configuration))
computers = computers_api.list_computers(api_version, expand=expand.list(), overrides=False)
For each computer, get the agent status for the protection module in which you are interested. Get the module status and then check its agent or appliance status. Any status other than active can indicate a problem with the agent or appliance. Note that if no agent is installed, there is no agent status. Similarly, with no appliance installed there is no appliance status.
if computer.anti_malware.module_status:
    agent_status = computer.anti_malware.module_status.agent_status
    appliance_status = computer.anti_malware.module_status.appliance_status
else:
    agent_status = None
    appliance_status = None

if agent_status and agent_status != "active":
    ...

if appliance_status and appliance_status != "active":
    ...
For non-active statuses, obtain the agent or appliance status message for the module:
module_info.append(computer.anti_malware.module_status.agent_status_message)
    module_info.append(computer.anti_malware.module_status.appliance_status_message)
The following example finds computers that have the Anti-Malware module turned off, or where the status of the module is not active.  In the full source code sample, the results are returned in a format that can be saved as a CSV file to open as a spreadsheet.
View source
computers_api = api.ComputersApi(api.ApiClient(configuration))
computers = computers_api.list_computers(api_version, expand=expand.list(), overrides=False)

# Get the list of computers and iterate over it
for computer in computers.computers:
    # Module information to add to the CSV string
    module_info = []

    # Check that the computer has a an agent or appliance status
    if computer.anti_malware.module_status:
        agent_status = computer.anti_malware.module_status.agent_status
        appliance_status = computer.anti_malware.module_status.appliance_status
    else:
        agent_status = None
        appliance_status = None

    # Agents that are not active for the module
    if agent_status and agent_status != "active":
        # Host name
        module_info.append(computer.host_name)

        # Module state
        module_info.append(computer.anti_malware.state)

        # Agent status and status message
        module_info.append("Agent")
        module_info.append(agent_status)
        module_info.append(computer.anti_malware.module_status.agent_status_message)

    # Appliances that are not active for the module
    if appliance_status and appliance_status != "active":
        # Host name
        module_info.append(computer.host_name)

        # Module state
        module_info.append(computer.anti_malware.state)

        # Appliance status and status message
        module_info.append("Appliance")
        module_info.append(appliance_status)
        module_info.append(computer.anti_malware.module_status.appliance_status_message)
Also see the List Computers, Describe a Computer, and Search Computers operations in the API Reference.

See the state of a virtual machine Parent topic

When a computer is a virtual machine, you can obtain several properties of the virtual machine, including the state (as defined by the virtual machine vendor). The Computer class provides access to several virtual machine summary objects, such as azureARMVirtualMachineSummary, ec2VirtualMachineSummary, and vmwareVMVirtualMachineSummary. (For a complete list, see the API Reference.)
You can obtain the virtual machine summary for your computer and use it to check the properties of the virtual machine, such as the state.

Get computer configurations Parent topic

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.
Tip
Tip
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. Use the expand parameter to retrieve only the computer information that you need.
# Include Anti-Malware information in the returned Computer object
expand = api.Expand(api.Expand.anti_malware, api.Expand.computer_settings)

# Get the computer object from Server & Workload Protection
computers_api = api.ComputersApi(api.ApiClient(configuration))
computer = computers_api.describe_computer(computer_id, api_version, expand=expand.list(), overrides=False)

# Get the Anti-Malware scan configuration id for the computer
real_time_scan_configuration_id = computer.anti_malware.real_time_scan_configuration_id

# Get the Anti-Malware properties for the computer
am_configs_api = api.AntiMalwareConfigurationsApi(api.ApiClient(configuration))
return am_configs_api.describe_anti_malware(real_time_scan_configuration_id, api_version)

Discover the Anti-Malware configuration of a computer Parent topic

AntiMalwareComputerExtension objects provide access to the following items of the Anti-malware configuration for a computer:
  • 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:

Procedure

  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.

What to do next

The following example obtain certain properties of the Anti-Malware configurations of a computer
View source
# Get the anti-malware scan configuration id for the computer
real_time_scan_configuration_id = computer.anti_malware.real_time_scan_configuration_id

# Get the anti-malware properties for the computer
am_configs_api = api.AntiMalwareConfigurationsApi(api.ApiClient(configuration))
return am_configs_api.describe_anti_malware(real_time_scan_configuration_id, api_version)
Also see the List Computers, Describe a Computer, and Search Computers operations in the API Reference.

Get applied intrusion prevention rules Parent topic

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

Procedure

  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.

What to do next

The following example retrieves the Intrusion Prevention rules that are applied to computers.
View source
# Extract intrusion prevention rules from the computers
im_rules = {}
for computer in computers_list.computers:
    im_rules[computer.host_name] = computer.intrusion_prevention.rule_ids
return im_rules
Also see the List Computers, Describe a Computer, and Search Computers operations in the API Reference. For information about authenticating API calls, see Authenticate with Server & Workload Protection.