From 192416d3e593e7716bca6c5e95b0cc1cad4c0991 Mon Sep 17 00:00:00 2001 From: Calvin Remsburg Date: Sun, 1 Dec 2024 07:29:42 -0600 Subject: [PATCH] adding documentation --- .../security_services/url_categories.md | 319 ++++++++++++++++++ docs/sdk/index.md | 2 + .../url_categories_models.md | 167 +++++++++ mkdocs.yml | 2 + 4 files changed, 490 insertions(+) create mode 100644 docs/sdk/config/security_services/url_categories.md create mode 100644 docs/sdk/models/security_services/url_categories_models.md diff --git a/docs/sdk/config/security_services/url_categories.md b/docs/sdk/config/security_services/url_categories.md new file mode 100644 index 00000000..d51df5ff --- /dev/null +++ b/docs/sdk/config/security_services/url_categories.md @@ -0,0 +1,319 @@ +# URL Categories Configuration Object + +The `URLCategories` class provides functionality to manage URL category objects in Palo Alto Networks' Strata Cloud +Manager. +URL categories allow you to define custom lists of URLs and categories for use in security policies and profiles. + +## Overview + +URL Categories in Strata Cloud Manager allow you to: + +- Create custom URL categories with lists of URLs +- Define category match patterns +- Organize categories within folders, snippets, or devices +- Apply filtering and management capabilities + +The SDK provides comprehensive error handling and logging capabilities to help troubleshoot issues during URL category +management. + +## Methods + +| Method | Description | +|------------|----------------------------------------------| +| `create()` | Creates a new URL category | +| `get()` | Retrieves a URL category by ID | +| `update()` | Updates an existing URL category | +| `delete()` | Deletes a URL category | +| `list()` | Lists URL categories with optional filtering | +| `fetch()` | Retrieves a single URL category by name | + +## Exceptions + +The SDK uses a hierarchical exception system for error handling: + +### Client Errors (4xx) + +- `InvalidObjectError`: Raised when URL category data is invalid or for invalid response formats +- `MissingQueryParameterError`: Raised when required parameters (folder, name) are empty +- `NotFoundError`: Raised when a URL category doesn't exist +- `AuthenticationError`: Raised for authentication failures +- `AuthorizationError`: Raised for permission issues +- `ConflictError`: Raised when URL category names conflict +- `NameNotUniqueError`: Raised when creating duplicate category names + +### Server Errors (5xx) + +- `ServerError`: Base class for server-side errors +- `APINotImplementedError`: When API endpoint isn't implemented +- `GatewayTimeoutError`: When request times out + +## Creating URL Categories + +The `create()` method allows you to define new URL categories with proper error handling. + +**Example: Creating a URL List Category** + +
+ + + +```python +from scm.client import Scm +from scm.config.security import URLCategories +from scm.exceptions import InvalidObjectError, NameNotUniqueError + +# Initialize client with logging +client = Scm( + client_id="your_client_id", + client_secret="your_client_secret", + tsg_id="your_tsg_id", + log_level="DEBUG" # Enable detailed logging +) + +url_categories = URLCategories(client) + +try: + category_data = { + "name": "blocked_sites", + "description": "Custom blocked URLs", + "type": "URL List", + "list": ["example.com", "test.com"], + "folder": "Texas" + } + + new_category = url_categories.create(category_data) + print(f"Created category: {new_category.name}") + +except NameNotUniqueError as e: + print(f"Category name already exists: {e.message}") +except InvalidObjectError as e: + print(f"Invalid category data: {e.message}") + if e.details: + print(f"Details: {e.details}") +``` + +
+ +## Getting URL Categories + +Use the `get()` method to retrieve a URL category by its ID. + +
+ + + +```python +try: + category_id = "123e4567-e89b-12d3-a456-426655440000" + category = url_categories.get(category_id) + print(f"Category Name: {category.name}") + print(f"Type: {category.type}") + print(f"URLs: {category.list}") + +except NotFoundError as e: + print(f"Category not found: {e.message}") +``` + +
+ +## Updating URL Categories + +The `update()` method allows you to modify existing URL categories using Pydantic models. + +
+ + + +```python +try: + # Fetch existing category as a Pydantic model + blocked_sites = url_categories.fetch(folder='Texas', name='blocked_sites') + + # Update the model's attributes + blocked_sites.description = "Updated blocked sites list" + blocked_sites.list.append("newsite.com") + + # Push changes to the SCM API + updated_category = url_categories.update(blocked_sites) + print(f"Updated category: {updated_category.name}") + print(f"New URL list: {updated_category.list}") + +except NotFoundError as e: + print(f"Category not found: {e.message}") +except InvalidObjectError as e: + print(f"Invalid update data: {e.message}") +``` + +
+ +## Deleting URL Categories + +Use the `delete()` method to remove a URL category. + +
+ + + +```python +try: + category_id = "123e4567-e89b-12d3-a456-426655440000" + url_categories.delete(category_id) + print("Category deleted successfully") + +except NotFoundError as e: + print(f"Category not found: {e.message}") +``` + +
+ +## Listing URL Categories + +The `list()` method retrieves multiple URL categories with optional filtering. You can filter the results using the +following kwargs: + +- `members`: List[str] - Filter by entries within a URL category list + +
+ + + +```python +try: + # List all categories in a folder + categories = url_categories.list(folder="Texas") + + # List categories containing specific URLs + filtered_categories = url_categories.list( + folder="Texas", + members=["example.com", "test.com"] + ) + + # Print the results + for category in categories: + print(f"Name: {category.name}") + print(f"Type: {category.type}") + print(f"URLs: {category.list}") + +except InvalidObjectError as e: + print(f"Invalid filter parameters: {e.message}") +except MissingQueryParameterError as e: + print(f"Missing required parameter: {e.message}") +``` + +
+ +## Fetching URL Categories + +The `fetch()` method retrieves a single URL category by name from a specific container, returning a Pydantic model. + +
+ + + +```python +try: + # Fetch a category by name from a specific folder + category = url_categories.fetch( + name="blocked_sites", + folder="Texas" + ) + print(f"Found category: {category.name}") + print(f"Current URL list: {category.list}") + +except NotFoundError as e: + print(f"Category not found: {e.message}") +except MissingQueryParameterError as e: + print(f"Missing required parameter: {e.message}") +``` + +
+ +## Full Workflow Example + +Here's a complete example demonstrating the full lifecycle of a URL category with proper error handling: + +
+ + + +```python +from scm.client import Scm +from scm.config.security import URLCategories +from scm.exceptions import ( + InvalidObjectError, + NotFoundError, + AuthenticationError, + NameNotUniqueError +) + +try: + # Initialize client with debug logging + client = Scm( + client_id="your_client_id", + client_secret="your_client_secret", + tsg_id="your_tsg_id", + log_level="DEBUG" + ) + + # Initialize URL categories object + url_categories = URLCategories(client) + + try: + # Create new category + category_data = { + "name": "test_category", + "description": "Test URL category", + "type": "URL List", + "list": ["example.com", "test.com"], + "folder": "Texas" + } + + new_category = url_categories.create(category_data) + print(f"Created category: {new_category.name}") + + # Fetch and update the category + try: + fetched_category = url_categories.fetch( + name="test_category", + folder="Texas" + ) + print(f"Found category: {fetched_category.name}") + + # Update the category using Pydantic model + fetched_category.description = "Updated test category" + fetched_category.list.append("newsite.com") + + updated_category = url_categories.update(fetched_category) + print(f"Updated category: {updated_category.name}") + print(f"New URL list: {updated_category.list}") + + except NotFoundError as e: + print(f"Category not found: {e.message}") + + # Clean up + url_categories.delete(new_category.id) + print("Category deleted successfully") + + except NameNotUniqueError as e: + print(f"Category name conflict: {e.message}") + except InvalidObjectError as e: + print(f"Invalid category data: {e.message}") + if e.details: + print(f"Details: {e.details}") + +except AuthenticationError as e: + print(f"Authentication failed: {e.message}") + print(f"Status code: {e.http_status_code}") +``` + +
+ +## Full script examples + +Refer to the [examples](../../../../examples/scm/config/security) directory. + +## Related Models + +- [URLCategoriesCreateModel](../../models/security_services/url_categories_models.md#Overview) +- [URLCategoriesUpdateModel](../../models/security_services/url_categories_models.md#Overview) +- [URLCategoriesResponseModel](../../models/security_services/url_categories_models.md#Overview) \ No newline at end of file diff --git a/docs/sdk/index.md b/docs/sdk/index.md index 96061ef5..ec3c9fb1 100644 --- a/docs/sdk/index.md +++ b/docs/sdk/index.md @@ -21,6 +21,7 @@ configuration objects and data models used to interact with Palo Alto Networks S - [Decryption Profile](config/security_services/decryption_profile.md) - [DNS Security Profile](config/security_services/dns_security_profile.md) - [Security Rule](config/security_services/security_rule.md) + - [URL Categories](config/security_services/url_categories.md) - [Vulnerability Protection Profile](config/security_services/vulnerability_protection_profile.md) - [Wildfire Antivirus Profile](config/security_services/wildfire_antivirus.md) - Data Models @@ -40,6 +41,7 @@ configuration objects and data models used to interact with Palo Alto Networks S - [Decryption Profile Models](models/security_services/decryption_profile_models.md) - [DNS Security Profile Models](models/security_services/dns_security_profile_models.md) - [Security Rule Models](models/security_services/security_rule_models.md) + - [URL Categories Models](models/security_services/url_categories_models.md) - [Vulnerability Protection Profile Models](models/security_services/vulnerability_protection_profile_models.md) - [Wildfire Antivirus Profile Models](models/security_services/wildfire_antivirus_profile_models.md) - [Exceptions](exceptions.md) diff --git a/docs/sdk/models/security_services/url_categories_models.md b/docs/sdk/models/security_services/url_categories_models.md new file mode 100644 index 00000000..f9385131 --- /dev/null +++ b/docs/sdk/models/security_services/url_categories_models.md @@ -0,0 +1,167 @@ +# URL Categories Models + +## Overview + +The URL Categories models provide a structured way to manage URL categories in Palo Alto Networks' Strata Cloud Manager. +These models support both URL List and Category Match types, which can be defined in folders, snippets, or devices. The +models handle validation of inputs and outputs when interacting with the SCM API. + +## Attributes + +| Attribute | Type | Required | Default | Description | +|-------------|---------------------------|----------|----------|------------------------------------------------| +| name | str | Yes | None | Name of the URL category | +| list | List[str] | Yes | None | Lists of URL categories | +| description | str | No | None | Description of the URL category | +| type | URLCategoriesListTypeEnum | No | URL List | Type of URL category (URL List/Category Match) | +| folder | str | No* | None | Folder where category is defined | +| snippet | str | No* | None | Snippet where category is defined | +| device | str | No* | None | Device where category is defined | +| id | UUID | Yes** | None | UUID of the URL category (response only) | + +\* Exactly one container type (folder/snippet/device) must be provided +\** Only required for response model + +## Exceptions + +The URL Categories models can raise the following exceptions during validation: + +- **ValueError**: Raised in several scenarios: + - When multiple container types (folder/snippet/device) are specified + - When no container type is specified for create operations + - When container name pattern validation fails + +## Model Validators + +### Container Type Validation + +For create operations, exactly one container type must be specified: + +
+ + + +```python +from scm.models.security import URLCategoriesCreateModel + +# This will raise a validation error +try: + category = URLCategoriesCreateModel( + name="blocked-sites", + list=["example.com", "test.com"], + folder="Shared", + device="fw01" # Can't specify both folder and device + ) +except ValueError as e: + print(e) # "Exactly one of 'folder', 'snippet', or 'device' must be provided." +``` + +
+ +## Usage Examples + +### Creating a URL List Category + +
+ + + +```python +from scm.config.security import URLCategories + +# Using dictionary +url_list_dict = { + "name": "blocked-sites", + "description": "Blocked websites", + "list": ["example.com", "test.com"], + "type": "URL List", + "folder": "Shared", +} + +url_categories = URLCategories(api_client) +response = url_categories.create(url_list_dict) + +# Using model directly +from scm.models.security import URLCategoriesCreateModel + +url_list = URLCategoriesCreateModel( + name="blocked-sites", + description="Blocked websites", + list=["example.com", "test.com"], + type="URL List", + folder="Shared" +) + +payload = url_list.model_dump(exclude_unset=True) +response = url_categories.create(payload) +``` + +
+ +### Creating a Category Match Category + +
+ + + +```python +# Using dictionary +category_match_dict = { + "name": "social-media", + "description": "Social media categories", + "list": ["social-networking", "personal-sites-and-blogs"], + "type": "Category Match", + "folder": "Shared" +} + +response = url_categories.create(category_match_dict) + +# Using model directly +from scm.models.security import URLCategoriesCreateModel, URLCategoriesListTypeEnum + +category_match = URLCategoriesCreateModel( + name="social-media", + description="Social media categories", + list=["social-networking", "personal-sites-and-blogs"], + type=URLCategoriesListTypeEnum.category_match, + folder="Shared" +) + +payload = category_match.model_dump(exclude_unset=True) +response = url_categories.create(payload) +``` + +
+ +### Updating a URL Category + +
+ + + +```python +# Using dictionary +update_dict = { + "id": "123e4567-e89b-12d3-a456-426655440000", + "name": "blocked-sites-updated", + "description": "Updated blocked websites", + "list": ["example.com", "test.com", "blocked.com"], +} + +response = url_categories.update(update_dict) + +# Using model directly +from scm.models.security import URLCategoriesUpdateModel + +update = URLCategoriesUpdateModel( + id="123e4567-e89b-12d3-a456-426655440000", + name="blocked-sites-updated", + description="Updated blocked websites", + list=["example.com", "test.com", "blocked.com"] +) + +payload = update.model_dump(exclude_unset=True) +response = url_categories.update(payload) +``` + +
\ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index d43447be..7bb7bbca 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -49,6 +49,7 @@ nav: - Decryption Profile: sdk/config/security_services/decryption_profile.md - DNS Security Profile: sdk/config/security_services/dns_security_profile.md - Security Rule: sdk/config/security_services/security_rule.md + - URL Categories: sdk/config/security_services/url_categories.md - Vulnerability Protection Security Profile: sdk/config/security_services/vulnerability_protection_profile.md - Wildfire Anti Virus Security Profile: sdk/config/security_services/wildfire_antivirus.md - Data Models: @@ -70,6 +71,7 @@ nav: - Decryption Profile Models: sdk/models/security_services/decryption_profile_models.md - DNS Security Profile Models: sdk/models/security_services/dns_security_profile_models.md - Security Rule Models: sdk/models/security_services/security_rule_models.md + - URL Categories Models: sdk/models/security_services/url_categories_models.md - Vulnerability Protection Security Profile Models: sdk/config/security_services/vulnerability_protection_profile_models.md - Wildfire Anti Virus Security Profile Models: sdk/models/security_services/wildfire_antivirus_profile_models.md - Exceptions: sdk/exceptions.md