Assign a Policy to a Computer (Bash and PowerShell)

Assign a policy to a computer so that the computer is protected according to the policy configuration. For example, assign a policy to a computer that was just added to Deep Security Manager, or that was discovered to have no policy assigned.

To assign a policy, you use the Modify a Computer operation.

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
The ID of the computer to which you are assigning the policy
The ID of the policy to assign

If you don't know the ID of the policy or the computer, you can use the Search for a Policy and Get a List of Computers recipes to obtain them.

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=

Enter the following command to store the ID of the computer, replacing <YOUR COMPUTER ID> with the ID of the computer:

computerID=<YOUR COMPUTER ID>

for example, computerID=51

Enter the following command to store the ID of the policy, replacing <YOUR POLCIY ID> with the ID of the computer:

policyID=<YOUR POLICY ID>

for example, policyID=1

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/computer_modify.json

Enter the following command to send the request:

curl -X POST "$url/api/computers/$computerID" -H "api-secret-key: $secret" -H "api-version: v1" -H "Content-Type: application/json" -d "{ \"policyID\": \"$policyID\" }" -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 a computer with the expected values for ID and policyID, similar to the following example.

{
    hostName: "testcomputer",
    displayName: "my test computer",
    description: "",
    lastIPUsed: "",
    platform: "Windows",
    groupID: 0,
    policyID: 1,
    relayListID: 1,
    lastSendPolicyRequest: 1568653868230,
    agentVersion: "12.0.0.563",
    computerStatus: {...},
    computerSettings: {...},
    ID: 51,
    antiMalware: {...},
    webReputation: {...},
    sensingMode: {...},
    firewall: {...},
    intrusionPrevention: {...},
    integrityMonitoring: {...},
    logInspection: {...},
    applicationControl: {...}
}

To keep the example brief, values that are comprised of multiple properties (i.e. objects) are represented as {...}. You will see all the information in your results.

PowerShell

Open PowerShell.
Enter the following command only 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; 'Content-Type' = "application/json"}

Enter the following command to store the ID of the computer, replacing <YOUR COMPUTER ID> with the ID of the computer:

$computerID = "%<YOUR COMPUTER ID>%"

for example, $computerID = "51"

Enter the following command to store the ID of the policy, replacing <YOUR POLCIY ID> with the ID of the computer:

$policyID = "<YOUR POLICY ID>"

for example, $policyID = "1"

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\policy_search.json"

Enter the following command to send the request:

Invoke-RestMethod -Method 'Post' -Uri "$url/api/computers/$computerID" -Headers $headers -Body @"
{"policyID": "$policyID"}
"@ -OutFile $file

If you receive the error message The underlying connection was closed: An unexpected error occurred on a send, close PowerShell, open PowerShell again, and try repeating steps.

{
    hostName: "testcomputer",
    displayName: "my test computer",
    description: "",
    lastIPUsed: "",
    platform: "Windows",
    groupID: 0,
    policyID: 1,
    relayListID: 1,
    lastSendPolicyRequest: 1568653868230,
    agentVersion: "12.0.0.563",
    computerStatus: {...},
    computerSettings: {...},
    ID: 51,
    antiMalware: {...},
    webReputation: {...},
    sensingMode: {...},
    firewall: {...},
    intrusionPrevention: {...},
    integrityMonitoring: {...},
    logInspection: {...},
    applicationControl: {...}
}

To keep the example brief, values that are comprised of multiple properties (i.e. objects) are represented as {...}. You will see all the information in your results.

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.
The returned computer object includes all of the configurations that are applied to the computer, including those set in the policy and any overrides that have been applied to the computer. To include only the overrides in the response, add ?overrides=true to the URL in the request, for example $url/api/computers/$computerID?overrides=true.

[API Cookbook](../api-cookbook)
[Modify a Computer](../api-reference/#operation/modifyComputer) (API Reference)
[Create and Configure a Policy](../create-and-configure-policies) - "Assign a policy to a computer" section (Guide)
[Configure Computers to Override Policies](../configure-computers-to-override-policies) (Guide)

Assign a Policy to a Computer (Bash and PowerShell)

Before you begin

Bash

PowerShell

Notes

Related resources