keyboard_arrow_down
  • 12.0
  • 20.0

Search for a Policy (Bash and PowerShell)

Search for policies on Deep Security Manager 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 that you need to complete this recipe:

  • The name or part of a name of a policy on your Deep Security Manager
  • 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 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 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%"
  • 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
  • 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 your Deep Security Manager 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 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 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 (i.e. objects) are represented as {...}. You will see all the information in your search results.
  • (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.

    • PowerShell

    1. Open PowerShell.
    2. Enter the following command if your Deep Security Manager uses a self-signed certificate to establish TLS connections (which is not suitable in production environments). 
      [System.Net.ServicePointManager]::ServerCertificateValidationCallback = { False }
    3. Enter the following command to use TLS 1.2, which the manager requires to create a secure connection: 
      [Net.ServicePointManager]::SecurityProtocol += [Net.SecurityProtocolType]::Tls12
    4. 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 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%"
  • 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/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.
  • 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 (i.e. objects) are represented as {...}. You will see all the information in your search results.
  • (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.

    • 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.