inspection#

The following methods allow for interaction with the ZPA Inspection Controller API endpoints.

Methods are accessible via zpa.inspection

class InspectionControllerAPI#

add_custom_control(name, default_action, severity, type, rules, **kwargs)#

Adds a new ZPA Inspection Custom Control.

Parameters:

name (str) – The name of the custom control.
default_action (str) –
The default action to take for matches against this custom control. Valid options are:
- PASS
- BLOCK
- REDIRECT
severity (str) –
The severity for events that match this custom control. Valid options are:
- CRITICAL
- ERROR
- WARNING
- INFO
type (str) –
The type of HTTP message this control matches. Valid options are:
- REQUEST
- RESPONSE

rules (list) –

A list of Inspection Control rule objects, with each object using the format:

{
    "names": ["name1", "name2"],
    "type": "rule_type",
    "conditions": [
        ("LHS", "OP", "RHS"),
        ("LHS", "OP", "RHS"),
    ],
}

**kwargs – Optional keyword args.

Keyword Arguments:

**description (str) – Additional information about the custom control.
**paranoia_level (int) – The paranoia level for the custom control.

Returns:

The newly created custom Inspection Control resource record.

Return type:

Box

Examples

Create a new custom Inspection Control with the minimum required parameters

print(
    zpa.inspection.add_custom_control(
        "test8",
        severity="INFO",
        description="test descr",
        paranoia_level="3",
        type="REQUEST",
        default_action="BLOCK",
        rules=[
            {
                "names": ["test"],
                "type": "REQUEST_HEADERS",
                "conditions": [("SIZE", "GE", "10"), ("VALUE", "CONTAINS", "test")],
            }
        ],
    )
)

add_profile(name, paranoia_level, predef_controls_version, **kwargs)#

Adds a ZPA Inspection Profile.

Parameters:

name (str) – The name of the Inspection Profile.
paranoia_level (int) – The paranoia level for the Inspection Profile.
predef_controls_version (str) – The version of the predefined controls that will be added.
**kwargs – Additional keyword args.

Keyword Arguments:

**description (str) – Additional information about the Inspection Profile.
**custom_controls (list) –
A tuple list of custom controls to be added to the Inspection profile.

Custom control tuples must follow the convention below:

(control_id, action)

e.g.
```
custom_controls = [(99999, "BLOCK"), (88888, "PASS")]
```
**predef_controls (list) –
A tuple list of predefined controls to be added to the Inspection profile.

Predefined control tuples must follow the convention below:

(control_id, action)

e.g.
```
predef_controls = [(77777, "BLOCK"), (66666, "PASS")]
```

Returns:

The newly created Inspection Profile resource record.

Return type:

Box

Examples

Add a new ZPA Inspection Profile with the minimum required parameters, printing the object to console after creation:

print(
    zpa.inspection.add_profile(
        name="predefined_controls",
        paranoia_level=3,
        predef_controls_version="OWASP_CRS/3.3.0",
    )
)

Add a new ZPA Inspection Profile that uses additional predefined controls and custom controls, printing the object to console after creation:

print(
    zpa.inspection.add_profile(
        name="block_common_xss",
        paranoia_level=2,
        predefined_controls=[("99999", "BLOCK")],
        predef_controls_version="OWASP_CRS/3.3.0",
        custom_controls=[("88888", "BLOCK")],
    )
)

delete_custom_control(control_id)#

Deletes the specified custom ZPA Inspection Control.

Parameters:: control_id (str) – The unique id for the custom control that will be deleted.
Returns:: The status code for the operation.
Return type:: int

Examples

Delete a custom ZPA Inspection Control with an id of 99999.

zpa.inspection.delete_custom_control("99999")

delete_profile(profile_id)#

Deletes the specified Inspection Profile.

Parameters:: profile_id (str) – The unique id for the Inspection Profile that will be deleted.
Returns:: The status code for the operation.
Return type:: int

Examples

Delete an Inspection Profile with an id of 999999:

zpa.inspection.delete_profile("999999")

get_custom_control(control_id)#

Returns the specified custom ZPA Inspection Control.

Parameters:: control_id (str) – The unique id of the custom ZPA Inspection Control to be returned.
Returns:: The custom ZPA Inspection Control resource record.
Return type:: Box

Examples

Print the Custom Inspection Control with an id of 99999:

print(zpa.inspection.get_custom_control("99999"))

get_predef_control(control_id)#

Returns the specified predefined ZPA Inspection Control.

Parameters:: control_id (str) – The unique id of the predefined ZPA Inspection Control to be returned.
Returns:: The ZPA Inspection Predefined Control resource record.
Return type:: Box

Examples

Print the ZPA Inspection Predefined Control with an id of 99999:

print(zpa.inspection.get_predef_control("99999"))

get_profile(profile_id)#

Returns the specified ZPA Inspection Profile.

Parameters:: profile_id (str) – The unique id of the ZPA Inspection Profile
Returns:: The specified ZPA Inspection Profile resource record.
Return type:: Box

Examples

Print the ZPA Inspection Profile with an id of 99999:

print(zpa.inspection.get_profile("99999"))

list_control_action_types()#

Returns a list of ZPA Inspection Control Action Types.

Returns:: A list containing the ZPA Inspection Control Action Types.
Return type:: BoxList

Examples

Iterate over the ZPA Inspection Control Action Types and print each one:

for action_type in zpa.inspection.list_control_action_types():
    print(action_type)

list_control_severity_types()#

Returns a list of Inspection Control Severity Types.

Returns:: A list containing all valid Inspection Control Severity Types.
Return type:: BoxList

Examples

Print all Inspection Control Severity Types

for severity in zpa.inspection.list_control_severity_types():
    print(severity)

list_control_types()#

Returns a list of ZPA Inspection Control Types.

Returns:: A list containing ZPA Inspection Control Types.
Return type:: BoxList

Examples

Print all ZPA Inspection Control Types:

for control_type in zpa.inspection.list_control_types():
    print(control_type)

list_custom_control_types()#

Returns a list of custom ZPA Inspection Control Types.

Returns:: A list containing custom ZPA Inspection Control Types.
Return type:: BoxList

Examples

Print all custom ZPA Inspection Control Types

for control_type in zpa.inspection.list_custom_control_types():
    print(control_type)

list_custom_controls(**kwargs)#

Returns a list of all custom ZPA Inspection Controls.

Parameters:

**kwargs – Optional keyword arguments.

Keyword Arguments:

**search (str) – The string used to search for a custom control by features and fields.
**sortdir (str) –
Specifies the sorting order for the search results.

Accepted values are:
- ASC - ascending order
- DESC - descending order

Returns:

A list containing all custom ZPA Inspection Controls.

Return type:

BoxList

Examples

Print a list of all custom ZPA Inspection Controls:

for control in zpa.inspection.list_custom_controls():
    print(control)

list_custom_http_methods()#

Returns a list of custom ZPA Inspection Control HTTP Methods.

Returns:: A list containing custom ZPA Inspection Control HTTP Methods.
Return type:: BoxList

Examples

Print all custom ZPA Inspection Control HTTP Methods:

for method in zpa.inspection.list_custom_http_methods():
    print(method)

list_predef_control_versions()#

Returns a list of predefined ZPA Inspection Control versions.

Returns:: A list containing all predefined ZPA Inspection Control versions.
Return type:: BoxList

Examples

Print all predefined ZPA Inspection Control versions:

for version in zpa.inspection.list_predef_control_versions():
    print(version)

list_predef_controls(version, **kwargs)#

Returns a list of predefined ZPA Inspection Controls.

Parameters:

version (str) – The version of the predefined controls to return.
**kwargs – Optional keyword args.

Keyword Arguments:

**search (str) – The string used to search for predefined inspection controls by features and fields.

Returns:

A list containing all predefined ZPA Inspection Controls that match the Version and Search string.

Return type:

BoxList

Examples

Return all predefined ZPA Inspection Controls for the given version:

for control in zpa.inspection.list_predef_controls(version="OWASP_CRS/3.3.0"):
    print(control)

Return predefined ZPA Inspection Controls matching a search string:

for control in zpa.inspection.list_predef_controls(search="new_control", version="OWASP_CRS/3.3.0"):
    print(control)

list_profiles(**kwargs)#

Returns the list of ZPA Inspection Profiles.

Parameters:

**kwargs – Optional keyword args.

Keyword Arguments:

**pagesize (int) – Specifies the page size. The default size is 20 and the maximum size is 500.
**search (str, optional) – The search string used to match against features and fields.

Returns:

The list of ZPA Inspection Profile resource records.

Return type:

BoxList

Examples

Iterate over all ZPA Inspection Profiles and print them:

for profile in zpa.inspection.list_profiles():
    print(profile)

profile_control_attach(profile_id, action, **kwargs)#

Attaches or detaches all predefined ZPA Inspection Controls to a ZPA Inspection Profile.

Parameters:

profile_id (str) – The unique id for the ZPA Inspection Profile that will be modified.
action (str) –
The association action that will be taken, accepted values are:
- attach: Attaches all predefined controls to the Inspection Profile with the specified version.
- detach: Detaches all predefined controls from the Inspection Profile.
**kwargs – Additional keyword arguments.

Keyword Arguments:

profile_version (str) – The version of the Predefined Controls to attach. Only required when using the attach action. Defaults to OWASP_CRS/3.3.0.

Returns:

The updated ZPA Inspection Profile resource record.

Return type:

Box

Examples

Attach all predefined controls to a ZPA Inspection Profile with an id of 99999:

updated_profile = zpa.inspection.profile_control_attach("99999", action="attach")

Attach all predefined controls to a ZPA Inspection Profile with an id of 99999 and specified version:

updated_profile = zpa.inspection.profile_control_attach(
    "99999",
    action="attach",
    profile_version="OWASP_CRS/3.2.0",
)

Detach all predefined controls from a ZPA Inspection Profile with an id of 99999:

updated_profile = zpa.inspection.profile_control_attach(
    "99999",
    action="detach",
)

Raises:: ValueError – If an incorrect value is supplied for action.

update_custom_control(control_id, **kwargs)#

Updates the specified custom ZPA Inspection Control.

Parameters:

control_id (str) – The unique id for the custom control that will be updated.
**kwargs – Optional keyword args.

Keyword Arguments:

**description (str) – Additional information about the custom control.
**default_action (str) –
The default action to take for matches against this custom control. Valid options are:
- PASS
- BLOCK
- REDIRECT
**name (str) – The name of the custom control.
**paranoia_level (int) – The paranoia level for the custom control.

**rules (list) –

A list of Inspection Control rule objects, with each object using the format:

{
    "names": ["name1", "name2"],
    "type": "rule_type",
    "conditions": [
        ("LHS", "OP", "RHS"),
        ("LHS", "OP", "RHS"),
    ],
}

**severity (str) –
The severity for events that match this custom control. Valid options are:
- CRITICAL
- ERROR
- WARNING
- INFO
**type (str) –
The type of HTTP message this control matches. Valid options are:
- REQUEST
- RESPONSE

Returns:

The updated custom ZPA Inspection Control resource record.

Return type:

Box

Examples

Update the description of a custom ZPA Inspection Control with an id of 99999:

print(
    zpa.inspection.update_custom_control(
        "99999",
        description="Updated description",
    )
)

Update the rules of a custom ZPA Inspection Control with an id of 88888:

print(
    zpa.inspection.update_custom_control(
        "88888",
        rules=[
            {
                "names": ["xforwardedfor_ge_20"],
                "type": "REQUEST_HEADERS",
                "conditions": [
                    ("SIZE", "GE", "20"),
                    ("VALUE", "CONTAINS", "X-Forwarded-For"),
                ],
            }
        ],
    )
)

update_profile(profile_id, **kwargs)#

Updates the specified ZPA Inspection Profile.

Parameters:

profile_id (str) – The unique id for the ZPA Inspection Profile that will be updated.
predef_controls_version (str) – The predefined controls version for the ZPA Inspection Profile. Defaults to OWASP_CRS/3.3.0.
**kwargs – Optional keyword args.

Keyword Arguments:

**custom_controls (list) –
A tuple list of custom controls to be added to the Inspection profile.

Custom control tuples must follow the convention below:

(control_id, action)

e.g.
```
custom_controls = [(99999, "BLOCK"), (88888, "PASS")]
```
**description (str) – Additional information about the Inspection Profile.
**name (str) – The name of the Inspection Profile.
**paranoia_level (int) – The paranoia level for the Inspection Profile.
**predef_controls (list) –
A tuple list of predefined controls to be added to the Inspection profile.

Predefined control tuples must follow the convention below:

(control_id, action)

e.g.
```
predef_controls = [(77777, "BLOCK"), (66666, "PASS")]
```
**predef_controls_version (str) – The version of the predefined controls that will be added.

Returns:

The updated ZPA Inspection Profile resource record.

Return type:

Box

Examples

Update the name and description of a ZPA Inspection Profile with the id 99999:

print(
    zpa.inspection.update_profile(
        "99999",
        name="inspect_common_predef_controls",
        description="Inspects common controls from the Predefined set.",
    )
)

Add a custom control to the ZPA Inspection Profile with the id 88888:

print(
    zpa.inspection.update_profile(
        "88888",
        custom_controls=[("2", "BLOCK")],
    )
)

update_profile_and_controls(profile_id, inspection_profile, **kwargs)#

Updates the inspection profile and controls for the specified ID.

Note

This method has not been fully implemented and will not be maintained. There seems to be functionality duplication with the default Inspection Profile update API call. **kwargs has been provided as a parameter for you to be able to add any additional args that Zscaler may add.

If you feel that this is in error and that this functionality should be correctly implemented by pyZscaler, raise an issue in the pyZscaler Github repo.

Parameters:

profile_id (str) – The unique id of the inspection profile.
inspection_profile (dict) – The new inspection profile object.
**kwargs – Additional keyword args.