Get a List of Computers (Bash and PowerShell)

Get a list of the computers that Deep Security Manager 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.

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 your Deep Security Manager
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 your Deep Security Manager, and <YOUR SECRET KEY> with the secret from your API key:
- ```
url=<YOUR URL>
```
  for example, url=https://192.168.1.100:4119 or url=https://example.com:4119

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" -k > $file

The -k option is necessary only when your Deep Security Manager uses a self-signed certificate to establish TLS connections, which is not suitable for production environments.

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 if your Deep Security Manager uses a self-signed certificate to establish TLS connections (which is not suitable for production environments).
```
[System.Net.ServicePointManager]::ServerCertificateValidationCallback = { False }
```
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 your Deep Security Manager, and <YOUR SECRET KEY> with the secret from your API key:
- ```
$url = "<YOUR URL>"
```
  for example, url=https://192.168.1.100:4119 or url=https://example.com:4119

$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.

Enter the following command to send the request:

Invoke-RestMethod "$url/api/computers?expand=$expand" -Headers $headers -OutFile $file

{
    "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 Invoke-RestMethod command.

Notes

If you open the JSON file in a text editor, the code appears on a single line which is difficult to read. Web browsers tend to format JSON so that it is readable. If your browser does not automatically format the JSON, consider installing a browser plugin that does.
To include multiple values for the expand query parameter, the URL in the API call must include an expand query string for each value, for example:
```
?expand=computerStatus&expand=computerProperties
```

Get a List of Computers (Bash and PowerShell)

Before you begin

Bash

PowerShell

Notes

Related resources