Focus

IoT Security API Reference

Get Active Policy Rule Recommendations

Table of Contents

Get Active Policy Rule Recommendations

Get a list of all active policy rule recommendations or all recommendations for one or more specific profiles.

Synopsis

URI	/pub/v4.0/policy/recommendation
HTTP Method	GET
FQDN	<customer-name>.iot.paloaltonetworks.com

Description

Get a list of all active policy rule recommendations or all the active recommendations for one or more IoT device profiles.

Request Fields

The URL of this request contains the following parameters:

Field	Description
customerid	(`Required`) The customer ID specifies the API call for a specific tenant. The following value is a string.
profile	A profile filters policy rule recommendations by one or more source profile names. The following value is a string with profile names separated by commas; for example: profile=Palo Alto Networks Device,iPhone,Polycom IP Phone. All profiles must be IoT profiles. Without a profile filter, the request returns all active policy rule recommendations.

For other parameters you can include in the URL—offset and pagelength—see the general parameters described in Get Started with the IoT Security API.

Policy Rule Recommendations Request Example

curl --location -X GET 'https://acmecorp.iot.paloaltonetworks.com/pub/v4.0/policy/recommendation?customerid=acmecorp' \
-H 'X-Key-Id: KEY_ID' \
-H 'X-Access-Key: ACCESS_KEY'

Success Response

Upon success, the HTTP response code is 200. In addition, this API returns a JSON object containing policy rules and their attributes.

An empty field indicates any. For example, if there are no IP addresses for destinationIpList, then the rule applies to any destination IP address.

Field	Description
ver	API version (string)
api	API path (string)
total	Total number of active recommended policy rules for which information was returned (integer)
policies	Array of active recommended policy rules (array)
id	Unique identifier composed of alphanumeric characters for the policy rule (string)
policySetName	Name of the user-defined policy set to which the policy rule belongs (string)
geo	Location of the destination in the policy rule (string): intranet (internal) or internet (external)
action	Action the firewall takes when applying the policy rule, which is always allow (string)
lastActivityTime	UTC timestamp for the last detected network activity corresponding to the elements in this policy rule (string)
sourceProfiles	Device profile assigned to devices initiating traffic to which the policy rule applies (array) Although this is an array, there can only be a single source profile.
apps	Applications to which the policy rule applies such as youtube-base (array)
destinationProfiles	Device profile of the destination in the policy rule. A destination device profile is used when the source and destination are in the same intranet and IoT Security is monitoring them both and has assigned a profile to the destination. (array)
sourceIpList	List of source IP addresses to which the policy rule applies (array) This is included in anticipation of future functionality and is currently always empty.
destinationIpList	List of destination IP addresses to which the policy rule applies (array) When a destination is internal, IoT Security displays its IP address in destinationIpList. When it’s external, IoT Security displays it in destinationFqdnList.
destinationFqdnList	List of destination FQDNs to which the policy rule applies (array) When a destination is external, IoT Security displays its IP address in destinationFqdnList. When it’s internal, IoT Security displays it in destinationIpList.
sourceZones	List of source zones to which the policy rule applies (array)
destinationZones	List of destination zones to which the policy rule applies (array)
destinationUrlCategories	List of categories to which the policy rule applies. Some examples: games, entertainment, and health-and-medicine (array)
services	List of non-standard service port numbers for an application or the user-defined values service-http and service-https (array) When IoT Security identifies an application that's using non-standard UDP or TCP port numbers, it displays the application name in "apps" and the non-standard port numbers in "services". When an application is using standard ports, IoT Security displays the application name and leaves "services" empty. If a user manually applied one of the predefined services service-http or service-https to an application, then the predefined service name appears in "services".
tags	System-defined tag IoTSecurityRecommended and any user-defined tags applied to the policy rule (array)
securityProfiles	List of Security profiles for antivirus, vulnerability protection, anti-spyware, and so on in the policy rule (array)
firewallList	List of firewalls that enforce the policy rule (array)
deviceGroups	(Panorama) List of device groups containing firewalls that enforce the policy rule (array)

Success Response Example

{
    "ver": "v4.0",
    "api": "/policy/recommendation",
    "total": 116,
    "policies": [
        {
            "id": "96122896cb71f1c302253842e1fb3518",
            "geo": "internet",
            "action": "allow",
            "lastActivityTime": "2021-06-03T04:43:26.400Z",
            "sourceProfiles": [
                "DICOM-Imager"
            ],
            "apps": [
                "cfdp"
            ],
            "destinationProfiles": [],
            "sourceIpList": [],
            "destinationIpList": [],
            "destinationFqdnList": [],
            "sourceZones": [],
            "destinationZones": [],
            "destinationUrlCategories": [],
            "services": [],
            "tags": [
                "IoTSecurityRecommended"
            ],
            "securityProfiles": [],
            "firewallList": [],
            "deviceGroups": []
        },
        ...
    ]
}

Policy Rule Recommendations for a Specific Profile Request Example

curl --location -X GET 'https://acmecorp.iot.paloaltonetworks.com/pub/v4.0/policy/recommendation?customerid=acmecorp&profile=DICOM-Imager' \
-H 'X-Key-Id: KEY_ID' \
-H 'X-Access-Key: ACCESS_KEY'

Error Response

Upon error, the reply includes an HTTP response code, an error message, and additional information describing the error. The HTTP response code is one of the following:

Field	Description
400	Bad Request. This occurs when an HTTP request contains an invalid query string.
403	Forbidden access. Either the provided API Key is invalid or it does not have the required RBAC permissions to run this API.
429	Too many requests. The number of requests for the list of recommended policy rules exceeded the rate limit of 180 queries per minute per tenant.
500	Internal server error. A unified status for API communication type errors.

Error Response Format

{code: STATUS_CODE, msg: GENERAL_MESSAGE}

Get a List of User-defined Tags