Search for a policy (Bash and PowerShell)

Search for policies on Workload Security to retrieve information about them. For example, you can search for policies that have recommendations mode turned off, or search for a specific policy by name and see the configured status of the protection modules. In this recipe you use the Search Policies operation to search for policies by name.

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:

• The name or part of a name of a policy on Workload Security

• The URL of your manager

• The secret key for your API key

Bash

1. Open Terminal or your preferred command-line tool.

2. 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=

3. Enter the following command to store your search string, replacing <YOUR POLICY NAME> with all or part of the name of the policy to search for:

   keyword="%<YOUR POLICY NAME>%"

   For example, keyword="%Base Policy%"

4. 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/policy_search.json

5. Enter the following command to send the request:

   curl -X POST "$url/api/policies/search" -H "api-secret-key: $secret" -H "api-version: v1" -H "Content-Type: application/json" \
   -d "{ \
   \"searchCriteria\": [ \
   { \
   \"fieldName\": \"name\", \
   \"stringTest\": \"equal\", \
   \"stringValue\": \"$keyword\", \
   \"stringWildcards\": true \
   } \
   ] \
   }" \
   -k > $file

   The -k option is necessary only when Workload Security uses a self-signed certificate to establish TLS connections, which is not suitable for use in 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 preceding command, replace > $file with | jq .

6. 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 one or more policies, similar to the following example:

   {
       name: "Base Policy",
       description: "A policy from which all other policies can inherit. ",
       policySettings: {...},
       recommendationScanMode: "ongoing",
       autoRequiresUpdate: "on",
       ID: 1,
       antiMalware: {...},
       webReputation: {...},
       sensingMode: {...},
       firewall: {...},
       intrusionPrevention: {...},
       integrityMonitoring: {...},
       logInspection: {...},
       applicationControl: {...}
   }

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

7. Optionally, try changing the value of the keyword variable to see how it affects the search results. For example, enter keyword=%linux% and rerun the curl command.

PowerShell

1. Open PowerShell.

2. Enter the following command to use TLS 1.2, which the manager requires to create a secure connection:

   [Net.ServicePointManager]::SecurityProtocol += [Net.SecurityProtocolType]::Tls12

3. 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 API KEY SECRET>"

     For example, $secret="5C58EADA-04BC-4ABC-45CF-B72725A0B674:aFBgpPV8eJQGaY2Dk0LmyQMD7nUGvyIDfIbIQo8Zgm8="

   • $headers = @{‘api-version’ = “v1”; ‘api-secret-key’ = $secret; 'Content-Type' = "application/json"}

4. Enter the following command to store your search string, replacing <YOUR POLICY NAME> with all or part of the name of the policy for which to search:

   $keyword="%<YOUR POLICY NAME>%"

   For example, $keyword="%Base Policy%"

5. 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"

6. Enter the following command to send the request:

   Invoke-RestMethod -Method 'Post' -Uri "$url/api/policies/search" -Headers $headers -Body @"
   {"searchCriteria": [
   {
   "fieldName": "name",
   "stringTest": "equal",
   "stringValue": "$keyword",
   "stringWildcards": true
   }
   ]}
   "@ -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.

7. 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 one or more policies, similar to the following example:

   {
       name: "Base Policy",
       description: "A policy from which all other policies can inherit. ",
       policySettings: {...},
       recommendationScanMode: "ongoing",
       autoRequiresUpdate: "on",
       ID: 1,
       antiMalware: {...},
       webReputation: {...},
       sensingMode: {...},
       firewall: {...},
       intrusionPrevention: {...},
       integrityMonitoring: {...},
       logInspection: {...},
       applicationControl: {...}
   }

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

8. Optionally, try changing the value of the keyword variable to see how it affects the search results. For example, enter keyword=%linux% and rerun 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.

• The 200 response example in the API Reference for the Search Policies operation provides descriptions of policy fields, which indicate which fields are searchable.

Related resources

• Set Up to Use Bash or PowerShell

• Search Policies (API Reference)

• Search for Resources (Guide)