Metadata-Version: 1.1
Name: pancloud
Version: 1.5.0
Summary: Python idiomatic SDK for the Palo Alto Networks Application Framework.
Home-page: https://github.com/PaloAltoNetworks/pancloud
Author: Steven Serrata
Author-email: sserrata@paloaltonetworks.com
License: ISC license
Description: ===================================
        Palo Alto Networks Cloud Python SDK
        ===================================
        
        Python idiomatic SDK for the Palo Alto Networks Application Framework.
        
        The Palo Alto Networks Cloud Python SDK (or `pancloud` for short) was created to assist developers with
        programmatically interacting with the Palo Alto Networks Application Framework.
        
        The primary goal is to provide full, low-level API coverage for the following Application Framework services:
        
            - Logging Service
            - Directory Sync Service
            - Event Service
        
        The secondary goal is to provide coverage, in the form of helpers, for common tasks/operations.
        
            - Log/event pagination
            - OAuth 2.0 and token refreshing
            - More, coming soon!
        
        * Documentation: https://pancloud.readthedocs.io
        * Free software: ISC license
        
        -----
        
        |requests| |pipenv| |pypi| |travis| |docs|
        
        -----
        
        Features
        --------
        
        - HTTP client wrapper for the popular Requests library with full access to its features.
        - Language bindings for Logging Service, Event Service and Directory Sync Service.
        - Helper methods for performing common tasks, such as log/event pagination.
        - Support for OAuth 2.0 grant code authorization flow.
        - Library of example scripts illustrating how to leverage `pancloud`.
        - Support for API Explorer Developer Tokens (Introduced in v1.5.0).
        
        Status
        ------
        
        The Palo Alto Networks Cloud Python SDK is considered **production/stable** at this time.
        
        Installation
        ------------
        
        From PyPI::
        
            $ pip install pancloud
        
        Install From GitHub
        -------------------
        
        Clone the repo::
        
            $ git clone https://github.com/PaloAltoNetworks/pancloud.git
        
        Use |pipenv| to install all dependencies and create a virtualenv for your project::
        
            $ pipenv install
        
        You can specify which python version to use by adding "--two" or "--three"::
        
            $ pipenv --three install
        
        Activate the pipenv shell::
        
            $ pipenv shell
        
        Obtaining and Using OAuth 2.0 Tokens
        ------------------------------------
        
        Work with your Developer Relations representative to register your
        application and receive the credentials needed to obtain an `access_token`.
        Normally, this requires a `client_id`, `client_secret`, and `refresh_token`.
        API Explorer may optionally be used to generate a Developer Token, which can
        be used in place of the `client_id`, `client_secret`, and `refresh_token`.
        
        For more information visit the following RTD page: `Credentials <https://pancloud.readthedocs.io/en/latest/guides/credentials.html>`__
        
        Example
        -------
        
        The following example assumes valid credentials are present::
        
            $ ./logging_query.py
        
            QUERY: {"queryId":"59801207-9a75-49c1-9f87-a2aa23f55774","sequenceNo":0,"queryStatus":"RUNNING","clientParameters":{},"result":{"esResult":null,"esQuery":{"table":["panw.traffic"],"query":{"aggregations":{},"size":1},"selections":[],"params":{}}}}
        
            JOB_FINISHED: queryId: 59801207-9a75-49c1-9f87-a2aa23f55774, sequenceNo: 0, retrieving from 0, size: 1, took: 117 ms
        
            RESULT: {"queryId":"59801207-9a75-49c1-9f87-a2aa23f55774","sequenceNo":0,"queryStatus":"JOB_FINISHED","clientParameters":{},"result":{"esResult":{"took":117,"hits":{"total":1878954,"maxScore":2,"hits":[{"_index":"117270009_panw.all_2018042400-2018062300_000000","_type":"traffic","_id":"117270009_lcaas:0:149314:0","_score":2,"_source":{"risk-of-app":"4","logset":"ForwardToLoggingService","bytes_received":14882,"natsport":53295,"sessionid":806912,"type":"traffic","parent_start_time":0,"packets":30,"characteristic-of-app":["able-to-transfer-file","has-known-vulnerability","tunnel-other-application","prone-to-misuse","is-saas"],"dg_hier_level_4":0,"dg_hier_level_1":11,"dg_hier_level_3":0,"dg_hier_level_2":0,"action":"allow","recsize":1622,"from":"L3-Trust","parent_session_id":0,"repeatcnt":1,"app":"web-browsing","vsys":"vsys1","nat":1,"technology-of-app":"browser-based","pkts_received":17,"chunks_sent":0,"receive_time":1524893357,"non-standard-dport":443,"subcategory-of-app":"internet-utility","chunks_received":0,"users":"panwdomain\\user1","srcuser":"panwdomain\\user1","proxy":1,"fwd":1,"config_ver":2049,"cloud_hostname":"sample-cft-fw","customer-id":"117270009","proto":"tcp","non_std_dport":1,"tunneled-app":"tunneled-app","is-saas-of-app":0,"natdport":443,"action_source":"from-policy","assoc_id":0,"dst":"66.135.212.201","natdst":"66.135.212.201","chunks":0,"flags":22020208,"rule":"Allow Outbound Browsing","dport":443,"elapsed":0,"sanctioned-state-of-app":0,"inbound_if":"ethernet1/2","device_name":"sample-cft-fw","subtype":"end","time_received":1524893357,"actionflags":-9223372036854776000,"tunnelid_imsi":0,"session_end_reason":"tcp-fin","natsrc":"10.0.0.100","seqno":1633879,"src":"10.0.1.101","start":1524893341,"time_generated":1524893357,"outbound_if":"ethernet1/1","category-of-app":"general-internet","bytes_sent":2152,"srcloc":"10.0.0.0-10.255.255.255","pkts_sent":13,"dstloc":"US","serial":"","bytes":17034,"vsys_id":1,"to":"L3-Untrust","category":"10006","sport":33562,"tunnel":0}}]},"id":"59801207-9a75-49c1-9f87-a2aa23f55774","from":0,"size":1,"completed":true,"state":"COMPLETED","timed_out":false},"esQuery":{"table":["panw.traffic"],"query":{"aggregations":{},"size":1},"selections":[],"params":{}}}}
        
            DELETE: {"success":true}
        
        Contributors
        ------------
        
        - Kevin Steves - `github <https://github.com/kevinsteves>`__
        - Steven Serrata - `github <https://github.com/sserrata>`__
        
        .. |pypi| image:: https://img.shields.io/pypi/pyversions/pancloud.svg
                :target: https://pypi.python.org/pypi/pancloud
        
        .. |travis| image:: https://img.shields.io/travis/PaloAltoNetworks/pancloud.svg
                :target: https://travis-ci.org/PaloAltoNetworks/pancloud
        
        .. |docs| image:: https://readthedocs.org/projects/pancloud/badge/?version=latest
                :target: https://pancloud.readthedocs.io/en/latest/?badge=latest
                :alt: Documentation Status
        
        .. |requests| image:: https://img.shields.io/badge/docs-requests-blue.svg
            :target: http://docs.python-requests.org/en/master
            :alt: Documentation Status
        
        .. |pipenv| image:: https://img.shields.io/badge/docs-pipenv-green.svg
            :target: https://docs.pipenv.org
            :alt: Documentation Status
        
        
        =======
        History
        =======
        
        1.5.0 (2019-02-27)
        ------------------
        
        * Added `flush()` method to `EventService` class.
        * Added `auto_refresh` support to `HTTPClient` `_apply_credentials()` method.
        * Removed `auto_retry` feature from `HTTPClient` class.
        * Refactored `HTTPClient` class `request()` method keyword argument overrides.
        * Removed unused `token_revoke_url` keyword argument.
        * Added support for API Explorer Developer Tokens to `Credentials` class.
        * Refactored `Credentials` `refresh()` method.
        
        1.4.0 (2018-10-04)
        ------------------
        
        * Added default URL to `HTTPClient` class.
        * Updated docstrings for `StorageAdapter`, `TinyDBStore` and `Credentials` classes.
        * Now returning `state` as `str` instead of `UUID` in `get_authorization_url()` method.
        * Now unifying display results for -m/-s/--write. For -m you now need an output specifier (-j/-p) to print the response.
        * Added `decode_jwt_payload()` method to allow for extracting/using all JWT fields.
        * Added -s option to allow for invocation of setter methods. This allows modifying of credential store fields.
        * Added credential setters to allow for modifying credentials.
        * Updated examples.
        * Switched from using `requests` to `HTTPClient` in `Credentials` class.
        * Now checking JWT access_token `exp` to determine if refresh if needed.
        * Now generating a new `state` each time `get_authorization_url()` is called.
        * Added `__repr__` to `Credentials` class with support for masking secrets.
        * Updated -E --ack,nack,poll options usage to be accurate.
        * `JOB_FAILED` response in `xpoll()` queryStatus now includes errorCode.
        
        1.3.0 (2018-08-04)
        ------------------
        
        * Added support for custom read/write credentials path.
        * `TinyDBStore` `fetch_credential()` now returns `None` instead of empty `str`.
        * Fixed bug that caused `_resolve_credential()` to be executed an inefficient number of times.
        * Now updating `HTTPClient` headers instead of overriding them which previously broke HTTP persistence.
        * Added JMESPath `isotime()` function to `summit.py` which prints epoch.
        * Added argument to `EventService` `xpoll()` method to support sleeping between polls.
        * Added `PAN_` prefix to envars to avoid name collisions.
        * Fixed bug when `R['R1_obj']['LoggingService.query']` is None and allow json=None case with special case of --end -1 which will not set a default end of now.
        * Fixed bug that nulled out credentials if an error occurred during a `fetch_tokens()` or `refresh()` operation.
        * Now enforcing strict credential resolution. Previous behavior allowed for merging credentials from different providers.
        * Added support for caching `refresh_token` to support rolling.
        * Added support for writing logs to `summit.py`.
        * Switch from using `data` param to `json` param in client/service methods.
        * Now defaulting `R1` to `None` so don't send body unless specified.
        * Now printing request headers and body at debug level 3 in `summit.py`.
        * Added enhancements to `summit.py` for specifying `startTime` and `endTime`.
        
        1.2.3 (2018-06-21)
        ------------------
        
        * Reversed the `access_token` lookup order in get_credentials() method.
        * Added `_resolve_credential()` to `access_token()` property method to support token caching.
        * Now comparing passed `access_token` in `refresh()` method to value returned by property method.
        
        1.2.2 (2018-06-20)
        ------------------
        
        * Added pancloud.adapters to find_packages include list to resolve issue with PyPI package.
        
        1.2.1 (2018-06-20)
        ------------------
        
        * Added requirements.txt to MANIFEST.in to address build issues with PyPI package.
        * Fixed issue in README.rst that prevented PyPI from properly rendering.
        
        1.2.0 (2018-06-20)
        ------------------
        
        * Updated README.rst
        * Updated RTD API Reference.
        * Added `pancloud` to requirements_dev.txt
        * Added docstrings to `Credentials` property methods.
        * Changed logging xpoll() to return entire log entry instead of just `_source` dictionary.
        * Added `Credentials` Storage Adapter feature and moved `TinyDB` code to `tinydb_adapter.py`, the default storage adapter.
        * Automatically carry `queryId` from `logging --query` response to `--id` in subsequent `--poll`, `--xpoll` and `--delete` in `summit.py`.
        * Various bug fixes and improvements to `summit.py`.
        * Added support for caching `access_token` in credentials store.
        * Added `write()` method to `LoggingService` class to support writing logs.
        * Fixed issues with `Credentials` `get_authorization_url` and `fetch_tokens` methods.
        * Added `logging_write.py` to examples.
        
        1.1.0 (2018-05-08)
        ------------------
        
        * Updated logging `xpoll()` to reflect behavior of current API.
        * Added `credentials.py` module to support OAuth2 operations.
        * Added `auto_refresh` and `auto_retry` support to `HTTPClient()`.
        * Added `PartialCredentialsError` exception to handle cases where incomplete credentials are passed to `Credentials`.
        * Removed extraneous dependencies, e.g. pyopenssl.
        * Cleaned up requirements.txt and PipLock files.
        * Added `TinyDB` package for reading/writing `credentials.json` file.
        * Now raising `PanCloudError` for `enforce_json` errors.
        * Removed logging `poll_all()` method and example script.
        * Now checking if `sequence_no` is `None` before incrementing in logging `iter_poll()` method.
        * Added event `xpoll()` method to support iterating through events.
        * Introducing `summit.py`, a command-line interface for `pancloud`.
        * Added `credentials` support to `summit.py` to enable writing `credentials.json` file and passing `Credentials` with requests.
        * Updated example scripts library to incorporate new credentials feature.
        
        1.0.3 (2018-04-26)
        ------------------
        
        * Overhauled and updated RTDs
        * Updated `__init__.py` to allow package-level imports
        * Fixed issue where starrifying authorization token in `__repr__` overrode value in request header.
        
        1.0.2 (2018-03-20)
        ------------------
        
        * Updated .gitignore to exclude .pytest_cache
        * Excluding certain functions/classes from tests until API Gateway is ready
        * Renamed tests modules to all lowercase
        * Bumped version to 1.0.2 from 1.0.1
        * Updated 'query' and 'poll' endpoints to reflect current working state of APIs
        * Fixed .travis.yml branch regex
        * Updated example scripts
        * Removed pyopenssl property method from HTTPClient
        * Removed test_repr() as not all tested python versions support ordered kwargs
        
        1.0.1 (2018-03-19)
        ------------------
        
        * Default to empty `path`
        
        1.0.0 (2018-03-16)
        ------------------
        
        * First release.
        
Keywords: pancloud
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: ISC License (ISCL)
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
