PyPANRestV2 2.1.0__py3-none-any.whl

pypanrestv2/XDR.py

@@ -0,0 +1,299 @@
+import requests
+from datetime import datetime, timezone
+import secrets
+import string
+import hashlib
+import json
+from requests.packages.urllib3.exceptions import InsecureRequestWarning
+import logging
+
+logger = logging.getLogger(__name__)
+
+# Disable insecure request warnings
+requests.packages.urllib3.disable_warnings(InsecureRequestWarning)
+
+class Cortex:
+    """
+    This class is used to establish a connection with a Cortex XDR tenant.
+    It generates the necessary headers for authentication.
+    """
+    def __init__(self, api_key_id, api_key, base_url, api_version='/public_api/v1'):
+        self.api_key_id = api_key_id
+        self.api_key = api_key
+        self.base_url = base_url
+        self.api_version = api_version
+
+    def generate_header(self):
+        """
+        Generates the authentication header required for Cortex XDR API requests.
+        """
+        nonce = ''.join(secrets.choice(string.ascii_letters + string.digits) for _ in range(64))
+        timestamp = int(datetime.now(timezone.utc).timestamp()) * 1000
+        auth_key = f"{self.api_key}{nonce}{timestamp}".encode("utf-8")
+        api_key_hash = hashlib.sha256(auth_key).hexdigest()
+
+        return {
+            "x-xdr-timestamp": str(timestamp),
+            "x-xdr-nonce": nonce,
+            "x-xdr-auth-id": str(self.api_key_id),
+            "Authorization": api_key_hash
+        }
+
+class XDR_Base:
+    """
+    Base class for XDR interactions. This class initializes a connection session
+    and defines basic GET method functionality for the derived classes.
+    """
+    def __init__(self, cortex_instance, api_name='', **kwargs):
+        self.cortex_instance = cortex_instance
+        self.api_name = api_name
+        self.session = requests.Session()
+        self.call_name = kwargs.get('call_name')
+        self.params = kwargs.get('params')
+
+    def get(self):
+        """
+        Generic GET request to retrieve data from Cortex XDR API.
+        """
+        url = f"{self.cortex_instance.base_url}{self.cortex_instance.api_version}{self.api_name}{self.call_name}"
+        response = self.session.post(url, headers=self.cortex_instance.generate_header(), json=self.params)
+        return json.loads(response.text) if response.status_code == 200 else response.status_code
+
+    def status(self):
+        self.api_name = '/healthcheck/'
+        self.call_name = ''
+        return self.get().get('status')
+
+    def info(self):
+        self.api_name = '/system/'
+        self.call_name = 'get_tenant_info'
+        self.params = {'request_data': {}}
+
+        return self.get()
+class Incidents(XDR_Base):
+    """
+    Class to handle incidents-related interactions with Cortex XDR.
+    """
+    def __init__(self, cortex_instance, **kwargs):
+        super().__init__(cortex_instance, '/incidents', **kwargs)
+
+        self.call_name = ''
+        self.params = kwargs.get('params') or {}
+        self.filter = []
+        self.ALERTFILTER = []
+        self.SEARCH_FROM = kwargs.get('SEARCH_FROM') or 0
+        self.SEARCH_TO = kwargs.get('SEARCH_TO') or 100
+        self.SORT_FIELD = kwargs.get('SORT_FIELD')
+        self.KEYWORD = kwargs.get('KEYWORD') or 'asc'
+
+    def IncidentFilterBuilder(self, FIELD, OPERATOR, VALUELIST):
+        Valid_FilterFields = ['modification_time', 'creation_time', 'incident_id_list', 'description', 'alert_sources',
+                              'status', 'starred']
+        Valid_FilterOperators = ['in', 'gte', 'lte', 'eq', 'neq', 'contains']
+        Valid_status = ['new', 'under_investigation', 'resolved_true_positive', 'resolved_known_issue',
+                        'resolved_duplicate_incident', 'resolved_false_positive', 'resolved_auto_resolve']
+
+        if FIELD not in Valid_FilterFields:
+            raise ValueError(f'{FIELD} is not a valid Field value. Please use one of {Valid_FilterFields}')
+
+        if OPERATOR not in Valid_FilterOperators:
+            raise ValueError(f'{OPERATOR} is not a valid Operator value. Please use one of {Valid_FilterOperators}')
+
+        if OPERATOR == 'in':
+            if FIELD in ['incident_id_list', 'alert_sources', 'description']:
+                if not isinstance(VALUELIST, list):
+                    raise ValueError(f'{VALUELIST} must be a list')
+        elif OPERATOR == 'contains':
+            if FIELD not in ['description']:
+                raise ValueError(f'When using Operator {OPERATOR}, the only valid keywords are [description].')
+        elif OPERATOR in ['gte', 'lte']:
+            if FIELD not in ['modification_time', 'creation_time']:
+                raise ValueError(
+                    f'When using Operator {OPERATOR}, the only valid keywords are [modification_time, creation_time].')
+        elif OPERATOR in ['eq', 'neq']:
+            if FIELD not in ['status']:
+                raise ValueError(f'When using Operator {OPERATOR}, the only valid keywords are [status].')
+            for i in VALUELIST:
+                if i not in Valid_status:
+                    raise ValueError(f'Status must be one of {Valid_status}.')
+
+        self.filter.append({'field': FIELD, 'operator': OPERATOR, 'value': VALUELIST})
+
+    def AlertFilterBuilder(self, FIELD, OPERATOR, VALUELIST):
+        Valid_FilterFields = ['alert_id_list', 'alert_source', 'severity', 'creation_time', 'server_creation_time']
+        Valid_FilterOperators = ['in', 'gte', 'lte']
+        Valid_severity = ['low', 'medium', 'high', 'critical', 'informational']
+
+        if FIELD not in Valid_FilterFields:
+            raise ValueError(f'{FIELD} is not a valid Field value. Please use one of {Valid_FilterFields}')
+
+        if OPERATOR not in Valid_FilterOperators:
+            raise ValueError(f'{OPERATOR} is not a valid Operator value. Please use one of {Valid_FilterOperators}')
+
+        if OPERATOR == 'in':
+            if FIELD == 'alert_id':
+                if not isinstance(FIELD, list):
+                    raise ValueError(f'{FIELD} must be a list')
+            elif FIELD == 'severity':
+                for i in VALUELIST:
+                    if i not in Valid_severity:
+                        raise ValueError(f'{FIELD} must be one of {Valid_severity} but {i} was provided.')
+        elif OPERATOR in ['gte', 'lte']:
+            if FIELD not in ['creation_time']:
+                raise ValueError(f'When using Operator {OPERATOR}, the only valid keywords are [creation_time].')
+        self.ALERTFILTER.append({'field': FIELD, 'operator': OPERATOR, 'value': VALUELIST})
+
+    def GetIncidents(self):
+        self.api_name = '/incidents'
+        self.call_name = '/get_incidents/'
+        self.SORT_FIELD = 'modification_time'
+        self.params = {
+            'request_data': {
+                'search_from': self.SEARCH_FROM,
+                'search_to': self.SEARCH_TO,
+                'sort': {
+                    'field': self.SORT_FIELD,
+                    'keyword': self.KEYWORD
+                },
+                'filters': self.filter
+            }
+        }
+        return self.get()
+
+    def GetAlerts(self):
+        self.api_name = '/alerts'
+        self.call_name = '/get_alerts_multi_events/'
+        self.SORT_FIELD = 'severity'
+        self.params = {
+            'request_data': {
+                'search_from': self.SEARCH_FROM,
+                'search_to': self.SEARCH_TO,
+                'sort': {
+                    'field': self.SORT_FIELD,
+                    'keyword': self.KEYWORD
+                },
+                'filters': self.ALERTFILTER
+            }
+        }
+        return self.get()
+
+class Endpoint(XDR_Base):
+    """
+    Class to handle endpoint-related interactions with Cortex XDR.
+    """
+    def __init__(self, cortex_instance, **kwargs):
+        super().__init__(cortex_instance, '/endpoints', **kwargs)
+
+        self.call_name = ''
+        self.params = kwargs.get('params') or {}
+        self.filter = []
+        self.search_from = kwargs.get('search_from') or 0
+        self.search_to = kwargs.get('search_to') or 100
+        self.sort_field = kwargs.get('sort_field') or 'last_seen'
+        self.keyword = kwargs.get('keyword') or 'asc'
+
+    def get_all(self):
+        self.call_name = '/get_endpoints'
+        return self.get()
+
+    def filter_builder(self, field, operator, valuelist):
+        valid_filter_fields = ['endpoint_id_list', 'endpoint_status', 'dist_name', 'first_seen', 'last_seen', 'ip_list',
+                               'group_name', 'platform', 'alias', 'isolate', 'hostname']
+        valid_filter_operators = ['in', 'gte', 'lte']
+
+        valid_endpoint_status = ['connected', 'disconnected', 'lost', 'uninstalled']
+        valid_platform = ['windows', 'linux', 'macos', 'android']
+        valid_isolate = ['isolated', 'unisolated']
+        valid_scan_status = ['none', 'pending', 'in_progress', 'canceled', 'aborted', 'pending_cancellation',
+                             'success', 'error']
+
+        if field not in valid_filter_fields:
+            raise ValueError(f'{field} is not a valid Field value. Please use one of {valid_filter_fields}')
+
+        if operator not in valid_filter_operators:
+            raise ValueError(f'{operator} is not a valid Operator value. Please use one of {valid_filter_operators}')
+
+        if operator == 'in':
+            if field in ['endpoint_id_list', 'dist_name', 'group_name', 'alias', 'hostname', 'username']:
+                for i in valuelist:
+                    if not isinstance(i, str):
+                        raise ValueError(f'{i} must be a string')
+
+            elif field == 'endpoint_status':
+                for i in valuelist:
+                    if i not in valid_endpoint_status:
+                        raise ValueError(f'{i} must be one of {valid_endpoint_status}')
+            elif field == 'ip_list':
+                for i in valuelist:
+                    if not isinstance(i, str):
+                        # TODO - validate the string is an IP address
+                        raise ValueError(f'{i} must be a string')
+            elif field == 'platform':
+                for i in valuelist:
+                    if i not in valid_platform:
+                        raise ValueError(f'{i} must be one of {valid_platform}')
+            elif field == 'isolate':
+                for i in valuelist:
+                    if i not in valid_isolate:
+                        raise ValueError(f'{i} must be one of {valid_isolate}')
+            elif field == 'scan_status':
+                for i in valuelist:
+                    if i not in valid_scan_status:
+                        raise ValueError(f'{i} must be one of {valid_scan_status}')
+        else:
+            if field not in ['first_seen', 'last_seen']:
+                raise ValueError(
+                    f'When using Operator {operator}, the only valid keywords are [first_seen, last_seen].')
+
+        self.filter.append({'field': field, 'operator': operator, 'value': valuelist})
+
+    def get_endpoint(self):
+        self.call_name = '/get_endpoint'
+        self.params = {
+            'request_data': {
+                'search_from': self.search_from,
+                'search_to': self.search_to,
+                'sort': {
+                    'field': self.sort_field,
+                    'keyword': self.keyword
+                },
+                'filters': self.filter
+            }
+        }
+        return self.get()
+
+    def get_violations(self):
+        self.api_name = '/device_control'
+        self.call_name = '/get_violations'
+        self.params = {
+            'request_data': {
+                'search_from': self.search_from,
+                'search_to': self.search_to,
+                'sort': {
+                    'field': self.sort_field,
+                    'keyword': self.keyword
+                },
+                'filters': self.filter
+            }
+        }
+        return self.get()
+
+def raw_date(date, format):
+    """
+    Taka a date that has a suffix of th, st or rd on a number and remove it.
+    :param date:
+    :return: The date in unixtime
+    """
+    BadDateList = date.split(' ')
+    newDate = []
+    for i in BadDateList:
+        if i.endswith('th'):
+            newDate.append(i.strip('th'))
+        elif i.endswith('st'):
+            newDate.append(i.strip('st'))
+        elif i.endswith('rd'):
+            newDate.append(i.strip('rd'))
+        else:
+            newDate.append(i)
+    GoodDate = datetime.strptime(' '.join(newDate), format)
+    return int(GoodDate.timestamp()) * 1000

pypanrestv2/__init__.py

@@ -0,0 +1,4 @@
+
+
+
+

pypanrestv2-2.1.0.dist-info/METADATA

@@ -0,0 +1,209 @@
+Metadata-Version: 2.1
+Name: PyPANRestV2
+Version: 2.1.0
+Summary: Python tools for interacting with Palo Alto Networks REST API.
+License: MIT
+Author: Mark Rzepa
+Author-email: mark@rzepa.com
+Requires-Python: >=3.11
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: dnspython (>=2.6.1)
+Requires-Dist: icecream (>=2.1.3)
+Requires-Dist: pycountry (>=23.12.11)
+Requires-Dist: python-dotenv (>=1.0.1)
+Requires-Dist: requests (>=2.31.0)
+Requires-Dist: tqdm (>=4.66.2)
+Requires-Dist: validators (>=0.22.0)
+Requires-Dist: xmltodict (>=0.13.0)
+Description-Content-Type: text/markdown
+
+# PyPanRestV2
+
+**PyPanRestV2** is a Python library designed to simplify interactions with Palo Alto Networks firewalls and Panorama via their REST API. It provides a higher level of abstraction, allowing users to manage firewalls and Panorama without needing to construct REST requests manually or work with XML for areas of the firewall configuration that still require it.
+
+---
+
+## Features
+
+- **High-Level Abstraction**: Simplifies interaction with the Palo Alto Networks API.
+- **Support for Firewalls and Panorama**: Manage both individual firewalls and Panorama devices.
+- **REST API Integration**: Allows seamless communication with devices.
+- **Convenient Pythonic Objects**: Intuitive Python objects for interacting with specific sections of Palo Alto firewall configurations.
+
+---
+
+## Installation
+
+To install `PyPanRestV2`, clone the repository and install it as a package:
+
+```bash
+# Clone the repository
+git clone https://github.com/mrzepa/pypanrestv2.git
+
+# Navigate to the project directory
+cd pypanrestv2
+
+# Install the package in development mode
+pip install -e .
+```
+
+This will install the package and all required dependencies automatically. The `-e` flag installs the package in "editable" mode, which is useful if you plan to modify the code or contribute to the project.
+
+---
+
+## Basic Usage
+
+### Import the Required Classes
+Start by importing the necessary classes from the library:
+
+```python
+from pypantrestv2 import Firewall, Panorama
+```
+
+### Connect to a Firewall or Panorama Device
+Create a `Firewall` or `Panorama` object by providing the required connection details:
+
+For a **Firewall**:
+```python
+firewall = Firewall(base_url="192.168.1.1", api_key="12345")
+```
+
+For **Panorama**:
+```python
+panorama = Panorama(base_url="192.168.2.1", username="admin", password="my_password")
+```
+
+### Common Use Cases
+
+#### 1. Managing Security Rules
+```python
+from pypanrestv2.Policies import SecurityRules
+
+# Create a new security rule
+security_rule = SecurityRules(firewall, name='allow_web')
+security_rule.source_zone = ['trust']
+security_rule.destination_zone = ['untrust']
+security_rule.source = ['any']
+security_rule.destination = ['any']
+security_rule.application = ['web-browsing']
+security_rule.service = ['application-default']
+security_rule.action = 'allow'
+security_rule.create()
+
+# Modify an existing rule
+existing_rule = SecurityRules(firewall, name='existing_rule')
+existing_rule.refresh()  # Load current configuration
+existing_rule.action = 'deny'
+existing_rule.update()
+```
+
+#### 2. Managing Address Objects
+```python
+from pypanrestv2.Objects import Addresses
+
+# Create a new address object
+address = Addresses(firewall, name='web_server')
+address.value = '192.168.1.100'
+address.type = 'ip-netmask'
+address.create()
+
+# Get all address objects
+all_addresses = Addresses.get_all(firewall)
+```
+
+#### 3. Working with Panorama Device Groups
+```python
+from pypanrestv2 import Panorama
+
+# Initialize Panorama connection
+panorama = Panorama(base_url='panorama.example.com', api_key='YOUR_API_KEY')
+
+# Add a device to a device group
+device_group = panorama.device_groups.get('Branch_Offices')
+device_group.add_device('serial123')
+```
+
+---
+
+## Repository
+
+Visit the project's GitHub repository for source code, documentation, enhancements, and contributions:
+
+[PyPanRestV2 Repository on GitHub](https://github.com/wellhealthtechnologies/PyPanRestV2.git)
+
+---
+
+## Requirements
+
+- **Python 3.11+** (or higher)
+- **Palo Alto Devices** or Panorama
+- Python modules listed in requirements.txt
+
+---
+
+## API Documentation
+
+The SDK provides access to the following main components:
+
+### Core Modules
+- `Firewall/Panorama`: Base connection and authentication
+- `Policies`: Security rules, NAT rules, and policy management
+- `Objects`: Address objects, service objects, and security profiles
+- `Network`: Interfaces, zones, and routing configuration
+- `Device`: System settings and device management
+
+### Error Handling
+
+The SDK uses custom exceptions for better error handling:
+
+```python
+from pypanrestv2.Exceptions import PANConnectionError, PANConfigError
+
+try:
+    firewall = Firewall(base_url='192.168.1.1', api_key='invalid_key')
+    firewall.test_connection()
+except PANConnectionError as e:
+    print(f'Connection failed: {e}')
+except PANConfigError as e:
+    print(f'Configuration error: {e}')
+```
+
+Common errors and solutions:
+- `PANConnectionError`: Check network connectivity and API credentials
+- `PANConfigError`: Verify object names and configuration values
+- `PANNotFoundError`: Ensure referenced objects exist
+
+## Status and Updates
+
+This SDK is actively maintained and regularly updated to support new PAN-OS versions. While not all API endpoints are implemented, core functionality is stable and production-ready. Check the GitHub repository for the latest updates and supported features.
+
+## Contributing
+
+Contributions are welcome! If you want to report issues, request features, or contribute to the library:
+
+1. Fork the repository.
+2. Create a feature branch: `git checkout -b my-feature`.
+3. Commit your changes: `git commit -m "Add detailed description of changes"`.
+4. Push to the branch: `git push origin my-feature`.
+5. Submit a pull request.
+
+Be sure to check the documentation, if provided, before starting contributions.
+
+---
+
+## License
+
+This project is licensed under the MIT. See the [LICENSE](./https://opensource.org/license/mit) file for details.
+
+---
+
+## Author
+
+Mark Rzepa
+mark@rzepa.com
+
+---
+

pypanrestv2-2.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+pypanrestv2/ApplicationHelper.py,sha256=fRszLlhaJevcECA_fiiDg9CW7bqXm8-1GDThwddVm7k,8486
+pypanrestv2/Base.py,sha256=XIN319xoaMGauI8yqiMmXTzNNcPqT4glAlrkiQPvWes,78763
+pypanrestv2/Device.py,sha256=wvjJlRu07WNZd-QgPIKhl5BX0MRWDQO-FACjwdYScb8,617
+pypanrestv2/Exceptions.py,sha256=jrhXq1JkIZz8mCZ8DViZwx_TThpT-dN5cxsDbMfY-wI,397
+pypanrestv2/Network.py,sha256=-thHyOf7XRQHtVkCTZfvQVQGr2O8d4VW_PEnYtGo2Mg,67894
+pypanrestv2/Objects.py,sha256=zmwf1wkgS13rD66LmQzmwfSSL6LCG8_c-PUibF_G52c,62116
+pypanrestv2/Panorama.py,sha256=8_uGEu236YORE8avXitqXUb9F5y-ujJl907O9XdoKgo,17877
+pypanrestv2/Policies.py,sha256=rsNkYuaPpZQiG-Zqm_NiwrJkYTpceYWegSWq2YqlDkY,31844
+pypanrestv2/XDR.py,sha256=K_am9ipuToadrSpY_C3yPRrQWlY4Xo_P-PeOxVWxL2Y,12386
+pypanrestv2/__init__.py,sha256=VFw4sJIt4Zc0-__eYnksN8Ku9qMhbPpHJEkXMWUiD30,4
+pypanrestv2-2.1.0.dist-info/METADATA,sha256=odLdfa36SEwfNptlCbfOtLVJk_ZmQbIgtz2RgyTLh9I,6191
+pypanrestv2-2.1.0.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
+pypanrestv2-2.1.0.dist-info/RECORD,,

pypanrestv2-2.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 1.9.0
+Root-Is-Purelib: true
+Tag: py3-none-any