diff --git a/docs/sdk/config/objects/application_filters.md b/docs/sdk/config/objects/application_filters.md new file mode 100644 index 0000000..5a75491 --- /dev/null +++ b/docs/sdk/config/objects/application_filters.md @@ -0,0 +1,369 @@ +# Application Filters Configuration Object + +## Table of Contents + +1. [Overview](#overview) +2. [Core Methods](#core-methods) +3. [Application Filter Model Attributes](#application-filter-model-attributes) +4. [Exceptions](#exceptions) +5. [Basic Configuration](#basic-configuration) +6. [Usage Examples](#usage-examples) + - [Creating Application Filters](#creating-application-filters) + - [Retrieving Application Filters](#retrieving-application-filters) + - [Updating Application Filters](#updating-application-filters) + - [Listing Application Filters](#listing-application-filters) + - [Deleting Application Filters](#deleting-application-filters) +7. [Managing Configuration Changes](#managing-configuration-changes) + - [Performing Commits](#performing-commits) + - [Monitoring Jobs](#monitoring-jobs) +8. [Error Handling](#error-handling) +9. [Best Practices](#best-practices) +10. [Full Script Examples](#full-script-examples) +11. [Related Models](#related-models) + +## Overview + +The `ApplicationFilters` class provides functionality to manage application filter definitions in Palo Alto Networks' +Strata +Cloud Manager. This class inherits from `BaseObject` and provides methods for creating, retrieving, updating, and +deleting +application filters that help organize and filter applications based on various criteria like categories, risk levels, +and behaviors. + +## Core Methods + +| Method | Description | Parameters | Return Type | +|------------|-----------------------------------|----------------------------------------------|-----------------------------------------| +| `create()` | Creates a new filter | `data: Dict[str, Any]` | `ApplicationFiltersResponseModel` | +| `get()` | Retrieves a filter by ID | `object_id: str` | `ApplicationFiltersResponseModel` | +| `update()` | Updates an existing filter | `application: ApplicationFiltersUpdateModel` | `ApplicationFiltersResponseModel` | +| `delete()` | Deletes a filter | `object_id: str` | `None` | +| `list()` | Lists filters with filtering | `folder: str`, `**filters` | `List[ApplicationFiltersResponseModel]` | +| `fetch()` | Gets filter by name and container | `name: str`, `folder: str` | `ApplicationFiltersResponseModel` | + +## Application Filter Model Attributes + +| Attribute | Type | Required | Description | +|-----------------------------|-----------|----------|---------------------------------------------| +| `name` | str | Yes | Name of filter (max 31 chars) | +| `id` | UUID | Yes* | Unique identifier (*response only) | +| `category` | List[str] | No | List of application categories | +| `sub_category` | List[str] | No | List of application subcategories | +| `technology` | List[str] | No | List of application technologies | +| `risk` | List[int] | No | List of risk levels (1-5) | +| `folder` | str | Yes** | Folder location (**one container required) | +| `snippet` | str | Yes** | Snippet location (**one container required) | +| `evasive` | bool | No | Filter evasive applications | +| `used_by_malware` | bool | No | Filter malware-associated apps | +| `transfers_files` | bool | No | Filter file-transferring apps | +| `has_known_vulnerabilities` | bool | No | Filter apps with vulnerabilities | +| `tunnels_other_apps` | bool | No | Filter tunneling applications | +| `prone_to_misuse` | bool | No | Filter misuse-prone applications | +| `pervasive` | bool | No | Filter pervasive applications | +| `is_saas` | bool | No | Filter SaaS applications | +| `new_appid` | bool | No | Filter new applications | +| `saas_risk` | List[str] | No | Filter by SaaS risk levels | +| `saas_certifications` | List[str] | No | Filter by SaaS certifications | + +## Exceptions + +| Exception | HTTP Code | Description | +|------------------------------|-----------|-------------------------------| +| `InvalidObjectError` | 400 | Invalid filter data or format | +| `MissingQueryParameterError` | 400 | Missing required parameters | +| `NameNotUniqueError` | 409 | Filter name already exists | +| `ObjectNotPresentError` | 404 | Filter not found | +| `ReferenceNotZeroError` | 409 | Filter still referenced | +| `AuthenticationError` | 401 | Authentication failed | +| `ServerError` | 500 | Internal server error | + +## Basic Configuration + +
+ + + +```python +from scm.client import Scm +from scm.config.objects import ApplicationFilters + +# Initialize client +client = Scm( + client_id="your_client_id", + client_secret="your_client_secret", + tsg_id="your_tsg_id" +) + +# Initialize ApplicationFilters object +app_filters = ApplicationFilters(client) +``` + +
+ +## Usage Examples + +### Creating Application Filters + +
+ + + +```python +# High-risk applications filter +high_risk_filter = { + "name": "high-risk-apps", + "category": ["business-systems", "collaboration"], + "risk": [4, 5], + "folder": "Texas", + "has_known_vulnerabilities": True, + "used_by_malware": True +} + +# Create high-risk filter +high_risk = app_filters.create(high_risk_filter) + +# SaaS applications filter +saas_filter = { + "name": "saas-apps", + "folder": "Texas", + "is_saas": True, + "saas_risk": ["high", "medium"], + "saas_certifications": ["soc2", "iso27001"] +} + +# Create SaaS filter +saas = app_filters.create(saas_filter) +``` + +
+ +### Retrieving Application Filters + +
+ + + +```python +# Fetch by name and folder +filter_obj = app_filters.fetch(name="high-risk-apps", folder="Texas") +print(f"Found filter: {filter_obj.name}") + +# Get by ID +filter_by_id = app_filters.get(filter_obj.id) +print(f"Retrieved filter: {filter_by_id.name}") +print(f"Risk levels: {filter_by_id.risk}") +``` + +
+ +### Updating Application Filters + +
+ + + +```python +# Fetch existing filter +existing_filter = app_filters.fetch(name="high-risk-apps", folder="Texas") + +# Update filter criteria +existing_filter.risk = [3, 4, 5] +existing_filter.category.append("networking") +existing_filter.prone_to_misuse = True +existing_filter.tunnels_other_apps = True + +# Perform update +updated_filter = app_filters.update(existing_filter) +``` + +
+ +### Listing Application Filters + +
+ + + +```python +# List with direct filter parameters +filtered_results = app_filters.list( + folder='Texas', + category=['business-systems'], + risk=[4, 5] +) + +# Process results +for filter_obj in filtered_results: + print(f"Name: {filter_obj.name}") + print(f"Categories: {filter_obj.category}") + print(f"Risk levels: {filter_obj.risk}") + +# Define filter parameters as dictionary +list_params = { + "folder": "Texas", + "technology": ["client-server"], + "subcategory": ["database"] +} + +# List with filters as kwargs +filtered_results = app_filters.list(**list_params) +``` + +
+ +### Deleting Application Filters + +
+ + + +```python +# Delete by ID +filter_id = "123e4567-e89b-12d3-a456-426655440000" +app_filters.delete(filter_id) +``` + +
+ +## Managing Configuration Changes + +### Performing Commits + +
+ + + +```python +# Prepare commit parameters +commit_params = { + "folders": ["Texas"], + "description": "Updated application filters", + "sync": True, + "timeout": 300 # 5 minute timeout +} + +# Commit the changes +result = app_filters.commit(**commit_params) + +print(f"Commit job ID: {result.job_id}") +``` + +
+ +### Monitoring Jobs + +
+ + + +```python +# Get status of specific job +job_status = app_filters.get_job_status(result.job_id) +print(f"Job status: {job_status.data[0].status_str}") + +# List recent jobs +recent_jobs = app_filters.list_jobs(limit=10) +for job in recent_jobs.data: + print(f"Job {job.id}: {job.type_str} - {job.status_str}") +``` + +
+ +## Error Handling + +
+ + + +```python +from scm.exceptions import ( + InvalidObjectError, + MissingQueryParameterError, + NameNotUniqueError, + ObjectNotPresentError, + ReferenceNotZeroError +) + +try: + # Create filter configuration + filter_config = { + "name": "test-filter", + "category": ["business-systems"], + "risk": [4, 5], + "folder": "Texas", + "has_known_vulnerabilities": True + } + + # Create the filter + new_filter = app_filters.create(filter_config) + + # Commit changes + result = app_filters.commit( + folders=["Texas"], + description="Added test filter", + sync=True + ) + + # Check job status + status = app_filters.get_job_status(result.job_id) + +except InvalidObjectError as e: + print(f"Invalid filter data: {e.message}") +except NameNotUniqueError as e: + print(f"Filter name already exists: {e.message}") +except ObjectNotPresentError as e: + print(f"Filter not found: {e.message}") +except ReferenceNotZeroError as e: + print(f"Filter still in use: {e.message}") +except MissingQueryParameterError as e: + print(f"Missing parameter: {e.message}") +``` + +
+ +## Best Practices + +1. **Filter Definition** + - Use descriptive filter names + - Combine multiple criteria effectively + - Keep filters focused and specific + - Document filter purposes + - Review and update regularly + +2. **Container Management** + - Always specify exactly one container (folder or snippet) + - Use consistent container names + - Validate container existence + - Group related filters + +3. **Performance** + - Avoid overly broad filters + - Use specific criteria combinations + - Consider filter evaluation impact + - Cache frequently used filters + - Monitor filter match counts + +4. **Security** + - Regularly review risk criteria + - Update vulnerability flags + - Monitor malware associations + - Track certification status + - Validate SaaS risks + +5. **Maintenance** + - Review filter effectiveness + - Update criteria as needed + - Remove unused filters + - Document filter changes + - Monitor filter usage + +## Full Script Examples + +Refer to +the [application_filters.py example](https://github.com/cdot65/pan-scm-sdk/blob/main/examples/scm/config/objects/application_filters.py). + +## Related Models + +- [ApplicationFiltersCreateModel](../../models/objects/application_filters_models.md#Overview) +- [ApplicationFiltersUpdateModel](../../models/objects/application_filters_models.md#Overview) +- [ApplicationFiltersResponseModel](../../models/objects/application_filters_models.md#Overview) diff --git a/docs/sdk/config/objects/index.md b/docs/sdk/config/objects/index.md index 801d9a4..2edb704 100644 --- a/docs/sdk/config/objects/index.md +++ b/docs/sdk/config/objects/index.md @@ -5,6 +5,7 @@ This section covers the configuration objects provided by the `pan-scm-sdk`: - [Address](address.md) - [Address Group](address_group.md) - [Application](application.md) +- [Application Filters](application_filters.md) - [Application Group](application_group.md) - [Service](service.md) @@ -27,6 +28,10 @@ Manage groups of address objects, supporting both static and dynamic membership. Manage application definitions, including their characteristics and associated ports. +### [Application Filters](application_filters.md) + +Manage application filters definitions, including their characteristics and associated members. + ### [Application Group](application_group.md) Manage application group definitions, including their characteristics and associated members. diff --git a/docs/sdk/config/security_services/index.md b/docs/sdk/config/security_services/index.md index 4d5c61d..2189b04 100644 --- a/docs/sdk/config/security_services/index.md +++ b/docs/sdk/config/security_services/index.md @@ -47,6 +47,12 @@ Configure DNS Security profiles to protect against: - Fast-flux DNS attacks - Known malicious domains +### [URL Categories](url_categories.md) + +Manage URL Categories to: + +- Create custom URL categories + ### [Vulnerability Protection Profile](vulnerability_protection_profile.md) Manage Vulnerability Protection profiles to: diff --git a/docs/sdk/index.md b/docs/sdk/index.md index 8942fbf..c155ee5 100644 --- a/docs/sdk/index.md +++ b/docs/sdk/index.md @@ -13,6 +13,7 @@ configuration objects and data models used to interact with Palo Alto Networks S - [Address](config/objects/address.md) - [Address Group](config/objects/address_group.md) - [Application](config/objects/application.md) + - [Application Filters](config/objects/application_filters.md) - [Application Group](config/objects/application_group.md) - [Service](config/objects/service.md) - [Service Group](config/objects/service_group.md) @@ -30,6 +31,7 @@ configuration objects and data models used to interact with Palo Alto Networks S - [Address Models](models/objects/address_models.md) - [Address Group Models](models/objects/address_group_models.md) - [Application Models](models/objects/application_models.md) + - [Application Filters Models](models/objects/application_filters_models.md) - [Application Group Models](models/objects/application_group_models.md) - [Service Models](models/objects/service_models.md) - [Service Group Models](models/objects/service_group_models.md) diff --git a/docs/sdk/models/objects/application_filters_models.md b/docs/sdk/models/objects/application_filters_models.md new file mode 100644 index 0000000..0cc30c6 --- /dev/null +++ b/docs/sdk/models/objects/application_filters_models.md @@ -0,0 +1,354 @@ +# Application Filters Models + +## Table of Contents + +1. [Overview](#overview) +2. [Core Methods](#core-methods) +3. [Application Filters Model Attributes](#application-filters-model-attributes) +4. [Exceptions](#exceptions) +5. [Basic Configuration](#basic-configuration) +6. [Usage Examples](#usage-examples) + - [Creating Application Filters](#creating-application-filters) + - [Retrieving Application Filters](#retrieving-application-filters) + - [Updating Application Filters](#updating-application-filters) + - [Listing Application Filters](#listing-application-filters) + - [Deleting Application Filters](#deleting-application-filters) +7. [Managing Configuration Changes](#managing-configuration-changes) +8. [Monitoring Jobs](#monitoring-jobs) +9. [Error Handling](#error-handling) +10. [Best Practices](#best-practices) +11. [Related Models](#related-models) + +## Overview + +The Application Filters models provide a structured way to manage application filters in Palo Alto Networks' Strata +Cloud Manager. +These models support filtering applications based on various criteria including categories, technologies, risk levels, +and behavioral +characteristics. + +## Core Methods + +| Method | Description | Parameters | Return Type | +|------------|------------------------------|-----------------------------------------|-----------------------------------------| +| `create()` | Creates a new filter | `data: Dict[str, Any]` | `ApplicationFiltersResponseModel` | +| `get()` | Retrieves a filter by ID | `object_id: str` | `ApplicationFiltersResponseModel` | +| `update()` | Updates an existing filter | `filter: ApplicationFiltersUpdateModel` | `ApplicationFiltersResponseModel` | +| `delete()` | Deletes a filter | `object_id: str` | `None` | +| `list()` | Lists filters with filtering | `folder: str`, `**filters` | `List[ApplicationFiltersResponseModel]` | + +## Application Filters Model Attributes + +| Attribute | Type | Required | Description | +|-----------------------------|-----------|----------|----------------------------------------------| +| `name` | str | Yes | Name of filter (max 31 chars) | +| `id` | UUID | No* | Unique identifier (*response only) | +| `category` | List[str] | No | List of application categories | +| `sub_category` | List[str] | No | List of application subcategories | +| `technology` | List[str] | No | List of technologies | +| `risk` | List[int] | No | List of risk levels | +| `evasive` | bool | No | Filter for evasive applications | +| `used_by_malware` | bool | No | Filter for applications used by malware | +| `transfers_files` | bool | No | Filter for file transfer applications | +| `has_known_vulnerabilities` | bool | No | Filter for applications with vulnerabilities | +| `tunnels_other_apps` | bool | No | Filter for tunneling applications | +| `prone_to_misuse` | bool | No | Filter for applications prone to misuse | +| `pervasive` | bool | No | Filter for pervasive applications | +| `is_saas` | bool | No | Filter for SaaS applications | +| `new_appid` | bool | No | Filter for applications with new AppID | +| `saas_certifications` | List[str] | No | Filter by SaaS certifications | +| `saas_risk` | List[str] | No | Filter by SaaS risk levels | +| `folder` | str | Yes** | Folder location (**one container required) | +| `snippet` | str | Yes** | Snippet location (**one container required) | + +\* Optional in create/update operations, required in response +\** Exactly one container type (folder/snippet) must be provided + +## Exceptions + +The Application Filters models can raise the following exceptions during validation: + +- **ValueError**: Raised in several scenarios: + - When multiple container types (folder/snippet) are specified + - When no container type is specified for create operations + - When invalid values are provided for boolean fields + - When list fields contain invalid or duplicate values + +## Basic Configuration + +
+ + + +```python +from scm.client import Scm +from scm.config.objects import ApplicationFilters + +# Initialize client +client = Scm( + client_id="your_client_id", + client_secret="your_client_secret", + tsg_id="your_tsg_id" +) + +# Initialize ApplicationFilters object +app_filters = ApplicationFilters(client) +``` + +
+ +## Usage Examples + +### Creating Application Filters + +
+ + + +```python +# Basic filter configuration +basic_filter = { + "name": "high-risk-apps", + "risk": [4, 5], + "has_known_vulnerabilities": True, + "folder": "Security" +} + +# Create basic filter +basic_filter_obj = app_filters.create(basic_filter) + +# Advanced filter configuration +saas_filter = { + "name": "risky-saas", + "is_saas": True, + "category": ["collaboration", "file-sharing"], + "risk": [3, 4, 5], + "transfers_files": True, + "folder": "Cloud" +} + +# Create SaaS filter +saas_filter_obj = app_filters.create(saas_filter) +``` + +
+ +### Retrieving Application Filters + +
+ + + +```python +# Fetch by ID +filter_id = "123e4567-e89b-12d3-a456-426655440000" +filter_obj = app_filters.get(filter_id) +print(f"Retrieved filter: {filter_obj.name}") + +# Fetch by name and folder +filter_obj = app_filters.fetch(name="high-risk-apps", folder="Security") +print(f"Found filter: {filter_obj.name}") +print(f"Risk levels: {filter_obj.risk}") +print(f"Has vulnerabilities: {filter_obj.has_known_vulnerabilities}") +``` + +
+ +### Updating Application Filters + +
+ + + +```python +# Update filter configuration +update_filter = { + "id": "123e4567-e89b-12d3-a456-426655440000", + "name": "high-risk-apps-updated", + "risk": [3, 4, 5], + "has_known_vulnerabilities": True, + "used_by_malware": True +} + +# Perform update +updated_filter = app_filters.update(update_filter) +``` + +
+ +### Listing Application Filters + +
+ + + +```python +# List all filters in a folder +all_filters = app_filters.list(folder="Security") + +# Process results +for filter_obj in all_filters: + print(f"Name: {filter_obj.name}") + if filter_obj.risk: + print(f"Risk levels: {filter_obj.risk}") + if filter_obj.category: + print(f"Categories: {', '.join(filter_obj.category)}") + +# List with specific criteria +saas_filters = app_filters.list( + folder="Cloud", + is_saas=True, + transfers_files=True +) + +# List with multiple filter parameters +high_risk_filters = app_filters.list( + folder="Security", + risk=[4, 5], + has_known_vulnerabilities=True +) +``` + +
+ +### Deleting Application Filters + +
+ + + +```python +# Delete by ID +filter_id = "123e4567-e89b-12d3-a456-426655440000" + +try: + app_filters.delete(filter_id) + print(f"Successfully deleted filter {filter_id}") +except ObjectNotPresentError: + print("Filter not found") +except ReferenceNotZeroError: + print("Filter is still referenced by security policies") +``` + +
+ +## Managing Configuration Changes + +### Performing Commits + +
+ + + +```python +# Prepare commit parameters +commit_params = { + "folders": ["Security", "Cloud"], + "description": "Updated application filters", + "sync": True, + "timeout": 300 # 5 minute timeout +} + +# Commit the changes +try: + result = app_filters.commit(**commit_params) + print(f"Commit job ID: {result.job_id}") +except CommitInProgressError: + print("Another commit is already in progress") +except CommitFailedError as e: + print(f"Commit failed: {str(e)}") +``` + +
+ +### Monitoring Jobs + +
+ + + +```python +# Get status of specific job +job_status = app_filters.get_job_status(result.job_id) +print(f"Job status: {job_status.data[0].status_str}") + +# List recent jobs +recent_jobs = app_filters.list_jobs(limit=10) +for job in recent_jobs.data: + print(f"Job {job.id}: {job.type_str} - {job.status_str}") + +# Wait for job completion +try: + app_filters.wait_for_job(result.job_id, timeout=300) + print("Configuration changes applied successfully") +except JobTimeoutError: + print("Job timed out waiting for completion") +except JobFailedError as e: + print(f"Job failed: {str(e)}") +``` + +## Error Handling + +
+ + + +```python +from scm.models.objects import ApplicationFiltersCreateModel + +try: + # This will raise a validation error + invalid_filter = ApplicationFiltersCreateModel( + name="invalid-filter", + risk=[6], # Invalid risk level + folder="Security", + snippet="MySnippet" # Can't specify both folder and snippet + ) +except ValueError as e: + print(f"Validation error: {str(e)}") + +try: + # This will raise a validation error for missing container + invalid_filter = ApplicationFiltersCreateModel( + name="invalid-filter", + risk=[3, 4] + # No folder or snippet specified + ) +except ValueError as e: + print(f"Validation error: {str(e)}") +``` + +
+ +## Best Practices + +1. **Filter Design** + - Use descriptive filter names + - Combine multiple criteria effectively + - Keep filters focused and specific + - Document filter purposes + - Review and update regularly + +2. **Container Management** + - Always specify exactly one container (folder or snippet) + - Use consistent container names + - Validate container existence + - Group related filters + +3. **Performance** + - Avoid overly broad filters + - Use specific criteria when possible + - Consider impact on policy processing + - Monitor filter match rates + +4. **Security** + - Regularly review high-risk filters + - Monitor new application matches + - Update risk criteria periodically + - Document security implications + +## Related Models + +- [ApplicationFiltersCreateModel](../../models/objects/application_filters_models.md#Overview) +- [ApplicationFiltersUpdateModel](../../models/objects/application_filters_models.md#Overview) +- [ApplicationFiltersResponseModel](../../models/objects/application_filters_models.md#Overview) \ No newline at end of file diff --git a/docs/sdk/models/objects/index.md b/docs/sdk/models/objects/index.md index 0cba81c..23f08ef 100644 --- a/docs/sdk/models/objects/index.md +++ b/docs/sdk/models/objects/index.md @@ -19,6 +19,7 @@ For each configuration object, there are corresponding request and response mode - [Address Models](address_models.md) - [Address Group Models](address_group_models.md) - [Application Models](application_models.md) +- [Application Filters Models](application_filters_models.md) - [Application Group Models](application_group_models.md) - [Service Models](service_models.md) - [Service Group Models](service_group_models.md) diff --git a/docs/sdk/models/security_services/index.md b/docs/sdk/models/security_services/index.md index 2996d7c..bbf3d3c 100644 --- a/docs/sdk/models/security_services/index.md +++ b/docs/sdk/models/security_services/index.md @@ -20,5 +20,6 @@ For each configuration object, there are corresponding request and response mode - [Decryption Profile Models](decryption_profile_models.md) - [DNS Security Profile Models](dns_security_profile_models.md) - [Security Rule Models](security_rule_models.md) +- [URL Categories Models](url_categories_models.md) - [Vulnerability Protection Profile Models](vulnerability_protection_profile_models.md) - [Wildfire Antivirus Security Profile Models](wildfire_antivirus_profile_models.md)