Table of contents

Topics on this page

PowerShell script details

Notes

Related Resources

Assign a policy to many computers (Bash and PowerShell)

This recipe creates a script that assigns a policy to many computers. The script searches for the computers to modify and then assigns the policy to each computer.

When you need to perform a task on many computers (hundreds or thousands), perform the work in small batches:

Retrieve a small batch of computers.
Assign the policy to each computer in the batch.
Repeat until all computers are assigned the policy.

Small batches makes more efficient use of Workload Security resources. This recipe assigns a policy to all computers in small batches.

Before you begin

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

jq for Bash

The Bash script uses jq to parse JSON data. To check if it is installed, open Terminal or your preferred command line tool and enter the following command:

jq --version

If jq is not found, visit jq website to install it.

Required information

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

The URL of Workload Security
The secret key for your API key
The ID of the policy to assign

If you do not know the ID of the policy, you can use the Search for a Policy recipe to obtain it.

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 Workload Security, 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=
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

Copy and paste the following code that searches for computers in batches and assigns the policy to them:

pagesize=10; idOfLastFound=0 ; \
while [ $pagesize -gt 0 ]; do \
    echo -e "\nGetting a batch of computers..." 
    page=$(curl -X POST "$url/api/computers/search?expand=none" -H "api-secret-key: $secret" -H "api-version: v1" -H "Content-Type: application/json" -# \
    -d "{ \
    \"searchCriteria\": [{ \
    \"idValue\": \"$idOfLastFound\", \
    \"idTest\": \"greater-than\"}], \
    \"maxItems\": \"$pagesize\" \
    }" \
    -k | jq '.[]'); \
    pagesize=$(echo $page | jq length); \
    for (( i=0; i&lt;$pagesize; i++)); do \
        computerId=$(echo $page | jq ".[$i][\"ID\"]"); \
        echo "Assigning policy to computer with ID $computerId"; \
        curl -X POST "$url/api/computers/${computerId}?expand=none" -H "api-secret-key: $secret" -H "api-version: v1" -H "Content-Type: application/json" -d "{ \"policyID\": \"$policyId\" }" -s -S -o /dev/null; \
    done; \
    idOfLastFound=$(echo $page | jq '.[-1]["ID"]'); \ 
done;

Bash script details

This script is a bit more complicated than what was done in other recipes.

Most of the code executes in a loop where each iteration of the loop searches for a batch of computers and modifies them. The loop ends when the search returns no more computers. To begin, the size of the batch was defined and the computer ID set to use as the basis of the search in the first iteration.

pagesize=10; idOfLastFound=0 ; \
while [ $pagesize -gt 0 ]; do \
...
done;

Inside the loop, cURL is used to search for a batch of computers. The search finds 10 computers that have an ID that is greater than the last ID found in the previous iteration. The result is piped to jq to obtain an array of computers:

page=$(curl -X POST "$url/api/computers/search?expand=none" -H "api-secret-key: $secret" -H "api-version: v1" -H "Content-Type: application/json" -# \
  -d "{ \
  \"searchCriteria\": [{ \
  \"idValue\": \"$idOfLastFound\", \
  \"idTest\": \"greater-than\"}], \
  \"maxItems\": \"$pagesize\" \
  }" \
  -k | jq '.[]'); \

Then, the number of returned computers was found:

pagesize=$(echo $page | jq length); \

For each computer, cURL is used to assign the policy:

  for (( i=0; i&lt;$pagesize; i++)); do \
    computerId=$(echo $page | jq ".[$i][\"ID\"]"); \
    echo "Assigning policy to computer with ID $computerId"; \
    curl -X POST "$url/api/computers/${computerId}?expand=none" -H "api-secret-key: $secret" -H "api-version: v1" -H "Content-Type: application/json" -d "{ \"policyID\": \"$policyId\" }" -k -s -S -o /dev/null; \
  done; \

Finally, located was the ID of the last computer found to use as the basis of the search in the next iteration:

idOfLastFound=$(echo $page | jq '.[-1][\"ID\"]'); \

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 your Workload Security, 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; 'Content-Type' = "application/json"}
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

Copy and paste the following code that searches for computers in batches and assigns the policy to them:

$pageSize = 10
$idOfLastFound = 0
while($pageSize -gt 0){
    Write-Output "Getting batch of computers..."
    $page = Invoke-RestMethod -Method 'Post' -Uri "$url/api/computers/search?expand=none" -Headers $headers -Body @"
    {"searchCriteria": [ 
        {
        "idTest": "greater-than", 
        "idValue": $idOfLastFound
        } 
    ],
    "maxItems": $pageSize}
"@
    $pageSize = $page.computers.Length
    for ($i=0; $i -lt $pageSize; $i++){
        $id = $page.computers.Get($i).ID
        Write-Output "Setting policy for computer with ID $id" 
        Invoke-RestMethod -Method 'Post' -Uri "$url/api/computers/${id}?expand=none" -Headers $headers -Body @"
        {"policyID": "$policyId"} 
"@ | Out-Null
    }
    if ($pageSize -gt 0 ) {
        $idOfLastFound = $page.computers.Get($pageSize - 1).ID
    }
}

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.

PowerShell script details

This script is a bit more complicated than what was done in other recipes.

Most of the code executes in a loop where each iteration of the loop searches for a batch of computers and modifies them. The loop ends when the search returns no more computers. To begin, the size of the batch was defined and the computer ID to use as the basis of the search in the first iteration was set:

$pageSize = 10
$idOfLastFound = 0
while($pageSize -gt 0){
...
}

Inside the loop, Invoke-RestMethod was called to search for a batch of computers. The search finds 10 computers that have an ID that is greater than the last ID found in the previous iteration:

page=$(curl -X POST "$url/api/computers/search?expand=none" -H "api-secret-key: $secret" -H "api-version: v1" -H "Content-Type: application/json" -# \
  -d "{ \
  \"searchCriteria\": [{ \
  \"idValue\": \"$idOfLastFound\", \
  \"idTest\": \"greater-than\"}], \
  \"maxItems\": \"$pagesize\" \
  }" \
  -k | jq '.[]'); \

Then, the number of returned computers was determined:

$pageSize = $page.computers.Length

For each computer, Invoke-RestMethod was called to assign the policy:

for ($i=0; $i -lt $pageSize; $i++){
        $id = $page.computers.Get($i).ID
        Write-Output "Setting policy for computer with ID $id" 
        Invoke-RestMethod -Method 'Post' -Uri "$url/api/computers/${id}?expand=none" -Headers $headers -Body @"
        {"policyID": "$policyId"}

Finally, located was the ID of the last computer found to use as the basis of the search in the next iteration:

$idOfLastFound = $page.computers.Get($pageSize - 1).ID

Notes

To change the size of the batch of computers that is processed, set the pagesize (Bash) or $pageSize (PowerShell) variable to a different value. The value of 10 is normally a conservative batch size.

Set up to use Bash or PowerShell
Modify a computer (API Reference
Create and configure a policy (Guide) – “Assign a policy to a computer” section
Configure computers to override policies (Guide)
Search for Resources (Guide) - "Limit search results and paging" section

Topics on this page

Assign a policy to many computers (Bash and PowerShell)

Before you begin

jq for Bash

Required information

Bash

Bash script details

PowerShell

PowerShell script details

Notes

Previous

Next