ips_signature_rules¶

The following methods allow for interaction with the ZIA IPS Signature Rules API endpoints.

Methods are accessible via zia.ips_signature_rules

Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED “AS IS” AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

class IPSSignatureRulesAPI¶

Bases: APIClient

A Client object for the IPS Signture Rules resource.

add_ips_signature_rule(**kwargs)¶

Creates a new custom IPS signature rule.

The supplied rule_text is validated against the ZIA dynamic-validation endpoint (validate_ips_signature_rule) before the create request is issued. If the rule is syntactically or semantically invalid, the method returns (None, None, ValueError(...)) and no create call is made.

See the Add ZIA Custom IPS Signature Rule API reference for further detail on optional keyword parameter structures.

Parameters:

name (str) – The name of the IPS Signature Rule.
**kwargs – Optional keyword args.

Keyword Arguments:

description (str) – Additional notes or information.
rule_text (str) – The custom signature rule text. Validated before submit.

Returns:

A tuple containing the newly added IPS Signature Rule, response, and error.

Return type:

tuple

Examples

Add a new IPS Signature Rule :

>>> added_rule, _, error = client.zia.ips_signature_rules.add_ips_signature_rule(
...     name=f"NewIPS_Signature_Rule_{random.randint(1000, 10000)}",
...     description=f"NewIPS_Signature_Rule_{random.randint(1000, 10000)}",
...     rule_text='alert http any any -> any any (msg:"HTTP /admin"; '
...               'content:"/admin"; http_uri; nocase; sid:1000010; rev:1;)',
... )
>>> if error:
...     print(f"Error adding IPS Signature Rule: {error}")
...     return
... print(f"IPS Signature Rule added successfully: {added_rule.as_dict()}")

delete_ips_signature_rule(rule_id)¶

Deletes the specified IPS Signature Rule.

See the Delete ZIA Custom IPS Signature Rule API reference for further detail on optional keyword parameter structures.

Parameters:: rule_id (int) – The unique identifier of the IPS Signature Rule.
Returns:: A tuple containing the response object and error (if any).
Return type:: tuple

Examples

Delete a IPS Signature Rule:

>>> _, _, error = client.zia.ips_signature_rules.delete_ips_signature_rule('73459')
>>> if error:
...     print(f"Error deleting IPS Signature Rule: {error}")
...     return
... print(f"IPS Signature Rule with ID {'73459' deleted successfully.")

export_custom_ips_signatures(filename=None)¶

Exports the custom IPS signature rules to a CSV file.

See the Export ZIA Custom IPS Signature Rules API reference for further detail on optional keyword parameter structures.

Parameters:: filename (str, optional) – Custom filename for the CSV file. Defaults to timestamped name.
Returns:: Path to the downloaded CSV file.
Return type:: str

Examples

Export custom IPS signature rules to a CSV:

>>> try:
...     filename = client.zia.ips_signature_rules.export_custom_ips_signatures(
...         filename="custom_ips_signature_rules.csv",
...     )
...     print(f"Custom IPS signature rules exported successfully: {filename}")
... except Exception as e:
...     print(f"Error during export: {e}")

get_ips_signature_rule(rule_id)¶

Fetches the custom IPS signature rules based on the specified ID

See the Get ZIA Custom IPS Signature Rule API reference for further detail on optional keyword parameter structures.

Parameters:: rule_id (int) – The unique identifier for the IPS Signature Rule.
Returns:: A tuple containing (IPS Signature Rule instance, Response, error).
Return type:: tuple

Examples

Print a specific IPS Signature Rule

>>> fetched_rule, _, error = client.zia.ips_signature_rules.get_ips_signature_rule(
    '1254654')
>>> if error:
...     print(f"Error fetching IPS Signature Rule by ID: {error}")
...     return
... print(f"Fetched IPS Signature Rule by ID: {fetched_rule.as_dict()}")

list_ips_signature_rules(query_params=None)¶

Lists custom IPS signature rules.

See the List ZIA Custom IPS Signature Rules API reference for further detail on optional keyword parameter structures.

Parameters:

{dict} (query_params) –

Map of query parameters for the request. [query_params.page] {int}: Specifies the page offset.

[query_params.page_size] {int}: Page size for pagination.

Returns:

A tuple containing (list of IPS Signture Rules instances, Response, error)

Return type:

tuple

Examples

List IPS Signture Rules using default settings:

>>> rules_list, _, error = client.zia.ips_signature_rules.list_ips_signature_rules(
    query_params={'page': '1', 'page_size': '250'})
>>> if error:
...     print(f"Error listing IPS Signature Rules: {error}")
...     return
... print(f"Total IPS Signature Rules found: {len(rules_list)}")
... for rule in rules_list:
...     print(rule.as_dict())

Client-side filtering with JMESPath:

The response object supports client-side filtering and projection via resp.search(expression). See the JMESPath documentation for expression syntax.

update_ips_signature_rule(rule_id, **kwargs)¶

Updates information for the specified IPS Signature Rule.

Note

Unlike add_ips_signature_rule(), this method does not call validate_ips_signature_rule() before issuing the update. The dynamic-validation endpoint flags any signature carrying a sid (or other unique identifiers) that already exists on the tenant as a duplicate — which on an update is the rule being modified itself, so a pre-flight check would reject every legitimate update. If you want to validate rule_text before updating, call validate_ips_signature_rule() explicitly from your code.

See the Update ZIA Custom IPS Signature Rule API reference for further detail on optional keyword parameter structures.

Parameters:

rule_id (int) – The unique ID for the IPS Signature Rule.

Keyword Arguments:

name (str) – The name of the IPS Signature Rule.
description (str) – Additional notes or information.
rule_text (str) – The custom signature rule text.

Returns:

A tuple containing the updated IPS Signature Rule, response, and error.

Return type:

tuple

Examples

Update an existing IPS Signature Rule :

>>> updated_rule, _, error = client.zia.ips_signature_rules.update_ips_signature_rule(
...     rule_id='1524566',
...     name=f"UpdatedIPS_Signature_Rule_{random.randint(1000, 10000)}",
...     description=f"UpdatedIPS_Signature_Rule_{random.randint(1000, 10000)}",
...     rule_text='alert http any any -> any any (msg:"HTTP /admin"; '
...               'content:"/admin"; http_uri; nocase; sid:1000010; rev:1;)',
... )
>>> if error:
...     print(f"Error updating IPS Signature Rule: {error}")
...     return
... print(f"IPS Signature Rule updated successfully: {updated_rule.as_dict()}")

validate_ips_signature_rule(rule_text)¶

Validates a new custom signature rule based on specific predefined conditions, such as syntax errors, duplicate signatures, and more.

See the Validate ZIA Custom IPS Signature Rule API reference for further detail on optional keyword parameter structures.

Parameters:: rule_text (str) – The custom signature rule text to be validated. Sent on the wire as {"ruleText": "<rule_text>"} to match the API contract.
Returns:: A tuple containing (ValidateIPSRuleText, Response, error).
Return type:: tuple

Example

To validate a custom signature rule text:

>>> rule_text = '''
... alert http any any -> any any (msg:"HTTP /admin"; content:"/admin";             ... http_uri; nocase; sid:1000010; rev:1;)
... '''
>>> result, _, error = client.zia.ips_signature_rules.validate_ips_signature_rule(
...     rule_text=rule_text,
... )
>>> if error:
...     print(f"Validation failed: {error}")
... elif result.status == 0 and not result.err_msg:
...     print("IPS signature rule is valid.")
... else:
...     print(f"Invalid rule: {result.err_msg} (position {result.err_position})")