pan-scm-cli 0.3.2__tar.gz → 0.4.0__tar.gz

pan_scm_cli-0.4.0/PKG-INFO

@@ -0,0 +1,710 @@
+Metadata-Version: 2.3
+Name: pan-scm-cli
+Version: 0.4.0
+Summary: CICD and Network Engineer-friendly CLI tool for Palo Alto Networks Strata Cloud Manager
+Author: Calvin Remsburg
+Author-email: dev@cdot.io
+Requires-Python: >=3.12,<3.14
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: dynaconf (>=3.2.11,<4.0.0)
+Requires-Dist: pan-scm-sdk (==0.3.40)
+Requires-Dist: pydantic (>=2.11.5,<3.0.0)
+Requires-Dist: pyyaml (>=6.0.2,<7.0.0)
+Requires-Dist: typer (>=0.15.4,<0.16.0)
+Description-Content-Type: text/markdown
+
+# Strata Cloud Manager CLI
+
+[![PyPI version](https://badge.fury.io/py/pan-scm-cli.svg)](https://badge.fury.io/py/pan-scm-cli)
+[![Python versions](https://img.shields.io/pypi/pyversions/pan-scm-cli.svg)](https://pypi.org/project/pan-scm-cli/)
+[![License](https://img.shields.io/github/license/cdot65/pan-scm-cli.svg)](https://github.com/cdot65/pan-scm-cli/blob/main/LICENSE)
+
+A command-line interface for managing Palo Alto Networks Strata Cloud Manager (SCM) configurations. This tool simplifies the management of security policies, objects, and configurations through an intuitive CLI.
+
+## Quick Start
+
+```bash
+# Install
+pip install pan-scm-cli
+
+# Set credentials
+export SCM_CLIENT_ID="your_client_id"
+export SCM_CLIENT_SECRET="your_client_secret"
+export SCM_TSG_ID="your_tsg_id"
+
+# Create an address object
+scm set objects address --folder Texas --name web-server --ip-netmask 10.1.1.100/32 --description "Web server"
+
+# List all addresses
+scm show objects address --folder Texas
+
+# Create a security rule
+scm set security rule --folder Texas --name allow-web \
+  --source-zones trust --destination-zones dmz \
+  --source-addresses any --destination-addresses web-server \
+  --services any --action allow
+```
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Getting Started](#getting-started)
+- [Common Use Cases](#common-use-cases)
+- [Command Reference](#command-reference)
+- [Advanced Features](#advanced-features)
+- [Troubleshooting](#troubleshooting)
+- [Contributing](#contributing)
+
+## Key Features
+
+- **Comprehensive Object Management**: Create, update, and delete security configurations
+- **Bulk Operations**: Import/export configurations using YAML files
+- **Smart Updates**: Automatically handles existing objects without errors
+- **Container Support**: Work with folders, snippets, and devices
+- **Mock Mode**: Test commands without making API calls
+- **Input Validation**: Prevents errors before they reach the API
+
+## Installation
+
+### Requirements
+
+- Python 3.10 or higher
+- An active Strata Cloud Manager account
+
+### Install via pip
+
+```bash
+pip install pan-scm-cli
+```
+
+## Getting Started
+
+### 1. Set Up Authentication
+
+Choose one of these methods to configure your credentials:
+
+#### Option A: Context-based Authentication (Recommended for Multiple Tenants)
+
+```bash
+# Create a context for each SCM tenant
+$ scm context create production \
+  --client-id "prod-app@123456789.iam.panserviceaccount.com" \
+  --client-secret "your-secret-key" \
+  --tsg-id "123456789"
+✓ Context 'production' created successfully
+✓ Context 'production' set as current
+
+# Create another context (with custom log level)
+$ scm context create development \
+  --client-id "dev-app@987654321.iam.panserviceaccount.com" \
+  --client-secret "your-dev-secret" \
+  --tsg-id "987654321" \
+  --log-level DEBUG
+✓ Context 'development' created successfully
+
+# View all available contexts
+$ scm context list
+                       SCM Authentication Contexts                        
+┏━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+┃ Context     ┃ Current ┃ Client ID                                       ┃
+┡━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
+│ production  │ ✓       │ prod-app@1...@123456789.iam.panserviceaccount.com │
+│ development │         │ dev-app@98...@987654321.iam.panserviceaccount.com │
+└─────────────┴─────────┴────────────────────────────────────────────────────┘
+
+# Show details of a specific context
+$ scm context show production
+Context: production
+
+Configuration:
+  Client ID: prod-app@123456789.iam.panserviceaccount.com
+  TSG ID: 123456789
+  Log Level: INFO
+  Client Secret: ***** (configured)
+
+# Switch between contexts
+$ scm context use development
+✓ Switched to context 'development'
+
+Client ID: dev-app@987654321.iam.panserviceaccount.com
+TSG ID: 987654321
+
+# Check current context
+$ scm context current
+Current context: development
+
+Client ID: dev-app@987654321.iam.panserviceaccount.com
+TSG ID: 987654321
+```
+
+#### Option B: Environment Variables (For CI/CD and Automation)
+
+```bash
+export SCM_CLIENT_ID="your_client_id"
+export SCM_CLIENT_SECRET="your_client_secret"
+export SCM_TSG_ID="your_tenant_service_group_id"
+```
+
+**Note:** Environment variables take precedence over contexts when both are set.
+
+### 2. Verify Your Setup
+
+```bash
+# Test current context authentication
+$ scm context test
+Testing authentication for context: development
+✓ Authentication successful!
+  Client ID: dev-app@987654321.iam.panserviceaccount.com
+  TSG ID: 987654321
+✓ API connectivity verified (found 42 address objects in Shared folder)
+
+# Test a specific context without switching
+$ scm context test production
+Testing authentication for context: production
+✓ Authentication successful!
+  Client ID: prod-app@123456789.iam.panserviceaccount.com
+  TSG ID: 123456789
+✓ API connectivity verified (found 15 address objects in Shared folder)
+
+# Test without API calls (mock mode)
+$ scm context test --mock
+Testing authentication for context: development
+✓ Authentication simulation successful (mock mode)
+  Client ID: dev-app@987654321.iam.panserviceaccount.com
+  TSG ID: 987654321
+```
+
+### 3. Try Your First Commands
+
+```bash
+# Create a tag
+scm set objects tag --folder Texas --name production --color Red --comments "Production resources"
+
+# Create an address
+scm set objects address --folder Texas --name web-server --ip-netmask 10.1.1.100/32
+
+# List all addresses
+scm show objects address --folder Texas
+```
+
+## Common Use Cases
+
+### Managing Network Objects
+
+#### Create Address Objects
+
+```bash
+# Single IP address
+scm set objects address --folder Texas --name web-server-1 --ip-netmask 10.1.1.100/32 --description "Production web server"
+
+# Subnet
+scm set objects address --folder Texas --name dmz-subnet --ip-netmask 10.0.0.0/24 --description "DMZ network"
+
+# FQDN
+scm set objects address --folder Texas --name external-site --fqdn example.com --description "External website"
+```
+
+#### Create Address Groups
+
+```bash
+# Static group with multiple members
+scm set objects address-group --folder Texas --name web-servers --type static --members "web-server-1,web-server-2"
+
+# Dynamic group based on tags
+scm set objects address-group --folder Texas --name dynamic-web-servers --type dynamic --filter "'web' and 'production'"
+```
+
+### Security Policy Management
+
+#### Create Security Zones
+
+```bash
+# Layer 3 zone
+scm set network zone --folder Texas --name dmz --mode layer3
+
+# Zone with user ID enabled
+scm set network zone --folder Texas --name trust --mode layer3 --enable-user-id
+```
+
+#### Create Security Rules
+
+```bash
+# Basic allow rule
+scm set security rule --folder Texas --name allow-web-traffic \
+  --source-zones trust \
+  --destination-zones dmz \
+  --source-addresses any \
+  --destination-addresses web-servers \
+  --services any \
+  --action allow \
+  --log-end
+
+# Application-specific rule
+scm set security rule --folder Texas --name allow-database \
+  --source-zones app-zone \
+  --destination-zones db-zone \
+  --source-addresses app-servers \
+  --destination-addresses database-servers \
+  --applications "mysql,postgresql" \
+  --action allow
+```
+
+### Service Management
+
+#### Create Custom Services
+
+```bash
+# TCP service
+scm set objects service --folder Texas --name custom-web --protocol tcp --port "8080,8443" --description "Custom web ports"
+
+# UDP service
+scm set objects service --folder Texas --name custom-dns --protocol udp --port 5353 --description "mDNS"
+
+# Service with timeout override
+scm set objects service --folder Texas --name long-running-db --protocol tcp --port 3306 --timeout 7200
+```
+
+#### Service Groups
+
+```bash
+# Group related services
+scm set objects service-group --folder Texas --name web-services --members "http,https,custom-web"
+```
+
+### Tag Management
+
+Tags help organize and categorize your objects:
+
+```bash
+# Environment tags
+scm set objects tag --folder Texas --name production --color Red --comments "Production environment"
+scm set objects tag --folder Texas --name development --color Green --comments "Development environment"
+scm set objects tag --folder Texas --name staging --color Blue --comments "Staging environment"
+
+# Category tags
+scm set objects tag --folder Texas --name database --color Orange --comments "Database resources"
+scm set objects tag --folder Texas --name web --color Cyan --comments "Web resources"
+```
+
+### Bulk Operations
+
+Work with multiple objects at once using YAML files:
+
+#### Export Configuration
+
+```bash
+# Export all addresses from a folder
+scm backup objects address --folder Texas
+# Creates: address_folder_texas_20250602_143000.yaml
+
+# Export with custom filename
+scm backup objects address-group --folder Texas --file my-groups.yaml
+
+# Export from different containers
+scm backup objects tag --snippet automation
+scm backup objects service --device austin-01
+```
+
+#### Import Configuration
+
+Create a YAML file for bulk import:
+
+```yaml
+# addresses.yaml
+addresses:
+  - name: web-01
+    description: "Production web server"
+    ip_netmask: 10.1.1.10/32
+    folder: Texas
+    tags:
+      - web
+      - production
+  
+  - name: web-02
+    description: "Production web server"
+    ip_netmask: 10.1.1.11/32
+    folder: Texas
+    tags:
+      - web
+      - production
+  
+  - name: db-01
+    description: "Database server"
+    ip_netmask: 10.2.1.10/32
+    folder: Texas
+    tags:
+      - database
+      - production
+```
+
+Import the configuration:
+
+```bash
+# Preview changes
+scm load objects address --file addresses.yaml --dry-run
+
+# Import to original locations
+scm load objects address --file addresses.yaml
+
+# Override location for all objects
+scm load objects address --file addresses.yaml --folder Production
+```
+
+### Context Management Examples
+
+#### Working with Multiple Tenants
+
+```bash
+# Create contexts for different environments
+$ scm context create prod-us \
+  --client-id "us-prod@111111111.iam.panserviceaccount.com" \
+  --client-secret "prod-secret" \
+  --tsg-id "111111111" \
+  --log-level WARNING
+✓ Context 'prod-us' created successfully
+
+$ scm context create prod-eu \
+  --client-id "eu-prod@222222222.iam.panserviceaccount.com" \
+  --client-secret "prod-secret" \
+  --tsg-id "222222222" \
+  --log-level WARNING
+✓ Context 'prod-eu' created successfully
+
+# List all contexts
+$ scm context list
+                           SCM Authentication Contexts                            
+┏━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+┃ Context     ┃ Current ┃ Client ID                                       ┃
+┡━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
+│ production  │         │ prod-app@1...@123456789.iam.panserviceaccount.com │
+│ development │ ✓       │ dev-app@98...@987654321.iam.panserviceaccount.com │
+│ prod-us     │         │ us-prod@11...@111111111.iam.panserviceaccount.com │
+│ prod-eu     │         │ eu-prod@22...@222222222.iam.panserviceaccount.com │
+└─────────────┴─────────┴────────────────────────────────────────────────────┘
+
+# Work with US production
+$ scm context use prod-us
+✓ Switched to context 'prod-us'
+
+$ scm show objects address --folder Texas
+[INFO] Using authentication context: prod-us
+Addresses in folder 'Texas':
+...
+
+# Switch to EU production
+$ scm context use prod-eu
+✓ Switched to context 'prod-eu'
+
+$ scm show objects address --folder London
+[INFO] Using authentication context: prod-eu
+Addresses in folder 'London':
+...
+
+# Delete a context you no longer need
+$ scm context delete old-dev
+Are you sure you want to delete context 'old-dev'? [y/N]: y
+✓ Context 'old-dev' deleted
+```
+
+### Docker Container Support
+
+The SCM CLI is available as a Docker image, providing a consistent environment across different platforms. The Docker image integrates seamlessly with the context management system:
+
+#### Running with Contexts
+
+```bash
+# Pull the official image
+docker pull ghcr.io/cdot65/pan-scm-cli:latest
+
+# Run with context volume mounting
+docker run -d \
+  --name pan-scm \
+  -v ~/.scm-cli:/home/scmuser/.scm-cli \
+  ghcr.io/cdot65/pan-scm-cli:latest
+
+# Your contexts are now available in the container
+docker exec pan-scm scm context list
+
+# Switch contexts in the container
+docker exec pan-scm scm context use production
+
+# Run commands with the active context
+docker exec pan-scm scm show objects address --folder Texas
+```
+
+#### Benefits of Docker with Contexts
+
+1. **Consistent Environment**: Same CLI version and dependencies across all systems
+2. **Context Portability**: Your contexts work identically on host and in containers
+3. **Security**: Credentials stay on the host, never baked into images
+4. **Multi-tenant Isolation**: Run multiple containers with different contexts simultaneously
+5. **CI/CD Ready**: Perfect for automated workflows with environment variable overrides
+
+#### Multi-tenant Example
+
+```bash
+# Run containers for different environments
+docker run -d --name scm-prod -v ~/.scm-cli:/home/scmuser/.scm-cli ghcr.io/cdot65/pan-scm-cli:latest
+docker run -d --name scm-dev -v ~/.scm-cli:/home/scmuser/.scm-cli ghcr.io/cdot65/pan-scm-cli:latest
+
+# Use different contexts in each container
+docker exec scm-prod scm context use production
+docker exec scm-dev scm context use development
+
+# Now each container operates on different tenants
+docker exec scm-prod scm show objects address --folder Production
+docker exec scm-dev scm show objects address --folder Development
+```
+
+### Complete Workflow Example
+
+Here's a complete example of setting up a web application security policy:
+
+```bash
+# Step 1: Create tags
+scm set objects tag --folder Texas --name web --color Cyan --comments "Web resources"
+scm set objects tag --folder Texas --name database --color Orange --comments "Database resources"
+scm set objects tag --folder Texas --name production --color Red --comments "Production environment"
+
+# Step 2: Create addresses
+scm set objects address --folder Texas --name web-01 --ip-netmask 10.1.1.10/32 --tag web,production
+scm set objects address --folder Texas --name web-02 --ip-netmask 10.1.1.11/32 --tag web,production
+scm set objects address --folder Texas --name db-01 --ip-netmask 10.2.1.10/32 --tag database,production
+
+# Step 3: Create address groups
+scm set objects address-group --folder Texas --name web-servers-group --type static --members "web-01,web-02"
+scm set objects address-group --folder Texas --name database-servers --type static --members "db-01"
+
+# Step 4: Create custom services
+scm set objects service --folder Texas --name custom-web --protocol tcp --port 443
+scm set objects service --folder Texas --name custom-db --protocol tcp --port 3306
+
+# Step 5: Create service group
+scm set objects service-group --folder Texas --name app-services --members "custom-web,custom-db"
+
+# Step 6: Create security zones
+scm set network zone --folder Texas --name trust --mode layer3
+scm set network zone --folder Texas --name dmz --mode layer3
+scm set network zone --folder Texas --name database --mode layer3
+
+# Step 7: Create security rule
+scm set security rule --folder Texas --name allow-web-to-db \
+  --source-zones dmz \
+  --destination-zones database \
+  --source-addresses web-servers-group \
+  --destination-addresses database-servers \
+  --services custom-db \
+  --action allow \
+  --log-end \
+  --description "Allow web servers to access database"
+
+# Step 8: Verify configuration
+scm show security rule --folder Texas --name allow-web-to-db
+```
+
+## Command Reference
+
+### Basic Command Structure
+
+```
+scm <action> <object-type> <object> [options]
+```
+
+### Actions
+
+- **set**: Create or update an object
+- **show**: Display objects (lists all by default, use --name for specific object)
+- **delete**: Remove an object
+- **load**: Import from YAML file
+- **backup**: Export to YAML file
+- **context**: Manage authentication contexts
+
+### Object Types
+
+- **objects**: Address, service, tag, application configurations
+- **network**: Security zones
+- **security**: Security rules and profiles
+- **deployment**: Bandwidth allocations
+
+### Common Options
+
+- `--folder`: Specify folder location (default: "Shared")
+- `--snippet`: Use snippet instead of folder
+- `--device`: Use device instead of folder
+- `--mock`: Run without API calls
+- `--help`: Show command help
+
+## Advanced Features
+
+### External Dynamic Lists (EDLs)
+
+Integrate threat intelligence feeds:
+
+```bash
+# Palo Alto Networks predefined lists
+scm set objects external-dynamic-list --folder Texas \
+  --name bulletproof-ips --type predefined_ip \
+  --url "panw-bulletproof-ip-list"
+
+# Custom threat feed with hourly updates
+scm set objects external-dynamic-list --folder Texas \
+  --name threat-feed --type ip \
+  --url "https://example.com/threats.txt" \
+  --recurring hourly
+
+# Domain blocklist with authentication
+scm set objects external-dynamic-list --folder Texas \
+  --name malicious-domains --type domain \
+  --url "https://secure.example.com/domains.txt" \
+  --username api_user --password secure_pass \
+  --recurring daily --hour 3
+```
+
+### Application Management
+
+Define custom applications:
+
+```bash
+# Create custom application
+scm set objects application --folder Texas --name internal-portal \
+  --category business-systems --subcategory general-business \
+  --technology browser-based --risk 2 \
+  --ports "tcp/443" --description "Internal employee portal"
+
+# High-risk application filter
+scm set objects application-filter --folder Texas --name high-risk-apps \
+  --category "file-sharing,peer-to-peer" --risk 4 --risk 5 \
+  --has-known-vulnerabilities
+```
+
+### HIP (Host Information Profile) Compliance
+
+Enforce endpoint compliance:
+
+```bash
+# Windows compliance check
+scm set objects hip-object --folder Texas --name windows-compliance \
+  --description "Windows security requirements" \
+  --host-info-os Microsoft --host-info-os-value All \
+  --host-info-managed \
+  --disk-encryption-enabled \
+  --patch-management-enabled
+
+# Create HIP profile
+scm set objects hip-profile --folder Texas --name secure-endpoints \
+  --match '{"windows-compliance": {"is": true}}' \
+  --description "Require compliant Windows endpoints"
+```
+
+### Log Forwarding
+
+Configure log collection:
+
+```bash
+# Syslog server profile
+scm set objects syslog-server-profile --folder Texas --name central-syslog \
+  --servers '[{"name": "primary", "server": "10.0.1.50", "port": 514, "transport": "TCP", "format": "BSD", "facility": "LOG_USER"}]'
+
+# HTTP server profile for SIEM
+scm set objects http-server-profile --folder Texas --name splunk-hec \
+  --servers '[{"name": "splunk", "address": "10.0.1.100", "protocol": "HTTPS", "port": 8088, "http_method": "POST"}]'
+
+# Log forwarding profile
+scm set objects log-forwarding-profile --folder Texas --name security-logs \
+  --match-list '[{"name": "threats", "log_type": "threat", "send_to_panorama": true}]'
+```
+
+## Troubleshooting
+
+### Common Issues
+
+#### Authentication Errors
+
+```bash
+# Check current authentication
+scm context test
+
+# If fails, verify credentials
+echo $SCM_CLIENT_ID
+echo $SCM_CLIENT_SECRET
+echo $SCM_TSG_ID
+```
+
+#### Object Already Exists
+
+The CLI handles existing objects gracefully:
+
+```bash
+# This will update if exists, create if not
+scm set objects address --folder Texas --name server --ip-netmask 10.1.1.1/32
+```
+
+#### Rate Limiting
+
+If you encounter rate limits:
+
+```bash
+# Use mock mode for testing
+scm set objects address --folder Texas --name test --ip-netmask 10.1.1.1/32 --mock
+
+# Or add delays in scripts
+sleep 1
+```
+
+### Debug Mode
+
+For detailed logging:
+
+```bash
+# Set log level
+export SCM_LOG_LEVEL=DEBUG
+
+# Run command
+scm show objects address --folder Texas
+```
+
+## Examples Directory
+
+The `examples/` directory contains ready-to-use templates:
+
+- `addresses.yml` - Common address objects
+- `rfc1918-addresses.yml` - Private IP ranges
+- `security-rules.yml` - Security policy examples
+- `tags.yml` - Tag organization system
+- `services.yml` - Custom service definitions
+- `hip-objects.yml` - HIP compliance configurations
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guide](./docs/about/contributing.md) for details.
+
+### Development Setup
+
+```bash
+# Clone repository
+git clone https://github.com/cdot65/pan-scm-cli.git
+cd pan-scm-cli
+
+# Install dependencies
+make setup
+
+# Run tests
+make tests
+
+# Check code quality
+make quality
+```
+
+## License
+
+Apache 2.0 - see [LICENSE](./LICENSE) for details.
+
+## Resources
+
+- [Documentation](https://cdot65.github.io/pan-scm-cli/)
+- [GitHub Issues](https://github.com/cdot65/pan-scm-cli/issues)
+- [Examples](./examples/)
+- [Release Notes](https://github.com/cdot65/pan-scm-cli/releases)
+