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.
expand
query string, all computer information is returned.Category of returned information | Supported values forexpand |
---|---|
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
orurl=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, enterexpand=computerProperties
and re-run thecurl
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
orurl=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
-
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 theInvoke-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 anexpand
query string for each value, for example:?expand=computerStatus&expand=computerProperties
Related resources
- API Cookbook
- List Computers (API Reference)
- Report on Computer Status (Guide)
- Performance Tips (Guide)