Developer Interface¶

This documentation covers all the available pancloud interfaces, excluding those implemented by external libraries.

HTTP Client¶

HTTP client wrapper for the excellent requests library.

class pancloud.httpclient.HTTPClient(**kwargs)[source]¶

Bases: object

HTTP client for the Application Framework REST API

request(**kwargs)[source]¶

Generate HTTP request using given parameters.

The request method prepares HTTP requests using class or method-level attributes/variables. Class-level attributes may be overridden by method-level variables offering greater flexibility and efficiency.

Parameters:	enforce_json (bool) – Require properly-formatted JSON or raise `HTTPError`. Defaults to `False`. path (str) – URI path to append to URL. Defaults to `empty`. raise_for_status (bool) – If `True`, raises `HTTPError` if status_code not in 2XX. Defaults to `False`. **kwargs – Supported `Session` and `HTTPAdapter` parameters.
Returns:	Requests Response() object
Return type:	requests.Response

Directory-Sync Service¶

Interact with the Application Framework Directory-Sync Service API.

To obtain rich information about users and devices for the purposes of reporting and policy enforcement, cloud-based applications need access to directory information. However, most directories are located on-premise so they cannot be accessed by cloud-based applications. The Directory Sync Service allows cloud-based applications to access directory data by using an on-premise agent to collect it, and then transferring the data to the cloud-based Directory-Sync Service.

Examples

Refer to the examples provided with this library.

class pancloud.directorysync.DirectorySyncService(**kwargs)[source]¶

Bases: object

An Application Framework Directory-Sync Service Instance.

attributes(**kwargs)[source]¶

Retrieve the attribute configuration object.

Retrieves a mapping that identifies the custom directory attributes configured for the Directory SyncService instance, and the mapping of the custom attributes to standard directory attributes.

Parameters:	**kwargs – Supported `request()` parameters.
Returns:	Requests Response() object.
Return type:	requests.Response

Examples

Refer to directory_attributes.py example.

count(object_class=None, params=None, **kwargs)[source]¶

Retrieve the attribute configuration object.

Retrieve a count of all directory entries that belong to the identified objectClass. The count is limited to a single domain.

Parameters:	params (dict) – Payload/request dictionary. object_class (str) – Directory object class. **kwargs – Supported `request()` parameters.
Returns:	Requests Response() object.
Return type:	requests.Response

Examples

Coming soon.

domains(**kwargs)[source]¶

Retrieves a list of all domains available.

Directory Sync Service can be configured to read directory entries from multiple domains. This API retrieves all the domains from which your Directory Sync Service instance is configured to read entries. Domains are identified in both DNS and distinguished name format.

Parameters:	**kwargs – Supported `request()` parameters.
Returns:	Requests Response() object.
Return type:	requests.Response

Examples

Coming soon.

query(object_class=None, json=None, **kwargs)[source]¶

Query data stored in directory.

Retrieves directory data by querying a Directory Sync Service cloud-based instance. The directory data is stored with the Directory Sync Service instance using an agent that is installed in the customer’s network.This agent retrieves directory data from the customer’s Active Directory, and then sends it to the cloud-based Directory Sync Service instance.

Parameters:	object_class (str) – Directory object class. json (dict) – Payload/request body. **kwargs – Supported `request()` parameters.
Returns:	Requests Response() object.
Return type:	requests.Response

Examples

Coming soon.

Event Service¶

Interact with the Application Framework Event Service API.

The Event Service allows your application to consume log data using a subscription (pull) model. When a customer activates your application in the Cloud Services Portal, a channel is assigned to it. This channel is dedicated to the customer’s application instance. The channel will contain no data for any other customer, or any other application instance. You will receive this channel’s ID as a part of the process that provisions your app for the customer in Palo Alto Network’s Application Framework.

Examples

Refer to the examples provided with this library.

class pancloud.event.EventService(**kwargs)[source]¶

Bases: object

An Application Framework Event Service Instance.

ack(channel_id=None, **kwargs)[source]¶

Send a read acknowledgment to the service.

Causes the channel’s start position to move to the channel’s current read position.

Parameters:	channel_id (str) – The channel ID. **kwargs – Supported `request()` parameters.
Returns:	Requests Response() object.
Return type:	requests.Response

Examples

Refer to event_ack.py example.

flush(channel_id=None, **kwargs)[source]¶

Discard all existing events from the event channel.

This endpoint removes all events from the channel. Use this endpoint only if you currently have unread events in your channel that you never intend to process.

Parameters:	channel_id (str) – The channel ID. **kwargs – Supported `request()` parameters.
Returns:	Requests Response() object.
Return type:	requests.Response

Examples

Refer to event_flush.py example.

get_filters(channel_id=None, **kwargs)[source]¶

Retrieve the filters currently set on the channel.

Returns filters set using the “Set Filters” endpoint. The response body contains a JSON object with a single field: “filters”. This field provides a JSON array of JSON objects. Each object identifies a log type and a filter.

Parameters:	channel_id (str) – The channel ID. **kwargs – Supported `request()` parameters.
Returns:	Requests Response() object.
Return type:	requests.Response

Examples

Refer to event_get_filters.py example.

nack(channel_id=None, **kwargs)[source]¶

Send a negative read-acknowledgement to the service.

Causes the channel’s read point to move to its previous position prior to the last poll.

Parameters:	channel_id (str) – The channel ID. **kwargs – Supported `request()` parameters.
Returns:	Requests Response() object.
Return type:	requests.Response

Examples

Refer to event_nack.py example.

poll(channel_id=None, json=None, **kwargs)[source]¶

Read one or more events from a channel.

Reads events (log records) from the identified channel. Events are read in chronological order.

Parameters:	channel_id (str) – The channel ID. json (dict) – Payload/request body. **kwargs – Supported `request()` parameters.
Returns:	Requests Response() object.
Return type:	requests.Response

Examples

Refer to event_poll.py example.

set_filters(channel_id=None, json=None, **kwargs)[source]¶

Set one or more filters for the channel.

Configures one or more filters for a channel. The filters specified by this API override any previously-configured filters.

Parameters:	channel_id (str) – The channel ID. json (dict) – Payload/request body. **kwargs – Supported `request()` parameters.
Returns:	Requests Response() object
Return type:	requests.Response

Examples

Refer to event_set_filters.py example.

xpoll(channel_id=None, json=None, ack=False, follow=False, pause=None, **kwargs)[source]¶

Retrieve logType, event entries iteratively in a non-greedy manner.

Generator function to return logType, event entries from poll API request.

Parameters:	channel_id (str) – The channel ID. json (dict) – Payload/request body. ack (bool) – True to acknowledge read. follow (bool) – True to continue polling after channelId empty. pause (float) – Seconds to sleep between poll when follow and channelId empty. **kwargs – Supported `request()` parameters.
Yields:	dictionary with single logType and event entries.

Logging Service¶

Interact with the Application Framework Logging Service API.

The Logging Service is a Palo Alto Networks cloud service which allows for the storage and retrieval of logging data. Any type of textual logging data can be stored in the Logging Service. Palo Alto Networks firewalls and software can write logging data to this service, as can the software and services created by Palo Alto Network’s various partners.

Examples

Refer to the examples provided with this library.

class pancloud.logging.LoggingService(**kwargs)[source]¶

Bases: object

An Application Framework Logging Service Instance.

delete(query_id=None, **kwargs)[source]¶

Delete a query job.

Uses the DELETE HTTP method to delete a query job. After calling this endpoint, it is an error to poll for query results using the queryId specified here.

Parameters:	query_id (str) – Specifies the ID of the query job. **kwargs – Supported `request()` parameters.
Returns:	Requests Response() object.
Return type:	requests.Response

Examples

Refer to logging_query.py example.

iter_poll(query_id=None, sequence_no=None, params=None, **kwargs)[source]¶

Retrieve pages iteratively in a non-greedy manner.

Automatically increments the sequenceNo as it continues to poll for results until the endpoint reports JOB_FINISHED or JOB_FAILED, or an exception is raised by the pancloud library.

Parameters:	params (dict) – Payload/request dictionary. query_id (str) – Specifies the ID of the query job. sequence_no (int) – Specifies the sequenceNo. **kwargs – Supported `request()` parameters.
Yields:	requests.Response – Requests Response() object.

Examples

Refer to logging_iter_poll.py example.

poll(query_id=None, sequence_no=None, params=None, **kwargs)[source]¶

Poll for asynchronous query results.

Continue to poll for results until this endpoint reports JOB_FINISHED or JOB_FAILED. The results of queries can be returned in multiple pages, each of which may contain many log records. Use this endpoint to poll for query result batches, as well as to track query result status.

Parameters:	params (dict) – Payload/request dictionary. query_id (str) – Specifies the ID of the query job. sequence_no (int) – Specifies the sequenceNo. **kwargs – Supported `request()` parameters.
Returns:	Requests Response() object.
Return type:	requests.Response

Examples

Refer to logging_query.py example.

query(json=None, **kwargs)[source]¶

Generate a query that retrieves log records.

Creates a query within the Logging Service that returns 0 or more log records. Query results can be returned in pages, depending on the size of your result set. You can retrieve pages using poll(), iter_poll(), poll_all() or xpoll().

Parameters:	json (dict) – Payload/request body. **kwargs – Supported `request()` parameters.
Returns:	Requests Response() object.
Return type:	requests.Response

Examples

Refer to logging_query.py example.

write(vendor_id=None, log_type=None, json=None, **kwargs)[source]¶

Write log records to the Logging Service.

This API requires a JSON array in its request body, each element of which represents a single log record. Log records are provided as JSON objects. Every log record must include the primary timestamp field that you identified when you registered your app. Every log record must also identify the log type.

Parameters:	vendor_id (str) – Vendor ID. log_type (str) – Log type. json (list) – Payload/request body. **kwargs – Supported `request()` parameters.
Returns:	Requests Response() object.
Return type:	requests.Response

Examples

Refer to logging_write.py example.

xpoll(query_id=None, sequence_no=None, params=None, delete_query=True, **kwargs)[source]¶

Retrieve individual logs iteratively in a non-greedy manner.

Generator function to return individual log entries from poll API request.

Parameters:	params (dict) – Payload/request dictionary. query_id (str) – Specifies the ID of the query job. sequence_no (int) – Specifies the sequenceNo. delete_query (bool) – True for delete, False otherwise. **kwargs – Supported `request()` parameters.
Yields:	dictionary with single log entry.

Credentials¶

Access, store and refresh credentials.

class pancloud.credentials.Credentials(access_token=None, auth_base_url=None, cache_token=True, client_id=None, client_secret=None, developer_token=None, developer_token_url=None, instance_id=None, profile=None, redirect_uri=None, region=None, refresh_token=None, scope=None, storage_adapter=None, storage_params=None, token_url=None, **kwargs)[source]¶

Bases: object

An Application Framework credentials object.

access_token¶: Get access_token.

cache_token¶: Get cache_token setting.

client_id¶: Get client_id.

client_secret¶: Get client_secret.

decode_jwt_payload(access_token=None)[source]¶

Extract payload field from JWT.

Parameters:	access_token (str) – Access token to decode. Defaults to `None`.
Returns:	JSON object that contains the claims conveyed by the JWT.
Return type:	dict

developer_token¶: Get developer token.

fetch_tokens(client_id=None, client_secret=None, code=None, redirect_uri=None, **kwargs)[source]¶

Exchange authorization code for token.

Parameters:	client_id (str) – OAuth2 client ID. Defaults to `None`. client_secret (str) – OAuth2 client secret. Defaults to `None`. code (str) – Authorization code. Defaults to `None`. redirect_uri (str) – Redirect URI. Defaults to `None`.
Returns:	Response from token URL.
Return type:	dict

get_authorization_url(client_id=None, instance_id=None, redirect_uri=None, region=None, scope=None, state=None)[source]¶

Generate authorization URL.

Parameters:	client_id (str) – OAuth2 client ID. Defaults to `None`. instance_id (str) – App Instance ID. Defaults to `None`. redirect_uri (str) – Redirect URI. Defaults to `None`. region (str) – App Region. Defaults to `None`. scope (str) – Permissions. Defaults to `None`. state (str) – UUID to detect CSRF. Defaults to `None`.
Returns:	Auth URL, state
Return type:	str, str

get_credentials()[source]¶

Get read-only credentials.

Returns:	Read-only credentials.
Return type:	class

jwt_exp¶: Get JWT exp.

jwt_is_expired(access_token=None, leeway=0)[source]¶

Validate JWT access token expiration.

Parameters:	access_token (str) – Access token to validate. Defaults to `None`. leeway (float) – Time in seconds to adjust for local clock skew. Defaults to 0.
Returns:	`True` if expired, otherwise `False`.
Return type:	bool

refresh(access_token=None, **kwargs)[source]¶

Refresh access and refresh tokens.

Parameters:	access_token (str) – Access token to refresh. Defaults to `None`.
Returns:	Refreshed access token.
Return type:	str

refresh_token¶: Get refresh_token.

remove_profile(profile)[source]¶

Remove profile from credentials store.

Parameters:	profile (str) – Credentials profile to remove.
Returns:	Return value of self.storage.remove_profile()

revoke_access_token(**kwargs)[source]¶: Revoke access token.

revoke_refresh_token(**kwargs)[source]¶: Revoke refresh token.

write_credentials()[source]¶

Write credentials.

Write credentials to credentials store.

Returns:	Return value of self.storage.write_credentials()

class pancloud.credentials.ReadOnlyCredentials(access_token, client_id, client_secret, refresh_token)¶

Bases: tuple

access_token¶: Alias for field number 0

client_id¶: Alias for field number 1

client_secret¶: Alias for field number 2

refresh_token¶: Alias for field number 3

Storage Adapter¶

Base adapter class.

class pancloud.adapters.adapter.StorageAdapter[source]¶

Bases: abc.ABC

A storage adapter abstract base class.

fetch_credential(credential=None, profile=None)[source]¶

Fetch credential from store.

Parameters:	credential (str) – Credential to fetch. profile (str) – Credentials profile. Defaults to `'default'`.

init_store()[source]¶: Initialize credentials store.

remove_profile(profile=None)[source]¶

Remove profile from store.

Parameters:	profile (str) – Credentials profile to remove.

write_credentials(credentials=None, profile=None, cache_token=None)[source]¶

Write credentials.

Write credentials to store.

Parameters:	cache_token (bool) – If `True`, stores `access_token` in token store. Defaults to `True`. credentials (class) – Read-only credentials. profile (str) – Credentials profile. Defaults to `'default'`.

TinyDB Store¶

TinyDB storage adapter.

class pancloud.adapters.tinydb_adapter.TinyDBStore(**kwargs)[source]¶

Bases: pancloud.adapters.adapter.StorageAdapter

fetch_credential(credential=None, profile=None)[source]¶

Fetch credential from credentials file.

Parameters:	credential (str) – Credential to fetch. profile (str) – Credentials profile. Defaults to `'default'`.
Returns:	Fetched credential or `None`.
Return type:	str, None

init_store()[source]¶: Initialize credentials store.

remove_profile(profile=None)[source]¶

Remove profile from credentials file.

Parameters:	profile (str) – Credentials profile to remove.
Returns:	List of affected document IDs.
Return type:	list

write_credentials(credentials=None, profile=None, cache_token=None)[source]¶

Write credentials.

Write credentials to credentials file. Performs upsert.

Parameters:	cache_token (bool) – If `True`, stores `access_token` in token store. Defaults to `True`. credentials (class) – Read-only credentials. profile (str) – Credentials profile. Defaults to `'default'`.
Returns:	Affected document ID.
Return type:	int

Exceptions¶

Exceptions raised by PAN Cloud library.

This module provides base classes for all errors raised by the PAN Cloud library. All other exceptions are raised and maintained by Python standard or nonstandard libraries.

exception pancloud.exceptions.HTTPError(inst)[source]¶

Bases: pancloud.exceptions.PanCloudError

A pancloud HTTP error occurred.

exception pancloud.exceptions.PanCloudError(message)[source]¶

Bases: exceptions.Exception

Base class for all exceptions raised by PAN Cloud library.

exception pancloud.exceptions.PartialCredentialsError(inst)[source]¶

Bases: pancloud.exceptions.PanCloudError

The required credentials were not supplied.

exception pancloud.exceptions.RequiredKwargsError(kwarg)[source]¶

Bases: pancloud.exceptions.PanCloudError

A required keyword argument was not passed.

exception pancloud.exceptions.UnexpectedKwargsError(kwargs)[source]¶

Bases: pancloud.exceptions.PanCloudError

An unexpected keyword argument was passed.