NAT Rules Models¶

Overview¶

The NAT Rules models provide a structured way to represent and validate NAT rule configuration data for Palo Alto Networks' Strata Cloud Manager. These models support configuration of source and destination address translation with various options including static IP mappings, dynamic IP and port allocation, and DNS rewrite functionality. The models handle validation of inputs and outputs when interacting with the SCM API.

Models¶

The module provides the following Pydantic models:

NatRuleBaseModel: Base model with fields common to all NAT rule operations
NatRuleCreateModel: Model for creating new NAT rules
NatRuleUpdateModel: Model for updating existing NAT rules
NatRuleResponseModel: Response model for NAT rule operations
NatRuleMoveModel: Model for moving/reordering NAT rules
SourceTranslation: Source translation configuration model
DynamicIpAndPort: Dynamic IP and port translation model
DynamicIpAndPortTranslatedAddress: Translated address container for dynamic IP and port
DynamicIpAndPortInterfaceAddress: Interface address container for dynamic IP and port
DynamicIp: Dynamic IP translation model
StaticIp: Static IP translation model
InterfaceAddress: Interface address configuration model
DestinationTranslation: Destination translation configuration model
DnsRewrite: DNS rewrite configuration model
NatType: Enum for NAT types
NatMoveDestination: Enum for move destination options
NatRulebase: Enum for rulebase options
DistributionMethod: Enum for distribution methods
DnsRewriteDirection: Enum for DNS rewrite directions
BiDirectional: Enum for bi-directional options

All models use extra="forbid" configuration (except NatRuleResponseModel which uses extra="ignore"), which rejects any fields not explicitly defined in the model.

Model Attributes¶

NatRuleBaseModel¶

This is the base model containing fields common to all NAT rule operations.

Attribute	Type	Required	Default	Description
`name`	`str`	Yes	None	The name of the NAT rule. Pattern: `^[a-zA-Z0-9_ \.-]+$`
`description`	`str`	No	None	Description of the NAT rule
`tag`	`List[TagName]`	No	[]	Tags associated with the NAT rule. Max 127 chars per tag
`disabled`	`bool`	No	False	Whether the NAT rule is disabled
`nat_type`	`NatType`	No	ipv4	Type of NAT operation (ipv4, nat64, nptv6)
`from_` (alias: `from`)	`List[str]`	No	["any"]	Source zone(s) for the NAT rule
`to_` (alias: `to`)	`List[str]`	No	["any"]	Destination zone(s) for the NAT rule
`to_interface`	`str`	No	None	Destination interface of the original packet
`source`	`List[str]`	No	["any"]	Source address(es) for the NAT rule
`destination`	`List[str]`	No	["any"]	Destination address(es) for the NAT rule
`service`	`str`	No	"any"	The TCP/UDP service associated with the NAT rule
`source_translation`	`SourceTranslation`	No	None	Configuration for source address translation
`destination_translation`	`DestinationTranslation`	No	None	Configuration for destination address translation
`active_active_device_binding`	`str`	No	None	Active/Active device binding
`folder`	`str`	No**	None	Folder where NAT rule is defined. Pattern: `^[a-zA-Z\d\-_. ]+$`. Max 64 chars
`snippet`	`str`	No**	None	Snippet where NAT rule is defined. Pattern: `^[a-zA-Z\d\-_. ]+$`. Max 64 chars
`device`	`str`	No**	None	Device where NAT rule is defined. Pattern: `^[a-zA-Z\d\-_. ]+$`. Max 64 chars

** Exactly one container (folder/snippet/device) must be provided for create operations

NatRuleCreateModel¶

Inherits all fields from NatRuleBaseModel and enforces that exactly one of folder, snippet, or device is provided during creation.

NatRuleUpdateModel¶

Extends NatRuleBaseModel by adding:

Attribute	Type	Required	Default	Description
`id`	`UUID`	Yes	None	The unique identifier of the NAT rule

NatRuleResponseModel¶

Extends NatRuleBaseModel by adding:

Attribute	Type	Required	Default	Description
`id`	`UUID`	Yes	None	The unique identifier of the NAT rule

Note: NatRuleResponseModel uses extra="ignore" configuration instead of extra="forbid", allowing it to accept additional fields returned by the API without raising validation errors.

Enum Types¶

NatType¶

Defines the NAT types supported by the system:

Value	Description
`ipv4`	IPv4 NAT (default)
`nat64`	NAT64 translation
`nptv6`	NPTv6 translation

NatMoveDestination¶

Defines valid destination values for rule movement:

Value	Description
`top`	Move to the top of the rulebase
`bottom`	Move to the bottom of the rulebase
`before`	Move before a specified rule
`after`	Move after a specified rule

NatRulebase¶

Defines valid rulebase values:

Value	Description
`pre`	Pre-rulebase
`post`	Post-rulebase

DistributionMethod¶

Defines distribution methods for dynamic destination translation:

Value	Description
`round-robin`	Round-robin distribution
`source-ip-hash`	Source IP hash distribution
`ip-modulo`	IP modulo distribution
`ip-hash`	IP hash distribution
`least-sessions`	Least sessions distribution

DnsRewriteDirection¶

Defines DNS rewrite direction options:

Value	Description
`reverse`	Reverse DNS rewrite
`forward`	Forward DNS rewrite

BiDirectional¶

Defines bi-directional translation options:

Value	Description
`yes`	Enable bi-directional translation
`no`	Disable bi-directional translation

Supporting Models¶

SourceTranslation¶

Main container for source translation configurations. Exactly one translation type must be provided.

Attribute	Type	Required	Default	Description
`dynamic_ip_and_port`	`DynamicIpAndPort`	No*	None	Dynamic IP and port translation configuration
`dynamic_ip`	`DynamicIp`	No*	None	Dynamic IP translation configuration
`static_ip`	`StaticIp`	No*	None	Static IP translation configuration

* Exactly one of these translation types must be provided

DynamicIpAndPort¶

Dynamic IP and port (PAT) translation configuration. Either translated_address or interface_address must be provided, but not both.

Attribute	Type	Required	Default	Description
`type`	`Literal`	No	"dynamic_ip_and_port"	Type identifier
`translated_address`	`List[str]`	No*	None	Translated source IP addresses
`interface_address`	`InterfaceAddress`	No*	None	Interface configuration for translation

* Exactly one of translated_address or interface_address must be provided

DynamicIpAndPortTranslatedAddress¶

Container model for dynamic IP and port translated address configuration.

Attribute	Type	Required	Default	Description
`translated_address`	`List[str]`	Yes	None	Translated source IP addresses

DynamicIpAndPortInterfaceAddress¶

Container model for dynamic IP and port interface address configuration.

Attribute	Type	Required	Default	Description
`interface`	`str`	Yes	None	Interface name
`ip`	`str`	No	None	Translated source IP address
`floating_ip`	`str`	No	None	Floating IP address

InterfaceAddress¶

Interface address configuration for translation.

Attribute	Type	Required	Default	Description
`interface`	`str`	Yes	None	Interface name
`ip`	`str`	No	None	IP address
`floating_ip`	`str`	No	None	Floating IP address

DynamicIp¶

Dynamic IP translation configuration with optional fallback settings.

Attribute	Type	Required	Default	Description
`translated_address`	`List[str]`	Yes	None	Translated IP addresses
`fallback_type`	`str`	No	None	Type of fallback configuration (translated_address or interface_address)
`fallback_address`	`List[str]`	No	None	Fallback IP addresses (when fallback_type is translated_address)
`fallback_interface`	`str`	No	None	Fallback interface name (when fallback_type is interface_address)
`fallback_ip`	`str`	No	None	Fallback IP address (when fallback_type is interface_address)

StaticIp¶

Static IP translation configuration.

Attribute	Type	Required	Default	Description
`translated_address`	`str`	Yes	None	Translated IP address
`bi_directional`	`BiDirectional`	No	None	Enable bi-directional translation (yes/no)

DestinationTranslation¶

Destination translation configuration.

Attribute	Type	Required	Default	Description
`translated_address`	`str`	No	None	Translated destination IP address
`translated_port`	`int`	No	None	Translated destination port (1-65535)
`dns_rewrite`	`DnsRewrite`	No	None	DNS rewrite configuration

DnsRewrite¶

DNS rewrite configuration.

Attribute	Type	Required	Default	Description
`direction`	`DnsRewriteDirection`	Yes	None	DNS rewrite direction

NatRuleMoveModel¶

Model for NAT rule move operations.

Attribute	Type	Required	Default	Description
`destination`	`NatMoveDestination`	Yes	None	Where to move the rule (top, bottom, before, after)
`rulebase`	`NatRulebase`	Yes	None	Which rulebase to use (pre or post)
`destination_rule`	`UUID`	No*	None	UUID of the reference rule for before/after moves

* Required when destination is before or after; must not be provided when destination is top or bottom

Exceptions¶

The models perform strict validation and will raise ValueError in scenarios such as:

When creating a NAT rule (NatRuleCreateModel), if not exactly one container (folder, snippet, or device) is provided.
When multiple source translation types are provided in SourceTranslation (must be exactly one of dynamic_ip_and_port, dynamic_ip, or static_ip).
When both translated_address and interface_address are provided (or neither) in DynamicIpAndPort.
When bi-directional static NAT (bi_directional="yes") is used together with destination translation in the same rule.
When DNS rewrite is used with NAT64 rule type.
When the NAT rule name does not match the required pattern ^[a-zA-Z0-9_ \.-]+$.
When list fields (from_, to_, source, destination, tag) contain duplicate values.
When container identifiers (folder, snippet, device) do not match the pattern ^[a-zA-Z\d\-_. ]+$ or exceed 64 characters.
When translated_port is outside the valid range of 1-65535.
When destination_rule is missing for before/after moves in NatRuleMoveModel.
When destination_rule is provided for top/bottom moves in NatRuleMoveModel.

Model Validators¶

Field Validators in `NatRuleBaseModel`¶

ensure_list_of_strings: Applied to from_, to_, source, destination, and tag fields. Converts a single string value to a list containing that string. Raises ValueError if the value is not a string or a list of strings.
ensure_unique_items: Applied to from_, to_, source, destination, and tag fields. Ensures all items in the list are unique. Raises ValueError if duplicate items are found.

Model Validators in `NatRuleBaseModel`¶

validate_nat64_dns_rewrite_compatibility: Ensures that DNS rewrite is not used with NAT64 type rules. If nat_type is nat64 and destination_translation.dns_rewrite is set, raises a ValueError.
validate_bidirectional_nat_compatibility: Ensures that bi-directional static NAT is not used together with destination translation. If source_translation.static_ip.bi_directional is "yes" and destination_translation is also set, raises a ValueError.

Field Validators in `StaticIp`¶

convert_boolean_to_enum: Applied to the bi_directional field. Converts boolean values to the corresponding BiDirectional enum value (True becomes BiDirectional.YES, False becomes BiDirectional.NO).

Model Validators in `DynamicIpAndPort`¶

validate_dynamic_ip_and_port: Ensures that exactly one of translated_address or interface_address is provided. Raises ValueError if both are provided or neither is provided.

Model Validators in `SourceTranslation`¶

validate_source_translation: Ensures that exactly one source translation type is provided among dynamic_ip_and_port, dynamic_ip, and static_ip. Raises ValueError if zero or more than one type is set.

Container Validation in `NatRuleCreateModel`¶

validate_container_type: After model initialization, this validator checks that exactly one of the container fields (folder, snippet, or device) is provided. If not, it raises a ValueError.

Move Configuration Validation in `NatRuleMoveModel`¶

validate_move_configuration: Validates the move configuration for NAT rule reordering. When destination is before or after, destination_rule must be provided. When destination is top or bottom, destination_rule must not be provided. Raises ValueError if these constraints are violated.

Usage Examples¶

Creating a Basic Source NAT Rule (Dynamic IP and Port)¶

Using a Dictionary¶

from scm.models.network.nat_rules import NatRuleCreateModel

nat_rule_data = {
    "name": "outbound-snat",
    "description": "Dynamic IP/Port source NAT for outbound traffic",
    "folder": "Texas",
    "from": ["trust"],
    "to": ["untrust"],
    "source": ["10.0.0.0/24"],
    "destination": ["any"],
    "service": "any",
    "source_translation": {
        "dynamic_ip_and_port": {
            "translated_address": ["192.168.1.100", "192.168.1.101"]
        }
    }
}

# Validate and create model instance
nat_rule = NatRuleCreateModel(**nat_rule_data)
payload = nat_rule.model_dump(exclude_unset=True, by_alias=True)
print(payload)

Using the Model Directly¶

from scm.models.network.nat_rules import (
    NatRuleCreateModel,
    SourceTranslation,
    DynamicIpAndPort,
)

# Create the source translation configuration
source_translation = SourceTranslation(
    dynamic_ip_and_port=DynamicIpAndPort(
        translated_address=["192.168.1.100", "192.168.1.101"]
    )
)

# Create the NAT rule
nat_rule = NatRuleCreateModel(
    name="outbound-snat",
    description="Dynamic IP/Port source NAT for outbound traffic",
    from_=["trust"],
    to_=["untrust"],
    source=["10.0.0.0/24"],
    destination=["any"],
    service="any",
    source_translation=source_translation,
    folder="Texas",
)
payload = nat_rule.model_dump(exclude_unset=True, by_alias=True)
print(payload)

Creating a NAT Rule with Interface Address Translation¶

from scm.models.network.nat_rules import (
    NatRuleCreateModel,
    SourceTranslation,
    DynamicIpAndPort,
    InterfaceAddress,
)

# Create interface address configuration
interface_addr = InterfaceAddress(
    interface="ethernet1/1",
    ip="192.168.1.1",
)

# Create the NAT rule using interface address
nat_rule = NatRuleCreateModel(
    name="interface-snat",
    description="Source NAT using interface address",
    from_=["trust"],
    to_=["untrust"],
    source=["10.0.0.0/24"],
    destination=["any"],
    source_translation=SourceTranslation(
        dynamic_ip_and_port=DynamicIpAndPort(
            interface_address=interface_addr
        )
    ),
    folder="Texas",
)
payload = nat_rule.model_dump(exclude_unset=True, by_alias=True)
print(payload)

Creating a Destination NAT Rule¶

from scm.models.network.nat_rules import NatRuleCreateModel

# Create destination NAT rule (port forwarding)
dnat_config = {
    "name": "web-server-dnat",
    "description": "Port forwarding to internal web server",
    "folder": "Texas",
    "from": ["untrust"],
    "to": ["trust"],
    "source": ["any"],
    "destination": ["203.0.113.10"],
    "service": "tcp-80",
    "destination_translation": {
        "translated_address": "10.0.0.100",
        "translated_port": 8080
    }
}

nat_rule = NatRuleCreateModel(**dnat_config)
payload = nat_rule.model_dump(exclude_unset=True, by_alias=True)
print(payload)

Creating a Static IP NAT Rule with Bi-directional Support¶

from scm.models.network.nat_rules import (
    NatRuleCreateModel,
    SourceTranslation,
    StaticIp,
    BiDirectional,
)

# Create a bi-directional static NAT rule
nat_rule = NatRuleCreateModel(
    name="server-static-nat",
    description="Bi-directional static NAT for server",
    from_=["any"],
    to_=["any"],
    source=["10.0.0.10"],
    destination=["any"],
    source_translation=SourceTranslation(
        static_ip=StaticIp(
            translated_address="192.168.1.100",
            bi_directional=BiDirectional.YES,
        )
    ),
    folder="Texas",
)
payload = nat_rule.model_dump(exclude_unset=True, by_alias=True)
print(payload)

Creating a Destination NAT Rule with DNS Rewrite¶

from scm.models.network.nat_rules import (
    NatRuleCreateModel,
    DestinationTranslation,
    DnsRewrite,
    DnsRewriteDirection,
)

# Create a destination NAT rule with DNS rewrite
nat_rule = NatRuleCreateModel(
    name="dns-rewrite-dnat",
    description="Destination NAT with DNS rewrite",
    from_=["untrust"],
    to_=["dmz"],
    source=["any"],
    destination=["203.0.113.50"],
    service="tcp-443",
    destination_translation=DestinationTranslation(
        translated_address="10.0.2.50",
        translated_port=443,
        dns_rewrite=DnsRewrite(
            direction=DnsRewriteDirection.REVERSE,
        ),
    ),
    folder="Texas",
)
payload = nat_rule.model_dump(exclude_unset=True, by_alias=True)
print(payload)

Creating a Dynamic IP NAT Rule with Fallback¶

from scm.models.network.nat_rules import (
    NatRuleCreateModel,
    SourceTranslation,
    DynamicIp,
)

# Create a dynamic IP NAT rule with fallback
nat_rule = NatRuleCreateModel(
    name="dynamic-ip-with-fallback",
    description="Dynamic IP NAT with translated address fallback",
    from_=["trust"],
    to_=["untrust"],
    source=["10.0.0.0/24"],
    destination=["any"],
    source_translation=SourceTranslation(
        dynamic_ip=DynamicIp(
            translated_address=["192.168.1.100", "192.168.1.101"],
            fallback_type="translated_address",
            fallback_address=["192.168.2.100", "192.168.2.101"],
        )
    ),
    folder="Texas",
)
payload = nat_rule.model_dump(exclude_unset=True, by_alias=True)
print(payload)

Updating a NAT Rule¶

from scm.client import ScmClient

# Initialize client
client = ScmClient(
    client_id="your_client_id",
    client_secret="your_client_secret",
    tsg_id="your_tsg_id"
)

# Fetch existing NAT rule
existing = client.nat_rule.fetch(name="outbound-snat", folder="Texas")

# Modify attributes using dot notation
existing.description = "Updated dynamic IP/Port source NAT"
existing.source = ["10.0.0.0/24", "10.0.1.0/24"]
existing.disabled = False

# Update the source translation addresses
existing.source_translation = {
    "dynamic_ip_and_port": {
        "translated_address": ["192.168.1.100", "192.168.1.101", "192.168.1.102"]
    }
}

# Pass modified object to update()
updated = client.nat_rule.update(existing)
print(f"Updated NAT rule: {updated.name}")

Moving a NAT Rule¶

from scm.models.network.nat_rules import NatRuleMoveModel, NatMoveDestination, NatRulebase

# Move a NAT rule to the top of the pre-rulebase
move_top = NatRuleMoveModel(
    destination=NatMoveDestination.TOP,
    rulebase=NatRulebase.PRE,
)
payload = move_top.model_dump(exclude_unset=True)
print(payload)

# Move a NAT rule before another rule
move_before = NatRuleMoveModel(
    destination=NatMoveDestination.BEFORE,
    rulebase=NatRulebase.PRE,
    destination_rule="987fcdeb-51d3-a456-426655440000",
)
payload = move_before.model_dump(exclude_unset=True)
print(payload)

Creating a NAT Rule with Tags¶

from scm.models.network.nat_rules import NatRuleCreateModel

nat_rule_data = {
    "name": "tagged-nat-rule",
    "description": "NAT rule with tags for organization",
    "folder": "Texas",
    "tag": ["Production", "Web-Traffic", "Outbound"],
    "from": ["trust"],
    "to": ["untrust"],
    "source": ["10.0.0.0/24"],
    "destination": ["any"],
    "nat_type": "ipv4",
    "source_translation": {
        "dynamic_ip_and_port": {
            "translated_address": ["203.0.113.100"]
        }
    }
}

nat_rule = NatRuleCreateModel(**nat_rule_data)
payload = nat_rule.model_dump(exclude_unset=True, by_alias=True)
print(payload)