pan-scm-sdk 0.10.2

Python SDK for Palo Alto Networks Strata Cloud Manager.

Strata Cloud Manager SDK

Python SDK for Palo Alto Networks Strata Cloud Manager.

NOTE: Please refer to the GitHub Pages documentation site for all examples

Table of Contents

• Strata Cloud Manager SDK
  • Table of Contents
  • Features
  • Development Guidelines
  • Installation
  • Usage
    • Authentication
      • Method 1: OAuth2 Client Credentials passed into a ScmClient instance
      • Method 2: Bearer Token Authentication
    • TLS Certificate Verification Control
    • Available Client Services
  • Development
    • Setup
    • Code Quality
    • Pre-commit Hooks
  • Contributing
  • License
  • Support

Features

• Flexible Authentication:
  • OAuth2 client credentials flow for standard authentication
  • Bearer token support for scenarios with pre-acquired tokens
• Resource Management: Create, read, update, and delete configuration objects such as addresses, address groups, applications, regions, internal DNS servers, and more.
• Data Validation: Utilize Pydantic models for data validation and serialization.
• Exception Handling: Comprehensive error handling with custom exceptions for API errors.
• Extensibility: Designed for easy extension to support additional resources and endpoints.

Development Guidelines

For developers working on this SDK:

• Service File Standards: See SDK_STYLING_GUIDE.md for comprehensive service file guidelines
• Model Standards: See PYDANTIC_MODELS_GUIDE.md for Pydantic model patterns and conventions
• Templates: Use SDK_SERVICE_TEMPLATE.py as a starting point for new services

Installation

Requirements:

• Python 3.10 or higher

Install the package via pip:

pip install pan-scm-sdk

Usage

TLS Certificate Verification Control

By default, the SDK verifies TLS certificates for all HTTPS requests. You can bypass TLS verification (for development or testing) by setting the verify_ssl flag to False when initializing Scm or ScmClient:

from scm.client import ScmClient

client = ScmClient(
    client_id="...",
    client_secret="...",
    tsg_id="...",
    verify_ssl=False,  # WARNING: disables TLS verification!
)

Warning: Disabling TLS verification is insecure and exposes you to man-in-the-middle attacks. Only use verify_ssl=False in trusted development environments.

Authentication

Before interacting with the SDK, you need to authenticate:

Method 1: OAuth2 Client Credentials passed into a ScmClient instance

from scm.client import ScmClient

# Initialize the API client with OAuth2 client credentials
api_client = ScmClient(
    client_id="your_client_id",
    client_secret="your_client_secret",
    tsg_id="your_tsg_id",
)

# The SCM client is now ready to use

Method 2: Bearer Token Authentication

If you already have a valid OAuth token, you can use it directly:

from scm.client import Scm

# Initialize the API client with a pre-acquired bearer token
api_client = Scm(
    access_token="your_bearer_token"
)

# The SCM client is now ready to use

NOTE: When using bearer token authentication, token refresh is your responsibility. For commit operations with bearer token auth, you must explicitly provide the admin parameter.

# Example of commit with bearer token authentication
api_client.commit(
    folders=["Texas"],
    description="Configuration changes",
    admin=["[e-mail]"],  # Required when using bearer token
    sync=True
)

Available Client Services

The unified client provides access to the following services through attribute-based access:

Client Property	Description
Objects
address	IP addresses, CIDR ranges, and FQDNs for security policies
address_group	Static or dynamic collections of address objects
application	Custom application definitions and signatures
application_filter	Filters for identifying applications by characteristics
application_group	Logical groups of applications for policy application
auto_tag_action	Automated tag assignment based on traffic and security events
dynamic_user_group	User groups with dynamic membership criteria
external_dynamic_list	Externally managed lists of IPs, URLs, or domains
hip_object	Host information profile match criteria
hip_profile	Endpoint security compliance profiles
http_server_profile	HTTP server configurations for logging and monitoring
log_forwarding_profile	Configurations for forwarding logs to external systems
quarantined_device	Management of devices blocked from network access
region	Geographic regions for policy control
schedule	Time-based policies and access control
service	Protocol and port definitions for network services
service_group	Collections of services for simplified policy management
syslog_server_profile	Syslog server configurations for centralized logging
tag	Resource classification and organization labels
Mobile Agent
auth_setting	GlobalProtect authentication settings
agent_version	GlobalProtect agent versions (read-only)
Network
aggregate_interface	Aggregated ethernet interfaces with LACP support
bgp_address_family_profile	BGP address family profiles (IPv4/IPv6 unicast/multicast)
bgp_auth_profile	BGP authentication profiles (MD5 for BGP sessions)
bgp_filtering_profile	BGP filtering profiles for inbound/outbound route filtering
bgp_redistribution_profile	BGP redistribution profiles for protocol route redistribution
bgp_route_map	BGP route maps for import/export policy control
bgp_route_map_redistribution	BGP route map redistribution with protocol crossover patterns
dhcp_interface	DHCP server and relay settings on interfaces
ethernet_interface	Physical ethernet interface configurations
ike_crypto_profile	IKE crypto profiles for VPN tunnel encryption
ike_gateway	IKE gateways for VPN tunnel endpoints
interface_management_profile	Interface management profiles (HTTPS, SSH, ping access)
ipsec_crypto_profile	IPsec crypto profiles for VPN tunnel encryption
ipsec_tunnel	IPsec tunnel objects for encrypted site-to-site connectivity
layer2_subinterface	Layer 2 VLAN subinterfaces for switching
layer3_subinterface	Layer 3 VLAN subinterfaces for routing
logical_router	Logical routers with VRF, BGP, OSPF, ECMP, static routes
loopback_interface	Loopback interfaces for management and routing
nat_rule	Network address translation policies for traffic routing
ospf_auth_profile	OSPF authentication profiles (MD5/password for adjacencies)
route_access_list	Route access lists for filtering routes by network/mask
route_prefix_list	Route prefix lists for prefix-based route filtering
security_zone	Security zones for network segmentation
tunnel_interface	Tunnel interfaces for VPN and overlay networks
vlan_interface	VLAN interfaces for network segmentation
dns_proxy	DNS proxy configurations for DNS interception and forwarding
pbf_rule	Policy-Based Forwarding rules for application-aware routing
qos_profile	QoS profiles for traffic shaping and bandwidth allocation
qos_rule	QoS policy rules with rule move/reorder support
zone_protection_profile	Zone protection with flood, scan, and packet-based defense
Deployment
bandwidth_allocation	Bandwidth allocation management for network capacity planning
bgp_routing	BGP routing configuration for network connectivity
internal_dns_server	Internal DNS server configurations for domain resolution
network_location	Geographic network locations for service connectivity
remote_network	Secure branch and remote site connectivity configurations
service_connection	Service connections to cloud service providers
Security
anti_spyware_profile	Protection against spyware, C2 traffic, and data exfiltration
decryption_profile	SSL/TLS traffic inspection configurations
dns_security_profile	Protection against DNS-based threats and tunneling
security_rule	Core security policies controlling network traffic
url_category	Custom URL categorization for web filtering
vulnerability_protection_profile	Defense against known CVEs and exploit attempts
wildfire_antivirus_profile	Cloud-based malware analysis and zero-day protection
Insights
alerts	Security alerts and threat intelligence notifications
Setup
device	Device resources and management
folder	Folder organization and hierarchy
label	Resource classification and simple key-value object labels
snippet	Reusable configuration snippets
variable	Typed variables with flexible container scoping

---

Development

Before starting development, please review:

• SDK_STYLING_GUIDE.md - Comprehensive guide for writing consistent SDK code
• PYDANTIC_MODELS_GUIDE.md - Guidelines for creating Pydantic models
• SDK_SERVICE_TEMPLATE.py - Template for new service files

Setup

1. Clone the repository:

   git clone https://github.com/cdot65/pan-scm-sdk.git
   cd pan-scm-sdk
   

2. Install dependencies and pre-commit hooks:

   make setup
   

   Alternatively, you can install manually:

   poetry install
   poetry run pre-commit install
   

Code Quality

This project uses ruff for linting and formatting:

# Run linting checks
make lint

# Format code
make format

# Auto-fix linting issues when possible
make fix

Pre-commit Hooks

We use pre-commit hooks to ensure code quality before committing:

# Run pre-commit hooks on all files
make pre-commit-all

The following checks run automatically before each commit:

• ruff linting and formatting
• Trailing whitespace removal
• End-of-file fixer
• YAML/JSON syntax checking
• Large file detection
• Python syntax validation
• Merge conflict detection
• Private key detection

Contributing

We welcome contributions! To contribute:

1. Fork the repository.
2. Create a new feature branch (git checkout -b feature/your-feature).
3. Make your changes, ensuring all linting and tests pass.
4. Commit your changes (git commit -m 'Add new feature').
5. Push to your branch (git push origin feature/your-feature).
6. Open a Pull Request.

Ensure your code adheres to the project's coding standards and includes tests where appropriate.

License

This project is licensed under the Apache 2.0 License. See the LICENSE file for details.

Support

For support and questions, please refer to the SUPPORT.md file in this repository.

---

Detailed documentation is available on our GitHub Pages documentation site.