Views:
Search for policies on Server & Workload Protection 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 Parent topic

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 name or part of a name of a policy on Server & Workload Protection
  • The URL of your manager
  • The secret key for your API key

Bash Parent topic

Procedure

  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 Server & Workload Protection, 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 Server & Workload Protection uses a self-signed certificate to establish TLS connections, which is not suitable for use in production environments.
    Tip
    Tip
    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 ..
  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: {...}
}
    Tip
    Tip
    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 search results.
  7. (Optional) Try changing the value of the keyword variable to see how it affects the search results. For example, enter keyword=%linux% and re-run the curl command.

What to do next

PowerShell Parent topic

Procedure

  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 Server & Workload Protection, 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 to search for:
    $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: {...}
}
    Tip
    Tip
    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 search results.
  8. (Optional) Try changing the value of the keyword variable to see how it affects the search results. For example, enter keyword=%linux% and re-run the Invoke-RestMethod command

What to do next

Notes Parent topic

  • 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 Parent topic