PyPANRestV2 2.1.0__tar.gz

pypanrestv2-2.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,186 @@
+# 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/pypanrestv2/ApplicationHelper.py

@@ -0,0 +1,220 @@
+class Operator:
+    def __init__(self, context):
+        self.context = context
+
+    @property
+    def context(self) -> str:
+        return self._context
+
+    @context.setter
+    def context(self, value):
+        if not isinstance(value, str):
+            raise ValueError("Context must be a string.")
+
+
+class PatternMatchOperator(Operator):
+    def __init__(self, context, pattern, qualifier):
+        super().__init__(context)
+        self.pattern = pattern
+        self.qualifier = self.initialize_qualifier(qualifier)
+
+    def initialize_qualifier(self, qualifier):
+        if 'entry' in qualifier:
+            return [{entry['@name']: entry['value']} for entry in qualifier['entry']]
+        return []
+
+    def to_dict(self):
+        return {
+            'type': 'pattern-match',
+            'context': self.context,
+            'pattern': self.pattern,
+            'qualifier': {'entry': self.qualifier},
+        }
+
+
+class GreaterThanOperator(Operator):
+    def __init__(self, context, value, qualifier):
+        super().__init__(context)
+        self.value = value
+        self.validate_value(value)
+        self.qualifier = self.initialize_qualifier(qualifier)
+
+    def validate_value(self, value):
+        if not isinstance(value, int) or not (0 <= value <= 4294967295):
+            raise ValueError("Value must be an integer between 0 and 4294967295.")
+
+    def initialize_qualifier(self, qualifier):
+        if 'entry' in qualifier:
+            return [{entry['@name']: entry['value']} for entry in qualifier['entry']]
+        return []
+
+    def to_dict(self):
+        return {
+            'type': 'greater-than',
+            'context': self.context,
+            'value': self.value,
+            'qualifier': {'entry': self.qualifier},
+        }
+
+
+class LessThanOperator(Operator):
+    def __init__(self, context, value, qualifier):
+        super().__init__(context)
+        self.value = value
+        self.validate_value(value)
+        self.qualifier = self.initialize_qualifier(qualifier)
+
+    def validate_value(self, value):
+        if not isinstance(value, int) or not (0 <= value <= 4294967295):
+            raise ValueError("Value must be an integer between 0 and 4294967295.")
+
+    def initialize_qualifier(self, qualifier):
+        if 'entry' in qualifier:
+            return [{entry['@name']: entry['value']} for entry in qualifier['entry']]
+        return []
+
+    def to_dict(self):
+        return {
+            'type': 'less-than',
+            'context': self.context,
+            'value': self.value,
+            'qualifier': {'entry': self.qualifier},
+        }
+
+
+class EqualToOperator(Operator):
+    def __init__(self, context, position, mask, value):
+        super().__init__(context)
+        self.position = position
+        self.mask = mask
+        self.value = value
+        self.validate_position(position)
+        self.validate_mask(mask)
+        self.validate_value(value)
+
+    def validate_position(self, position):
+        if not isinstance(position, str) or len(position) > 127:
+            raise ValueError("Position must be a string up to 127 characters long.")
+
+    def validate_mask(self, mask):
+        if not isinstance(mask, str) or not re.match(r'^0[xX][0-9A-Fa-f]{8}$', mask):
+            raise ValueError("Mask must be a 4-byte hex value.")
+
+    def validate_value(self, value):
+        if not isinstance(value, str) or len(value) > 10:
+            raise ValueError("Value must be a string up to 10 characters long.")
+
+    def to_dict(self):
+        return {
+            'type': 'equal-to',
+            'context': self.context,
+            'position': self.position,
+            'mask': self.mask,
+            'value': self.value,
+        }
+
+class OrConditionEntry:
+    def __init__(self, name, operator_data):
+        self.validate_name(name)
+        self.name = name
+        self.operator = self.initialize_operator(operator_data)
+
+    def validate_name(self, name):
+        if not isinstance(name, str) or len(name) > 31:
+            raise ValueError("Invalid name in or-condition entry.")
+
+    def initialize_operator(self, operator_data):
+        if not isinstance(operator_data, dict):
+            raise ValueError("Operator data must be a dictionary.")
+
+        operator_type = operator_data.get('type')
+        if operator_type == 'pattern-match':
+            return PatternMatchOperator(context=operator_data.get('context'),
+                                        pattern=operator_data.get('pattern'),
+                                        qualifier=operator_data.get('qualifier'))
+        elif operator_type == 'greater-than':
+            return GreaterThanOperator(context=operator_data.get('context'),
+                                       value=operator_data.get('value'),
+                                       qualifier=operator_data.get('qualifier'))
+        elif operator_type == 'less-than':
+            return GreaterThanOperator(context=operator_data.get('context'),
+                                       value=operator_data.get('value'),
+                                       qualifier=operator_data.get('qualifier'))
+        elif operator_type == 'equal-to':
+            return EqualToOperator(context=operator_data.get('context'),
+                                   position=operator_data.get('position'),
+                                   mask=operator_data.get('mask'),
+                                   value=operator_data.get('value'))
+        else:
+            raise ValueError(f"Unsupported operator type: {operator_type}")
+
+    def to_dict(self):
+        # Convert the OrConditionEntry instance to a dictionary format
+        or_condition_dict = {
+            'name': self.name,
+            # Include operator serialization here once operator.to_dict() is defined
+            'operator': self.operator.to_dict() if self.operator else None,
+        }
+        return or_condition_dict
+
+class AndConditionEntry:
+    def __init__(self, name, or_condition=None):
+        self.validate_name(name)
+        self.name = name
+        self.or_condition = self.initialize_or_condition(or_condition)
+
+    def validate_name(self, name):
+        if not isinstance(name, str) or len(name) > 31:
+            raise ValueError("Invalid name in and-condition entry.")
+        # Ensures the name consists only of allowed characters
+        if not all(char.isalnum() or char in "._-" for char in name):
+            raise ValueError("Name in and-condition entry contains invalid characters.")
+
+    def initialize_or_condition(self, or_condition):
+        if or_condition and 'entry' in or_condition:
+            return [OrConditionEntry(**entry) for entry in or_condition['entry']]
+        return []
+
+    def to_dict(self):
+        # Convert the AndConditionEntry instance to a dictionary format
+        and_condition_dict = {
+            'name': self.name,
+            # Serialize or-condition if it's present
+            'or-condition': {'entry': [condition.to_dict() for condition in self.or_condition] if self.or_condition else None},
+        }
+        return and_condition_dict
+
+
+class SignatureEntry:
+    def __init__(self, name, comment="", scope="protocol-data-unit", order_free="no", and_condition=None):
+        self.validate_name(name)
+        self.name = name
+        self.comment = comment
+        self.scope = self.validate_scope(scope)
+        self.order_free = self.validate_order_free(order_free)
+        self.and_condition = self.initialize_and_condition(and_condition)
+
+    def to_dict(self):
+        # Convert the SignatureEntry instance to a dictionary format suitable for inclusion in self.entry
+        signature_dict = {
+            'name': self.name,
+            'comment': self.comment,
+            'scope': self.scope,
+            'order-free': self.order_free,
+            'and-condition': {'entry': [condition.to_dict() for condition in self.and_condition] if self.and_condition else None},
+        }
+        return signature_dict
+
+    def validate_name(self, name):
+        if not isinstance(name, str) or len(name) > 31 or not all(char.isalnum() or char in "._-" for char in name):
+            raise ValueError("Invalid name for signature entry.")
+
+    def validate_scope(self, scope):
+        if scope not in ["protocol-data-unit", "session"]:
+            raise ValueError("Invalid scope value.")
+        return scope
+
+    def validate_order_free(self, order_free):
+        if order_free not in ["yes", "no"]:
+            raise ValueError("Invalid order-free value.")
+        return order_free