Configuring AppProtection Controls Using API

This article provides information on managing Zscaler Private Access (ZPA) AppProtection control use cases using APIs. All APIs are rate limited. To learn more, see Understanding Rate Limiting.

Prerequisite API Calls

Before you can add a new custom control for a customer, you must get the following:

Getting AppProtection Control Action Types

To get AppProtection control action types:

  1. Send a GET request to the following endpoint in the inspection-control-controller: mgmtconfig/v1/admin/customers/{customerId}/inspectionControls/actionTypes.
  2. Provide the customerId, the ZPA tenant ID of the customer, in the request endpoint. For example: mgmtconfig/v1/admin/customers/72057615512764416/inspectionControls/actionTypes.

A successful response returns code 200. To learn more, see API Response Codes and Error Messages.

Getting AppProtection Control Types

To get AppProtection control types:

  1. Send a GET request to the following endpoint in the inspection-control-controller: /mgmtconfig/v1/admin/customers/{customerId}/inspectionControls/controlTypes.
  2. Provide the customerId, the ZPA tenant ID of the customer, in the request endpoint. For example: /mgmtconfig/v1/admin/customers/72057615512764416/inspectionControls/controlTypes.

A successful response returns code 200. To learn more, see API Response Codes and Error Messages.

Getting AppProtection Control Severity Types

To get the AppProtection control severity types:

  1. Send a GET request to the following endpoint in the inspection-control-controller: /mgmtconfig/v1/admin/customers/{customerId}/inspectionControls/severityTypes.
  2. Provide the customerId, the ZPA tenant ID of the customer, in the request endpoint. For example: /mgmtconfig/v1/admin/customers/217246660302995456/inspectionControls/severityTypes.

A successful response returns code 200. To learn more, see API Response Codes and Error Messages.

Getting the AppProtection Custom Control Types

To get the AppProtection custom control types, send a GET request to the following endpoint in the inspection-control-controller: /mgmtconfig/v1/admin/inspectionControls/customControlTypes.

  • {
  "REQUEST": [
    "REQUEST_HEADERS",
    "REQUEST_COOKIES",
    "REQUEST_URI",
    "REQUEST_METHOD",
    "REQUEST_BODY",
    "QUERY_STRING"
  ],
  "RESPONSE": [
    "RESPONSE_HEADERS",
    "RESPONSE_BODY"
  ]
}
    Close

Getting the Supported HTTP Methods

To get the supported HTTP methods:

  1. Send a GET request to the following endpoint in the inspection-control-controller: /mgmtconfig/v1/admin/customers/{customerId}/inspectionControls/custom/httpMethods.
  2. Provide the customerId, the ZPA tenant ID of the customer, in the request endpoint. For example: /mgmtconfig/v1/admin/customers/217246660302995456/inspectionControls/custom/httpMethods.

A successful response returns code 200. To learn more, see API Response Codes and Error Messages.

Creating a New Custom Control

To create a new custom control for a customer:

  1. Send a POST request to the following endpoint in the inspection-control-controller: /mgmtconfig/v1/admin/customers/{customerId}/inspectionControls/custom.
  2. Provide the customerId, the ZPA tenant ID of the customer, in the request endpoint. For example: /mgmtconfig/v1/admin/customers/72057594038056530/inspectionControls/custom.
  3. Include the request headers to provide information about the request context:
  • Content-Type: application/json
  • Authorization: Bearer <access_token>
  1. Use the following JSON payload and provide the following information:
  • Name of the custom control
  • Control type of the custom control
  • Control action of the custom control
  • Rules of the custom control
  • {
  "action": "PASS",
  "actionValue": "string",
  "associatedInspectionProfileNames": [
    {
      "id": 0,
      "name": "string"
    }
  ],
  "controlNumber": 0,
  "controlRuleJson": "string",
  "creationTime": 0,
  "defaultAction": "PASS",
  "defaultActionValue": "string",
  "description": "string",
  "id": 0,
  "modifiedBy": 0,
  "modifiedTime": 0,
  "name": "string",
  "paranoiaLevel": 0,
  "rules": [
    {
      "conditions": [
        {
          "lhs": "SIZE",
          "op": "RX",
          "rhs": "string"
        }
      ],
      "names": [
        "string"
      ],
      "type": "REQUEST_HEADERS"
    }
  ],
  "severity": "CRITICAL",
  "type": "REQUEST",
  "version": "string"
}
    Close
  • {
    "type": "REQUEST",
    "defaultAction": "BLOCK",
    "paranoiaLevel": 1,
    "severity": "CRITICAL",
    "name": "custom control",
    "description": "",
    "rules": [
        {
            "conditions": [
                {
                    "lhs": "SIZE",
                    "op": "GE",
                    "rhs": "1000"
                }
            ],
            "names": [example],
            "type": "REQUEST_BODY"
        },
        {
            "conditions": [
                {
                    "lhs": "VALUE",
                    "op": "RX",
                    "rhs": "POST"
                }
            ],
            "names": [test, demo, inspection],
            "type": "REQUEST_METHOD"
        }
    ]
}
    Close
  • {
    "type": "string",
    "defaultAction": "string",
    "severity": "string",
    "name": "string",
    "rules": [{
        "conditions": [{
            "lhs": "string",
            "op": "string",
            "rhs": "string"
        }],
        "names": ["string"],
        "type": "string"
    }]
}
    Close
  • {
    "id": "72057594038078996",
    "creationTime": "1652715710",
    "modifiedBy": "72057594038056530",
    "name": "Demo_custom control",
    "severity": "CRITICAL",
    "controlNumber": "5500004",
    "version": "1.0",
    "paranoiaLevel": "1",
    "defaultAction": "BLOCK",
    "type": "REQUEST",
    "controlRuleJson": "[{\"type\":\"REQUEST_BODY\",\"conditions\":[{\"lhs\":\"SIZE\",\"op\":\"GE\",\"rhs\":\"1000\"}]},{\"type\":\"REQUEST_METHOD\",\"conditions\":[{\"lhs\":\"VALUE\",\"op\":\"RX\",\"rhs\":\"POST\"}]}]",
    "rules": [
      {
        "type": "REQUEST_BODY",
        "conditions": [
          {
            "lhs": "SIZE",
            "op": "GE",
            "rhs": "1000"
          }
        ]
      },
    {
    "type": "REQUEST_METHOD",
    "conditions": [
      {
        "lhs": "VALUE",
        "op": "RX",
        "rhs": "POST"
      }
    ]
}
    Close

A successful response returns code 201. To learn more, see API Response Codes and Error Messages.

You choose the AppProtection control criteria you want to include in the JSON payload. Refer to the Adding Field Descriptions section for supported values.

Adding Field Descriptions

The following table includes descriptions of available fields you can use for the AppProtection control use cases:

Field Description Required Value
action The performed action Yes

Supported values:

  • PASS
  • BLOCK
  • REDIRECT
actionValue Denotes the action Yes Any string
associatedInspectionProfileName Name of the AppProtection profile No String
controlRuleJson The control rule in JSON format that has the conditions and type of control for the AppProtection control No Any string
defaultAction The performed action Yes

Supported values:

  • PASS
  • BLOCK
  • REDIRECT
defaultActionValue This is used to provide the redirect URL if the default action is set to REDIRECT No String
description Description of the custom control No String
name Name of the custom control Yes String
panaoiaLevel The OWASP Predefined Paranoia Level. To learn more, see Configuring AppProtection Profiles. Yes

Integer

Range: [1-4], inclusive
rules Rules of the custom controls applied as conditions Yes JSON
rules.type Type value for the rules Yes

String

If type is set to REQUEST, users can only select one of the following values for rules.type:

  • REQUEST_HEADERS
  • REQUEST_COOKIES
  • REQUEST_URI
  • REQUEST_METHOD
  • QUERY_STRING

If type is set to RESPONSE, users can only select one of the following values for rule.type:

  • RESPONSE_HEADERS
  • RESPONSE_BODY
rules.names Name of the rules. If rules.type is set to REQUEST_HEADERS, REQUEST_COOKIES, or RESPONSE_HEADERS, the rules.names field is required. Yes List of string values or a single string
severity Severity of the control number Yes

Supported values:

  • CRITICAL
  • ERROR
  • WARNING
  • INFO
type Rules to be applied to the request or response type Yes

Supported values:

  • REQUEST
  • RESPONSE
conditions.lhs Signifies the key for the object type Yes

String

Supported values:

  • SIZE
  • VALUE
conditions.rhs Denotes the value for the given object type. Its value depends on the key. Yes

String

If rules.type is set to REQUEST_METHOD, the conditions.rhs field must have one of the following values:

  • GET
  • HEAD
  • POST
  • OPTIONS
  • PUT
  • DELETE
  • TRACE
conditions.op Denotes the operation type. Yes

String

If lhs is set to SIZE, then the user may pass one of the following:

  • EQ: Equals
  • LE: Less than or equal to
  • GE: Greater than or equal to

If the lhs is set to VALUE, then the user may pass one of the following:

  • CONTAINS
  • STARTS_WITH
  • ENDS_WITH
  • RX

Getting All Custom Controls

To get all custom controls:

  1. Send a GET request to the following endpoint in the inspection-control-controller: /mgmtconfig/v1/admin/customers/{customerId}/inspectionControls/custom.
  2. Provide the customerId, the ZPA tenant ID of the customer, in the request endpoint. For example: /mgmtconfig/v1/admin/customers/72057615512764416/inspectionControls/custom.
  • {
  "totalPages": "1",
  "list": [
    {
      "id": "73170362082263045",
      "modifiedTime": "1638465732",
      "creationTime": "1638465437",
      "modifiedBy": "72057594038056531",
      "name": "Test name One",
      "description": "Default description",
      "severity": "CRITICAL",
      "controlNumber": "4500000",
      "version": "1.0",
      "paranoiaLevel": "1",
      "defaultAction": "PASS",
      "defaultActionValue": "REDIRECT",
      "type": "REQUEST",
      "controlRuleJson": "[{\"type\":\"REQUEST_HEADERS\",\"names\":[\"Sample text\"],\"conditions\":[{\"lhs\":\"SIZE\",\"op\":\"EQ\",\"rhs\":\"300\"}]}]"
    },
    {
      "id": "73170362082263047",
      "modifiedTime": "1638465699",
      "creationTime": "1638465611",
      "modifiedBy": "72057594038056531",
      "name": "Test name Three",
      "description": "Default description",
      "severity": "CRITICAL",
      "controlNumber": "4500002",
      "version": "1.0",
      "paranoiaLevel": "1",
      "defaultAction": "PASS",
      "defaultActionValue": "REDIRECT",
      "type": "REQUEST",
      "controlRuleJson": "[{\"type\":\"REQUEST_HEADERS\",\"names\":[\"Sample text\"],\"conditions\":[{\"lhs\":\"SIZE\",\"op\":\"EQ\",\"rhs\":\"300\"}]}]"
    }
  ]
}
    Close

A successful response returns code 200. To learn more, see API Response Codes and Error Messages.

This API supports pagination. To get a paginated response:

  1. Send a GET request to the following endpoint: /mgmtconfig/v1/admin/customers/{customerId}/inspectionControls/custom?page=1&pagesize=20.
  2. Provide the following in the request endpoint:
  • customerId: The ZPA tenant ID of the customer.
  • Valid values for page and page size parameters.

For example: /mgmtconfig/v1/admin/customers/72057615512764416/inspectionControls/custom?page=1&pagesize=2.

  • {
  "totalPages": "100",
  "list": [
    {
      "id": "72057594038037607",
      "modifiedTime": "1628532877",
      "creationTime": "1622144195",
      "modifiedBy": "72057594037973665",
      "name": "custom control 1",
      "description": "desc",
      "severity": "INFO",
      "controlNumber": "80000",
      "version": "1.0",
      "paranoiaLevel": "1",
      "defaultAction": "PASS",
      "associatedInspectionProfileNames": [
        {
          "id": "72057594038073206",
          "name": "aProfileWithWebsocketControls"
        },
        {
          "id": "72057594038049518",
          "name": "TestProfileWithWebsocketControls"
        },
      ],
      "type": "REQUEST",
      "controlRuleJson": "[{\"type\":\"REQUEST_HEADERS\",\"names\":[\"Sample Text, \",\"Sample Text\"],\"conditions\":[{\"lhs\":\"SIZE\",\"op\":\"EQ\",\"rhs\":\"4\"},{\"lhs\":\"VALUE\",\"op\":\"RX\",\"rhs\":\"dfgdfg\"}]},{\"type\":\"REQUEST_URI\",\"conditions\":[{\"lhs\":\"VALUE\",\"op\":\"RX\",\"rhs\":\"fdg\"}]},{\"type\":\"QUERY_STRING\",\"conditions\":[{\"lhs\":\"VALUE\",\"op\":\"RX\",\"rhs\":\"sdgfs\"}]},{\"type\":\"REQUEST_COOKIES\",\"names\":[\"gsds\"],\"conditions\":[{\"lhs\":\"SIZE\",\"op\":\"EQ\",\"rhs\":\"4\"},{\"lhs\":\"VALUE\",\"op\":\"RX\",\"rhs\":\"dfg\"}]},{\"type\":\"REQUEST_BODY\",\"conditions\":[{\"lhs\":\"VALUE\",\"op\":\"RX\",\"rhs\":\"sdfsd\"}]},{\"type\":\"REQUEST_METHOD\",\"conditions\":[{\"lhs\":\"VALUE\",\"op\":\"RX\",\"rhs\":\"DELETE\"}]}]"
    }
  ]
}
    Close

If not provided, the default page size is 20. The maximum page size is 500.

A successful response returns code 200. To learn more, see API Response Codes and Error Messages.

Getting a Custom Control by ID

To get a custom control by ID:

  1. Send a GET request to the following endpoint in the inspection-control-controller: /mgmtconfig/v1/admin/customers/{customerId}/inspectionControls/custom/{id}.
  2. Provide the following in the request endpoint:
  • customerId: The ZPA tenant ID of the customer.
  • id: The unique identifier of the AppProtection control.

For example: /mgmtconfig/v1/admin/customers/72057615512764416/inspectionControls/custom/72057594038037608.

  • {
  "id": "72057594038037608",
  "modifiedTime": "1628508820",
  "creationTime": "1622144273",
  "modifiedBy": "72057594037973665",
  "name": "Test cc2",
  "severity": "ERROR",
  "controlNumber": "80001",
  "version": "1.0",
  "paranoiaLevel": "1",
  "defaultAction": "REDIRECT",
  "defaultActionValue": "http://www.toggle1.com",
  "associatedInspectionProfileNames": [
    {
      "id": "72057594038043697",
      "name": "testInspectionProfile"
    },
    {
      "id": "72057594038047624",
      "name": "testInspectionProfile2"
    }
  ],
  "type": "RESPONSE",
  "controlRuleJson": "[{\"type\":\"RESPONSE_HEADERS\",\"names\":[\"ds\"],\"conditions\":[{\"lhs\":\"SIZE\",\"op\":\"EQ\",\"rhs\":\"300\"}]},{\"type\":\"RESPONSE_BODY\",\"conditions\":[{\"lhs\":\"VALUE\",\"op\":\"RX\",\"rhs\":\"test\"}]}]"
}
    Close

A successful response returns code 200. To learn more, see API Response Codes and Error Messages.

Updating a Custom Control

To update a custom control:

  1. Send a PUT request to the following endpoint in the inspection-control-controller: /mgmtconfig/v1/admin/customers/{customerId}/inspectionControls/custom/{id}.
  2. Provide the following in the request endpoint:
  • customerId: The ZPA tenant ID of the customer.
  • id: The unique identifier of the AppProtection control.

For example: /mgmtconfig/v1/admin/customers/72057615512764416/inspectionControls/custom/72057594038037608.

A successful response returns Code 204 - No Content, meaning the custom control is updated. To learn more, see API Response Codes and Error Messages.

Deleting a Custom Control

To delete a custom control:

  1. Send a DELETE request to the following endpoint in the inspection-control-controller: /mgmtconfig/v1/admin/customers/{customerId}/inspectionControls/custom/{id}.
  2. Provide the following in the request endpoint:
  • customerId: The ZPA tenant ID of the customer.
  • id: The unique identifier of the AppProtection control.

For example: /mgmtconfig/v1/admin/customers/72057615512764416/inspectionControls/custom/72057594038037608.

A successful response yields Code 204 - No Content, meaning the custom control is deleted. To learn more, see API Response Codes and Error Messages.

Getting Associated Profile Details by Control ID

To get the name and ID of the associated profile by control ID:

  1. Send a GET request to the following endpoint in the inspection-control-controller: /mgmtconfig/v1/admin/customers/{customerId}/inspectionControls/custom/{id}/profiles.
  2. Provide the following in the request endpoint:
  • customerId: The ZPA tenant ID of the customer.
  • id: The unique identifier of the AppProtection control.

For example: /mgmtconfig/v1/admin/customers/72057615512764416/inspectionControls/custom/217246660303025057/profiles.

  • [
  {
    "id": "72057594038073206",
    "name": "aProfileWithWebsocketControls"
  },
  {
    "id": "72057594038049518",
    "name": "testProfileWithWebSocketControls"
  },
]
    Close

A successful response returns code 200. To learn more, see API Response Codes and Error Messages.

Getting All Predefined AppProtection Controls

To get all predefined AppProtection controls:

  1. Send a GET request to the following endpoint in the inspection-control-controller: /mgmtconfig/v1/admin/customers/{customerId}/inspectionControls/predefined.
  2. Provide the following in the request endpoint:
  1. Include the mandatory default predefined controls in the request endpoint with the search string.

For example: /mgmtconfig/v1/admin/customers/217246660302995456/inspectionControls/predefined?search=controlGroup%20eq%20Preprocessors&version=OWASP_CRS%2f3.3.0.

The preprocessor is the group for the default controls.

  • [
  {
    "controlGroup": "Preprocessors",
    "predefinedInspectionControls": [
      {
        "id": "72057594037930391",
        "modifiedTime": "1631459708",
        "creationTime": "1631459708",
        "name": "Internal error flagged",
        "description": "Internal error flagged",
        "severity": "CRITICAL",
        "controlNumber": "200005",
        "version": "OWASP_CRS/3.3.0",
        "paranoiaLevel": "1",
        "defaultAction": "BLOCK",
        "controlGroup": "Preprocessors"
      },
      {
        "id": "72057594037930409",
        "modifiedTime": "1632525142",
        "creationTime": "1632525142",
        "name": "Method is not allowed by policy",
        "description": "This rule check if the Method is allowed by policy",
        "severity": "CRITICAL",
        "controlNumber": "911100",
        "version": "OWASP_CRS/3.3.0",
        "paranoiaLevel": "1",
        "defaultAction": "BLOCK",
        "controlGroup": "Preprocessors"
      },
      {
        "id": "72057594037929947",
        "modifiedTime": "1621936649",
        "creationTime": "1621936649",
        "name": "Invalid HTTP Request Line",
        "description": "Validate request line against the format specified in the HTTP RFC.",
        "severity": "WARNING",
        "controlNumber": "920100",
        "version": "OWASP_CRS/3.3.0",
        "paranoiaLevel": "1",
        "defaultAction": "BLOCK",
        "controlGroup": "Preprocessors"
      },
      {
        "id": "72057594037929950",
        "modifiedTime": "1621936649",
        "creationTime": "1621936649",
        "name": "Content-Length HTTP header is not numeric",
        "description": "Accept only digits in content length.",
        "severity": "CRITICAL",
        "controlNumber": "920160",
        "version": "OWASP_CRS/3.3.0",
        "paranoiaLevel": "1",
        "defaultAction": "BLOCK",
        "controlGroup": "Preprocessors"
      },
      {
        "id": "72057594037929954",
        "modifiedTime": "1621936649",
        "creationTime": "1621936649",
        "name": "Content-Length and Transfer-Encoding headers present",
        "description": "This rule blocks if both Content-Length and Transfer-Encoding headers present.",
        "severity": "WARNING",
        "controlNumber": "920181",
        "version": "OWASP_CRS/3.3.0",
        "paranoiaLevel": "1",
        "defaultAction": "BLOCK",
        "controlGroup": "Preprocessors"
      },
      {
        "id": "72057594037929988",
        "modifiedTime": "1621936649",
        "creationTime": "1621936649",
        "name": "HTTP protocol version is not allowed by policy",
        "description": "This rule checks for HTTP Protocol version is from allowed versions or not.",
        "severity": "CRITICAL",
        "controlNumber": "920430",
        "version": "OWASP_CRS/3.3.0",
        "paranoiaLevel": "1",
        "defaultAction": "BLOCK",
        "controlGroup": "Preprocessors"
      }
    ],
    "defaultGroup": true
  }
]
    Close

A successful response returns code 200. To learn more, see API Response Codes and Error Messages.

Getting a Predefined Control by ID

To get a predefined AppProtection control by ID:

  1. Send a GET request to the following endpoint in the inspection-control-controller: /mgmtconfig/v1/admin/customers/{customerId}/inspectionControls/predefined/{id}.
  2. Provide the following in the request endpoint:
  • customerId: The ZPA tenant ID of the customer.
  • id: The unique identifier of the AppProtection control.

For example: /mgmtconfig/v1/admin/customers/217246660302995456/inspectionControls/predefined/72057594038049511.

  • {
  "id": "72057594038049511",
  "modifiedTime": "1629743139",
  "creationTime": "1629743139",
  "name": "Failed to parse request body",
  "description": "Failed to parse request body",
  "severity": "CRITICAL",
  "controlNumber": "200002",
  "version": "OWASP_CRS/3.3.0",
  "paranoiaLevel": "1",
  "defaultAction": "BLOCK",
  "controlGroup": "Protocol Issues"
}
    Close

A successful response returns code 200. To learn more, see API Response Codes and Error Messages.

Getting All Predefined AppProtection Control Versions

To get all predefined AppProtection control versions:

  1. Send a GET request to the following endpoint in the inspection-control-controller: /mgmtconfig/v1/admin/customers/{customerId}/inspectionControls/predefined/versions.
  2. Provide the customerId, the ZPA tenant ID of the customer, in the request endpoint. For example: /mgmtconfig/v1/admin/customers/217246660302995456/inspectionControls/predefined/versions.

A successful response returns code 200. To learn more, see API Response Codes and Error Messages.