API Reference

class proofpoint_itm.client.ITMClient(config, scope='*', verify=True, development=False, **kwargs)

Bases: object

Client class for Proofpoint ITM SaaS API.

This class shall be initialized with a config dictionary containing the client_id, tenant_id, and client_secret:

{
    "tenant_id" : "The tenant name"
    "client_id" : "application client id"
    "client_secret": "client secret for token based auth"
}

activity_search(query: dict, entity: str, params: dict = None, headers: dict = None, stream: bool = False) → dict

Performs a search query against the activity API

Parameters:

• query (dict) – A dict representing an Elasticsearch query, will be converted to json string

• entity (str) – entityTypes to search for Accepted values: event, casbevent, audit, network

• params (dict) – A dict of web request url parameters ex. offset = 0, limit=500

• headers (dict) – Headers to include in the http request, if not provided a default header will be created with auth info

• stream (bool) – Flag to invoke the streaming response

Returns:

A dictionary containing the API response.

Return type:

dict

add_activity_assignee(fqid, admin_id, headers: dict = None) → dict

Adds an assignee to an activity.

Parameters:

• fqid (str) – The fully qualified ID of the activity to add the assignee to.

• admin_id (str) – The admin ID that will be assigned to the activity.

• headers (dict, optional) – Additional headers to include in the HTTP request. Defaults to an empty dictionary.

Returns:

A dictionary containing the API response.

Return type:

dict

add_activity_tag(fqid, tag_id, headers: dict = None, params: dict = None) → dict

Add a tag to an activity.

Parameters:

• fqid (str) – The fully qualified ID of the activity to add the tag to.

• tag_id (str) – The ID of the tag to be added.

• headers (dict, optional) – Additional headers to include in the HTTP request. Defaults to an empty dictionary.

• params (dict) – Custom query parameters to send with request

Returns:

A dictionary containing the API response.

Return type:

dict

create_agent_policy(policy: AgentPolicy, headers: dict = None, test: bool = False) → dict

Create an new agent policy from a proofpoint_itm.classes.AgentPolicy object

Parameters:

• policy (AgentPolicy) – A proofpoint_itm.classes.AgentPolicy object to create

• headers (dict) – headers to include in the http request, if not provided a default header will be created with auth info

• test (bool) – Test flag to return fake success status

Returns:

A dictionary containing the created agent policy.

Return type:

dict

create_detector(detector: Detector, headers: dict = None) → dict

Create a new detector.

Parameters:

• detector (Detector) – The Detector object representing the new detector to be created.

• headers (dict, optional) – Additional headers to include in the HTTP request. Defaults to an empty dictionary.

Returns:

A dictionary containing the API response.

Return type:

dict

create_detector_set(detector_set: DetectorSet, headers: dict = None) → dict

Create a new detector set.

Parameters:

• detector_set (DetectorSet) – The DetectorSet object representing the new detector set to be created.

• headers (dict, optional) – Additional headers to include in the HTTP request. Defaults to an empty dictionary.

Returns:

A dictionary containing the created detector set.

Return type:

dict

create_dictionaries(dictionaries: list[Dictionary], headers: dict = None) → list

Creates or updates a batch list of dictionaries

Parameters:

• dictionaries (list) – A list of proofpoint_itm.classes.Dictionary objects

• headers (dict) – Headers to include in the http request, if not provided a default header will be created with auth info

Returns:

A list containing the created dictionaries.

Return type:

list

create_dictionary(dictionary: Dictionary, headers: dict = None) → dict

Create a new dictionary.

Parameters:

• dictionary (Dictionary) – The proofpoint_itm.classes.Dictionary object representing the new dictionary to be created.

• headers (dict, optional) – Additional headers to include in the HTTP request. Defaults to an empty dictionary.

Returns:

A dictionary containing the created dictionary.

Return type:

dict

create_notification_policy(target_group: TargetGroup, headers: dict = None, test: bool = False) → dict

Create new notification policy (target-group)

Creates a new notification policy from a proofpoint_itm.classes.TargetGroup object

Parameters:

• target_group (obj) – proofpoint_itm.classes.TargetGroup object

• headers (dict) – headers to include in the http request, if not provided a default header will be created with auth info

• test (bool) – Test flag to return fake generated uuid

Returns:

A dictionary containing the created notification policy.

Return type:

dict

create_predicate(predicate: Predicate, headers: dict = None, test: bool = False) → dict

Creates a new predicate from a proofpoint_itm.classes.Predicate object

Parameters:

• predicate (obj) – proofpoint_itm.classes.Predicate object

• headers (dict) – headers to include in the http request, if not provided a default header will be created with auth info

• test (bool) – Test flag to return fake generated uuid

Returns:

A dictionary containing the API response.

Return type:

dict

create_rule(rule: Rule, headers: dict = None, test=False) → dict

Create new rule

Creates a new rule from a proofpoint_itm.classes.Rule object

Parameters:

• rule (obj) – proofpoint_itm.classes.Rule object

• headers (dict) – headers to include in the http request, if not provided a default header will be created with auth info

• test (bool) – Test flag to return fake generated uuid

Returns:

A dictionary containing the API response.

Return type:

dict

create_tag(tag: Tag, headers: dict = None, test: bool = False) → dict

Create a new tag.

Parameters:

• tag (obj) – The proofpoint_itm.classes.Tag object representing the tag to be created.

• headers (dict, optional) – Additional headers to include in the HTTP request. If not provided, a default header will be created with auth info.

• test (bool, optional) – Test flag to return a fake generated UUID. Defaults to False.

Returns:

API response containing the created tag.

Return type:

dict

delete_detector_set(id_: str, headers: dict = None) → dict

Delete a detector set.

Parameters:

• id (str) – The ID of the detector set to delete.

• headers (dict, optional) – Additional headers to include in the HTTP request. Defaults to an empty dictionary.

Returns:

A dictionary containing the API response.

Return type:

dict

delete_dictionary(id_: str, headers: dict = None) → dict

Delete a dictionary.

Parameters:

• id (str) – The ID of the dictionary to delete.

• headers (dict, optional) – Additional headers to include in the HTTP request. Defaults to an empty dictionary.

Returns:

A dictionary containing the API response.

Return type:

dict

delete_predicate(id_, headers: dict = None)

Delete a predicate.

Parameters:

• id (str) – The ID of the object to delete.

• headers (dict, optional) – Additional headers to include in the HTTP request. Defaults to an empty dictionary.

Returns:

A dictionary containing the API response.

Return type:

dict

delete_rule(id_, headers: dict = None)

Delete a rule.

Parameters:

• id (str) – The ID of the object to delete.

• headers (dict, optional) – Additional headers to include in the HTTP request. Defaults to an empty dictionary.

Returns:

A dictionary containing the API response.

Return type:

dict

depot_search(query: dict, entity: str, params: dict = None, headers: dict = None) → dict

Performs a search query against the depot API

Parameters:

• query (dict) – A dict representing an Elasticsearch query, will be converted to json string

• entity (str) – entityTypes to search for Accepted values: list, predicate, tag, article

• params (dict) – A dict of web request url parameters ex. offset = 0, limit=500

• headers (dict) – Headers to include in the http request, if not provided a default header will be created with auth info

Returns:

A dictionary containing the API response.

Return type:

dict

get_agent_policies(includes: str = '*', headers: dict = None, params: dict = None) → list

Retrieves agent policies from the specified API endpoint.

Parameters:

• includes (str, optional) – A string specifying the entities to include in the response. Defaults to ‘*’, which includes all entities.

• headers (dict, optional) – Additional headers to be included in the request. Defaults to an empty dictionary.

• params (dict, optional) – Additional parameters to control the request, such as ‘limit’ and ‘offset’. Defaults to None.

Returns:

A list containing the retrieved agent policies.

Return type:

list

get_agent_policy(id_: str, includes: str = '*', headers: dict = None, params: dict = None) → dict

Retrieves a specific agent policy based on the provided ID from the specified API endpoint.

Parameters:

• id (str) – The ID of the agent policy to retrieve.

• includes (str, optional) – A string specifying the entities to include in the response. Defaults to ‘*’, which includes all entities.

• headers (dict, optional) – Additional headers to be included in the request. Defaults to an empty dictionary.

• params (dict, optional) – Additional parameters to control the request, such as ‘limit’ and ‘offset’. Defaults to None.

Returns:

A dictionary containing the retrieved agent policy.

Return type:

dict

get_conditions(includes: str = '*', headers: dict = None, params: dict = None) → list

Query for all custom match predicates (user created) that are not auto created from rules

Uses the get_predicates call, then post filters for kind = it:predicate:custom:match

Parameters:

• includes (str) – comma-separated list of attributes to include, default = *

• headers (dict) – headers to include in the http request, if not provided a default header will be created with auth info

• params (dict) – Custom query parameters to include in GET request

Returns:

Returns list of predicate objects

Return type:

list

get_detector(id_: str, headers: dict = None) → dict

Retrieve a specific detector from the API endpoint.

Parameters:

• id (str) – The ID of the detector to retrieve.

• headers (dict, optional) – Additional headers to include in the HTTP request. Defaults to an empty dictionary.

Returns:

A dictionary containing the retrieved detector.

Return type:

dict

get_detector_set(id_: str, headers: dict = None) → dict

Retrieve a specific detector set from the API endpoint based on the provided ID.

Parameters:

• id (str) – The ID of the detector set to retrieve.

• headers (dict, optional) – Additional headers to include in the HTTP request. Defaults to an empty dictionary.

Returns:

A dictionary containing the retrieved detector set.

Return type:

dict

get_detector_sets(headers: dict = None) → list

Retrieve detector sets from the API endpoint.

Parameters:

headers (dict, optional) – Additional headers to include in the HTTP request. Defaults to an empty dictionary.

Returns:

A list containing the retrieved detector sets.

Return type:

list

get_detectors(headers: dict = None) → list

Retrieve detectors from the API endpoint.

This method retrieves detectors related to DLP configurations from the specified API endpoint.

Parameters:

headers (dict, optional) – Additional headers to include in the HTTP request. Defaults to an empty dictionary.

Returns:

A list containing the retrieved detectors.

Return type:

list

get_dictionaries(headers: dict = None, includes: str = '*', params: dict = None) → list

Retrieve dictionaries from the API endpoint.

Parameters:

• headers (dict, optional) – Additional headers to include in the HTTP request. Defaults to an empty dictionary.

• includes (str, optional) – A string specifying the entities to include in the response. Defaults to ‘*’, which includes all entities.

• params (dict) – Custom query parameters to include in request

Returns:

A list containing the retrieved dictionaries.

Return type:

list

get_dictionary(id_: str, headers: dict = None, includes: str = None, params: dict = None) → dict

Retrieve a specific dictionary from the API endpoint.

Parameters:

• id (str) – The ID of the dictionary to retrieve.

• headers (dict, optional) – Additional headers to include in the HTTP request. Defaults to an empty dictionary.

• includes (str, optional) – A string specifying the entities to include in the response. Defaults to None.

• params (dict) – Custom query parameters to include in request

Returns:

A dictionary containing the retrieved dictionary.

Return type:

dict

get_dictionary_terms(id_: str, headers: dict = None, includes: str = '*', params: dict = None) → list

Retrieve terms from a specific dictionary in the API endpoint.

Parameters:

• id (str) – The ID of the dictionary to retrieve terms from.

• headers (dict, optional) – Additional headers to include in the HTTP request. Defaults to an empty dictionary.

• includes (str, optional) – A string specifying the entities to include in the response. Defaults to ‘*’, which includes all entities.

• params (dict) – Custom query parameters to include in request

Returns:

A list containing the retrieved terms.

Return type:

list

get_endpoints(includes: str = '*', kind: str = '*', status: str = '*', headers: dict = None, count: bool = False, params: dict = None) → dict

Fetches all endpoints of a given kind from the registry api

Parameters:

• includes (str) – List of attributes to return, defaults to ‘*’

• kind (str) – Type of agent to return, Accepts ‘*’, ‘agent:saas’, or ‘updater:saas’, defaults to ‘*’

• status (str) – Filter by agent status Accepts: ‘*’, HEALTHY, UNHEALTHY, UNREACHABLE, DEAD, INACTIVE

• headers (dict) – Headers to include in web request

• count (bool) – Return count of endpoints only

• params (dict) – Custom query parameters to include in web request

Returns:

A list of endpoint objects

Return type:

dict

get_notification_policies(includes: str = '*', headers: dict = None) → list

Query for all notification policies in the notifications API

Parameters:

• includes (str) – comma-separated list of attributes to include, default = *

• headers (dict) – headers to include in the http request, if not provided a default header will be created with auth info

• params (dict) – Custom query parameters to include in request

Returns:

A list containing notification policies

Return type:

list

get_predicate(id_: str, includes: str = '*', headers: dict = None, params: dict = None) → dict

Query for a single predicate by ID

Parameters:

• id (str) – The predicate id to return

• includes (str) – Comma-separated list of attributes to include, default = *

• headers (dict) – headers to include in the http request, if not provided a default header will be created with auth info

• params (dict) – Custom query parameters to include in GET request

Returns:

A dict of predicate attributes

Return type:

dict

get_predicates(includes: str = '*', headers: dict = None, params: dict = None) → list

Query for all predicates in the depot API, does not return built-in

Parameters:

• includes (str) – Comma-separated list of attributes to include, default = *

• headers (dict) – headers to include in the http request, if not a default header will be created with auth info

• params (dict) – Custom query parameters to include in GET request

Returns:

A list of predicate objects

Return type:

list

get_rule(id_: str, includes: str = '*', headers: dict = None, params: dict = None) → dict

Query for rule by ID in the depot API

Parameters:

• id (str) – Rule id to return, if not provided, return all

• includes (str) – comma-separated list of attributes to include, default = *

• headers (dict) – headers to include in the http request, if not provided a default header will be created with auth info

• params (dict) – Custom query parameters to include in GET request

Returns:

A dict of rule attributes

Return type:

dict

get_rules(includes: str = '*', headers: dict = None, params: dict = None) → list

Query for all rules in the depot API

Parameters:

• includes (str) – comma-separated list of attributes to include, default = *

• headers (dict) – headers to include in the http request, if not provided a default header will be created with auth info

• params (dict) – Custom query parameters to include in GET request

Returns:

A list of rules objects

Return type:

list

get_smartids(headers: dict = None) → list

Retrieve smart IDs from the API endpoint.

Parameters:

headers (dict, optional) – Additional headers to include in the HTTP request. Defaults to an empty dictionary.

Returns:

A dictionary containing the retrieved smart IDs.

Return type:

dict

get_tag(id_: str, includes: str = '*', headers: dict = None) → dict

Get tag by ID.

Parameters:

• id (str) – The tag ID.

• includes (str) – Comma-separated list of attributes to include. Default is ‘*’.

• headers (dict) – Headers to include in the HTTP request. If not provided, a default header will be created with auth info.

• params (dict) – Custom query parameters to include in GET request

Returns:

A dictionary of tag information.

Return type:

dict

get_tags(includes: str = '*', headers: dict = None, params: dict = None) → list

Query for all tags in the depot API, does not return built-in tags

Parameters:

• includes (str) – Comma-separated list of attributes to include, default is ‘*’.

• headers (dict) – Headers to include in the HTTP request, if not provided, a default header will be created with auth info.

• params (dict) – Custom query parameters to include in GET request

Returns:

A list of tags objects.

Return type:

list

notification_search(query: dict, entity: str, params: dict = None, headers: dict = None) → dict

Performs a search query against the depot API

Parameters:

• query (dict) – A dict representing an Elasticsearch query, will be converted to json string

• entity (str) – entityTypes to search for Accepted values: target-group, notification

• params (dict) – A dict of web request url parameters ex. offset = 0, limit=500

• headers (dict) – Headers to include in the http request, if not provided a default header will be created with auth info

Returns:

A dictionary containing the API response.

Return type:

dict

overwrite_agent_policy(id_, policy: AgentPolicy, headers: dict = None, test: bool = False) → dict

Overwrite an Agent Policy by ID

Parameters:

• id (str) – ID of the policy to update

• policy (AgentPolicy) – A proofpoint_itm.classes.AgentPolicy object

• headers (dict) – headers to include in the http request, if not provided a default header will be created with auth info

• test (bool) – Test flag to return fake success status

Returns:

A dictionary containing the updated agent policy.

Return type:

dict

overwrite_predicate(id_, predicate: Predicate, headers: dict = None, test: bool = False) → dict

Overwrite a predicate by ID, Performs a ‘PUT’ method call to the depot/predicate API

Parameters:

• id (str) – ID of the predicate to udpate

• data (dict) – A dict of the keys/values to update

• headers (dict) – headers to include in the http request, if not provided a default header will be created with auth info

• test (bool) – Test flag to return fake generated uuid

Returns:

A dictionary containing the API response.

Return type:

dict

publish_config(headers: dict = None, artifactID: str = 'activity', data: dict = None) → dict

This method publishes a configuration artifact triggers a configuration push.

Parameters:

• headers (dict, optional) – Additional headers to include in the HTTP request. Defaults to an empty dictionary.

• artifactID (str, optional) – The ID of the artifact to publish. Defaults to ‘activity’.

• data (dict, optional) – The configuration data to publish. Defaults to an empty dictionary.

Returns:

A dictionary containing the API response.

Return type:

dict

registry_search(query: dict, entity: str, params: dict = None, headers: dict = None, stream: bool = False) → dict

Performs a search query against the registry API

Parameters:

• query (dict) – A dict representing an Elasticsearch query, will be converted to json string

• entity (str) – entityTypes to search for Accepted values: event, casbevent, audit, network

• params (dict) – A dict of web request url parameters ex. offset=0, limit=500

• headers (dict) – Headers to include in the http request, if not provided a default header will be created with auth info

• stream (bool) – Flag to invoke the streaming response

Returns:

A dictionary containing the API response.

Return type:

dict

ruler_search(query: str, entity: str, params: dict = None, headers: dict = None) → dict

Performs a search query against the ruler API

Parameters:

• query (dict) – A dict representing an Elasticsearch query, will be converted to json string

• entity (str) – entityTypes to search for Accepted values: artifact, rule, rulechain

• params (dict) – A dict of web request url parameters ex. offset = 0, limit=500

• headers (dict) – Headers to include in the http request, if not provided a default header will be created with auth info

Returns:

A dictionary containing the API response.

Return type:

dict

update_agent_policy(id_, policy: AgentPolicy, headers: dict = None, test: bool = False) → dict

Update an Agent Policy by ID

Parameters:

• id (str) – ID of the policy to update

• policy (AgentPolicy) – A proofpoint_itm.classes.AgentPolicy object

• headers (dict) – headers to include in the http request, if not provided a default header will be created with auth info

• test (bool) – Test flag to return fake success status

Returns:

A dictionary containing the updated agent policy.

Return type:

dict

update_detector(id_: str, detector: Detector, headers: dict = None) → dict

This method updates an existing detector with the provided ID based on a Detector object.

Parameters:

• id (str) – The ID of the detector to update.

• detector (Detector) – The Detector object representing the updated detector.

• headers (dict, optional) – Additional headers to include in the HTTP request. Defaults to an empty dictionary.

Returns:

A dictionary containing the API response.

Return type:

dict

update_detector_set(id_: str, detector_set: DetectorSet, headers: dict = None) → dict

Update a detector set with the provided ID based on a DetectorSet object.

Parameters:

• id (str) – The ID of the detector set to update.

• detector_set (DetectorSet) – The DetectorSet object representing the updated detector set.

• headers (dict, optional) – Additional headers to include in the HTTP request. Defaults to an empty dictionary.

Returns:

A dictionary containing the updated detector set.

Return type:

dict

update_dictionary(id_: str, dictionary: Dictionary, headers: dict = None) → dict

Update a dictionary.

Parameters:

• id (str) – The ID of the dictionary to update.

• dictionary (Dictionary) – The Dictionary object representing the updated dictionary.

• headers (dict, optional) – Additional headers to include in the HTTP request. Defaults to an empty dictionary.

Returns:

A dictionary containing the updated dictionary.

Return type:

dict

update_event_workflow(fqid: str, status: str, headers: dict = None) → dict

Update workflow status of an alert/incident

Parameters:

• fqid (str) – The fqid of an event/incident

• status (str) – The new status to be applied to the incident Accepts new, reopened, in-progress, escalated, on-hold, resolved, false-positive, not-an-issue

Returns:

A dictionary containing the API response.

Return type:

dict

update_notification_policy(id_: str, target_group: TargetGroup, headers: dict = None, test: bool = False) → dict

Update existing notification policy (target-group)

Updates an existing notification policy from a proofpoint_itm.classes.TargetGroup object

Parameters:

• id (str) – The target-group ID to update

• target_group (obj) – proofpoint_itm.classes.TargetGroup object

• headers (dict) – headers to include in the http request, if not provided a default header will be created with auth info

• test (bool) – Test flag to return fake generated uuid

Returns:

A dictionary containing the updated notification policy.

Return type:

dict

update_predicate(id_, predicate: Predicate, headers: dict = None, test: bool = False) → dict

Update a predicate by ID. Performs a ‘PATCH’ method call to the depot/predicate API

Parameters:

• id (str) – ID of the predicate to udpate

• data (dict) – A dict of the keys/values to update

• headers (dict) – headers to include in the http request, if not provided a default header will be created with auth info

• test (bool) – Test flag to return fake generated uuid

Returns:

A dictionary containing the API response.

Return type:

dict

update_rule(id_: str, rule: Rule, headers: dict = None, test: bool = False) → dict

Updates an existing rule from a proofpoint_itm.classes.Rule object

Parameters:

• id (str) – Rule ID to update

• rule (obj) – proofpoint_itm.classes.Rule object

• headers (dict) – headers to include in the http request, if not provided a default header will be created with auth info

• test (bool) – Test flag to return fake generated uuid

Returns:

A dictionary containing the API response.

Return type:

dict

update_tag(id_: str, tag: Tag, headers: dict = None, test: bool = False) → dict

Update a tag.

Parameters:

• id (str) – The ID of the tag to update.

• tag (Tag) – The proofpoint_itm.classes.Tag object representing the updated tag.

• headers (dict, optional) – Additional headers to include in the HTTP request. Defaults to an empty dictionary.

• test (bool, optional) – A flag to indicate whether to return a fake generated UUID. Defaults to False.

Returns:

A dictionary containing the updated tag.

Return type:

dict