Get a List of Computers (Bash and PowerShell)

Get a list of the computers that Server & Workload Protection protects (or has detected) and focus the returned data to include the security status of each computer. Use the List Computers operation to get a list of computers. Use the optional expand query parameter to focus on the status information.

When you list computers, by default all available computer information is returned. You can use the expand query parameter so that only the information in which you are interested is returned. At a minimum the basic information about each computer is returned, such as the computer ID, policy ID, and platform.

Note

When you do not include the expand query string, all computer information is returned.

Category of returned information	Supported values for expand
Minimum information	none
All information	all (default)
Current status	computerStatus , securityUpdates , tasks
Configuration	computerSettings , interfaces
Security module configuration	allSecurityModules (includes information for all modules), antiMalware , applicationControl , firewall , integrityMonitoring , intrusionPrevention , logInspection , SAP , webReputation
Virtual machine information	allVirtualMachineSummaries (includes information for all types of virtual machines), azureARMVirtualMachineSummary , azureVMVirtualMachineSummary , ec2VirtualMachineSummary , ESXSummary , noConnectorVirtualMachineSummary , vcloudVMVirtualMachineSummary , vmwareVMVirtualMachineSummary , workspaceVirtualMachineSummary ,

Before you begin

You should have already verified that your environment is set up to use the API using Bash or PowerShell.

Gather the following information that you need to complete this recipe:

The URL of Server & Workload Protection
The secret key for your API key

Bash

Open Terminal or your preferred command line tool.
Enter the following commands to store details about your request, replacing <YOUR URL> with the URL of Server & Workload Protection, and <YOUR SECRET KEY> with the secret from your API key:
- url=<YOUR URL>
  
  for example, url=https://cloudone.trendmicro.com
- secret=<YOUR SECRET KEY>
  
  for example, secret=5C58EADA-04BC-4ABC-45CF-B72925A0B674:aFBgpPV8eJQGaY2Dk0LmyQMD7nUGvyIDfIbIQo8Zgm8=
- expand=computerStatus
Enter the following command to specify the JSON file where you want to save the response data, replacing <FILE PATH> with the file to create. Specify a file name with the .json extension:

file=<FILE PATH>

For example, file=~/Documents/computers_status.json saves the file below your home directory.

Enter the following command to send the request:

curl -X GET "$url/api/computers?expand=$expand" -H "api-secret-key: $secret" -H "api-version:
                           v1" > $file

Tip

To print the returned JSON in the terminal in a readable format (instead of writing to a file), pipe the results of the cURL command to jq. In the above command, replace > $file with | jq ..

Open the JSON file in a Web browser. (The Web browser should format the JSON so that it is readable.) You should see JSON code that represents an array of computers. Each computer is represented with code that is similar to the following example:

{
    "hostName": "gui2-336",
    "displayName": "",
    "description": "",
    "lastIPUsed": "127.0.1.1",
    "platform": "Unknown",
    "groupID": 0,
    "policyID": 1,
    "relayListID": 0,
    "lastSendPolicyRequest": 1566335191390,
    "agentVersion": "0.0.0.0",
    "computerStatus": {
        "agentStatus": "inactive",
        "agentStatusMessages": [
            "Unmanaged (Unknown)"
        ]
    },
    "ID": 201
}

The computerStatus key contains the status information. In this example, the computer is not protected.

(Optional) Try changing the value of the expand variable to see how it affects the returned JSON. For example, enter expand=computerProperties and re-run the curl command.

PowerShell

Open PowerShell.
Enter the following command to use TLS 1.2, which the manager requires to create a secure connection:
```
[Net.ServicePointManager]::SecurityProtocol += [Net.SecurityProtocolType]::Tls12
```
Enter the following commands to store details about your request, replacing <YOUR URL> with the URL of Server & Workload Protection, and <YOUR SECRET KEY> with the secret from your API key:
- $url = "<YOUR URL>"
  
  for example, url=https://cloudone.trendmicro.com
- $secret = "<YOUR API KEY SECRET>"
  
  for example,$secret="5C58EADA-04BC-4ABC-45CF-B72725A0B674:aFBgpPV8eJQGaY2Dk0LmyQMD7nUGvyIDfIbIQo8Zgm8="
- $headers = @{api-version = v1; api-secret-key = $secret}
- $expand="computerStatus"
Enter the following command to specify the JSON file where you want to save the response data, replacing <FILE PATH> with the file to create. Specify a file name with the .json extension:

$file="<FILE PATH>"

For example, $file="$HOME\Documents\computers_status.json" saves the file below your home directory.