dlp_dictionary¶

The following methods allow for interaction with the ZIA DLP Dictionary API endpoints.

Methods are accessible via zia.dlp_dictionary

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 DLPDictionaryAPI¶

Bases: APIClient

A Client object for the DLP Dictionary resource.

add_dict(name, custom_phrase_match_type, dictionary_type, **kwargs)¶

Add a new Patterns and Phrases DLP Dictionary to ZIA.

Parameters:

name (str) – The name of the DLP Dictionary.
match_type (str) – The DLP custom phrase/pattern match type. Accepted values are all or any.

Keyword Arguments:

description (str) – Additional information about the DLP Dictionary.
phrases (list) –
A list of DLP phrases, with each phrase provided by a tuple following the convention (action, pattern). Accepted actions are all or unique. E.g.
```
('all', 'TOP SECRET')
('unique', 'COMMERCIAL-IN-CONFIDENCE')
```
patterns (list) –
A list of DLP patterns, with each pattern provided by a tuple following the convention (action, pattern). Accepted actions are all or unique. E.g.
```
('all', r'\d{2} \d{3} \d{3} \d{3}')
('unique', '[A-Z]{6}[A-Z0-9]{2,5}')
```

Returns:

The newly created DLP Dictionary resource record.

Return type:

Tuple

Examples

Match text found that contains an IPv4 address using patterns:

>>> zia.dlp_dictionary.add_dict(name='IPv4 Addresses',
...                description='Matches IPv4 address pattern.',
...                match_type='all',
...                patterns=[
...                    ('all', r'\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}(/(\d|[1-2]\d|3[0-2]))?')
...                ]))

Match text found that contains government document caveats using phrases.

>>> zia.dlp_dictionary.add_dict(name='Gov Document Caveats',
...                description='Matches government classification caveats.',
...                match_type='any',
...                phrases=[
...                    ('all', 'TOP SECRET'),
...                    ('all', 'SECRET'),
...                    ('all', 'CONFIDENTIAL')
...                ]))

Match text found that meets the criteria for a Secret Project’s document markings using phrases and patterns:

>>> zia.dlp_dictionary.add_dict(name='Secret Project Documents',
...                description='Matches documents created for the Secret Project.',
...                match_type='any',
...                phrases=[
...                    ('all', 'Project Umbrella'),
...                    ('all', 'UMBRELLA')
...                ],
...                patterns=[
...                    ('unique', '\d{1,2}-\d{1,2}-[A-Z]{5}')
...                ]))

delete_dict(dict_id)¶

Deletes the DLP Dictionary that matches the specified DLP Dictionary id.

Parameters:: dict_id (str) – The unique id for the DLP Dictionary.
Returns:: The status code for the operation.
Return type:: int

Examples

>>> zia.dlp_dictionary.delete_dict('8')

get_dict(dict_id)¶

Returns the DLP Dictionary that matches the specified DLP Dictionary id.

Parameters:: dict_id (str) – The unique id for the DLP Dictionary.
Returns:: The ZIA DLP Dictionary resource record.
Return type:: Tuple

Examples

>>> fetched_dict, _, error = client.zia.dlp_dictionary.get_dict('5865456')
>>> if error:
...     print(f"Error fetching dictionary by ID: {error}")
...     return
... print(f"Fetched dictionary by ID: {fetched_dict.as_dict()}")

list_dict_predefined_identifiers(dict_name)¶

Returns a list of predefined identifiers for a specific DLP dictionary by its name.

Parameters:: dict_name (str) – The name of the predefined DLP dictionary. Supported Predefined Identifiers are: ASPP_LEAKAGE, CRED_LEAKAGE, EUIBAN_LEAKAGE, PPEU_LEAKAGE, USDL_LEAKAGE
Returns:: A tuple containing (list of predefined identifiers, Response, error)
Return type:: tuple

Examples

List predefined identifiers for the ‘USDL_LEAKAGE’ dictionary

>>> pprint(zia.dlp_dictionary.list_dict_predefined_identifiers('USDL_LEAKAGE'))

list_dicts(query_params=None)¶

Returns a list of all custom and predefined ZIA DLP Dictionaries.

Parameters:: {dict} (query_params) – Map of query parameters for the request. [query_params.search] {str}: Search string to match a DLP dictionary’s name or description attributes
Returns:: A tuple containing (list of DLPDictionaries instances, Response, error)
Return type:: tuple

Example

List all dlp dictionaries:

>>> dict_list, response, error = client.zia.dlp_dictionary.list_dicts()
... if error:
...    print(f"Error listing dlp dictionaries: {error}")
...    return
... print(f"Total dictionaries found: {len(dict_list)}")
... for dict in dict_list:
...    print(dict.as_dict())

filtering dlp dictionaries by name :

>>> dict_list, response, error = client.zia.dlp_dictionary.list_dicts(
    query_params={"search": 'GDPR'}
)
... if error:
...    print(f"Error listing dlp dictionaries: {error}")
...    return
... print(f"Total dictionaries found: {len(dict_list)}")
... for dict in dict_list:
...    print(dict.as_dict())

list_dicts_lite(query_params=None)¶

Lists name and ID dictionary of all custom and predefined DLP dictionaries. If the search parameter is provided, the function filters the rules client-side.

Parameters:: {dict} (query_params) – Map of query parameters for the request. [query_params.search] {str}: The search string used to match against a dictionary name.
Returns:: List of DLP Dictionary resource records.
Return type:: tuple

Examples

Gets a list of all DLP Dictionary.

>>> fetched_dicts, response, error = client.zia.dlp_dictionary.list_dicts()
... if error:
...     print(f"Error listing DLP Dictionaries: {error}")
...     return
... print(f"Fetched dictionaries: {[dictionary.as_dict() for dictionary in fetched_dicts]}")

Gets a list of all DLP Dictionary name and ID.

>>> dict, response, error = = client.zia.dlp_dictionary.list_dicts(query_params={"search": 'EUIBAN_LEAKAGE'})
... if error:
...     print(f"Error listing DLP Dictionary: {error}")
...     return
... print(f"Fetched dictionary: {[dictionary.as_dict() for dictionary in dict]}")

update_dict(dict_id, **kwargs)¶

Updates the specified DLP Dictionary.

Parameters:

dict_id (str) – The unique id of the DLP Dictionary.
**kwargs – Optional keyword args.

Keyword Arguments:

description (str) – Additional information about the DLP Dictionary.
match_type (str) – The DLP custom phrase/pattern match type. Accepted values are all or any.
name (str) – The name of the DLP Dictionary.
phrases (list) –
A list of DLP phrases, with each phrase provided by a tuple following the convention (action, pattern). Accepted actions are all or unique. E.g.
```
('all', 'TOP SECRET')
('unique', 'COMMERCIAL-IN-CONFIDENCE')
```
patterns (list) –
A list of DLP pattersn, with each pattern provided by a tuple following the convention (action, pattern). Accepted actions are all or unique. E.g.
```
('all', r'\d{2} \d{3} \d{3} \d{3}')
('unique', '[A-Z]{6}[A-Z0-9]{2,5}')
```

Returns:

The updated DLP Dictionary resource record.

Return type:

tuple

Examples

Update the name of a DLP Dictionary:

>>> zia.dlp_dictionary.update_dict('3',
...                name='IPv4 and IPv6 Addresses')

Update the description and phrases for a DLP Dictionary.

>>> zia.dlp_dictionary.update_dict('4',
...        description='Updated government caveats.'
...        phrases=[
...                    ('all', 'TOP SECRET'),
...                    ('all', 'SECRET'),
...                    ('all', 'PROTECTED')
...                ])

validate_dict(pattern)¶

Validates the provided pattern for usage in a DLP Dictionary.

Note: The ZIA API documentation doesn’t provide information on how to structure a request for this API endpoint. This endpoint is returning a valid response but validation isn’t failing for obvious wrong patterns. Use at own risk.

Parameters:: pattern (str) – DLP Pattern for evaluation.
Returns:: A tuple containing the validation result (DLPPatternValidation instance), response, and error.
Return type:: tuple