Report on Computer Status

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.

Discover unprotected computers

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 in the Deep Security Help Center.

Find computers based on agent status

Computers that have no agent or appliance installed are not protected by Deep Security. 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": {...},
    ...
}

An offline status can indicate that Deep Security Manager cannot communicate with the computer. With this status, the agent or appliance can be running normally and providing protection. However, the manager cannot send security updates to the agent or appliance.

Use the following general procedure to discover unprotected computers:

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

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:

Python

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

JavaScript

const getListOfComputers = () => {
  const computersApi = new api.ComputersApi();
  return computersApi.listComputers(apiVersion, opts);
};

Java

ComputersApi computersApi = new ComputersApi();
Computers computers = computersApi.listComputers(expand.list(), Boolean.FALSE, apiVersion);

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.

Python

if computer.agent_finger_print == None and computer.appliance_finger_print == None:

JavaScript

if ((computer.agentFingerPrint === undefined) & (computer.applianceFingerPrint === undefined))

Java

if (computer.getAgentFingerPrint() == null && computer.getApplianceFingerPrint() == null)

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.

Python

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":
    ...

JavaScript

const agentIsActive = computer.computerStatus.agentStatus == api.ComputerStatus.AgentStatusEnum.active;
if (computer.agentFingerPrint !== undefined && !agentIsActive) {
    ...
}

const applianceIsActive = computer.computerStatus.applianceStatus == api.ComputerStatus.ApplianceStatusEnum.active;
if (computer.applianceFingerPrint !== undefined && !applianceIsActive) {
    ...
}

Java

boolean agentIsActive = computer.getComputerStatus().getAgentStatus() == ComputerStatus.AgentStatusEnum.ACTIVE;
if (computer.getAgentFingerPrint() != null && !agentIsActive) {
    ...
}
boolean applianceIsActive = computer.getComputerStatus().getApplianceStatus() == ComputerStatus.ApplianceStatusEnum.ACTIVE;
if (computer.getApplianceFingerPrint() != null && !applianceIsActive) {
    ....
}

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.

Python

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("")

JavaScript

computerInfo.push( computer.computerStatus.agentStatusMessages !== undefined ? computer.computerStatus.agentStatusMessages : "" );

computerInfo.push( computer.tasks !== undefined ? computer.tasks.agentTasks : "");

Java

String statusMessages = (computer.getComputerStatus().getAgentStatusMessages() != null) ? computer.getComputerStatus().getAgentStatusMessages().toString() : "";
computerInfo.add(statusMessages);

String agentTasks = (computer.getTasks() != null) ? computer.getTasks().getAgentTasks().toString() : "";
computerInfo.add(agentTasks);

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.

Python

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("")

JavaScript

View source

// Get the computers and iterate them
getListOfComputers()
  .then(computers => {
    for (const computer of computers.computers) {
      const computerInfo = []; // Stores computer status information
      // Report on computers with no agent or appliance
      if ((computer.agentFingerPrint === undefined) & (computer.applianceFingerPrint === undefined)) {
        // Hostname and protection type
        computerInfo.push(computer.hostName);
        computerInfo.push("None");
        // Agent/appliance status and status message
        computerInfo.push("No agent/appliance");
        computerInfo.push(
          computer.computerStatus.agentStatus !== undefined ? computer.computerStatus.agentStatusMessages : ""
        );
      } else {
        // Report on problem agents and appliances
        const agentIsActive = computer.computerStatus.agentStatus == api.ComputerStatus.AgentStatusEnum.active;
        const applianceIsActive =
          computer.computerStatus.applianceStatus == api.ComputerStatus.ApplianceStatusEnum.active;
        if (computer.agentFingerPrint !== undefined && !agentIsActive) {
          // Agent is installed but not active
          computerInfo.push(computer.hostName);
          computerInfo.push("Agent");
          computerInfo.push(
            computer.computerStatus.agentStatus !== undefined ? computer.computerStatus.agentStatus : ""
          );
          computerInfo.push(
            computer.computerStatus.agentStatusMessages !== undefined
              ? computer.computerStatus.agentStatusMessages
              : ""
          );
          computerInfo.push(computer.tasks !== undefined ? computer.tasks.agentTasks : "");
        }
        if (computer.applianceFingerPrint !== undefined && !applianceIsActive) {
          // Appliance is installed but not active
          computerInfo.push(computer.hostName);
          computerInfo.push("Appliance");
          computerInfo.push(
            computer.computerStatus.applianceStatus !== undefined ? computer.computerStatus.applianceStatus : ""
          );
          computerInfo.push(
            computer.computerStatus.applianceStatusMessages !== undefined
              ? computer.computerStatus.applianceStatusMessages
              : ""
          );
          computerInfo.push(computer.tasks !== undefined ? computer.tasks.applianceTasks : "");
        }
      }
    }
  })

Java

View source

// Include computer status information in the returned Computer objects
Expand expand = new Expand(Expand.OptionsEnum.COMPUTER_STATUS);

// Get all computers
ComputersApi computersApi = new ComputersApi();
Computers computers = computersApi.listComputers(expand.list(), Boolean.FALSE, apiVersion);

for (Computer computer : computers.getComputers()) {
    List<String> computerInfo = new ArrayList<>();

    // Report on computers with no agent or appliance
    if (computer.getAgentFingerPrint() == null && computer.getApplianceFingerPrint() == null) {

        // Hostname and protection type
        computerInfo.add(computer.getHostName());
        computerInfo.add("None");

        // Agent/appliance status and status messages
        computerInfo.add("No agent/appliance");
        String statusMessages = (computer.getComputerStatus().getAgentStatus() != null) ? computer.getComputerStatus().getAgentStatusMessages().toString() : "";
        computerInfo.add(statusMessages);

    } else {
        // Report on problem agents and appliances
        boolean agentIsActive = computer.getComputerStatus().getAgentStatus() == ComputerStatus.AgentStatusEnum.ACTIVE;
        boolean applianceIsActive = computer.getComputerStatus().getApplianceStatus() == ComputerStatus.ApplianceStatusEnum.ACTIVE;

        // Agent is installed but is not active
        if (computer.getAgentFingerPrint() != null && !agentIsActive) {

            // Hostname and protection type
            computerInfo.add(computer.getHostName());
            computerInfo.add("Agent");

            // Agent status, status messages, and tasks
            String agentStatus = (computer.getComputerStatus().getAgentStatus() != null) ? computer.getComputerStatus().getAgentStatus().getValue() : "";
            computerInfo.add(agentStatus);
            String statusMessages = (computer.getComputerStatus().getAgentStatusMessages() != null) ? computer.getComputerStatus().getAgentStatusMessages().toString() : "";
            computerInfo.add(statusMessages);
            String agentTasks = (computer.getTasks() != null) ? computer.getTasks().getAgentTasks().toString() : "";
            computerInfo.add(agentTasks);
        }

        // Appliance is installed but is not active
        if (computer.getApplianceFingerPrint() != null && !applianceIsActive) {

            // Hostname and protection type
            computerInfo.add(computer.getHostName());
            computerInfo.add("Appliance");

            // Applicance status, messages, and tasks
            String applianceStatus = (computer.getComputerStatus().getApplianceStatus() != null) ? computer.getComputerStatus().getApplianceStatus().getValue() : "";
            computerInfo.add(applianceStatus);
            String applianceStatusMessages = computer.getComputerStatus().getApplianceStatusMessages() != null ? computer.getComputerStatus().getApplianceStatusMessages().toString() : "";
            computerInfo.add(applianceStatusMessages);
            String applianceTasks = (computer.getTasks() != null) ? computer.getTasks().getApplianceTasks().toString() : "";
            computerInfo.add(applianceTasks);
        }
    }
}

Also see the List Computers, Describe a Computer, and Search Computers operations in the API Reference.

Find computers based on module status

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:

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

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:

Python

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

JavaScript

const getListOfComputers = () => {
  const computersApi = new api.ComputersApi();
  return computersApi.listComputers(apiVersion, opts);
};

Java

ComputersApi computersApi = new ComputersApi();
Computers computers = computersApi.listComputers(expand.list(), Boolean.FALSE, apiVersion);

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.

Python

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":
    ...

JavaScript

const agentStatus = computer.antiMalware.moduleStatus.agentStatus;
if (agentStatus !== undefined && agentStatus !== api.ComputerModuleStatus.AgentStatusEnum.active) {
    ...
}

const applianceStatus = computer.antiMalware.moduleStatus.applianceStatus;
if (applianceStatus !== undefined && agentStatus !== api.ComputerModuleStatus.ApplianceStatusEnum.active) {
    ...
}

Java

AgentStatusEnum agentStatus = computer.getAntiMalware().getModuleStatus().getAgentStatus();
if (agentStatus != null && agentStatus != AgentStatusEnum.ACTIVE) {
    ...
}

ApplianceStatusEnum applianceStatus = computer.getAntiMalware().getModuleStatus().getApplianceStatus();
if (applianceStatus != null && applianceStatus != ApplianceStatusEnum.ACTIVE) {
    ...
}

For non-active statuses, obtain the agent or appliance status message for the module:

Python

module_info.append(computer.anti_malware.module_status.agent_status_message)

module_info.append(computer.anti_malware.module_status.appliance_status_message)

JavaScript

moduleInfo.push(computer.antiMalware.moduleStatus.agentStatusMessages);

moduleInfo.push(computer.antiMalware.moduleStatus.applianceStatusMessages);

Java

moduleInfo.add(computer.getAntiMalware().getModuleStatus().getAgentStatusMessage());

moduleInfo.add(computer.getAntiMalware().getModuleStatus().getApplianceStatusMessage());

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.

Python

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)

JavaScript

View source

  let moduleInfo = [];
  const agentStatus = computer.antiMalware.moduleStatus.agentStatus;
  const applianceStatus = computer.antiMalware.moduleStatus.applianceStatus;

  // Agents that are not active for the module
  if (agentStatus !== undefined && agentStatus !== api.ComputerModuleStatus.AgentStatusEnum.active) {
    // Hostname
    moduleInfo.push(computer.hostName);
    // Module state
    moduleInfo.push(computer.antiMalware.state);
    // Agent status and status message
    moduleInfo.push("Agent");
    moduleInfo.push(agentStatus);
    moduleInfo.push(computer.antiMalware.moduleStatus.agentStatusMessages);
  }
  // Appliances that are not active for the module
  if (applianceStatus !== undefined && agentStatus !== api.ComputerModuleStatus.ApplianceStatusEnum.active) {
    // Hostname
    moduleInfo.push(computer.hostName);
    // Module state
    moduleInfo.push(computer.antiMalware.state);
    // Agent status and status message
    moduleInfo.push("Appliance");
    moduleInfo.push(applianceStatus);
    moduleInfo.push(computer.antiMalware.moduleStatus.applianceStatusMessages);
  }

Java

View source

// Include Anti-Malware information in the returned Computer objects
Expand expand = new Expand(Expand.OptionsEnum.ANTI_MALWARE);

// Get a list of computers
ComputersApi computersApi = new ComputersApi();
Computers computers = computersApi.listComputers(expand.list(), Boolean.FALSE, apiVersion);

for (Computer computer : computers.getComputers()) {

    // Module information to add to the CSV string
    List<String> moduleInfo = new ArrayList<>();

    AgentStatusEnum agentStatus = computer.getAntiMalware().getModuleStatus().getAgentStatus();
    ApplianceStatusEnum applianceStatus = computer.getAntiMalware().getModuleStatus().getApplianceStatus();

    // Agents that are not active for the module
    if (agentStatus != null && agentStatus != AgentStatusEnum.ACTIVE) {

        // Hostname
        moduleInfo.add(computer.getHostName());

        // Module state
        moduleInfo.add(computer.getAntiMalware().getState().getValue());

        // Agent status and status message
        moduleInfo.add("Agent");
        moduleInfo.add(agentStatus.getValue());
        moduleInfo.add(computer.getAntiMalware().getModuleStatus().getAgentStatusMessage());
    }

    // Appliances that are not active for the module
    if (applianceStatus != null && applianceStatus != ApplianceStatusEnum.ACTIVE) {

        // Hostname
        moduleInfo.add(computer.getHostName());

        // Module state
        moduleInfo.add(computer.getAntiMalware().getState().getValue());

        // Appliance status and status messages
        moduleInfo.add("Appliance");
        moduleInfo.add(computer.getAntiMalware().getModuleStatus().getApplianceStatus().getValue());
        moduleInfo.add(computer.getAntiMalware().getModuleStatus().getApplianceStatusMessage());
    }
}

Also see the List Computers, Describe a Computer, and Search Computers operations in the API Reference.

See the state of a virtual machine

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

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. Use the expand parameter to retrieve only the computer information that you need.

Python

# 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 Deep Security Manager
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)

JavaScript

const getComputer = () => {
  const computersApi = new api.ComputersApi();

  // Include Anti-Malware and computer settings information in returned Computer objects
  const Options = api.Expand.OptionsEnum;
  const expand = new api.Expand.Expand(Options.antiMalware, Options.computerSettings);
  const opts = {
    expand: expand.list(),
    overrides: false
  };

  return computersApi.describeComputer(computerID, apiVersion, opts);
};

Java

ComputersApi computersApi = new ComputersApi();
AntiMalwareConfigurationsApi amConfigApi = new AntiMalwareConfigurationsApi();

// Include Anti-Malware information in the returned Computer objects
Expand expand = new Expand(Expand.OptionsEnum.ANTI_MALWARE, Expand.OptionsEnum.COMPUTER_SETTINGS);

// Get all computers
Computers computers = computersApi.listComputers(expand.list(), Boolean.FALSE, apiVersion);

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:

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

The following example obtain certain properties of the Anti-Malware configurations of a computer

Python

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)

JavaScript

View source

// Retrieves certain Anti-Malware properties from a computer object
function getAntiMalwareInfo(computer) {
  const status = {};
  status.name = computer.hostName;
  status.state = computer.antiMalware.state;
  status.smartScanErrorEnabled = computer.computerSettings.antiMalwareSettingSmartScanState;
  return status;
}

Java

View source

Map<String, Object> amStatus = new HashMap<>(); // Stores the computer host names and the properties
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, apiVersion);
    amStatus.put("directories", amc.getDirectoriesToScan());
    if (amc.getDirectoriesToScan() == AntiMalwareConfiguration.DirectoriesToScanEnum.DIRECTORY_LIST) {
        amStatus.put("scan-dirs", amc.getDirectoryListID());
    }
}

Also see the List Computers, Describe a Computer, and Search Computers operations in the API Reference.

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.

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

The following example retrieves the Intrusion Prevention rules that are applied to computers.

Python

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

JavaScript

View source

// Extracts intrusion prevention rules from computers
const getRules = computers => {
  const rules = {};
  for (let i = 0; i < computers.computers.length; i++) {
    rules[computers.computers[i].hostName] = computers.computers[i].intrusionPrevention.ruleIDs;
  }
  return rules;
};

Java

View source

Map<Integer, List<Integer>> computerRules = new HashMap<>();
// 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());
}

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 Deep Security Manager.