2026/11/13 - AWS Network Firewall - 8 updated api methods
Changes Releasing Firewall Proxy API and deprecating Egress Proxy API.
{'NatGatewayCreateMappings': [{'AllocationIds': ['string'],
'PrivateIps': ['string'],
'SubnetId': 'string'}]}
Associates the specified subnets in the Amazon VPC to the firewall. You can specify one subnet for each of the Availability Zones that the VPC spans.
This request creates an Network Firewall firewall endpoint in each of the subnets. To enable the firewall's protections, you must also modify the VPC's route tables for each subnet's Availability Zone, to redirect the traffic that's coming into and going out of the zone through the firewall endpoint.
For a proxy mode firewall, use this operation to add Availability Zones to the firewall. For each subnet, specify a NAT gateway in NatGatewayCreateMappings in the same Availability Zone. You can't add an Availability Zone that the firewall already uses. The firewall keeps working in its other Availability Zones while Network Firewall sets up the new one. If Network Firewall can't set up the new Availability Zone, it removes the Availability Zone from the firewall. It also deletes the NAT gateway that it created there. The Availability Zone's Attachment status shows the reason. You can then add the Availability Zone again.
See also: AWS API Documentation
Request Syntax
client.associate_subnets(
UpdateToken='string',
FirewallArn='string',
FirewallName='string',
SubnetMappings=[
{
'SubnetId': 'string',
'IPAddressType': 'DUALSTACK'|'IPV4'|'IPV6'
},
],
NatGatewayCreateMappings=[
{
'SubnetId': 'string',
'AllocationIds': [
'string',
],
'PrivateIps': [
'string',
]
},
]
)
string
An optional token that you can use for optimistic locking. Network Firewall returns a token to your requests that access the firewall. The token marks the state of the firewall resource at the time of the request.
To make an unconditional change to the firewall, omit the token in your update request. Without the token, Network Firewall performs your updates regardless of whether the firewall has changed since you last retrieved it.
To make a conditional change to the firewall, provide the token in your update request. Network Firewall uses the token to ensure that the firewall hasn't changed since you last retrieved it. If it has changed, the operation fails with an InvalidTokenException. If this happens, retrieve the firewall again to get a current copy of it with a new token. Reapply your changes as needed, then try the operation again using the new token.
string
The Amazon Resource Name (ARN) of the firewall.
You must specify the ARN or the name, and you can specify both.
string
The descriptive name of the firewall. You can't change the name of a firewall after you create it.
You must specify the ARN or the name, and you can specify both.
list
[REQUIRED]
The IDs of the subnets that you want to associate with the firewall.
(dict) --
The ID for a subnet that's used in an association with a firewall. This is used in CreateFirewall, AssociateSubnets, and CreateVpcEndpointAssociation. Network Firewall creates an instance of the associated firewall in each subnet that you specify, to filter traffic in the subnet's Availability Zone.
SubnetId (string) -- [REQUIRED]
The unique identifier for the subnet.
IPAddressType (string) --
The subnet's IP address type. You can't change the IP address type after you create the subnet.
list
The NAT gateways that Network Firewall creates for the Availability Zones that you add to a proxy mode firewall. For a proxy mode firewall, you must specify one mapping for each Availability Zone in SubnetMappings, and no other Availability Zones. Each NAT gateway subnet must be in the firewall's VPC and can't be one of the firewall endpoint subnets.
You can't specify this for a firewall that isn't a proxy mode firewall.
(dict) --
A NAT gateway that Network Firewall creates for a proxy mode firewall in one Availability Zone. You use this in CreateFirewall and AssociateSubnets.
To create a public NAT gateway, specify AllocationIds, and one PrivateIps address for each Elastic IP address. To create a private NAT gateway, specify only PrivateIps. You must specify at least one of them. Each Elastic IP address and private IP address can appear only once in a request.
The NAT gateway is a resource in your account. To change its IP addresses, use Amazon EC2 NAT gateway actions.
SubnetId (string) -- [REQUIRED]
The ID of the subnet where Network Firewall creates the NAT gateway. The subnet must be in the firewall's VPC and can't be one of the firewall endpoint subnets. Each mapping must be in a different Availability Zone.
AllocationIds (list) --
The allocation IDs of the Elastic IP addresses for a public NAT gateway, from 1 to 8. For each allocation ID, specify one address in PrivateIps. If you don't specify this, Network Firewall creates a private NAT gateway.
(string) --
PrivateIps (list) --
The private IPv4 addresses of the NAT gateway. The addresses must be in the subnet that you specify and can't be the subnet's reserved addresses.
For a public NAT gateway, you must specify exactly one address for each Elastic IP address in AllocationIds, even if you specify only one. For a private NAT gateway, specify from 1 to 8 addresses. The first address is the primary address.
(string) --
dict
Response Syntax
{
'FirewallArn': 'string',
'FirewallName': 'string',
'SubnetMappings': [
{
'SubnetId': 'string',
'IPAddressType': 'DUALSTACK'|'IPV4'|'IPV6'
},
],
'UpdateToken': 'string'
}
Response Structure
(dict) --
FirewallArn (string) --
The Amazon Resource Name (ARN) of the firewall.
FirewallName (string) --
The descriptive name of the firewall. You can't change the name of a firewall after you create it.
SubnetMappings (list) --
The IDs of the subnets that are associated with the firewall.
(dict) --
The ID for a subnet that's used in an association with a firewall. This is used in CreateFirewall, AssociateSubnets, and CreateVpcEndpointAssociation. Network Firewall creates an instance of the associated firewall in each subnet that you specify, to filter traffic in the subnet's Availability Zone.
SubnetId (string) --
The unique identifier for the subnet.
IPAddressType (string) --
The subnet's IP address type. You can't change the IP address type after you create the subnet.
UpdateToken (string) --
An optional token that you can use for optimistic locking. Network Firewall returns a token to your requests that access the firewall. The token marks the state of the firewall resource at the time of the request.
To make an unconditional change to the firewall, omit the token in your update request. Without the token, Network Firewall performs your updates regardless of whether the firewall has changed since you last retrieved it.
To make a conditional change to the firewall, provide the token in your update request. Network Firewall uses the token to ensure that the firewall hasn't changed since you last retrieved it. If it has changed, the operation fails with an InvalidTokenException. If this happens, retrieve the firewall again to get a current copy of it with a new token. Reapply your changes as needed, then try the operation again using the new token.
{'NatGatewayCreateMappings': [{'AllocationIds': ['string'],
'PrivateIps': ['string'],
'SubnetId': 'string'}],
'ProxySettings': {'CertificateArn': 'string', 'DomainName': 'string'},
'TransparentFilteringNatScope': 'NAT_ALL | NAT_NONE'}
Response {'Firewall': {'NatGatewayCreateMappings': [{'AllocationIds': ['string'],
'PrivateIps': ['string'],
'SubnetId': 'string'}],
'ProxySettings': {'CertificateArn': 'string',
'DomainName': 'string'},
'TransparentFilteringNatScope': 'NAT_ALL | NAT_NONE'}}
Creates an Network Firewall Firewall and accompanying FirewallStatus for a VPC.
The firewall defines the configuration settings for an Network Firewall firewall. The settings that you can define at creation include the firewall policy, the subnets in your VPC to use for the firewall endpoints, and any tags that are attached to the firewall Amazon Web Services resource.
After you create a firewall, you can provide additional settings, like the logging configuration.
To update the settings for a firewall, you use the operations that apply to the settings themselves, for example UpdateLoggingConfiguration, AssociateSubnets, and UpdateFirewallDeleteProtection.
To manage a firewall's tags, use the standard Amazon Web Services resource tagging operations, ListTagsForResource, TagResource, and UntagResource.
To retrieve information about firewalls, use ListFirewalls and DescribeFirewall.
To generate a report on the last 30 days of traffic monitored by a firewall, use StartAnalysisReport.
To create a proxy mode firewall, specify VpcEndpoint and NatGatewayCreateMappings instead of VpcId and SubnetMappings. A proxy mode firewall is an explicit forward proxy. Your clients send HTTP and HTTPS proxy requests to the firewall's proxy DNS name, which DescribeFirewall returns in each Availability Zone's Attachment. The firewall evaluates proxy traffic with the stateful rules in its firewall policy, and sends allowed traffic out through the NAT gateway in the same Availability Zone. Your clients don't need route table changes. In each Availability Zone, the firewall has one endpoint and one NAT gateway, which Network Firewall creates for you.
See also: AWS API Documentation
Request Syntax
client.create_firewall(
FirewallName='string',
FirewallPolicyArn='string',
VpcId='string',
SubnetMappings=[
{
'SubnetId': 'string',
'IPAddressType': 'DUALSTACK'|'IPV4'|'IPV6'
},
],
DeleteProtection=True|False,
SubnetChangeProtection=True|False,
FirewallPolicyChangeProtection=True|False,
Description='string',
Tags=[
{
'Key': 'string',
'Value': 'string'
},
],
EncryptionConfiguration={
'KeyId': 'string',
'Type': 'CUSTOMER_KMS'|'AWS_OWNED_KMS_KEY'
},
EnabledAnalysisTypes=[
'TLS_SNI'|'HTTP_HOST',
],
TransitGatewayId='string',
AvailabilityZoneMappings=[
{
'AvailabilityZone': 'string'
},
],
AvailabilityZoneChangeProtection=True|False,
NatGatewayCreateMappings=[
{
'SubnetId': 'string',
'AllocationIds': [
'string',
],
'PrivateIps': [
'string',
]
},
],
ProxySettings={
'ListenerProperties': [
{
'Port': 123,
'Type': 'HTTP'|'HTTPS'
},
],
'CertificateArn': 'string',
'DomainName': 'string'
},
VpcEndpoint={
'VpcId': 'string',
'SubnetMappings': [
{
'SubnetId': 'string',
'IPAddressType': 'DUALSTACK'|'IPV4'|'IPV6'
},
]
},
TransparentFilteringNatScope='NAT_ALL'|'NAT_NONE'
)
string
[REQUIRED]
The descriptive name of the firewall. You can't change the name of a firewall after you create it.
string
[REQUIRED]
The Amazon Resource Name (ARN) of the FirewallPolicy that you want to use for the firewall.
string
The unique identifier of the VPC where Network Firewall should create the firewall.
You can't change this setting after you create the firewall.
list
The public subnets to use for your Network Firewall firewalls. Each subnet must belong to a different Availability Zone in the VPC. Network Firewall creates a firewall endpoint in each subnet.
(dict) --
The ID for a subnet that's used in an association with a firewall. This is used in CreateFirewall, AssociateSubnets, and CreateVpcEndpointAssociation. Network Firewall creates an instance of the associated firewall in each subnet that you specify, to filter traffic in the subnet's Availability Zone.
SubnetId (string) -- [REQUIRED]
The unique identifier for the subnet.
IPAddressType (string) --
The subnet's IP address type. You can't change the IP address type after you create the subnet.
boolean
A flag indicating whether it is possible to delete the firewall. A setting of TRUE indicates that the firewall is protected against deletion. Use this setting to protect against accidentally deleting a firewall that is in use. When you create a firewall, the operation initializes this flag to TRUE.
boolean
A setting indicating whether the firewall is protected against changes to the subnet associations. Use this setting to protect against accidentally modifying the subnet associations for a firewall that is in use. When you create a firewall, the operation initializes this setting to TRUE.
boolean
A setting indicating whether the firewall is protected against a change to the firewall policy association. Use this setting to protect against accidentally modifying the firewall policy for a firewall that is in use. When you create a firewall, the operation initializes this setting to TRUE.
string
A description of the firewall.
list
The key:value pairs to associate with the resource.
(dict) --
A key:value pair associated with an Amazon Web Services resource. The key:value pair can be anything you define. Typically, the tag key represents a category (such as "environment") and the tag value represents a specific value within that category (such as "test," "development," or "production"). You can add up to 50 tags to each Amazon Web Services resource.
Key (string) -- [REQUIRED]
The part of the key:value pair that defines a tag. You can use a tag key to describe a category of information, such as "customer." Tag keys are case-sensitive.
Value (string) -- [REQUIRED]
The part of the key:value pair that defines a tag. You can use a tag value to describe a specific value within a category, such as "companyA" or "companyB." Tag values are case-sensitive.
dict
A complex type that contains settings for encryption of your firewall resources.
KeyId (string) --
The ID of the Amazon Web Services Key Management Service (KMS) customer managed key. You can use any of the key identifiers that KMS supports, unless you're using a key that's managed by another account. If you're using a key managed by another account, then specify the key ARN. For more information, see Key ID in the Amazon Web Services KMS Developer Guide.
Type (string) -- [REQUIRED]
The type of Amazon Web Services KMS key to use for encryption of your Network Firewall resources.
list
An optional setting indicating the specific traffic analysis types to enable on the firewall.
(string) --
string
Required when creating a transit gateway-attached firewall. The unique identifier of the transit gateway to attach to this firewall. You can provide either a transit gateway from your account or one that has been shared with you through Resource Access Manager.
For information about creating firewalls, see CreateFirewall. For specific guidance about transit gateway-attached firewalls, see Considerations for transit gateway-attached firewalls in the Network Firewall Developer Guide.
list
Required. The Availability Zones where you want to create firewall endpoints for a transit gateway-attached firewall. You must specify at least one Availability Zone. Consider enabling the firewall in every Availability Zone where you have workloads to maintain Availability Zone isolation.
You can modify Availability Zones later using AssociateAvailabilityZones or DisassociateAvailabilityZones, but this may briefly disrupt traffic. The AvailabilityZoneChangeProtection setting controls whether you can make these modifications.
(dict) --
Defines the mapping between an Availability Zone and a firewall endpoint for a transit gateway-attached firewall. Each mapping represents where the firewall can process traffic. You use these mappings when calling CreateFirewall, AssociateAvailabilityZones, and DisassociateAvailabilityZones.
To retrieve the current Availability Zone mappings for a firewall, use DescribeFirewall.
AvailabilityZone (string) -- [REQUIRED]
The ID of the Availability Zone where the firewall endpoint is located. For example, us-east-2a. The Availability Zone must be in the same Region as the transit gateway.
boolean
Optional. A setting indicating whether the firewall is protected against changes to its Availability Zone configuration. When set to TRUE, you cannot add or remove Availability Zones without first disabling this protection using UpdateAvailabilityZoneChangeProtection.
Default value: FALSE
list
The NAT gateways that Network Firewall creates for a proxy mode firewall, one for each Availability Zone. When you specify this, you create a proxy mode firewall. Destinations see the IP address of the NAT gateway in the client's Availability Zone as the source of the traffic.
Specify one mapping for each Availability Zone in VpcEndpoint, and no other Availability Zones. Each NAT gateway subnet must be in the VpcEndpoint VPC and can't be one of the firewall endpoint subnets.
You need permission to call the Amazon EC2 CreateNatGateway action.
If Network Firewall can't set up an Availability Zone, for example because Amazon EC2 rejects the NAT gateway, it removes the Availability Zone from the firewall. It also deletes the NAT gateway that it created there. The Availability Zone's Attachment status is FAILED, and its status message explains why. You can add the Availability Zone again with AssociateSubnets. If no Availability Zone can be set up, the firewall status is FAILED.
(dict) --
A NAT gateway that Network Firewall creates for a proxy mode firewall in one Availability Zone. You use this in CreateFirewall and AssociateSubnets.
To create a public NAT gateway, specify AllocationIds, and one PrivateIps address for each Elastic IP address. To create a private NAT gateway, specify only PrivateIps. You must specify at least one of them. Each Elastic IP address and private IP address can appear only once in a request.
The NAT gateway is a resource in your account. To change its IP addresses, use Amazon EC2 NAT gateway actions.
SubnetId (string) -- [REQUIRED]
The ID of the subnet where Network Firewall creates the NAT gateway. The subnet must be in the firewall's VPC and can't be one of the firewall endpoint subnets. Each mapping must be in a different Availability Zone.
AllocationIds (list) --
The allocation IDs of the Elastic IP addresses for a public NAT gateway, from 1 to 8. For each allocation ID, specify one address in PrivateIps. If you don't specify this, Network Firewall creates a private NAT gateway.
(string) --
PrivateIps (list) --
The private IPv4 addresses of the NAT gateway. The addresses must be in the subnet that you specify and can't be the subnet's reserved addresses.
For a public NAT gateway, you must specify exactly one address for each Elastic IP address in AllocationIds, even if you specify only one. For a private NAT gateway, specify from 1 to 8 addresses. The first address is the primary address.
(string) --
dict
The proxy settings for a proxy mode firewall: the ports and protocols on which the firewall's proxy listens for traffic, and optionally your own domain name and certificate. If you don't specify listeners, the firewall listens for HTTP on port 3128 and HTTPS on port 8443.
To change the listeners later, use UpdateProxySettings.
ListenerProperties (list) -- [REQUIRED]
The listeners of the firewall's proxy. Specify at least one listener, and at most one HTTP listener and one HTTPS listener. Each listener needs a port from 1 to 65535, and the two listeners must use different ports.
If you don't specify listeners when you create the firewall, the firewall listens for HTTP on port 3128 and HTTPS on port 8443.
(dict) --
Open port for taking HTTP or HTTPS traffic.
Port (integer) --
Port for processing traffic.
Type (string) --
Selection of HTTP or HTTPS traffic.
CertificateArn (string) --
The Amazon Resource Name (ARN) of the certificate that the firewall's HTTPS proxy listener presents to clients. The certificate must be an Certificate Manager (ACM) certificate in the same account and Region as the firewall. Its subject alternative names must cover DomainName, either exactly or with a wildcard that matches exactly one label. For example, *.example.com covers proxy.example.com. If you don't specify this, Network Firewall uses a certificate that it manages for a domain name that it generates.
You manage and renew the certificate in ACM, and Network Firewall uses renewed certificates automatically. While the firewall uses the certificate, you can't delete it from ACM. Your clients must trust the certificate's certificate authority.
If you specify CertificateArn, you must also specify DomainName. You can set them only when you create the firewall. When you call UpdateProxySettings, specify the same values.
DomainName (string) --
The domain name that your clients use to reach the firewall's proxy. The name must have at least two labels and at most 253 characters. It can't contain a wildcard or use the proxy-id.nfw.region.amazonaws.com format, and the certificate in CertificateArn must cover it. If you don't specify this, Network Firewall generates a domain name.
Network Firewall creates the Route 53 private hosted zones that resolve this name to the firewall endpoints, so you don't need to configure DNS. A VPC can have only one private hosted zone with a given name. If a VPC that the firewall serves already has one with this name, Network Firewall can't set up the Availability Zones in that VPC.
If you specify DomainName, you must also specify CertificateArn. You can set them only when you create the firewall. When you call UpdateProxySettings, specify the same values.
dict
The VPC and subnets for the endpoints of a proxy mode firewall. Network Firewall creates a firewall endpoint in each subnet that you specify. It also creates the firewall's NAT gateways in this VPC, in the subnets that you specify in NatGatewayCreateMappings.
To create a proxy mode firewall, you must specify VpcEndpoint and NatGatewayCreateMappings, and you must not specify the top-level VpcId and SubnetMappings. Specify one subnet for each Availability Zone where you want to use the firewall.
VpcId (string) -- [REQUIRED]
The ID of the VPC where Network Firewall creates the endpoints and NAT gateways of a proxy mode firewall.
SubnetMappings (list) -- [REQUIRED]
The subnets where Network Firewall creates the firewall endpoints of a proxy mode firewall. Specify one subnet for each Availability Zone, and a NAT gateway mapping in each of those Availability Zones.
(dict) --
The ID for a subnet that's used in an association with a firewall. This is used in CreateFirewall, AssociateSubnets, and CreateVpcEndpointAssociation. Network Firewall creates an instance of the associated firewall in each subnet that you specify, to filter traffic in the subnet's Availability Zone.
SubnetId (string) -- [REQUIRED]
The unique identifier for the subnet.
IPAddressType (string) --
The subnet's IP address type. You can't change the IP address type after you create the subnet.
string
How a proxy mode firewall handles traffic that isn't sent to its proxy listener. If you don't specify a value, the firewall uses NAT_ALL. You can choose from the following values:
NAT_ALL - After inspection, the firewall sends this traffic out through its NAT gateway, which translates the source address.
NAT_NONE - After inspection, the firewall returns this traffic to the firewall endpoint without address translation.
You can specify this only for a proxy mode firewall, and you can't change it after you create the firewall.
dict
Response Syntax
{
'Firewall': {
'FirewallName': 'string',
'FirewallArn': 'string',
'FirewallPolicyArn': 'string',
'VpcId': 'string',
'SubnetMappings': [
{
'SubnetId': 'string',
'IPAddressType': 'DUALSTACK'|'IPV4'|'IPV6'
},
],
'DeleteProtection': True|False,
'SubnetChangeProtection': True|False,
'FirewallPolicyChangeProtection': True|False,
'Description': 'string',
'FirewallId': 'string',
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
],
'EncryptionConfiguration': {
'KeyId': 'string',
'Type': 'CUSTOMER_KMS'|'AWS_OWNED_KMS_KEY'
},
'NumberOfAssociations': 123,
'EnabledAnalysisTypes': [
'TLS_SNI'|'HTTP_HOST',
],
'TransitGatewayId': 'string',
'TransitGatewayOwnerAccountId': 'string',
'AvailabilityZoneMappings': [
{
'AvailabilityZone': 'string'
},
],
'AvailabilityZoneChangeProtection': True|False,
'NatGatewayCreateMappings': [
{
'SubnetId': 'string',
'AllocationIds': [
'string',
],
'PrivateIps': [
'string',
]
},
],
'ProxySettings': {
'ListenerProperties': [
{
'Port': 123,
'Type': 'HTTP'|'HTTPS'
},
],
'CertificateArn': 'string',
'DomainName': 'string'
},
'VpcEndpoint': {
'VpcId': 'string',
'SubnetMappings': [
{
'SubnetId': 'string',
'IPAddressType': 'DUALSTACK'|'IPV4'|'IPV6'
},
]
},
'TransparentFilteringNatScope': 'NAT_ALL'|'NAT_NONE'
},
'FirewallStatus': {
'Status': 'PROVISIONING'|'DELETING'|'READY'|'FAILED',
'ConfigurationSyncStateSummary': 'PENDING'|'IN_SYNC'|'CAPACITY_CONSTRAINED',
'SyncStates': {
'string': {
'Attachment': {
'SubnetId': 'string',
'EndpointId': 'string',
'Status': 'CREATING'|'DELETING'|'FAILED'|'ERROR'|'SCALING'|'READY',
'StatusMessage': 'string',
'DnsName': 'string'
},
'Config': {
'string': {
'SyncStatus': 'PENDING'|'IN_SYNC'|'CAPACITY_CONSTRAINED'|'NOT_SUBSCRIBED'|'DEPRECATED',
'UpdateToken': 'string'
}
},
'NatGatewayAttachments': [
{
'NatGatewayId': 'string',
'Status': 'CREATING'|'READY'|'UPDATING'|'FAILED'|'DELETING',
'StatusMessage': 'string',
'DnsName': 'string'
},
]
}
},
'CapacityUsageSummary': {
'CIDRs': {
'AvailableCIDRCount': 123,
'UtilizedCIDRCount': 123,
'IPSetReferences': {
'string': {
'ResolvedCIDRCount': 123
}
}
}
},
'TransitGatewayAttachmentSyncState': {
'AttachmentId': 'string',
'TransitGatewayAttachmentStatus': 'CREATING'|'DELETING'|'DELETED'|'FAILED'|'ERROR'|'READY'|'PENDING_ACCEPTANCE'|'REJECTING'|'REJECTED',
'StatusMessage': 'string'
}
}
}
Response Structure
(dict) --
Firewall (dict) --
The configuration settings for the firewall. These settings include the firewall policy and the subnets in your VPC to use for the firewall endpoints.
FirewallName (string) --
The descriptive name of the firewall. You can't change the name of a firewall after you create it.
FirewallArn (string) --
The Amazon Resource Name (ARN) of the firewall.
FirewallPolicyArn (string) --
The Amazon Resource Name (ARN) of the firewall policy.
The relationship of firewall to firewall policy is many to one. Each firewall requires one firewall policy association, and you can use the same firewall policy for multiple firewalls.
VpcId (string) --
The unique identifier of the VPC where the firewall is in use.
SubnetMappings (list) --
The primary public subnets that Network Firewall is using for the firewall. Network Firewall creates a firewall endpoint in each subnet. Create a subnet mapping for each Availability Zone where you want to use the firewall.
These subnets are all defined for a single, primary VPC, and each must belong to a different Availability Zone. Each of these subnets establishes the availability of the firewall in its Availability Zone.
In addition to these subnets, you can define other endpoints for the firewall in VpcEndpointAssociation resources. You can define these additional endpoints for any VPC, and for any of the Availability Zones where the firewall resource already has a subnet mapping. VPC endpoint associations give you the ability to protect multiple VPCs using a single firewall, and to define multiple firewall endpoints for a VPC in a single Availability Zone.
(dict) --
The ID for a subnet that's used in an association with a firewall. This is used in CreateFirewall, AssociateSubnets, and CreateVpcEndpointAssociation. Network Firewall creates an instance of the associated firewall in each subnet that you specify, to filter traffic in the subnet's Availability Zone.
SubnetId (string) --
The unique identifier for the subnet.
IPAddressType (string) --
The subnet's IP address type. You can't change the IP address type after you create the subnet.
DeleteProtection (boolean) --
A flag indicating whether it is possible to delete the firewall. A setting of TRUE indicates that the firewall is protected against deletion. Use this setting to protect against accidentally deleting a firewall that is in use. When you create a firewall, the operation initializes this flag to TRUE.
SubnetChangeProtection (boolean) --
A setting indicating whether the firewall is protected against changes to the subnet associations. Use this setting to protect against accidentally modifying the subnet associations for a firewall that is in use. When you create a firewall, the operation initializes this setting to TRUE.
FirewallPolicyChangeProtection (boolean) --
A setting indicating whether the firewall is protected against a change to the firewall policy association. Use this setting to protect against accidentally modifying the firewall policy for a firewall that is in use. When you create a firewall, the operation initializes this setting to TRUE.
Description (string) --
A description of the firewall.
FirewallId (string) --
The unique identifier for the firewall.
Tags (list) --
(dict) --
A key:value pair associated with an Amazon Web Services resource. The key:value pair can be anything you define. Typically, the tag key represents a category (such as "environment") and the tag value represents a specific value within that category (such as "test," "development," or "production"). You can add up to 50 tags to each Amazon Web Services resource.
Key (string) --
The part of the key:value pair that defines a tag. You can use a tag key to describe a category of information, such as "customer." Tag keys are case-sensitive.
Value (string) --
The part of the key:value pair that defines a tag. You can use a tag value to describe a specific value within a category, such as "companyA" or "companyB." Tag values are case-sensitive.
EncryptionConfiguration (dict) --
A complex type that contains the Amazon Web Services KMS encryption configuration settings for your firewall.
KeyId (string) --
The ID of the Amazon Web Services Key Management Service (KMS) customer managed key. You can use any of the key identifiers that KMS supports, unless you're using a key that's managed by another account. If you're using a key managed by another account, then specify the key ARN. For more information, see Key ID in the Amazon Web Services KMS Developer Guide.
Type (string) --
The type of Amazon Web Services KMS key to use for encryption of your Network Firewall resources.
NumberOfAssociations (integer) --
The number of VpcEndpointAssociation resources that use this firewall.
EnabledAnalysisTypes (list) --
An optional setting indicating the specific traffic analysis types to enable on the firewall.
(string) --
TransitGatewayId (string) --
The unique identifier of the transit gateway associated with this firewall. This field is only present for transit gateway-attached firewalls.
TransitGatewayOwnerAccountId (string) --
The Amazon Web Services account ID that owns the transit gateway. This may be different from the firewall owner's account ID when using a shared transit gateway.
AvailabilityZoneMappings (list) --
The Availability Zones where the firewall endpoints are created for a transit gateway-attached firewall. Each mapping specifies an Availability Zone where the firewall processes traffic.
(dict) --
Defines the mapping between an Availability Zone and a firewall endpoint for a transit gateway-attached firewall. Each mapping represents where the firewall can process traffic. You use these mappings when calling CreateFirewall, AssociateAvailabilityZones, and DisassociateAvailabilityZones.
To retrieve the current Availability Zone mappings for a firewall, use DescribeFirewall.
AvailabilityZone (string) --
The ID of the Availability Zone where the firewall endpoint is located. For example, us-east-2a. The Availability Zone must be in the same Region as the transit gateway.
AvailabilityZoneChangeProtection (boolean) --
A setting indicating whether the firewall is protected against changes to its Availability Zone configuration. When set to TRUE, you must first disable this protection before adding or removing Availability Zones.
NatGatewayCreateMappings (list) --
The NAT gateways that you specified for Network Firewall to create for a proxy mode firewall. To get the IDs and status of the NAT gateways that are attached to the firewall, see NatGatewayAttachments in the firewall's SyncStates.
(dict) --
A NAT gateway that Network Firewall creates for a proxy mode firewall in one Availability Zone. You use this in CreateFirewall and AssociateSubnets.
To create a public NAT gateway, specify AllocationIds, and one PrivateIps address for each Elastic IP address. To create a private NAT gateway, specify only PrivateIps. You must specify at least one of them. Each Elastic IP address and private IP address can appear only once in a request.
The NAT gateway is a resource in your account. To change its IP addresses, use Amazon EC2 NAT gateway actions.
SubnetId (string) --
The ID of the subnet where Network Firewall creates the NAT gateway. The subnet must be in the firewall's VPC and can't be one of the firewall endpoint subnets. Each mapping must be in a different Availability Zone.
AllocationIds (list) --
The allocation IDs of the Elastic IP addresses for a public NAT gateway, from 1 to 8. For each allocation ID, specify one address in PrivateIps. If you don't specify this, Network Firewall creates a private NAT gateway.
(string) --
PrivateIps (list) --
The private IPv4 addresses of the NAT gateway. The addresses must be in the subnet that you specify and can't be the subnet's reserved addresses.
For a public NAT gateway, you must specify exactly one address for each Elastic IP address in AllocationIds, even if you specify only one. For a private NAT gateway, specify from 1 to 8 addresses. The first address is the primary address.
(string) --
ProxySettings (dict) --
The proxy settings of a proxy mode firewall: its listeners and, if you specified them, your own CertificateArn and DomainName.
ListenerProperties (list) --
The listeners of the firewall's proxy. Specify at least one listener, and at most one HTTP listener and one HTTPS listener. Each listener needs a port from 1 to 65535, and the two listeners must use different ports.
If you don't specify listeners when you create the firewall, the firewall listens for HTTP on port 3128 and HTTPS on port 8443.
(dict) --
Open port for taking HTTP or HTTPS traffic.
Port (integer) --
Port for processing traffic.
Type (string) --
Selection of HTTP or HTTPS traffic.
CertificateArn (string) --
The Amazon Resource Name (ARN) of the certificate that the firewall's HTTPS proxy listener presents to clients. The certificate must be an Certificate Manager (ACM) certificate in the same account and Region as the firewall. Its subject alternative names must cover DomainName, either exactly or with a wildcard that matches exactly one label. For example, *.example.com covers proxy.example.com. If you don't specify this, Network Firewall uses a certificate that it manages for a domain name that it generates.
You manage and renew the certificate in ACM, and Network Firewall uses renewed certificates automatically. While the firewall uses the certificate, you can't delete it from ACM. Your clients must trust the certificate's certificate authority.
If you specify CertificateArn, you must also specify DomainName. You can set them only when you create the firewall. When you call UpdateProxySettings, specify the same values.
DomainName (string) --
The domain name that your clients use to reach the firewall's proxy. The name must have at least two labels and at most 253 characters. It can't contain a wildcard or use the proxy-id.nfw.region.amazonaws.com format, and the certificate in CertificateArn must cover it. If you don't specify this, Network Firewall generates a domain name.
Network Firewall creates the Route 53 private hosted zones that resolve this name to the firewall endpoints, so you don't need to configure DNS. A VPC can have only one private hosted zone with a given name. If a VPC that the firewall serves already has one with this name, Network Firewall can't set up the Availability Zones in that VPC.
If you specify DomainName, you must also specify CertificateArn. You can set them only when you create the firewall. When you call UpdateProxySettings, specify the same values.
VpcEndpoint (dict) --
The VPC and subnets for the endpoints of a proxy mode firewall.
VpcId (string) --
The ID of the VPC where Network Firewall creates the endpoints and NAT gateways of a proxy mode firewall.
SubnetMappings (list) --
The subnets where Network Firewall creates the firewall endpoints of a proxy mode firewall. Specify one subnet for each Availability Zone, and a NAT gateway mapping in each of those Availability Zones.
(dict) --
The ID for a subnet that's used in an association with a firewall. This is used in CreateFirewall, AssociateSubnets, and CreateVpcEndpointAssociation. Network Firewall creates an instance of the associated firewall in each subnet that you specify, to filter traffic in the subnet's Availability Zone.
SubnetId (string) --
The unique identifier for the subnet.
IPAddressType (string) --
The subnet's IP address type. You can't change the IP address type after you create the subnet.
TransparentFilteringNatScope (string) --
How a proxy mode firewall handles traffic that isn't sent to its proxy listener. NAT_ALL sends this traffic out through the firewall's NAT gateway after inspection. NAT_NONE returns it to the firewall endpoint without address translation.
FirewallStatus (dict) --
Detailed information about the current status of a Firewall. You can retrieve this for a firewall by calling DescribeFirewall and providing the firewall name and ARN.
The firewall status indicates a combined status. It indicates whether all subnets are up-to-date with the latest firewall configurations, which is based on the sync states config values, and also whether all subnets have their endpoints fully enabled, based on their sync states attachment values.
Status (string) --
The readiness of the configured firewall to handle network traffic across all of the Availability Zones where you have it configured. This setting is READY only when the ConfigurationSyncStateSummary value is IN_SYNC and the Attachment Status values for all of the configured subnets are READY.
ConfigurationSyncStateSummary (string) --
The configuration sync state for the firewall. This summarizes the Config settings in the SyncStates for this firewall status object.
When you create a firewall or update its configuration, for example by adding a rule group to its firewall policy, Network Firewall distributes the configuration changes to all Availability Zones that have subnets defined for the firewall. This summary indicates whether the configuration changes have been applied everywhere.
This status must be IN_SYNC for the firewall to be ready for use, but it doesn't indicate that the firewall is ready. The Status setting indicates firewall readiness. It's based on this setting and the readiness of the firewall endpoints to take traffic.
SyncStates (dict) --
Status for the subnets that you've configured in the firewall. This contains one array element per Availability Zone where you've configured a subnet in the firewall.
These objects provide detailed information for the settings ConfigurationSyncStateSummary and Status.
(string) --
(dict) --
The status of the firewall endpoint and firewall policy configuration for a single VPC subnet. This is part of the FirewallStatus.
For each VPC subnet that you associate with a firewall, Network Firewall does the following:
Instantiates a firewall endpoint in the subnet, ready to take traffic.
Configures the endpoint with the current firewall policy settings, to provide the filtering behavior for the endpoint.
When you update a firewall, for example to add a subnet association or change a rule group in the firewall policy, the affected sync states reflect out-of-sync or not ready status until the changes are complete.
Attachment (dict) --
The configuration and status for a single firewall subnet. For each configured subnet, Network Firewall creates the attachment by instantiating the firewall endpoint in the subnet so that it's ready to take traffic.
SubnetId (string) --
The unique identifier of the subnet that you've specified to be used for a firewall endpoint.
EndpointId (string) --
The identifier of the firewall endpoint that Network Firewall has instantiated in the subnet. You use this to identify the firewall endpoint in the VPC route tables, when you redirect the VPC traffic through the endpoint.
Status (string) --
The current status of the firewall endpoint instantiation in the subnet.
When this value is READY, the endpoint is available to handle network traffic. Otherwise, this value reflects its state, for example CREATING or DELETING.
StatusMessage (string) --
If Network Firewall fails to create or delete the firewall endpoint in the subnet, it populates this with the reason for the error or failure and how to resolve it. A FAILED status indicates a non-recoverable state, and a ERROR status indicates an issue that you can fix. Depending on the error, it can take as many as 15 minutes to populate this field. For more information about the causes for failiure or errors and solutions available for this field, see Troubleshooting firewall endpoint failures in the Network Firewall Developer Guide.
DnsName (string) --
The proxy DNS name of a proxy mode firewall. Your clients send proxy requests to the firewall at this name. It's your ProxySettings DomainName if you specified one, or a name that Network Firewall generates in the format proxy-id.nfw.region.amazonaws.com.
The firewall has one proxy DNS name for every Availability Zone and VPC that it serves. In each Availability Zone, the name resolves to the firewall endpoint in that Availability Zone, so traffic stays in your client's Availability Zone. Your clients must use the VPC's Route 53 Resolver.
Config (dict) --
The configuration status of the firewall endpoint in a single VPC subnet. Network Firewall provides each endpoint with the rules that are configured in the firewall policy. Each time you add a subnet or modify the associated firewall policy, Network Firewall synchronizes the rules in the endpoint, so it can properly filter network traffic.
(string) --
(dict) --
Provides configuration status for a single policy or rule group that is used for a firewall endpoint. Network Firewall provides each endpoint with the rules that are configured in the firewall policy. Each time you add a subnet or modify the associated firewall policy, Network Firewall synchronizes the rules in the endpoint, so it can properly filter network traffic. This is part of a SyncState for a firewall.
SyncStatus (string) --
Indicates whether this object is in sync with the version indicated in the update token.
UpdateToken (string) --
The current version of the object that is either in sync or pending synchronization.
NatGatewayAttachments (list) --
The NAT gateway that's attached to a proxy mode firewall in the Availability Zone, and the status of the attachment. To get NAT gateway details, such as IP addresses, use the Amazon EC2 DescribeNatGateways action.
A proxy mode firewall is READY when at least one Availability Zone's firewall endpoint and NAT gateway attachment are READY.
(dict) --
The NAT gateway that's attached to a proxy mode firewall in an Availability Zone, and the status of the attachment. Traffic that the firewall allows in the Availability Zone leaves through this NAT gateway.
NatGatewayId (string) --
The ID of the NAT gateway.
Status (string) --
The status of the NAT gateway attachment. READY means that the NAT gateway is attached and the firewall can send traffic through it. Other values are CREATING, UPDATING, DELETING, and FAILED.
StatusMessage (string) --
The reason that Network Firewall couldn't create or attach the NAT gateway, if it couldn't.
DnsName (string) --
The proxy DNS name of the firewall in this Availability Zone. This is the same as the DnsName of the firewall's Attachment.
CapacityUsageSummary (dict) --
Describes the capacity usage of the resources contained in a firewall's reference sets. Network Firewall calculates the capacity usage by taking an aggregated count of all of the resources used by all of the reference sets in a firewall.
CIDRs (dict) --
Describes the capacity usage of the CIDR blocks used by the IP set references in a firewall.
AvailableCIDRCount (integer) --
The number of CIDR blocks available for use by the IP set references in a firewall.
UtilizedCIDRCount (integer) --
The number of CIDR blocks used by the IP set references in a firewall.
IPSetReferences (dict) --
The list of the IP set references used by a firewall.
(string) --
(dict) --
General information about the IP set.
ResolvedCIDRCount (integer) --
Describes the total number of CIDR blocks currently in use by the IP set references in a firewall. To determine how many CIDR blocks are available for you to use in a firewall, you can call AvailableCIDRCount.
TransitGatewayAttachmentSyncState (dict) --
The synchronization state of the transit gateway attachment. This indicates whether the firewall's transit gateway configuration is properly synchronized and operational. Use this to verify that your transit gateway configuration changes have been applied.
AttachmentId (string) --
The unique identifier of the transit gateway attachment.
TransitGatewayAttachmentStatus (string) --
The current status of the transit gateway attachment.
Valid values are:
CREATING - The attachment is being created
DELETING - The attachment is being deleted
DELETED - The attachment has been deleted
FAILED - The attachment creation has failed and cannot be recovered
ERROR - The attachment is in an error state that might be recoverable
READY - The attachment is active and processing traffic
PENDING_ACCEPTANCE - The attachment is waiting to be accepted
REJECTING - The attachment is in the process of being rejected
REJECTED - The attachment has been rejected
StatusMessage (string) --
A message providing additional information about the current status, particularly useful when the transit gateway attachment is in a non- READY state.
Valid values are:
CREATING - The attachment is being created
DELETING - The attachment is being deleted
DELETED - The attachment has been deleted
FAILED - The attachment creation has failed and cannot be recovered
ERROR - The attachment is in an error state that might be recoverable
READY - The attachment is active and processing traffic
PENDING_ACCEPTANCE - The attachment is waiting to be accepted
REJECTING - The attachment is in the process of being rejected
REJECTED - The attachment has been rejected
For information about troubleshooting endpoint failures, see Troubleshooting firewall endpoint failures in the Network Firewall Developer Guide.
{'TLSInspectionConfiguration': {'ServerCertificateConfigurations': {'DefaultDecryptionBehavior': 'DECRYPT '
'| '
'BYPASS',
'Scopes': {'DecryptionAction': 'DECRYPT '
'| '
'BYPASS',
'DeploymentMode': 'TRANSPARENT_FIREWALL_ONLY '
'| '
'EXPLICIT_PROXY_ONLY '
'| '
'ALL',
'DomainMatch': {'Domains': ['string']}}}}}
Creates an Network Firewall TLS inspection configuration. Network Firewall uses TLS inspection configurations to decrypt your firewall's inbound and outbound SSL/TLS traffic. After decryption, Network Firewall inspects the traffic according to your firewall policy's stateful rules, and then re-encrypts it before sending it to its destination. You can enable inspection of your firewall's inbound traffic, outbound traffic, or both. To use TLS inspection with your firewall, you must first import or provision certificates using ACM, create a TLS inspection configuration, add that configuration to a new firewall policy, and then associate that policy with your firewall.
To update the settings for a TLS inspection configuration, use UpdateTLSInspectionConfiguration.
To manage a TLS inspection configuration's tags, use the standard Amazon Web Services resource tagging operations, ListTagsForResource, TagResource, and UntagResource.
To retrieve information about TLS inspection configurations, use ListTLSInspectionConfigurations and DescribeTLSInspectionConfiguration.
For more information about TLS inspection configurations, see Inspecting SSL/TLS traffic with TLS inspection configurations in the Network Firewall Developer Guide.
See also: AWS API Documentation
Request Syntax
client.create_tls_inspection_configuration(
TLSInspectionConfigurationName='string',
TLSInspectionConfiguration={
'ServerCertificateConfigurations': [
{
'ServerCertificates': [
{
'ResourceArn': 'string'
},
],
'Scopes': [
{
'Sources': [
{
'AddressDefinition': 'string'
},
],
'Destinations': [
{
'AddressDefinition': 'string'
},
],
'SourcePorts': [
{
'FromPort': 123,
'ToPort': 123
},
],
'DestinationPorts': [
{
'FromPort': 123,
'ToPort': 123
},
],
'Protocols': [
123,
],
'DomainMatch': {
'Domains': [
'string',
]
},
'DecryptionAction': 'DECRYPT'|'BYPASS',
'DeploymentMode': 'TRANSPARENT_FIREWALL_ONLY'|'EXPLICIT_PROXY_ONLY'|'ALL'
},
],
'CertificateAuthorityArn': 'string',
'CheckCertificateRevocationStatus': {
'RevokedStatusAction': 'PASS'|'DROP'|'REJECT',
'UnknownStatusAction': 'PASS'|'DROP'|'REJECT'
},
'DefaultDecryptionBehavior': 'DECRYPT'|'BYPASS'
},
]
},
Description='string',
Tags=[
{
'Key': 'string',
'Value': 'string'
},
],
EncryptionConfiguration={
'KeyId': 'string',
'Type': 'CUSTOMER_KMS'|'AWS_OWNED_KMS_KEY'
}
)
string
[REQUIRED]
The descriptive name of the TLS inspection configuration. You can't change the name of a TLS inspection configuration after you create it.
dict
[REQUIRED]
The object that defines a TLS inspection configuration. This, along with TLSInspectionConfigurationResponse, define the TLS inspection configuration. You can retrieve all objects for a TLS inspection configuration by calling DescribeTLSInspectionConfiguration.
Network Firewall uses a TLS inspection configuration to decrypt traffic. Network Firewall re-encrypts the traffic before sending it to its destination.
To use a TLS inspection configuration, you add it to a new Network Firewall firewall policy, then you apply the firewall policy to a firewall. Network Firewall acts as a proxy service to decrypt and inspect the traffic traveling through your firewalls. You can reference a TLS inspection configuration from more than one firewall policy, and you can use a firewall policy in more than one firewall. For more information about using TLS inspection configurations, see Inspecting SSL/TLS traffic with TLS inspection configurations in the Network Firewall Developer Guide.
ServerCertificateConfigurations (list) --
Lists the server certificate configurations that are associated with the TLS configuration.
(dict) --
Configures the Certificate Manager certificates and scope that Network Firewall uses to decrypt and re-encrypt traffic using a TLSInspectionConfiguration. You can configure ServerCertificates for inbound SSL/TLS inspection, a CertificateAuthorityArn for outbound SSL/TLS inspection, or both. For information about working with certificates for TLS inspection, see Using SSL/TLS server certficiates with TLS inspection configurations in the Network Firewall Developer Guide.
ServerCertificates (list) --
The list of server certificates to use for inbound SSL/TLS inspection.
(dict) --
Any Certificate Manager (ACM) Secure Sockets Layer/Transport Layer Security (SSL/TLS) server certificate that's associated with a ServerCertificateConfiguration. Used in a TLSInspectionConfiguration for inspection of inbound traffic to your firewall. You must request or import a SSL/TLS certificate into ACM for each domain Network Firewall needs to decrypt and inspect. Network Firewall uses the SSL/TLS certificates to decrypt specified inbound SSL/TLS traffic going to your firewall. For information about working with certificates in Certificate Manager, see Request a public certificate or Importing certificates in the Certificate Manager User Guide.
ResourceArn (string) --
The Amazon Resource Name (ARN) of the Certificate Manager SSL/TLS server certificate that's used for inbound SSL/TLS inspection.
Scopes (list) --
A list of scopes.
(dict) --
Settings that define the Secure Sockets Layer/Transport Layer Security (SSL/TLS) traffic that Network Firewall should decrypt for inspection by the stateful rule engine.
Sources (list) --
The source IP addresses and address ranges to decrypt for inspection, in CIDR notation. If not specified, this matches with any source address.
(dict) --
A single IP address specification. This is used in the MatchAttributes source and destination specifications.
AddressDefinition (string) -- [REQUIRED]
Specify an IP address or a block of IP addresses in Classless Inter-Domain Routing (CIDR) notation. Network Firewall supports all address ranges for IPv4 and IPv6.
Examples:
To configure Network Firewall to inspect for the IP address 192.0.2.44, specify 192.0.2.44/32.
To configure Network Firewall to inspect for IP addresses from 192.0.2.0 to 192.0.2.255, specify 192.0.2.0/24.
To configure Network Firewall to inspect for the IP address 1111:0000:0000:0000:0000:0000:0000:0111, specify 1111:0000:0000:0000:0000:0000:0000:0111/128.
To configure Network Firewall to inspect for IP addresses from 1111:0000:0000:0000:0000:0000:0000:0000 to 1111:0000:0000:0000:ffff:ffff:ffff:ffff, specify 1111:0000:0000:0000:0000:0000:0000:0000/64.
For more information about CIDR notation, see the Wikipedia entry Classless Inter-Domain Routing.
Destinations (list) --
The destination IP addresses and address ranges to decrypt for inspection, in CIDR notation. If not specified, this matches with any destination address.
(dict) --
A single IP address specification. This is used in the MatchAttributes source and destination specifications.
AddressDefinition (string) -- [REQUIRED]
Specify an IP address or a block of IP addresses in Classless Inter-Domain Routing (CIDR) notation. Network Firewall supports all address ranges for IPv4 and IPv6.
Examples:
To configure Network Firewall to inspect for the IP address 192.0.2.44, specify 192.0.2.44/32.
To configure Network Firewall to inspect for IP addresses from 192.0.2.0 to 192.0.2.255, specify 192.0.2.0/24.
To configure Network Firewall to inspect for the IP address 1111:0000:0000:0000:0000:0000:0000:0111, specify 1111:0000:0000:0000:0000:0000:0000:0111/128.
To configure Network Firewall to inspect for IP addresses from 1111:0000:0000:0000:0000:0000:0000:0000 to 1111:0000:0000:0000:ffff:ffff:ffff:ffff, specify 1111:0000:0000:0000:0000:0000:0000:0000/64.
For more information about CIDR notation, see the Wikipedia entry Classless Inter-Domain Routing.
SourcePorts (list) --
The source ports to decrypt for inspection, in Transmission Control Protocol (TCP) format. If not specified, this matches with any source port.
You can specify individual ports, for example 1994, and you can specify port ranges, such as 1990:1994.
(dict) --
A single port range specification. This is used for source and destination port ranges in the stateless rule MatchAttributes, SourcePorts, and DestinationPorts settings.
FromPort (integer) -- [REQUIRED]
The lower limit of the port range. This must be less than or equal to the ToPort specification.
ToPort (integer) -- [REQUIRED]
The upper limit of the port range. This must be greater than or equal to the FromPort specification.
DestinationPorts (list) --
The destination ports to decrypt for inspection, in Transmission Control Protocol (TCP) format. If not specified, this matches with any destination port.
You can specify individual ports, for example 1994, and you can specify port ranges, such as 1990:1994.
(dict) --
A single port range specification. This is used for source and destination port ranges in the stateless rule MatchAttributes, SourcePorts, and DestinationPorts settings.
FromPort (integer) -- [REQUIRED]
The lower limit of the port range. This must be less than or equal to the ToPort specification.
ToPort (integer) -- [REQUIRED]
The upper limit of the port range. This must be greater than or equal to the FromPort specification.
Protocols (list) --
The protocols to inspect for, specified using the assigned internet protocol number (IANA) for each protocol. If not specified, this matches with any protocol.
Network Firewall currently supports only TCP.
(integer) --
DomainMatch (dict) --
The domains that this scope matches, based on the host name in the client's HTTP CONNECT request. Domain matching applies only to proxy mode firewalls. If you specify DomainMatch, you must set DeploymentMode to EXPLICIT_PROXY_ONLY. If you don't specify DomainMatch, the scope matches traffic by its source, destination, ports, and protocols only.
Domains (list) -- [REQUIRED]
The domains to match. You can specify an exact domain, such as example.com, or a domain with a single leading wildcard label, such as *.example.com. You can specify from 1 to 50 domains, and each domain can be up to 255 characters long.
(string) --
DecryptionAction (string) --
Whether the firewall decrypts traffic that matches this scope. You can choose from the following values:
DECRYPT - The firewall decrypts the traffic for inspection.
BYPASS - The firewall doesn't decrypt the traffic.
DeploymentMode (string) --
The type of firewall that this scope applies to. If you don't specify a value, the scope applies to both types, the same as ALL. You can choose from the following values:
ALL - The scope applies to both transparent firewalls and proxy mode firewalls.
TRANSPARENT_FIREWALL_ONLY - The scope applies only to transparent firewalls.
EXPLICIT_PROXY_ONLY - The scope applies only to proxy mode firewalls. A scope that specifies DomainMatch must use this value.
CertificateAuthorityArn (string) --
The Amazon Resource Name (ARN) of the imported certificate authority (CA) certificate within Certificate Manager (ACM) to use for outbound SSL/TLS inspection.
The following limitations apply:
You can use CA certificates that you imported into ACM, but you can't generate CA certificates with ACM.
You can't use certificates issued by Private Certificate Authority.
For more information about configuring certificates for outbound inspection, see Using SSL/TLS certificates with TLS inspection configurations in the Network Firewall Developer Guide.
For information about working with certificates in ACM, see Importing certificates in the Certificate Manager User Guide.
CheckCertificateRevocationStatus (dict) --
When enabled, Network Firewall checks if the server certificate presented by the server in the SSL/TLS connection has a revoked or unkown status. If the certificate has an unknown or revoked status, you must specify the actions that Network Firewall takes on outbound traffic. To check the certificate revocation status, you must also specify a CertificateAuthorityArn in ServerCertificateConfiguration.
RevokedStatusAction (string) --
Configures how Network Firewall processes traffic when it determines that the certificate presented by the server in the SSL/TLS connection has a revoked status.
PASS - Allow the connection to continue, and pass subsequent packets to the stateful engine for inspection.
DROP - Network Firewall closes the connection and drops subsequent packets for that connection.
REJECT - Network Firewall sends a TCP reject packet back to your client. The service closes the connection and drops subsequent packets for that connection. REJECT is available only for TCP traffic.
UnknownStatusAction (string) --
Configures how Network Firewall processes traffic when it determines that the certificate presented by the server in the SSL/TLS connection has an unknown status, or a status that cannot be determined for any other reason, including when the service is unable to connect to the OCSP and CRL endpoints for the certificate.
PASS - Allow the connection to continue, and pass subsequent packets to the stateful engine for inspection.
DROP - Network Firewall closes the connection and drops subsequent packets for that connection.
REJECT - Network Firewall sends a TCP reject packet back to your client. The service closes the connection and drops subsequent packets for that connection. REJECT is available only for TCP traffic.
DefaultDecryptionBehavior (string) --
What the firewall does with SSL/TLS traffic that doesn't match any scope in this server certificate configuration. This setting applies only to proxy mode firewalls. If you don't specify a value, the firewall uses BYPASS. You can choose from the following values:
BYPASS - The firewall doesn't decrypt the traffic.
DECRYPT - The firewall decrypts the traffic for inspection. You can use DECRYPT only if every scope in the configuration sets DeploymentMode to EXPLICIT_PROXY_ONLY.
string
A description of the TLS inspection configuration.
list
The key:value pairs to associate with the resource.
(dict) --
A key:value pair associated with an Amazon Web Services resource. The key:value pair can be anything you define. Typically, the tag key represents a category (such as "environment") and the tag value represents a specific value within that category (such as "test," "development," or "production"). You can add up to 50 tags to each Amazon Web Services resource.
Key (string) -- [REQUIRED]
The part of the key:value pair that defines a tag. You can use a tag key to describe a category of information, such as "customer." Tag keys are case-sensitive.
Value (string) -- [REQUIRED]
The part of the key:value pair that defines a tag. You can use a tag value to describe a specific value within a category, such as "companyA" or "companyB." Tag values are case-sensitive.
dict
A complex type that contains optional Amazon Web Services Key Management Service (KMS) encryption settings for your Network Firewall resources. Your data is encrypted by default with an Amazon Web Services owned key that Amazon Web Services owns and manages for you. You can use either the Amazon Web Services owned key, or provide your own customer managed key. To learn more about KMS encryption of your Network Firewall resources, see Encryption at rest with Amazon Web Services Key Managment Service in the Network Firewall Developer Guide.
KeyId (string) --
The ID of the Amazon Web Services Key Management Service (KMS) customer managed key. You can use any of the key identifiers that KMS supports, unless you're using a key that's managed by another account. If you're using a key managed by another account, then specify the key ARN. For more information, see Key ID in the Amazon Web Services KMS Developer Guide.
Type (string) -- [REQUIRED]
The type of Amazon Web Services KMS key to use for encryption of your Network Firewall resources.
dict
Response Syntax
{
'UpdateToken': 'string',
'TLSInspectionConfigurationResponse': {
'TLSInspectionConfigurationArn': 'string',
'TLSInspectionConfigurationName': 'string',
'TLSInspectionConfigurationId': 'string',
'TLSInspectionConfigurationStatus': 'ACTIVE'|'DELETING'|'ERROR'|'UPDATING',
'Description': 'string',
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
],
'LastModifiedTime': datetime(2015, 1, 1),
'NumberOfAssociations': 123,
'EncryptionConfiguration': {
'KeyId': 'string',
'Type': 'CUSTOMER_KMS'|'AWS_OWNED_KMS_KEY'
},
'Certificates': [
{
'CertificateArn': 'string',
'CertificateSerial': 'string',
'Status': 'string',
'StatusMessage': 'string'
},
],
'CertificateAuthority': {
'CertificateArn': 'string',
'CertificateSerial': 'string',
'Status': 'string',
'StatusMessage': 'string'
}
}
}
Response Structure
(dict) --
UpdateToken (string) --
A token used for optimistic locking. Network Firewall returns a token to your requests that access the TLS inspection configuration. The token marks the state of the TLS inspection configuration resource at the time of the request.
To make changes to the TLS inspection configuration, you provide the token in your request. Network Firewall uses the token to ensure that the TLS inspection configuration hasn't changed since you last retrieved it. If it has changed, the operation fails with an InvalidTokenException. If this happens, retrieve the TLS inspection configuration again to get a current copy of it with a current token. Reapply your changes as needed, then try the operation again using the new token.
TLSInspectionConfigurationResponse (dict) --
The high-level properties of a TLS inspection configuration. This, along with the TLSInspectionConfiguration, define the TLS inspection configuration. You can retrieve all objects for a TLS inspection configuration by calling DescribeTLSInspectionConfiguration.
TLSInspectionConfigurationArn (string) --
The Amazon Resource Name (ARN) of the TLS inspection configuration.
TLSInspectionConfigurationName (string) --
The descriptive name of the TLS inspection configuration. You can't change the name of a TLS inspection configuration after you create it.
TLSInspectionConfigurationId (string) --
A unique identifier for the TLS inspection configuration. This ID is returned in the responses to create and list commands. You provide it to operations such as update and delete.
TLSInspectionConfigurationStatus (string) --
Detailed information about the current status of a TLSInspectionConfiguration. You can retrieve this for a TLS inspection configuration by calling DescribeTLSInspectionConfiguration and providing the TLS inspection configuration name and ARN.
Description (string) --
A description of the TLS inspection configuration.
Tags (list) --
The key:value pairs to associate with the resource.
(dict) --
A key:value pair associated with an Amazon Web Services resource. The key:value pair can be anything you define. Typically, the tag key represents a category (such as "environment") and the tag value represents a specific value within that category (such as "test," "development," or "production"). You can add up to 50 tags to each Amazon Web Services resource.
Key (string) --
The part of the key:value pair that defines a tag. You can use a tag key to describe a category of information, such as "customer." Tag keys are case-sensitive.
Value (string) --
The part of the key:value pair that defines a tag. You can use a tag value to describe a specific value within a category, such as "companyA" or "companyB." Tag values are case-sensitive.
LastModifiedTime (datetime) --
The last time that the TLS inspection configuration was changed.
NumberOfAssociations (integer) --
The number of firewall policies that use this TLS inspection configuration.
EncryptionConfiguration (dict) --
A complex type that contains the Amazon Web Services KMS encryption configuration settings for your TLS inspection configuration.
KeyId (string) --
The ID of the Amazon Web Services Key Management Service (KMS) customer managed key. You can use any of the key identifiers that KMS supports, unless you're using a key that's managed by another account. If you're using a key managed by another account, then specify the key ARN. For more information, see Key ID in the Amazon Web Services KMS Developer Guide.
Type (string) --
The type of Amazon Web Services KMS key to use for encryption of your Network Firewall resources.
Certificates (list) --
A list of the certificates associated with the TLS inspection configuration.
(dict) --
Contains metadata about an Certificate Manager certificate.
CertificateArn (string) --
The Amazon Resource Name (ARN) of the certificate.
CertificateSerial (string) --
The serial number of the certificate.
Status (string) --
The status of the certificate.
StatusMessage (string) --
Contains details about the certificate status, including information about certificate errors.
CertificateAuthority (dict) --
Contains metadata about an Certificate Manager certificate.
CertificateArn (string) --
The Amazon Resource Name (ARN) of the certificate.
CertificateSerial (string) --
The serial number of the certificate.
Status (string) --
The status of the certificate.
StatusMessage (string) --
Contains details about the certificate status, including information about certificate errors.
{'DeleteAssociatedNatGateways': 'boolean'}
Response {'Firewall': {'NatGatewayCreateMappings': [{'AllocationIds': ['string'],
'PrivateIps': ['string'],
'SubnetId': 'string'}],
'ProxySettings': {'CertificateArn': 'string',
'DomainName': 'string'},
'TransparentFilteringNatScope': 'NAT_ALL | NAT_NONE'}}
Deletes the specified Firewall and its FirewallStatus. This operation requires the firewall's DeleteProtection flag to be FALSE. You can't revert this operation.
You can check whether a firewall is in use by reviewing the route tables for the Availability Zones where you have firewall subnet mappings. Retrieve the subnet mappings by calling DescribeFirewall. You define and update the route tables through Amazon VPC. As needed, update the route tables for the zones to remove the firewall endpoints. When the route tables no longer use the firewall endpoints, you can remove the firewall safely.
To delete a firewall, remove the delete protection if you need to using UpdateFirewallDeleteProtection, then delete the firewall by calling DeleteFirewall.
Deleting a proxy mode firewall detaches its NAT gateways. To also delete the NAT gateways that Network Firewall created for the firewall, specify DeleteAssociatedNatGateways.
See also: AWS API Documentation
Request Syntax
client.delete_firewall(
FirewallName='string',
FirewallArn='string',
DeleteAssociatedNatGateways=True|False
)
string
The descriptive name of the firewall. You can't change the name of a firewall after you create it.
You must specify the ARN or the name, and you can specify both.
string
The Amazon Resource Name (ARN) of the firewall.
You must specify the ARN or the name, and you can specify both.
boolean
Specifies whether to delete the NAT gateways that Network Firewall created for a proxy mode firewall when you delete the firewall. You can choose from the following values:
FALSE - Network Firewall detaches the NAT gateways from the firewall and keeps them. This is the default.
TRUE - Network Firewall also deletes the NAT gateways. The firewall status stays DELETING until they're deleted. You need permission to call the Amazon EC2 DeleteNatGateway action.
You can't specify TRUE for a firewall that isn't a proxy mode firewall.
dict
Response Syntax
{
'Firewall': {
'FirewallName': 'string',
'FirewallArn': 'string',
'FirewallPolicyArn': 'string',
'VpcId': 'string',
'SubnetMappings': [
{
'SubnetId': 'string',
'IPAddressType': 'DUALSTACK'|'IPV4'|'IPV6'
},
],
'DeleteProtection': True|False,
'SubnetChangeProtection': True|False,
'FirewallPolicyChangeProtection': True|False,
'Description': 'string',
'FirewallId': 'string',
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
],
'EncryptionConfiguration': {
'KeyId': 'string',
'Type': 'CUSTOMER_KMS'|'AWS_OWNED_KMS_KEY'
},
'NumberOfAssociations': 123,
'EnabledAnalysisTypes': [
'TLS_SNI'|'HTTP_HOST',
],
'TransitGatewayId': 'string',
'TransitGatewayOwnerAccountId': 'string',
'AvailabilityZoneMappings': [
{
'AvailabilityZone': 'string'
},
],
'AvailabilityZoneChangeProtection': True|False,
'NatGatewayCreateMappings': [
{
'SubnetId': 'string',
'AllocationIds': [
'string',
],
'PrivateIps': [
'string',
]
},
],
'ProxySettings': {
'ListenerProperties': [
{
'Port': 123,
'Type': 'HTTP'|'HTTPS'
},
],
'CertificateArn': 'string',
'DomainName': 'string'
},
'VpcEndpoint': {
'VpcId': 'string',
'SubnetMappings': [
{
'SubnetId': 'string',
'IPAddressType': 'DUALSTACK'|'IPV4'|'IPV6'
},
]
},
'TransparentFilteringNatScope': 'NAT_ALL'|'NAT_NONE'
},
'FirewallStatus': {
'Status': 'PROVISIONING'|'DELETING'|'READY'|'FAILED',
'ConfigurationSyncStateSummary': 'PENDING'|'IN_SYNC'|'CAPACITY_CONSTRAINED',
'SyncStates': {
'string': {
'Attachment': {
'SubnetId': 'string',
'EndpointId': 'string',
'Status': 'CREATING'|'DELETING'|'FAILED'|'ERROR'|'SCALING'|'READY',
'StatusMessage': 'string',
'DnsName': 'string'
},
'Config': {
'string': {
'SyncStatus': 'PENDING'|'IN_SYNC'|'CAPACITY_CONSTRAINED'|'NOT_SUBSCRIBED'|'DEPRECATED',
'UpdateToken': 'string'
}
},
'NatGatewayAttachments': [
{
'NatGatewayId': 'string',
'Status': 'CREATING'|'READY'|'UPDATING'|'FAILED'|'DELETING',
'StatusMessage': 'string',
'DnsName': 'string'
},
]
}
},
'CapacityUsageSummary': {
'CIDRs': {
'AvailableCIDRCount': 123,
'UtilizedCIDRCount': 123,
'IPSetReferences': {
'string': {
'ResolvedCIDRCount': 123
}
}
}
},
'TransitGatewayAttachmentSyncState': {
'AttachmentId': 'string',
'TransitGatewayAttachmentStatus': 'CREATING'|'DELETING'|'DELETED'|'FAILED'|'ERROR'|'READY'|'PENDING_ACCEPTANCE'|'REJECTING'|'REJECTED',
'StatusMessage': 'string'
}
}
}
Response Structure
(dict) --
Firewall (dict) --
A firewall defines the behavior of a firewall, the main VPC where the firewall is used, the Availability Zones where the firewall can be used, and one subnet to use for a firewall endpoint within each of the Availability Zones. The Availability Zones are defined implicitly in the subnet specifications.
In addition to the firewall endpoints that you define in this Firewall specification, you can create firewall endpoints in VpcEndpointAssociation resources for any VPC, in any Availability Zone where the firewall is already in use.
The status of the firewall, for example whether it's ready to filter network traffic, is provided in the corresponding FirewallStatus. You can retrieve both the firewall and firewall status by calling DescribeFirewall.
FirewallName (string) --
The descriptive name of the firewall. You can't change the name of a firewall after you create it.
FirewallArn (string) --
The Amazon Resource Name (ARN) of the firewall.
FirewallPolicyArn (string) --
The Amazon Resource Name (ARN) of the firewall policy.
The relationship of firewall to firewall policy is many to one. Each firewall requires one firewall policy association, and you can use the same firewall policy for multiple firewalls.
VpcId (string) --
The unique identifier of the VPC where the firewall is in use.
SubnetMappings (list) --
The primary public subnets that Network Firewall is using for the firewall. Network Firewall creates a firewall endpoint in each subnet. Create a subnet mapping for each Availability Zone where you want to use the firewall.
These subnets are all defined for a single, primary VPC, and each must belong to a different Availability Zone. Each of these subnets establishes the availability of the firewall in its Availability Zone.
In addition to these subnets, you can define other endpoints for the firewall in VpcEndpointAssociation resources. You can define these additional endpoints for any VPC, and for any of the Availability Zones where the firewall resource already has a subnet mapping. VPC endpoint associations give you the ability to protect multiple VPCs using a single firewall, and to define multiple firewall endpoints for a VPC in a single Availability Zone.
(dict) --
The ID for a subnet that's used in an association with a firewall. This is used in CreateFirewall, AssociateSubnets, and CreateVpcEndpointAssociation. Network Firewall creates an instance of the associated firewall in each subnet that you specify, to filter traffic in the subnet's Availability Zone.
SubnetId (string) --
The unique identifier for the subnet.
IPAddressType (string) --
The subnet's IP address type. You can't change the IP address type after you create the subnet.
DeleteProtection (boolean) --
A flag indicating whether it is possible to delete the firewall. A setting of TRUE indicates that the firewall is protected against deletion. Use this setting to protect against accidentally deleting a firewall that is in use. When you create a firewall, the operation initializes this flag to TRUE.
SubnetChangeProtection (boolean) --
A setting indicating whether the firewall is protected against changes to the subnet associations. Use this setting to protect against accidentally modifying the subnet associations for a firewall that is in use. When you create a firewall, the operation initializes this setting to TRUE.
FirewallPolicyChangeProtection (boolean) --
A setting indicating whether the firewall is protected against a change to the firewall policy association. Use this setting to protect against accidentally modifying the firewall policy for a firewall that is in use. When you create a firewall, the operation initializes this setting to TRUE.
Description (string) --
A description of the firewall.
FirewallId (string) --
The unique identifier for the firewall.
Tags (list) --
(dict) --
A key:value pair associated with an Amazon Web Services resource. The key:value pair can be anything you define. Typically, the tag key represents a category (such as "environment") and the tag value represents a specific value within that category (such as "test," "development," or "production"). You can add up to 50 tags to each Amazon Web Services resource.
Key (string) --
The part of the key:value pair that defines a tag. You can use a tag key to describe a category of information, such as "customer." Tag keys are case-sensitive.
Value (string) --
The part of the key:value pair that defines a tag. You can use a tag value to describe a specific value within a category, such as "companyA" or "companyB." Tag values are case-sensitive.
EncryptionConfiguration (dict) --
A complex type that contains the Amazon Web Services KMS encryption configuration settings for your firewall.
KeyId (string) --
The ID of the Amazon Web Services Key Management Service (KMS) customer managed key. You can use any of the key identifiers that KMS supports, unless you're using a key that's managed by another account. If you're using a key managed by another account, then specify the key ARN. For more information, see Key ID in the Amazon Web Services KMS Developer Guide.
Type (string) --
The type of Amazon Web Services KMS key to use for encryption of your Network Firewall resources.
NumberOfAssociations (integer) --
The number of VpcEndpointAssociation resources that use this firewall.
EnabledAnalysisTypes (list) --
An optional setting indicating the specific traffic analysis types to enable on the firewall.
(string) --
TransitGatewayId (string) --
The unique identifier of the transit gateway associated with this firewall. This field is only present for transit gateway-attached firewalls.
TransitGatewayOwnerAccountId (string) --
The Amazon Web Services account ID that owns the transit gateway. This may be different from the firewall owner's account ID when using a shared transit gateway.
AvailabilityZoneMappings (list) --
The Availability Zones where the firewall endpoints are created for a transit gateway-attached firewall. Each mapping specifies an Availability Zone where the firewall processes traffic.
(dict) --
Defines the mapping between an Availability Zone and a firewall endpoint for a transit gateway-attached firewall. Each mapping represents where the firewall can process traffic. You use these mappings when calling CreateFirewall, AssociateAvailabilityZones, and DisassociateAvailabilityZones.
To retrieve the current Availability Zone mappings for a firewall, use DescribeFirewall.
AvailabilityZone (string) --
The ID of the Availability Zone where the firewall endpoint is located. For example, us-east-2a. The Availability Zone must be in the same Region as the transit gateway.
AvailabilityZoneChangeProtection (boolean) --
A setting indicating whether the firewall is protected against changes to its Availability Zone configuration. When set to TRUE, you must first disable this protection before adding or removing Availability Zones.
NatGatewayCreateMappings (list) --
The NAT gateways that you specified for Network Firewall to create for a proxy mode firewall. To get the IDs and status of the NAT gateways that are attached to the firewall, see NatGatewayAttachments in the firewall's SyncStates.
(dict) --
A NAT gateway that Network Firewall creates for a proxy mode firewall in one Availability Zone. You use this in CreateFirewall and AssociateSubnets.
To create a public NAT gateway, specify AllocationIds, and one PrivateIps address for each Elastic IP address. To create a private NAT gateway, specify only PrivateIps. You must specify at least one of them. Each Elastic IP address and private IP address can appear only once in a request.
The NAT gateway is a resource in your account. To change its IP addresses, use Amazon EC2 NAT gateway actions.
SubnetId (string) --
The ID of the subnet where Network Firewall creates the NAT gateway. The subnet must be in the firewall's VPC and can't be one of the firewall endpoint subnets. Each mapping must be in a different Availability Zone.
AllocationIds (list) --
The allocation IDs of the Elastic IP addresses for a public NAT gateway, from 1 to 8. For each allocation ID, specify one address in PrivateIps. If you don't specify this, Network Firewall creates a private NAT gateway.
(string) --
PrivateIps (list) --
The private IPv4 addresses of the NAT gateway. The addresses must be in the subnet that you specify and can't be the subnet's reserved addresses.
For a public NAT gateway, you must specify exactly one address for each Elastic IP address in AllocationIds, even if you specify only one. For a private NAT gateway, specify from 1 to 8 addresses. The first address is the primary address.
(string) --
ProxySettings (dict) --
The proxy settings of a proxy mode firewall: its listeners and, if you specified them, your own CertificateArn and DomainName.
ListenerProperties (list) --
The listeners of the firewall's proxy. Specify at least one listener, and at most one HTTP listener and one HTTPS listener. Each listener needs a port from 1 to 65535, and the two listeners must use different ports.
If you don't specify listeners when you create the firewall, the firewall listens for HTTP on port 3128 and HTTPS on port 8443.
(dict) --
Open port for taking HTTP or HTTPS traffic.
Port (integer) --
Port for processing traffic.
Type (string) --
Selection of HTTP or HTTPS traffic.
CertificateArn (string) --
The Amazon Resource Name (ARN) of the certificate that the firewall's HTTPS proxy listener presents to clients. The certificate must be an Certificate Manager (ACM) certificate in the same account and Region as the firewall. Its subject alternative names must cover DomainName, either exactly or with a wildcard that matches exactly one label. For example, *.example.com covers proxy.example.com. If you don't specify this, Network Firewall uses a certificate that it manages for a domain name that it generates.
You manage and renew the certificate in ACM, and Network Firewall uses renewed certificates automatically. While the firewall uses the certificate, you can't delete it from ACM. Your clients must trust the certificate's certificate authority.
If you specify CertificateArn, you must also specify DomainName. You can set them only when you create the firewall. When you call UpdateProxySettings, specify the same values.
DomainName (string) --
The domain name that your clients use to reach the firewall's proxy. The name must have at least two labels and at most 253 characters. It can't contain a wildcard or use the proxy-id.nfw.region.amazonaws.com format, and the certificate in CertificateArn must cover it. If you don't specify this, Network Firewall generates a domain name.
Network Firewall creates the Route 53 private hosted zones that resolve this name to the firewall endpoints, so you don't need to configure DNS. A VPC can have only one private hosted zone with a given name. If a VPC that the firewall serves already has one with this name, Network Firewall can't set up the Availability Zones in that VPC.
If you specify DomainName, you must also specify CertificateArn. You can set them only when you create the firewall. When you call UpdateProxySettings, specify the same values.
VpcEndpoint (dict) --
The VPC and subnets for the endpoints of a proxy mode firewall.
VpcId (string) --
The ID of the VPC where Network Firewall creates the endpoints and NAT gateways of a proxy mode firewall.
SubnetMappings (list) --
The subnets where Network Firewall creates the firewall endpoints of a proxy mode firewall. Specify one subnet for each Availability Zone, and a NAT gateway mapping in each of those Availability Zones.
(dict) --
The ID for a subnet that's used in an association with a firewall. This is used in CreateFirewall, AssociateSubnets, and CreateVpcEndpointAssociation. Network Firewall creates an instance of the associated firewall in each subnet that you specify, to filter traffic in the subnet's Availability Zone.
SubnetId (string) --
The unique identifier for the subnet.
IPAddressType (string) --
The subnet's IP address type. You can't change the IP address type after you create the subnet.
TransparentFilteringNatScope (string) --
How a proxy mode firewall handles traffic that isn't sent to its proxy listener. NAT_ALL sends this traffic out through the firewall's NAT gateway after inspection. NAT_NONE returns it to the firewall endpoint without address translation.
FirewallStatus (dict) --
Detailed information about the current status of a Firewall. You can retrieve this for a firewall by calling DescribeFirewall and providing the firewall name and ARN.
The firewall status indicates a combined status. It indicates whether all subnets are up-to-date with the latest firewall configurations, which is based on the sync states config values, and also whether all subnets have their endpoints fully enabled, based on their sync states attachment values.
Status (string) --
The readiness of the configured firewall to handle network traffic across all of the Availability Zones where you have it configured. This setting is READY only when the ConfigurationSyncStateSummary value is IN_SYNC and the Attachment Status values for all of the configured subnets are READY.
ConfigurationSyncStateSummary (string) --
The configuration sync state for the firewall. This summarizes the Config settings in the SyncStates for this firewall status object.
When you create a firewall or update its configuration, for example by adding a rule group to its firewall policy, Network Firewall distributes the configuration changes to all Availability Zones that have subnets defined for the firewall. This summary indicates whether the configuration changes have been applied everywhere.
This status must be IN_SYNC for the firewall to be ready for use, but it doesn't indicate that the firewall is ready. The Status setting indicates firewall readiness. It's based on this setting and the readiness of the firewall endpoints to take traffic.
SyncStates (dict) --
Status for the subnets that you've configured in the firewall. This contains one array element per Availability Zone where you've configured a subnet in the firewall.
These objects provide detailed information for the settings ConfigurationSyncStateSummary and Status.
(string) --
(dict) --
The status of the firewall endpoint and firewall policy configuration for a single VPC subnet. This is part of the FirewallStatus.
For each VPC subnet that you associate with a firewall, Network Firewall does the following:
Instantiates a firewall endpoint in the subnet, ready to take traffic.
Configures the endpoint with the current firewall policy settings, to provide the filtering behavior for the endpoint.
When you update a firewall, for example to add a subnet association or change a rule group in the firewall policy, the affected sync states reflect out-of-sync or not ready status until the changes are complete.
Attachment (dict) --
The configuration and status for a single firewall subnet. For each configured subnet, Network Firewall creates the attachment by instantiating the firewall endpoint in the subnet so that it's ready to take traffic.
SubnetId (string) --
The unique identifier of the subnet that you've specified to be used for a firewall endpoint.
EndpointId (string) --
The identifier of the firewall endpoint that Network Firewall has instantiated in the subnet. You use this to identify the firewall endpoint in the VPC route tables, when you redirect the VPC traffic through the endpoint.
Status (string) --
The current status of the firewall endpoint instantiation in the subnet.
When this value is READY, the endpoint is available to handle network traffic. Otherwise, this value reflects its state, for example CREATING or DELETING.
StatusMessage (string) --
If Network Firewall fails to create or delete the firewall endpoint in the subnet, it populates this with the reason for the error or failure and how to resolve it. A FAILED status indicates a non-recoverable state, and a ERROR status indicates an issue that you can fix. Depending on the error, it can take as many as 15 minutes to populate this field. For more information about the causes for failiure or errors and solutions available for this field, see Troubleshooting firewall endpoint failures in the Network Firewall Developer Guide.
DnsName (string) --
The proxy DNS name of a proxy mode firewall. Your clients send proxy requests to the firewall at this name. It's your ProxySettings DomainName if you specified one, or a name that Network Firewall generates in the format proxy-id.nfw.region.amazonaws.com.
The firewall has one proxy DNS name for every Availability Zone and VPC that it serves. In each Availability Zone, the name resolves to the firewall endpoint in that Availability Zone, so traffic stays in your client's Availability Zone. Your clients must use the VPC's Route 53 Resolver.
Config (dict) --
The configuration status of the firewall endpoint in a single VPC subnet. Network Firewall provides each endpoint with the rules that are configured in the firewall policy. Each time you add a subnet or modify the associated firewall policy, Network Firewall synchronizes the rules in the endpoint, so it can properly filter network traffic.
(string) --
(dict) --
Provides configuration status for a single policy or rule group that is used for a firewall endpoint. Network Firewall provides each endpoint with the rules that are configured in the firewall policy. Each time you add a subnet or modify the associated firewall policy, Network Firewall synchronizes the rules in the endpoint, so it can properly filter network traffic. This is part of a SyncState for a firewall.
SyncStatus (string) --
Indicates whether this object is in sync with the version indicated in the update token.
UpdateToken (string) --
The current version of the object that is either in sync or pending synchronization.
NatGatewayAttachments (list) --
The NAT gateway that's attached to a proxy mode firewall in the Availability Zone, and the status of the attachment. To get NAT gateway details, such as IP addresses, use the Amazon EC2 DescribeNatGateways action.
A proxy mode firewall is READY when at least one Availability Zone's firewall endpoint and NAT gateway attachment are READY.
(dict) --
The NAT gateway that's attached to a proxy mode firewall in an Availability Zone, and the status of the attachment. Traffic that the firewall allows in the Availability Zone leaves through this NAT gateway.
NatGatewayId (string) --
The ID of the NAT gateway.
Status (string) --
The status of the NAT gateway attachment. READY means that the NAT gateway is attached and the firewall can send traffic through it. Other values are CREATING, UPDATING, DELETING, and FAILED.
StatusMessage (string) --
The reason that Network Firewall couldn't create or attach the NAT gateway, if it couldn't.
DnsName (string) --
The proxy DNS name of the firewall in this Availability Zone. This is the same as the DnsName of the firewall's Attachment.
CapacityUsageSummary (dict) --
Describes the capacity usage of the resources contained in a firewall's reference sets. Network Firewall calculates the capacity usage by taking an aggregated count of all of the resources used by all of the reference sets in a firewall.
CIDRs (dict) --
Describes the capacity usage of the CIDR blocks used by the IP set references in a firewall.
AvailableCIDRCount (integer) --
The number of CIDR blocks available for use by the IP set references in a firewall.
UtilizedCIDRCount (integer) --
The number of CIDR blocks used by the IP set references in a firewall.
IPSetReferences (dict) --
The list of the IP set references used by a firewall.
(string) --
(dict) --
General information about the IP set.
ResolvedCIDRCount (integer) --
Describes the total number of CIDR blocks currently in use by the IP set references in a firewall. To determine how many CIDR blocks are available for you to use in a firewall, you can call AvailableCIDRCount.
TransitGatewayAttachmentSyncState (dict) --
The synchronization state of the transit gateway attachment. This indicates whether the firewall's transit gateway configuration is properly synchronized and operational. Use this to verify that your transit gateway configuration changes have been applied.
AttachmentId (string) --
The unique identifier of the transit gateway attachment.
TransitGatewayAttachmentStatus (string) --
The current status of the transit gateway attachment.
Valid values are:
CREATING - The attachment is being created
DELETING - The attachment is being deleted
DELETED - The attachment has been deleted
FAILED - The attachment creation has failed and cannot be recovered
ERROR - The attachment is in an error state that might be recoverable
READY - The attachment is active and processing traffic
PENDING_ACCEPTANCE - The attachment is waiting to be accepted
REJECTING - The attachment is in the process of being rejected
REJECTED - The attachment has been rejected
StatusMessage (string) --
A message providing additional information about the current status, particularly useful when the transit gateway attachment is in a non- READY state.
Valid values are:
CREATING - The attachment is being created
DELETING - The attachment is being deleted
DELETED - The attachment has been deleted
FAILED - The attachment creation has failed and cannot be recovered
ERROR - The attachment is in an error state that might be recoverable
READY - The attachment is active and processing traffic
PENDING_ACCEPTANCE - The attachment is waiting to be accepted
REJECTING - The attachment is in the process of being rejected
REJECTED - The attachment has been rejected
For information about troubleshooting endpoint failures, see Troubleshooting firewall endpoint failures in the Network Firewall Developer Guide.
{'Firewall': {'NatGatewayCreateMappings': [{'AllocationIds': ['string'],
'PrivateIps': ['string'],
'SubnetId': 'string'}],
'ProxySettings': {'CertificateArn': 'string',
'DomainName': 'string'},
'TransparentFilteringNatScope': 'NAT_ALL | NAT_NONE'}}
Returns the data objects for the specified firewall.
See also: AWS API Documentation
Request Syntax
client.describe_firewall(
FirewallName='string',
FirewallArn='string'
)
string
The descriptive name of the firewall. You can't change the name of a firewall after you create it.
You must specify the ARN or the name, and you can specify both.
string
The Amazon Resource Name (ARN) of the firewall.
You must specify the ARN or the name, and you can specify both.
dict
Response Syntax
{
'UpdateToken': 'string',
'Firewall': {
'FirewallName': 'string',
'FirewallArn': 'string',
'FirewallPolicyArn': 'string',
'VpcId': 'string',
'SubnetMappings': [
{
'SubnetId': 'string',
'IPAddressType': 'DUALSTACK'|'IPV4'|'IPV6'
},
],
'DeleteProtection': True|False,
'SubnetChangeProtection': True|False,
'FirewallPolicyChangeProtection': True|False,
'Description': 'string',
'FirewallId': 'string',
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
],
'EncryptionConfiguration': {
'KeyId': 'string',
'Type': 'CUSTOMER_KMS'|'AWS_OWNED_KMS_KEY'
},
'NumberOfAssociations': 123,
'EnabledAnalysisTypes': [
'TLS_SNI'|'HTTP_HOST',
],
'TransitGatewayId': 'string',
'TransitGatewayOwnerAccountId': 'string',
'AvailabilityZoneMappings': [
{
'AvailabilityZone': 'string'
},
],
'AvailabilityZoneChangeProtection': True|False,
'NatGatewayCreateMappings': [
{
'SubnetId': 'string',
'AllocationIds': [
'string',
],
'PrivateIps': [
'string',
]
},
],
'ProxySettings': {
'ListenerProperties': [
{
'Port': 123,
'Type': 'HTTP'|'HTTPS'
},
],
'CertificateArn': 'string',
'DomainName': 'string'
},
'VpcEndpoint': {
'VpcId': 'string',
'SubnetMappings': [
{
'SubnetId': 'string',
'IPAddressType': 'DUALSTACK'|'IPV4'|'IPV6'
},
]
},
'TransparentFilteringNatScope': 'NAT_ALL'|'NAT_NONE'
},
'FirewallStatus': {
'Status': 'PROVISIONING'|'DELETING'|'READY'|'FAILED',
'ConfigurationSyncStateSummary': 'PENDING'|'IN_SYNC'|'CAPACITY_CONSTRAINED',
'SyncStates': {
'string': {
'Attachment': {
'SubnetId': 'string',
'EndpointId': 'string',
'Status': 'CREATING'|'DELETING'|'FAILED'|'ERROR'|'SCALING'|'READY',
'StatusMessage': 'string',
'DnsName': 'string'
},
'Config': {
'string': {
'SyncStatus': 'PENDING'|'IN_SYNC'|'CAPACITY_CONSTRAINED'|'NOT_SUBSCRIBED'|'DEPRECATED',
'UpdateToken': 'string'
}
},
'NatGatewayAttachments': [
{
'NatGatewayId': 'string',
'Status': 'CREATING'|'READY'|'UPDATING'|'FAILED'|'DELETING',
'StatusMessage': 'string',
'DnsName': 'string'
},
]
}
},
'CapacityUsageSummary': {
'CIDRs': {
'AvailableCIDRCount': 123,
'UtilizedCIDRCount': 123,
'IPSetReferences': {
'string': {
'ResolvedCIDRCount': 123
}
}
}
},
'TransitGatewayAttachmentSyncState': {
'AttachmentId': 'string',
'TransitGatewayAttachmentStatus': 'CREATING'|'DELETING'|'DELETED'|'FAILED'|'ERROR'|'READY'|'PENDING_ACCEPTANCE'|'REJECTING'|'REJECTED',
'StatusMessage': 'string'
}
}
}
Response Structure
(dict) --
UpdateToken (string) --
An optional token that you can use for optimistic locking. Network Firewall returns a token to your requests that access the firewall. The token marks the state of the firewall resource at the time of the request.
To make an unconditional change to the firewall, omit the token in your update request. Without the token, Network Firewall performs your updates regardless of whether the firewall has changed since you last retrieved it.
To make a conditional change to the firewall, provide the token in your update request. Network Firewall uses the token to ensure that the firewall hasn't changed since you last retrieved it. If it has changed, the operation fails with an InvalidTokenException. If this happens, retrieve the firewall again to get a current copy of it with a new token. Reapply your changes as needed, then try the operation again using the new token.
Firewall (dict) --
The configuration settings for the firewall. These settings include the firewall policy and the subnets in your VPC to use for the firewall endpoints.
FirewallName (string) --
The descriptive name of the firewall. You can't change the name of a firewall after you create it.
FirewallArn (string) --
The Amazon Resource Name (ARN) of the firewall.
FirewallPolicyArn (string) --
The Amazon Resource Name (ARN) of the firewall policy.
The relationship of firewall to firewall policy is many to one. Each firewall requires one firewall policy association, and you can use the same firewall policy for multiple firewalls.
VpcId (string) --
The unique identifier of the VPC where the firewall is in use.
SubnetMappings (list) --
The primary public subnets that Network Firewall is using for the firewall. Network Firewall creates a firewall endpoint in each subnet. Create a subnet mapping for each Availability Zone where you want to use the firewall.
These subnets are all defined for a single, primary VPC, and each must belong to a different Availability Zone. Each of these subnets establishes the availability of the firewall in its Availability Zone.
In addition to these subnets, you can define other endpoints for the firewall in VpcEndpointAssociation resources. You can define these additional endpoints for any VPC, and for any of the Availability Zones where the firewall resource already has a subnet mapping. VPC endpoint associations give you the ability to protect multiple VPCs using a single firewall, and to define multiple firewall endpoints for a VPC in a single Availability Zone.
(dict) --
The ID for a subnet that's used in an association with a firewall. This is used in CreateFirewall, AssociateSubnets, and CreateVpcEndpointAssociation. Network Firewall creates an instance of the associated firewall in each subnet that you specify, to filter traffic in the subnet's Availability Zone.
SubnetId (string) --
The unique identifier for the subnet.
IPAddressType (string) --
The subnet's IP address type. You can't change the IP address type after you create the subnet.
DeleteProtection (boolean) --
A flag indicating whether it is possible to delete the firewall. A setting of TRUE indicates that the firewall is protected against deletion. Use this setting to protect against accidentally deleting a firewall that is in use. When you create a firewall, the operation initializes this flag to TRUE.
SubnetChangeProtection (boolean) --
A setting indicating whether the firewall is protected against changes to the subnet associations. Use this setting to protect against accidentally modifying the subnet associations for a firewall that is in use. When you create a firewall, the operation initializes this setting to TRUE.
FirewallPolicyChangeProtection (boolean) --
A setting indicating whether the firewall is protected against a change to the firewall policy association. Use this setting to protect against accidentally modifying the firewall policy for a firewall that is in use. When you create a firewall, the operation initializes this setting to TRUE.
Description (string) --
A description of the firewall.
FirewallId (string) --
The unique identifier for the firewall.
Tags (list) --
(dict) --
A key:value pair associated with an Amazon Web Services resource. The key:value pair can be anything you define. Typically, the tag key represents a category (such as "environment") and the tag value represents a specific value within that category (such as "test," "development," or "production"). You can add up to 50 tags to each Amazon Web Services resource.
Key (string) --
The part of the key:value pair that defines a tag. You can use a tag key to describe a category of information, such as "customer." Tag keys are case-sensitive.
Value (string) --
The part of the key:value pair that defines a tag. You can use a tag value to describe a specific value within a category, such as "companyA" or "companyB." Tag values are case-sensitive.
EncryptionConfiguration (dict) --
A complex type that contains the Amazon Web Services KMS encryption configuration settings for your firewall.
KeyId (string) --
The ID of the Amazon Web Services Key Management Service (KMS) customer managed key. You can use any of the key identifiers that KMS supports, unless you're using a key that's managed by another account. If you're using a key managed by another account, then specify the key ARN. For more information, see Key ID in the Amazon Web Services KMS Developer Guide.
Type (string) --
The type of Amazon Web Services KMS key to use for encryption of your Network Firewall resources.
NumberOfAssociations (integer) --
The number of VpcEndpointAssociation resources that use this firewall.
EnabledAnalysisTypes (list) --
An optional setting indicating the specific traffic analysis types to enable on the firewall.
(string) --
TransitGatewayId (string) --
The unique identifier of the transit gateway associated with this firewall. This field is only present for transit gateway-attached firewalls.
TransitGatewayOwnerAccountId (string) --
The Amazon Web Services account ID that owns the transit gateway. This may be different from the firewall owner's account ID when using a shared transit gateway.
AvailabilityZoneMappings (list) --
The Availability Zones where the firewall endpoints are created for a transit gateway-attached firewall. Each mapping specifies an Availability Zone where the firewall processes traffic.
(dict) --
Defines the mapping between an Availability Zone and a firewall endpoint for a transit gateway-attached firewall. Each mapping represents where the firewall can process traffic. You use these mappings when calling CreateFirewall, AssociateAvailabilityZones, and DisassociateAvailabilityZones.
To retrieve the current Availability Zone mappings for a firewall, use DescribeFirewall.
AvailabilityZone (string) --
The ID of the Availability Zone where the firewall endpoint is located. For example, us-east-2a. The Availability Zone must be in the same Region as the transit gateway.
AvailabilityZoneChangeProtection (boolean) --
A setting indicating whether the firewall is protected against changes to its Availability Zone configuration. When set to TRUE, you must first disable this protection before adding or removing Availability Zones.
NatGatewayCreateMappings (list) --
The NAT gateways that you specified for Network Firewall to create for a proxy mode firewall. To get the IDs and status of the NAT gateways that are attached to the firewall, see NatGatewayAttachments in the firewall's SyncStates.
(dict) --
A NAT gateway that Network Firewall creates for a proxy mode firewall in one Availability Zone. You use this in CreateFirewall and AssociateSubnets.
To create a public NAT gateway, specify AllocationIds, and one PrivateIps address for each Elastic IP address. To create a private NAT gateway, specify only PrivateIps. You must specify at least one of them. Each Elastic IP address and private IP address can appear only once in a request.
The NAT gateway is a resource in your account. To change its IP addresses, use Amazon EC2 NAT gateway actions.
SubnetId (string) --
The ID of the subnet where Network Firewall creates the NAT gateway. The subnet must be in the firewall's VPC and can't be one of the firewall endpoint subnets. Each mapping must be in a different Availability Zone.
AllocationIds (list) --
The allocation IDs of the Elastic IP addresses for a public NAT gateway, from 1 to 8. For each allocation ID, specify one address in PrivateIps. If you don't specify this, Network Firewall creates a private NAT gateway.
(string) --
PrivateIps (list) --
The private IPv4 addresses of the NAT gateway. The addresses must be in the subnet that you specify and can't be the subnet's reserved addresses.
For a public NAT gateway, you must specify exactly one address for each Elastic IP address in AllocationIds, even if you specify only one. For a private NAT gateway, specify from 1 to 8 addresses. The first address is the primary address.
(string) --
ProxySettings (dict) --
The proxy settings of a proxy mode firewall: its listeners and, if you specified them, your own CertificateArn and DomainName.
ListenerProperties (list) --
The listeners of the firewall's proxy. Specify at least one listener, and at most one HTTP listener and one HTTPS listener. Each listener needs a port from 1 to 65535, and the two listeners must use different ports.
If you don't specify listeners when you create the firewall, the firewall listens for HTTP on port 3128 and HTTPS on port 8443.
(dict) --
Open port for taking HTTP or HTTPS traffic.
Port (integer) --
Port for processing traffic.
Type (string) --
Selection of HTTP or HTTPS traffic.
CertificateArn (string) --
The Amazon Resource Name (ARN) of the certificate that the firewall's HTTPS proxy listener presents to clients. The certificate must be an Certificate Manager (ACM) certificate in the same account and Region as the firewall. Its subject alternative names must cover DomainName, either exactly or with a wildcard that matches exactly one label. For example, *.example.com covers proxy.example.com. If you don't specify this, Network Firewall uses a certificate that it manages for a domain name that it generates.
You manage and renew the certificate in ACM, and Network Firewall uses renewed certificates automatically. While the firewall uses the certificate, you can't delete it from ACM. Your clients must trust the certificate's certificate authority.
If you specify CertificateArn, you must also specify DomainName. You can set them only when you create the firewall. When you call UpdateProxySettings, specify the same values.
DomainName (string) --
The domain name that your clients use to reach the firewall's proxy. The name must have at least two labels and at most 253 characters. It can't contain a wildcard or use the proxy-id.nfw.region.amazonaws.com format, and the certificate in CertificateArn must cover it. If you don't specify this, Network Firewall generates a domain name.
Network Firewall creates the Route 53 private hosted zones that resolve this name to the firewall endpoints, so you don't need to configure DNS. A VPC can have only one private hosted zone with a given name. If a VPC that the firewall serves already has one with this name, Network Firewall can't set up the Availability Zones in that VPC.
If you specify DomainName, you must also specify CertificateArn. You can set them only when you create the firewall. When you call UpdateProxySettings, specify the same values.
VpcEndpoint (dict) --
The VPC and subnets for the endpoints of a proxy mode firewall.
VpcId (string) --
The ID of the VPC where Network Firewall creates the endpoints and NAT gateways of a proxy mode firewall.
SubnetMappings (list) --
The subnets where Network Firewall creates the firewall endpoints of a proxy mode firewall. Specify one subnet for each Availability Zone, and a NAT gateway mapping in each of those Availability Zones.
(dict) --
The ID for a subnet that's used in an association with a firewall. This is used in CreateFirewall, AssociateSubnets, and CreateVpcEndpointAssociation. Network Firewall creates an instance of the associated firewall in each subnet that you specify, to filter traffic in the subnet's Availability Zone.
SubnetId (string) --
The unique identifier for the subnet.
IPAddressType (string) --
The subnet's IP address type. You can't change the IP address type after you create the subnet.
TransparentFilteringNatScope (string) --
How a proxy mode firewall handles traffic that isn't sent to its proxy listener. NAT_ALL sends this traffic out through the firewall's NAT gateway after inspection. NAT_NONE returns it to the firewall endpoint without address translation.
FirewallStatus (dict) --
Detailed information about the current status of a Firewall. You can retrieve this for a firewall by calling DescribeFirewall and providing the firewall name and ARN.
The firewall status indicates a combined status. It indicates whether all subnets are up-to-date with the latest firewall configurations, which is based on the sync states config values, and also whether all subnets have their endpoints fully enabled, based on their sync states attachment values.
Status (string) --
The readiness of the configured firewall to handle network traffic across all of the Availability Zones where you have it configured. This setting is READY only when the ConfigurationSyncStateSummary value is IN_SYNC and the Attachment Status values for all of the configured subnets are READY.
ConfigurationSyncStateSummary (string) --
The configuration sync state for the firewall. This summarizes the Config settings in the SyncStates for this firewall status object.
When you create a firewall or update its configuration, for example by adding a rule group to its firewall policy, Network Firewall distributes the configuration changes to all Availability Zones that have subnets defined for the firewall. This summary indicates whether the configuration changes have been applied everywhere.
This status must be IN_SYNC for the firewall to be ready for use, but it doesn't indicate that the firewall is ready. The Status setting indicates firewall readiness. It's based on this setting and the readiness of the firewall endpoints to take traffic.
SyncStates (dict) --
Status for the subnets that you've configured in the firewall. This contains one array element per Availability Zone where you've configured a subnet in the firewall.
These objects provide detailed information for the settings ConfigurationSyncStateSummary and Status.
(string) --
(dict) --
The status of the firewall endpoint and firewall policy configuration for a single VPC subnet. This is part of the FirewallStatus.
For each VPC subnet that you associate with a firewall, Network Firewall does the following:
Instantiates a firewall endpoint in the subnet, ready to take traffic.
Configures the endpoint with the current firewall policy settings, to provide the filtering behavior for the endpoint.
When you update a firewall, for example to add a subnet association or change a rule group in the firewall policy, the affected sync states reflect out-of-sync or not ready status until the changes are complete.
Attachment (dict) --
The configuration and status for a single firewall subnet. For each configured subnet, Network Firewall creates the attachment by instantiating the firewall endpoint in the subnet so that it's ready to take traffic.
SubnetId (string) --
The unique identifier of the subnet that you've specified to be used for a firewall endpoint.
EndpointId (string) --
The identifier of the firewall endpoint that Network Firewall has instantiated in the subnet. You use this to identify the firewall endpoint in the VPC route tables, when you redirect the VPC traffic through the endpoint.
Status (string) --
The current status of the firewall endpoint instantiation in the subnet.
When this value is READY, the endpoint is available to handle network traffic. Otherwise, this value reflects its state, for example CREATING or DELETING.
StatusMessage (string) --
If Network Firewall fails to create or delete the firewall endpoint in the subnet, it populates this with the reason for the error or failure and how to resolve it. A FAILED status indicates a non-recoverable state, and a ERROR status indicates an issue that you can fix. Depending on the error, it can take as many as 15 minutes to populate this field. For more information about the causes for failiure or errors and solutions available for this field, see Troubleshooting firewall endpoint failures in the Network Firewall Developer Guide.
DnsName (string) --
The proxy DNS name of a proxy mode firewall. Your clients send proxy requests to the firewall at this name. It's your ProxySettings DomainName if you specified one, or a name that Network Firewall generates in the format proxy-id.nfw.region.amazonaws.com.
The firewall has one proxy DNS name for every Availability Zone and VPC that it serves. In each Availability Zone, the name resolves to the firewall endpoint in that Availability Zone, so traffic stays in your client's Availability Zone. Your clients must use the VPC's Route 53 Resolver.
Config (dict) --
The configuration status of the firewall endpoint in a single VPC subnet. Network Firewall provides each endpoint with the rules that are configured in the firewall policy. Each time you add a subnet or modify the associated firewall policy, Network Firewall synchronizes the rules in the endpoint, so it can properly filter network traffic.
(string) --
(dict) --
Provides configuration status for a single policy or rule group that is used for a firewall endpoint. Network Firewall provides each endpoint with the rules that are configured in the firewall policy. Each time you add a subnet or modify the associated firewall policy, Network Firewall synchronizes the rules in the endpoint, so it can properly filter network traffic. This is part of a SyncState for a firewall.
SyncStatus (string) --
Indicates whether this object is in sync with the version indicated in the update token.
UpdateToken (string) --
The current version of the object that is either in sync or pending synchronization.
NatGatewayAttachments (list) --
The NAT gateway that's attached to a proxy mode firewall in the Availability Zone, and the status of the attachment. To get NAT gateway details, such as IP addresses, use the Amazon EC2 DescribeNatGateways action.
A proxy mode firewall is READY when at least one Availability Zone's firewall endpoint and NAT gateway attachment are READY.
(dict) --
The NAT gateway that's attached to a proxy mode firewall in an Availability Zone, and the status of the attachment. Traffic that the firewall allows in the Availability Zone leaves through this NAT gateway.
NatGatewayId (string) --
The ID of the NAT gateway.
Status (string) --
The status of the NAT gateway attachment. READY means that the NAT gateway is attached and the firewall can send traffic through it. Other values are CREATING, UPDATING, DELETING, and FAILED.
StatusMessage (string) --
The reason that Network Firewall couldn't create or attach the NAT gateway, if it couldn't.
DnsName (string) --
The proxy DNS name of the firewall in this Availability Zone. This is the same as the DnsName of the firewall's Attachment.
CapacityUsageSummary (dict) --
Describes the capacity usage of the resources contained in a firewall's reference sets. Network Firewall calculates the capacity usage by taking an aggregated count of all of the resources used by all of the reference sets in a firewall.
CIDRs (dict) --
Describes the capacity usage of the CIDR blocks used by the IP set references in a firewall.
AvailableCIDRCount (integer) --
The number of CIDR blocks available for use by the IP set references in a firewall.
UtilizedCIDRCount (integer) --
The number of CIDR blocks used by the IP set references in a firewall.
IPSetReferences (dict) --
The list of the IP set references used by a firewall.
(string) --
(dict) --
General information about the IP set.
ResolvedCIDRCount (integer) --
Describes the total number of CIDR blocks currently in use by the IP set references in a firewall. To determine how many CIDR blocks are available for you to use in a firewall, you can call AvailableCIDRCount.
TransitGatewayAttachmentSyncState (dict) --
The synchronization state of the transit gateway attachment. This indicates whether the firewall's transit gateway configuration is properly synchronized and operational. Use this to verify that your transit gateway configuration changes have been applied.
AttachmentId (string) --
The unique identifier of the transit gateway attachment.
TransitGatewayAttachmentStatus (string) --
The current status of the transit gateway attachment.
Valid values are:
CREATING - The attachment is being created
DELETING - The attachment is being deleted
DELETED - The attachment has been deleted
FAILED - The attachment creation has failed and cannot be recovered
ERROR - The attachment is in an error state that might be recoverable
READY - The attachment is active and processing traffic
PENDING_ACCEPTANCE - The attachment is waiting to be accepted
REJECTING - The attachment is in the process of being rejected
REJECTED - The attachment has been rejected
StatusMessage (string) --
A message providing additional information about the current status, particularly useful when the transit gateway attachment is in a non- READY state.
Valid values are:
CREATING - The attachment is being created
DELETING - The attachment is being deleted
DELETED - The attachment has been deleted
FAILED - The attachment creation has failed and cannot be recovered
ERROR - The attachment is in an error state that might be recoverable
READY - The attachment is active and processing traffic
PENDING_ACCEPTANCE - The attachment is waiting to be accepted
REJECTING - The attachment is in the process of being rejected
REJECTED - The attachment has been rejected
For information about troubleshooting endpoint failures, see Troubleshooting firewall endpoint failures in the Network Firewall Developer Guide.
{'TLSInspectionConfiguration': {'ServerCertificateConfigurations': {'DefaultDecryptionBehavior': 'DECRYPT '
'| '
'BYPASS',
'Scopes': {'DecryptionAction': 'DECRYPT '
'| '
'BYPASS',
'DeploymentMode': 'TRANSPARENT_FIREWALL_ONLY '
'| '
'EXPLICIT_PROXY_ONLY '
'| '
'ALL',
'DomainMatch': {'Domains': ['string']}}}}}
Returns the data objects for the specified TLS inspection configuration.
See also: AWS API Documentation
Request Syntax
client.describe_tls_inspection_configuration(
TLSInspectionConfigurationArn='string',
TLSInspectionConfigurationName='string'
)
string
The Amazon Resource Name (ARN) of the TLS inspection configuration.
You must specify the ARN or the name, and you can specify both.
string
The descriptive name of the TLS inspection configuration. You can't change the name of a TLS inspection configuration after you create it.
You must specify the ARN or the name, and you can specify both.
dict
Response Syntax
{
'UpdateToken': 'string',
'TLSInspectionConfiguration': {
'ServerCertificateConfigurations': [
{
'ServerCertificates': [
{
'ResourceArn': 'string'
},
],
'Scopes': [
{
'Sources': [
{
'AddressDefinition': 'string'
},
],
'Destinations': [
{
'AddressDefinition': 'string'
},
],
'SourcePorts': [
{
'FromPort': 123,
'ToPort': 123
},
],
'DestinationPorts': [
{
'FromPort': 123,
'ToPort': 123
},
],
'Protocols': [
123,
],
'DomainMatch': {
'Domains': [
'string',
]
},
'DecryptionAction': 'DECRYPT'|'BYPASS',
'DeploymentMode': 'TRANSPARENT_FIREWALL_ONLY'|'EXPLICIT_PROXY_ONLY'|'ALL'
},
],
'CertificateAuthorityArn': 'string',
'CheckCertificateRevocationStatus': {
'RevokedStatusAction': 'PASS'|'DROP'|'REJECT',
'UnknownStatusAction': 'PASS'|'DROP'|'REJECT'
},
'DefaultDecryptionBehavior': 'DECRYPT'|'BYPASS'
},
]
},
'TLSInspectionConfigurationResponse': {
'TLSInspectionConfigurationArn': 'string',
'TLSInspectionConfigurationName': 'string',
'TLSInspectionConfigurationId': 'string',
'TLSInspectionConfigurationStatus': 'ACTIVE'|'DELETING'|'ERROR'|'UPDATING',
'Description': 'string',
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
],
'LastModifiedTime': datetime(2015, 1, 1),
'NumberOfAssociations': 123,
'EncryptionConfiguration': {
'KeyId': 'string',
'Type': 'CUSTOMER_KMS'|'AWS_OWNED_KMS_KEY'
},
'Certificates': [
{
'CertificateArn': 'string',
'CertificateSerial': 'string',
'Status': 'string',
'StatusMessage': 'string'
},
],
'CertificateAuthority': {
'CertificateArn': 'string',
'CertificateSerial': 'string',
'Status': 'string',
'StatusMessage': 'string'
}
}
}
Response Structure
(dict) --
UpdateToken (string) --
A token used for optimistic locking. Network Firewall returns a token to your requests that access the TLS inspection configuration. The token marks the state of the TLS inspection configuration resource at the time of the request.
To make changes to the TLS inspection configuration, you provide the token in your request. Network Firewall uses the token to ensure that the TLS inspection configuration hasn't changed since you last retrieved it. If it has changed, the operation fails with an InvalidTokenException. If this happens, retrieve the TLS inspection configuration again to get a current copy of it with a current token. Reapply your changes as needed, then try the operation again using the new token.
TLSInspectionConfiguration (dict) --
The object that defines a TLS inspection configuration. This, along with TLSInspectionConfigurationResponse, define the TLS inspection configuration. You can retrieve all objects for a TLS inspection configuration by calling DescribeTLSInspectionConfiguration.
Network Firewall uses a TLS inspection configuration to decrypt traffic. Network Firewall re-encrypts the traffic before sending it to its destination.
To use a TLS inspection configuration, you add it to a new Network Firewall firewall policy, then you apply the firewall policy to a firewall. Network Firewall acts as a proxy service to decrypt and inspect the traffic traveling through your firewalls. You can reference a TLS inspection configuration from more than one firewall policy, and you can use a firewall policy in more than one firewall. For more information about using TLS inspection configurations, see Inspecting SSL/TLS traffic with TLS inspection configurations in the Network Firewall Developer Guide.
ServerCertificateConfigurations (list) --
Lists the server certificate configurations that are associated with the TLS configuration.
(dict) --
Configures the Certificate Manager certificates and scope that Network Firewall uses to decrypt and re-encrypt traffic using a TLSInspectionConfiguration. You can configure ServerCertificates for inbound SSL/TLS inspection, a CertificateAuthorityArn for outbound SSL/TLS inspection, or both. For information about working with certificates for TLS inspection, see Using SSL/TLS server certficiates with TLS inspection configurations in the Network Firewall Developer Guide.
ServerCertificates (list) --
The list of server certificates to use for inbound SSL/TLS inspection.
(dict) --
Any Certificate Manager (ACM) Secure Sockets Layer/Transport Layer Security (SSL/TLS) server certificate that's associated with a ServerCertificateConfiguration. Used in a TLSInspectionConfiguration for inspection of inbound traffic to your firewall. You must request or import a SSL/TLS certificate into ACM for each domain Network Firewall needs to decrypt and inspect. Network Firewall uses the SSL/TLS certificates to decrypt specified inbound SSL/TLS traffic going to your firewall. For information about working with certificates in Certificate Manager, see Request a public certificate or Importing certificates in the Certificate Manager User Guide.
ResourceArn (string) --
The Amazon Resource Name (ARN) of the Certificate Manager SSL/TLS server certificate that's used for inbound SSL/TLS inspection.
Scopes (list) --
A list of scopes.
(dict) --
Settings that define the Secure Sockets Layer/Transport Layer Security (SSL/TLS) traffic that Network Firewall should decrypt for inspection by the stateful rule engine.
Sources (list) --
The source IP addresses and address ranges to decrypt for inspection, in CIDR notation. If not specified, this matches with any source address.
(dict) --
A single IP address specification. This is used in the MatchAttributes source and destination specifications.
AddressDefinition (string) --
Specify an IP address or a block of IP addresses in Classless Inter-Domain Routing (CIDR) notation. Network Firewall supports all address ranges for IPv4 and IPv6.
Examples:
To configure Network Firewall to inspect for the IP address 192.0.2.44, specify 192.0.2.44/32.
To configure Network Firewall to inspect for IP addresses from 192.0.2.0 to 192.0.2.255, specify 192.0.2.0/24.
To configure Network Firewall to inspect for the IP address 1111:0000:0000:0000:0000:0000:0000:0111, specify 1111:0000:0000:0000:0000:0000:0000:0111/128.
To configure Network Firewall to inspect for IP addresses from 1111:0000:0000:0000:0000:0000:0000:0000 to 1111:0000:0000:0000:ffff:ffff:ffff:ffff, specify 1111:0000:0000:0000:0000:0000:0000:0000/64.
For more information about CIDR notation, see the Wikipedia entry Classless Inter-Domain Routing.
Destinations (list) --
The destination IP addresses and address ranges to decrypt for inspection, in CIDR notation. If not specified, this matches with any destination address.
(dict) --
A single IP address specification. This is used in the MatchAttributes source and destination specifications.
AddressDefinition (string) --
Specify an IP address or a block of IP addresses in Classless Inter-Domain Routing (CIDR) notation. Network Firewall supports all address ranges for IPv4 and IPv6.
Examples:
To configure Network Firewall to inspect for the IP address 192.0.2.44, specify 192.0.2.44/32.
To configure Network Firewall to inspect for IP addresses from 192.0.2.0 to 192.0.2.255, specify 192.0.2.0/24.
To configure Network Firewall to inspect for the IP address 1111:0000:0000:0000:0000:0000:0000:0111, specify 1111:0000:0000:0000:0000:0000:0000:0111/128.
To configure Network Firewall to inspect for IP addresses from 1111:0000:0000:0000:0000:0000:0000:0000 to 1111:0000:0000:0000:ffff:ffff:ffff:ffff, specify 1111:0000:0000:0000:0000:0000:0000:0000/64.
For more information about CIDR notation, see the Wikipedia entry Classless Inter-Domain Routing.
SourcePorts (list) --
The source ports to decrypt for inspection, in Transmission Control Protocol (TCP) format. If not specified, this matches with any source port.
You can specify individual ports, for example 1994, and you can specify port ranges, such as 1990:1994.
(dict) --
A single port range specification. This is used for source and destination port ranges in the stateless rule MatchAttributes, SourcePorts, and DestinationPorts settings.
FromPort (integer) --
The lower limit of the port range. This must be less than or equal to the ToPort specification.
ToPort (integer) --
The upper limit of the port range. This must be greater than or equal to the FromPort specification.
DestinationPorts (list) --
The destination ports to decrypt for inspection, in Transmission Control Protocol (TCP) format. If not specified, this matches with any destination port.
You can specify individual ports, for example 1994, and you can specify port ranges, such as 1990:1994.
(dict) --
A single port range specification. This is used for source and destination port ranges in the stateless rule MatchAttributes, SourcePorts, and DestinationPorts settings.
FromPort (integer) --
The lower limit of the port range. This must be less than or equal to the ToPort specification.
ToPort (integer) --
The upper limit of the port range. This must be greater than or equal to the FromPort specification.
Protocols (list) --
The protocols to inspect for, specified using the assigned internet protocol number (IANA) for each protocol. If not specified, this matches with any protocol.
Network Firewall currently supports only TCP.
(integer) --
DomainMatch (dict) --
The domains that this scope matches, based on the host name in the client's HTTP CONNECT request. Domain matching applies only to proxy mode firewalls. If you specify DomainMatch, you must set DeploymentMode to EXPLICIT_PROXY_ONLY. If you don't specify DomainMatch, the scope matches traffic by its source, destination, ports, and protocols only.
Domains (list) --
The domains to match. You can specify an exact domain, such as example.com, or a domain with a single leading wildcard label, such as *.example.com. You can specify from 1 to 50 domains, and each domain can be up to 255 characters long.
(string) --
DecryptionAction (string) --
Whether the firewall decrypts traffic that matches this scope. You can choose from the following values:
DECRYPT - The firewall decrypts the traffic for inspection.
BYPASS - The firewall doesn't decrypt the traffic.
DeploymentMode (string) --
The type of firewall that this scope applies to. If you don't specify a value, the scope applies to both types, the same as ALL. You can choose from the following values:
ALL - The scope applies to both transparent firewalls and proxy mode firewalls.
TRANSPARENT_FIREWALL_ONLY - The scope applies only to transparent firewalls.
EXPLICIT_PROXY_ONLY - The scope applies only to proxy mode firewalls. A scope that specifies DomainMatch must use this value.
CertificateAuthorityArn (string) --
The Amazon Resource Name (ARN) of the imported certificate authority (CA) certificate within Certificate Manager (ACM) to use for outbound SSL/TLS inspection.
The following limitations apply:
You can use CA certificates that you imported into ACM, but you can't generate CA certificates with ACM.
You can't use certificates issued by Private Certificate Authority.
For more information about configuring certificates for outbound inspection, see Using SSL/TLS certificates with TLS inspection configurations in the Network Firewall Developer Guide.
For information about working with certificates in ACM, see Importing certificates in the Certificate Manager User Guide.
CheckCertificateRevocationStatus (dict) --
When enabled, Network Firewall checks if the server certificate presented by the server in the SSL/TLS connection has a revoked or unkown status. If the certificate has an unknown or revoked status, you must specify the actions that Network Firewall takes on outbound traffic. To check the certificate revocation status, you must also specify a CertificateAuthorityArn in ServerCertificateConfiguration.
RevokedStatusAction (string) --
Configures how Network Firewall processes traffic when it determines that the certificate presented by the server in the SSL/TLS connection has a revoked status.
PASS - Allow the connection to continue, and pass subsequent packets to the stateful engine for inspection.
DROP - Network Firewall closes the connection and drops subsequent packets for that connection.
REJECT - Network Firewall sends a TCP reject packet back to your client. The service closes the connection and drops subsequent packets for that connection. REJECT is available only for TCP traffic.
UnknownStatusAction (string) --
Configures how Network Firewall processes traffic when it determines that the certificate presented by the server in the SSL/TLS connection has an unknown status, or a status that cannot be determined for any other reason, including when the service is unable to connect to the OCSP and CRL endpoints for the certificate.
PASS - Allow the connection to continue, and pass subsequent packets to the stateful engine for inspection.
DROP - Network Firewall closes the connection and drops subsequent packets for that connection.
REJECT - Network Firewall sends a TCP reject packet back to your client. The service closes the connection and drops subsequent packets for that connection. REJECT is available only for TCP traffic.
DefaultDecryptionBehavior (string) --
What the firewall does with SSL/TLS traffic that doesn't match any scope in this server certificate configuration. This setting applies only to proxy mode firewalls. If you don't specify a value, the firewall uses BYPASS. You can choose from the following values:
BYPASS - The firewall doesn't decrypt the traffic.
DECRYPT - The firewall decrypts the traffic for inspection. You can use DECRYPT only if every scope in the configuration sets DeploymentMode to EXPLICIT_PROXY_ONLY.
TLSInspectionConfigurationResponse (dict) --
The high-level properties of a TLS inspection configuration. This, along with the TLSInspectionConfiguration, define the TLS inspection configuration. You can retrieve all objects for a TLS inspection configuration by calling DescribeTLSInspectionConfiguration.
TLSInspectionConfigurationArn (string) --
The Amazon Resource Name (ARN) of the TLS inspection configuration.
TLSInspectionConfigurationName (string) --
The descriptive name of the TLS inspection configuration. You can't change the name of a TLS inspection configuration after you create it.
TLSInspectionConfigurationId (string) --
A unique identifier for the TLS inspection configuration. This ID is returned in the responses to create and list commands. You provide it to operations such as update and delete.
TLSInspectionConfigurationStatus (string) --
Detailed information about the current status of a TLSInspectionConfiguration. You can retrieve this for a TLS inspection configuration by calling DescribeTLSInspectionConfiguration and providing the TLS inspection configuration name and ARN.
Description (string) --
A description of the TLS inspection configuration.
Tags (list) --
The key:value pairs to associate with the resource.
(dict) --
A key:value pair associated with an Amazon Web Services resource. The key:value pair can be anything you define. Typically, the tag key represents a category (such as "environment") and the tag value represents a specific value within that category (such as "test," "development," or "production"). You can add up to 50 tags to each Amazon Web Services resource.
Key (string) --
The part of the key:value pair that defines a tag. You can use a tag key to describe a category of information, such as "customer." Tag keys are case-sensitive.
Value (string) --
The part of the key:value pair that defines a tag. You can use a tag value to describe a specific value within a category, such as "companyA" or "companyB." Tag values are case-sensitive.
LastModifiedTime (datetime) --
The last time that the TLS inspection configuration was changed.
NumberOfAssociations (integer) --
The number of firewall policies that use this TLS inspection configuration.
EncryptionConfiguration (dict) --
A complex type that contains the Amazon Web Services KMS encryption configuration settings for your TLS inspection configuration.
KeyId (string) --
The ID of the Amazon Web Services Key Management Service (KMS) customer managed key. You can use any of the key identifiers that KMS supports, unless you're using a key that's managed by another account. If you're using a key managed by another account, then specify the key ARN. For more information, see Key ID in the Amazon Web Services KMS Developer Guide.
Type (string) --
The type of Amazon Web Services KMS key to use for encryption of your Network Firewall resources.
Certificates (list) --
A list of the certificates associated with the TLS inspection configuration.
(dict) --
Contains metadata about an Certificate Manager certificate.
CertificateArn (string) --
The Amazon Resource Name (ARN) of the certificate.
CertificateSerial (string) --
The serial number of the certificate.
Status (string) --
The status of the certificate.
StatusMessage (string) --
Contains details about the certificate status, including information about certificate errors.
CertificateAuthority (dict) --
Contains metadata about an Certificate Manager certificate.
CertificateArn (string) --
The Amazon Resource Name (ARN) of the certificate.
CertificateSerial (string) --
The serial number of the certificate.
Status (string) --
The status of the certificate.
StatusMessage (string) --
Contains details about the certificate status, including information about certificate errors.
{'ProxySettings': {'CertificateArn': 'string', 'DomainName': 'string'}}
Modifies the proxy settings of a proxy mode firewall. Use this operation to change the ports and protocols on which the firewall's proxy listens for traffic. The new listeners take effect without recreating the firewall.
The ProxySettings that you provide replace the firewall's current proxy settings. If you created the firewall with your own CertificateArn and DomainName, you must specify the same values in every request. You can't change or remove them.
See also: AWS API Documentation
Request Syntax
client.update_proxy_settings(
FirewallArn='string',
FirewallName='string',
UpdateToken='string',
ProxySettings={
'ListenerProperties': [
{
'Port': 123,
'Type': 'HTTP'|'HTTPS'
},
],
'CertificateArn': 'string',
'DomainName': 'string'
}
)
string
The Amazon Resource Name (ARN) of the firewall.
You must specify the ARN or the name, and you can specify both.
string
The descriptive name of the firewall. You can't change the name of a firewall after you create it.
You must specify the ARN or the name, and you can specify both.
string
An optional token that you can use for optimistic locking. Network Firewall returns a token to your requests that access the firewall. The token marks the state of the firewall resource at the time of the request.
To make an unconditional change to the firewall, omit the token in your update request. Without the token, Network Firewall performs your updates regardless of whether the firewall has changed since you last retrieved it.
To make a conditional change to the firewall, provide the token in your update request. Network Firewall uses the token to ensure that the firewall hasn't changed since you last retrieved it. If it has changed, the operation fails with an InvalidTokenException. If this happens, retrieve the firewall again to get a current copy of it with a new token. Reapply your changes as needed, then try the operation again using the new token.
dict
The proxy settings to set on the firewall. These replace the current proxy settings. Specify at least one listener, and at most one HTTP listener and one HTTPS listener, on different ports. If the firewall uses your own CertificateArn and DomainName, specify the same values that you used to create the firewall.
ListenerProperties (list) -- [REQUIRED]
The listeners of the firewall's proxy. Specify at least one listener, and at most one HTTP listener and one HTTPS listener. Each listener needs a port from 1 to 65535, and the two listeners must use different ports.
If you don't specify listeners when you create the firewall, the firewall listens for HTTP on port 3128 and HTTPS on port 8443.
(dict) --
Open port for taking HTTP or HTTPS traffic.
Port (integer) --
Port for processing traffic.
Type (string) --
Selection of HTTP or HTTPS traffic.
CertificateArn (string) --
The Amazon Resource Name (ARN) of the certificate that the firewall's HTTPS proxy listener presents to clients. The certificate must be an Certificate Manager (ACM) certificate in the same account and Region as the firewall. Its subject alternative names must cover DomainName, either exactly or with a wildcard that matches exactly one label. For example, *.example.com covers proxy.example.com. If you don't specify this, Network Firewall uses a certificate that it manages for a domain name that it generates.
You manage and renew the certificate in ACM, and Network Firewall uses renewed certificates automatically. While the firewall uses the certificate, you can't delete it from ACM. Your clients must trust the certificate's certificate authority.
If you specify CertificateArn, you must also specify DomainName. You can set them only when you create the firewall. When you call UpdateProxySettings, specify the same values.
DomainName (string) --
The domain name that your clients use to reach the firewall's proxy. The name must have at least two labels and at most 253 characters. It can't contain a wildcard or use the proxy-id.nfw.region.amazonaws.com format, and the certificate in CertificateArn must cover it. If you don't specify this, Network Firewall generates a domain name.
Network Firewall creates the Route 53 private hosted zones that resolve this name to the firewall endpoints, so you don't need to configure DNS. A VPC can have only one private hosted zone with a given name. If a VPC that the firewall serves already has one with this name, Network Firewall can't set up the Availability Zones in that VPC.
If you specify DomainName, you must also specify CertificateArn. You can set them only when you create the firewall. When you call UpdateProxySettings, specify the same values.
dict
Response Syntax
{
'FirewallArn': 'string',
'FirewallName': 'string',
'UpdateToken': 'string',
'ProxySettings': {
'ListenerProperties': [
{
'Port': 123,
'Type': 'HTTP'|'HTTPS'
},
],
'CertificateArn': 'string',
'DomainName': 'string'
}
}
Response Structure
(dict) --
FirewallArn (string) --
The Amazon Resource Name (ARN) of the firewall.
FirewallName (string) --
The descriptive name of the firewall. You can't change the name of a firewall after you create it.
UpdateToken (string) --
An optional token that you can use for optimistic locking. Network Firewall returns a token to your requests that access the firewall. The token marks the state of the firewall resource at the time of the request.
To make an unconditional change to the firewall, omit the token in your update request. Without the token, Network Firewall performs your updates regardless of whether the firewall has changed since you last retrieved it.
To make a conditional change to the firewall, provide the token in your update request. Network Firewall uses the token to ensure that the firewall hasn't changed since you last retrieved it. If it has changed, the operation fails with an InvalidTokenException. If this happens, retrieve the firewall again to get a current copy of it with a new token. Reapply your changes as needed, then try the operation again using the new token.
ProxySettings (dict) --
The updated proxy settings for the firewall.
ListenerProperties (list) --
The listeners of the firewall's proxy. Specify at least one listener, and at most one HTTP listener and one HTTPS listener. Each listener needs a port from 1 to 65535, and the two listeners must use different ports.
If you don't specify listeners when you create the firewall, the firewall listens for HTTP on port 3128 and HTTPS on port 8443.
(dict) --
Open port for taking HTTP or HTTPS traffic.
Port (integer) --
Port for processing traffic.
Type (string) --
Selection of HTTP or HTTPS traffic.
CertificateArn (string) --
The Amazon Resource Name (ARN) of the certificate that the firewall's HTTPS proxy listener presents to clients. The certificate must be an Certificate Manager (ACM) certificate in the same account and Region as the firewall. Its subject alternative names must cover DomainName, either exactly or with a wildcard that matches exactly one label. For example, *.example.com covers proxy.example.com. If you don't specify this, Network Firewall uses a certificate that it manages for a domain name that it generates.
You manage and renew the certificate in ACM, and Network Firewall uses renewed certificates automatically. While the firewall uses the certificate, you can't delete it from ACM. Your clients must trust the certificate's certificate authority.
If you specify CertificateArn, you must also specify DomainName. You can set them only when you create the firewall. When you call UpdateProxySettings, specify the same values.
DomainName (string) --
The domain name that your clients use to reach the firewall's proxy. The name must have at least two labels and at most 253 characters. It can't contain a wildcard or use the proxy-id.nfw.region.amazonaws.com format, and the certificate in CertificateArn must cover it. If you don't specify this, Network Firewall generates a domain name.
Network Firewall creates the Route 53 private hosted zones that resolve this name to the firewall endpoints, so you don't need to configure DNS. A VPC can have only one private hosted zone with a given name. If a VPC that the firewall serves already has one with this name, Network Firewall can't set up the Availability Zones in that VPC.
If you specify DomainName, you must also specify CertificateArn. You can set them only when you create the firewall. When you call UpdateProxySettings, specify the same values.
{'TLSInspectionConfiguration': {'ServerCertificateConfigurations': {'DefaultDecryptionBehavior': 'DECRYPT '
'| '
'BYPASS',
'Scopes': {'DecryptionAction': 'DECRYPT '
'| '
'BYPASS',
'DeploymentMode': 'TRANSPARENT_FIREWALL_ONLY '
'| '
'EXPLICIT_PROXY_ONLY '
'| '
'ALL',
'DomainMatch': {'Domains': ['string']}}}}}
Updates the TLS inspection configuration settings for the specified TLS inspection configuration. You use a TLS inspection configuration by referencing it in one or more firewall policies. When you modify a TLS inspection configuration, you modify all firewall policies that use the TLS inspection configuration.
To update a TLS inspection configuration, first call DescribeTLSInspectionConfiguration to retrieve the current TLSInspectionConfiguration object, update the object as needed, and then provide the updated object to this call.
See also: AWS API Documentation
Request Syntax
client.update_tls_inspection_configuration(
TLSInspectionConfigurationArn='string',
TLSInspectionConfigurationName='string',
TLSInspectionConfiguration={
'ServerCertificateConfigurations': [
{
'ServerCertificates': [
{
'ResourceArn': 'string'
},
],
'Scopes': [
{
'Sources': [
{
'AddressDefinition': 'string'
},
],
'Destinations': [
{
'AddressDefinition': 'string'
},
],
'SourcePorts': [
{
'FromPort': 123,
'ToPort': 123
},
],
'DestinationPorts': [
{
'FromPort': 123,
'ToPort': 123
},
],
'Protocols': [
123,
],
'DomainMatch': {
'Domains': [
'string',
]
},
'DecryptionAction': 'DECRYPT'|'BYPASS',
'DeploymentMode': 'TRANSPARENT_FIREWALL_ONLY'|'EXPLICIT_PROXY_ONLY'|'ALL'
},
],
'CertificateAuthorityArn': 'string',
'CheckCertificateRevocationStatus': {
'RevokedStatusAction': 'PASS'|'DROP'|'REJECT',
'UnknownStatusAction': 'PASS'|'DROP'|'REJECT'
},
'DefaultDecryptionBehavior': 'DECRYPT'|'BYPASS'
},
]
},
Description='string',
EncryptionConfiguration={
'KeyId': 'string',
'Type': 'CUSTOMER_KMS'|'AWS_OWNED_KMS_KEY'
},
UpdateToken='string'
)
string
The Amazon Resource Name (ARN) of the TLS inspection configuration.
string
The descriptive name of the TLS inspection configuration. You can't change the name of a TLS inspection configuration after you create it.
dict
[REQUIRED]
The object that defines a TLS inspection configuration. This, along with TLSInspectionConfigurationResponse, define the TLS inspection configuration. You can retrieve all objects for a TLS inspection configuration by calling DescribeTLSInspectionConfiguration.
Network Firewall uses a TLS inspection configuration to decrypt traffic. Network Firewall re-encrypts the traffic before sending it to its destination.
To use a TLS inspection configuration, you add it to a new Network Firewall firewall policy, then you apply the firewall policy to a firewall. Network Firewall acts as a proxy service to decrypt and inspect the traffic traveling through your firewalls. You can reference a TLS inspection configuration from more than one firewall policy, and you can use a firewall policy in more than one firewall. For more information about using TLS inspection configurations, see Inspecting SSL/TLS traffic with TLS inspection configurations in the Network Firewall Developer Guide.
ServerCertificateConfigurations (list) --
Lists the server certificate configurations that are associated with the TLS configuration.
(dict) --
Configures the Certificate Manager certificates and scope that Network Firewall uses to decrypt and re-encrypt traffic using a TLSInspectionConfiguration. You can configure ServerCertificates for inbound SSL/TLS inspection, a CertificateAuthorityArn for outbound SSL/TLS inspection, or both. For information about working with certificates for TLS inspection, see Using SSL/TLS server certficiates with TLS inspection configurations in the Network Firewall Developer Guide.
ServerCertificates (list) --
The list of server certificates to use for inbound SSL/TLS inspection.
(dict) --
Any Certificate Manager (ACM) Secure Sockets Layer/Transport Layer Security (SSL/TLS) server certificate that's associated with a ServerCertificateConfiguration. Used in a TLSInspectionConfiguration for inspection of inbound traffic to your firewall. You must request or import a SSL/TLS certificate into ACM for each domain Network Firewall needs to decrypt and inspect. Network Firewall uses the SSL/TLS certificates to decrypt specified inbound SSL/TLS traffic going to your firewall. For information about working with certificates in Certificate Manager, see Request a public certificate or Importing certificates in the Certificate Manager User Guide.
ResourceArn (string) --
The Amazon Resource Name (ARN) of the Certificate Manager SSL/TLS server certificate that's used for inbound SSL/TLS inspection.
Scopes (list) --
A list of scopes.
(dict) --
Settings that define the Secure Sockets Layer/Transport Layer Security (SSL/TLS) traffic that Network Firewall should decrypt for inspection by the stateful rule engine.
Sources (list) --
The source IP addresses and address ranges to decrypt for inspection, in CIDR notation. If not specified, this matches with any source address.
(dict) --
A single IP address specification. This is used in the MatchAttributes source and destination specifications.
AddressDefinition (string) -- [REQUIRED]
Specify an IP address or a block of IP addresses in Classless Inter-Domain Routing (CIDR) notation. Network Firewall supports all address ranges for IPv4 and IPv6.
Examples:
To configure Network Firewall to inspect for the IP address 192.0.2.44, specify 192.0.2.44/32.
To configure Network Firewall to inspect for IP addresses from 192.0.2.0 to 192.0.2.255, specify 192.0.2.0/24.
To configure Network Firewall to inspect for the IP address 1111:0000:0000:0000:0000:0000:0000:0111, specify 1111:0000:0000:0000:0000:0000:0000:0111/128.
To configure Network Firewall to inspect for IP addresses from 1111:0000:0000:0000:0000:0000:0000:0000 to 1111:0000:0000:0000:ffff:ffff:ffff:ffff, specify 1111:0000:0000:0000:0000:0000:0000:0000/64.
For more information about CIDR notation, see the Wikipedia entry Classless Inter-Domain Routing.
Destinations (list) --
The destination IP addresses and address ranges to decrypt for inspection, in CIDR notation. If not specified, this matches with any destination address.
(dict) --
A single IP address specification. This is used in the MatchAttributes source and destination specifications.
AddressDefinition (string) -- [REQUIRED]
Specify an IP address or a block of IP addresses in Classless Inter-Domain Routing (CIDR) notation. Network Firewall supports all address ranges for IPv4 and IPv6.
Examples:
To configure Network Firewall to inspect for the IP address 192.0.2.44, specify 192.0.2.44/32.
To configure Network Firewall to inspect for IP addresses from 192.0.2.0 to 192.0.2.255, specify 192.0.2.0/24.
To configure Network Firewall to inspect for the IP address 1111:0000:0000:0000:0000:0000:0000:0111, specify 1111:0000:0000:0000:0000:0000:0000:0111/128.
To configure Network Firewall to inspect for IP addresses from 1111:0000:0000:0000:0000:0000:0000:0000 to 1111:0000:0000:0000:ffff:ffff:ffff:ffff, specify 1111:0000:0000:0000:0000:0000:0000:0000/64.
For more information about CIDR notation, see the Wikipedia entry Classless Inter-Domain Routing.
SourcePorts (list) --
The source ports to decrypt for inspection, in Transmission Control Protocol (TCP) format. If not specified, this matches with any source port.
You can specify individual ports, for example 1994, and you can specify port ranges, such as 1990:1994.
(dict) --
A single port range specification. This is used for source and destination port ranges in the stateless rule MatchAttributes, SourcePorts, and DestinationPorts settings.
FromPort (integer) -- [REQUIRED]
The lower limit of the port range. This must be less than or equal to the ToPort specification.
ToPort (integer) -- [REQUIRED]
The upper limit of the port range. This must be greater than or equal to the FromPort specification.
DestinationPorts (list) --
The destination ports to decrypt for inspection, in Transmission Control Protocol (TCP) format. If not specified, this matches with any destination port.
You can specify individual ports, for example 1994, and you can specify port ranges, such as 1990:1994.
(dict) --
A single port range specification. This is used for source and destination port ranges in the stateless rule MatchAttributes, SourcePorts, and DestinationPorts settings.
FromPort (integer) -- [REQUIRED]
The lower limit of the port range. This must be less than or equal to the ToPort specification.
ToPort (integer) -- [REQUIRED]
The upper limit of the port range. This must be greater than or equal to the FromPort specification.
Protocols (list) --
The protocols to inspect for, specified using the assigned internet protocol number (IANA) for each protocol. If not specified, this matches with any protocol.
Network Firewall currently supports only TCP.
(integer) --
DomainMatch (dict) --
The domains that this scope matches, based on the host name in the client's HTTP CONNECT request. Domain matching applies only to proxy mode firewalls. If you specify DomainMatch, you must set DeploymentMode to EXPLICIT_PROXY_ONLY. If you don't specify DomainMatch, the scope matches traffic by its source, destination, ports, and protocols only.
Domains (list) -- [REQUIRED]
The domains to match. You can specify an exact domain, such as example.com, or a domain with a single leading wildcard label, such as *.example.com. You can specify from 1 to 50 domains, and each domain can be up to 255 characters long.
(string) --
DecryptionAction (string) --
Whether the firewall decrypts traffic that matches this scope. You can choose from the following values:
DECRYPT - The firewall decrypts the traffic for inspection.
BYPASS - The firewall doesn't decrypt the traffic.
DeploymentMode (string) --
The type of firewall that this scope applies to. If you don't specify a value, the scope applies to both types, the same as ALL. You can choose from the following values:
ALL - The scope applies to both transparent firewalls and proxy mode firewalls.
TRANSPARENT_FIREWALL_ONLY - The scope applies only to transparent firewalls.
EXPLICIT_PROXY_ONLY - The scope applies only to proxy mode firewalls. A scope that specifies DomainMatch must use this value.
CertificateAuthorityArn (string) --
The Amazon Resource Name (ARN) of the imported certificate authority (CA) certificate within Certificate Manager (ACM) to use for outbound SSL/TLS inspection.
The following limitations apply:
You can use CA certificates that you imported into ACM, but you can't generate CA certificates with ACM.
You can't use certificates issued by Private Certificate Authority.
For more information about configuring certificates for outbound inspection, see Using SSL/TLS certificates with TLS inspection configurations in the Network Firewall Developer Guide.
For information about working with certificates in ACM, see Importing certificates in the Certificate Manager User Guide.
CheckCertificateRevocationStatus (dict) --
When enabled, Network Firewall checks if the server certificate presented by the server in the SSL/TLS connection has a revoked or unkown status. If the certificate has an unknown or revoked status, you must specify the actions that Network Firewall takes on outbound traffic. To check the certificate revocation status, you must also specify a CertificateAuthorityArn in ServerCertificateConfiguration.
RevokedStatusAction (string) --
Configures how Network Firewall processes traffic when it determines that the certificate presented by the server in the SSL/TLS connection has a revoked status.
PASS - Allow the connection to continue, and pass subsequent packets to the stateful engine for inspection.
DROP - Network Firewall closes the connection and drops subsequent packets for that connection.
REJECT - Network Firewall sends a TCP reject packet back to your client. The service closes the connection and drops subsequent packets for that connection. REJECT is available only for TCP traffic.
UnknownStatusAction (string) --
Configures how Network Firewall processes traffic when it determines that the certificate presented by the server in the SSL/TLS connection has an unknown status, or a status that cannot be determined for any other reason, including when the service is unable to connect to the OCSP and CRL endpoints for the certificate.
PASS - Allow the connection to continue, and pass subsequent packets to the stateful engine for inspection.
DROP - Network Firewall closes the connection and drops subsequent packets for that connection.
REJECT - Network Firewall sends a TCP reject packet back to your client. The service closes the connection and drops subsequent packets for that connection. REJECT is available only for TCP traffic.
DefaultDecryptionBehavior (string) --
What the firewall does with SSL/TLS traffic that doesn't match any scope in this server certificate configuration. This setting applies only to proxy mode firewalls. If you don't specify a value, the firewall uses BYPASS. You can choose from the following values:
BYPASS - The firewall doesn't decrypt the traffic.
DECRYPT - The firewall decrypts the traffic for inspection. You can use DECRYPT only if every scope in the configuration sets DeploymentMode to EXPLICIT_PROXY_ONLY.
string
A description of the TLS inspection configuration.
dict
A complex type that contains the Amazon Web Services KMS encryption configuration settings for your TLS inspection configuration.
KeyId (string) --
The ID of the Amazon Web Services Key Management Service (KMS) customer managed key. You can use any of the key identifiers that KMS supports, unless you're using a key that's managed by another account. If you're using a key managed by another account, then specify the key ARN. For more information, see Key ID in the Amazon Web Services KMS Developer Guide.
Type (string) -- [REQUIRED]
The type of Amazon Web Services KMS key to use for encryption of your Network Firewall resources.
string
[REQUIRED]
A token used for optimistic locking. Network Firewall returns a token to your requests that access the TLS inspection configuration. The token marks the state of the TLS inspection configuration resource at the time of the request.
To make changes to the TLS inspection configuration, you provide the token in your request. Network Firewall uses the token to ensure that the TLS inspection configuration hasn't changed since you last retrieved it. If it has changed, the operation fails with an InvalidTokenException. If this happens, retrieve the TLS inspection configuration again to get a current copy of it with a current token. Reapply your changes as needed, then try the operation again using the new token.
dict
Response Syntax
{
'UpdateToken': 'string',
'TLSInspectionConfigurationResponse': {
'TLSInspectionConfigurationArn': 'string',
'TLSInspectionConfigurationName': 'string',
'TLSInspectionConfigurationId': 'string',
'TLSInspectionConfigurationStatus': 'ACTIVE'|'DELETING'|'ERROR'|'UPDATING',
'Description': 'string',
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
],
'LastModifiedTime': datetime(2015, 1, 1),
'NumberOfAssociations': 123,
'EncryptionConfiguration': {
'KeyId': 'string',
'Type': 'CUSTOMER_KMS'|'AWS_OWNED_KMS_KEY'
},
'Certificates': [
{
'CertificateArn': 'string',
'CertificateSerial': 'string',
'Status': 'string',
'StatusMessage': 'string'
},
],
'CertificateAuthority': {
'CertificateArn': 'string',
'CertificateSerial': 'string',
'Status': 'string',
'StatusMessage': 'string'
}
}
}
Response Structure
(dict) --
UpdateToken (string) --
A token used for optimistic locking. Network Firewall returns a token to your requests that access the TLS inspection configuration. The token marks the state of the TLS inspection configuration resource at the time of the request.
To make changes to the TLS inspection configuration, you provide the token in your request. Network Firewall uses the token to ensure that the TLS inspection configuration hasn't changed since you last retrieved it. If it has changed, the operation fails with an InvalidTokenException. If this happens, retrieve the TLS inspection configuration again to get a current copy of it with a current token. Reapply your changes as needed, then try the operation again using the new token.
TLSInspectionConfigurationResponse (dict) --
The high-level properties of a TLS inspection configuration. This, along with the TLSInspectionConfiguration, define the TLS inspection configuration. You can retrieve all objects for a TLS inspection configuration by calling DescribeTLSInspectionConfiguration.
TLSInspectionConfigurationArn (string) --
The Amazon Resource Name (ARN) of the TLS inspection configuration.
TLSInspectionConfigurationName (string) --
The descriptive name of the TLS inspection configuration. You can't change the name of a TLS inspection configuration after you create it.
TLSInspectionConfigurationId (string) --
A unique identifier for the TLS inspection configuration. This ID is returned in the responses to create and list commands. You provide it to operations such as update and delete.
TLSInspectionConfigurationStatus (string) --
Detailed information about the current status of a TLSInspectionConfiguration. You can retrieve this for a TLS inspection configuration by calling DescribeTLSInspectionConfiguration and providing the TLS inspection configuration name and ARN.
Description (string) --
A description of the TLS inspection configuration.
Tags (list) --
The key:value pairs to associate with the resource.
(dict) --
A key:value pair associated with an Amazon Web Services resource. The key:value pair can be anything you define. Typically, the tag key represents a category (such as "environment") and the tag value represents a specific value within that category (such as "test," "development," or "production"). You can add up to 50 tags to each Amazon Web Services resource.
Key (string) --
The part of the key:value pair that defines a tag. You can use a tag key to describe a category of information, such as "customer." Tag keys are case-sensitive.
Value (string) --
The part of the key:value pair that defines a tag. You can use a tag value to describe a specific value within a category, such as "companyA" or "companyB." Tag values are case-sensitive.
LastModifiedTime (datetime) --
The last time that the TLS inspection configuration was changed.
NumberOfAssociations (integer) --
The number of firewall policies that use this TLS inspection configuration.
EncryptionConfiguration (dict) --
A complex type that contains the Amazon Web Services KMS encryption configuration settings for your TLS inspection configuration.
KeyId (string) --
The ID of the Amazon Web Services Key Management Service (KMS) customer managed key. You can use any of the key identifiers that KMS supports, unless you're using a key that's managed by another account. If you're using a key managed by another account, then specify the key ARN. For more information, see Key ID in the Amazon Web Services KMS Developer Guide.
Type (string) --
The type of Amazon Web Services KMS key to use for encryption of your Network Firewall resources.
Certificates (list) --
A list of the certificates associated with the TLS inspection configuration.
(dict) --
Contains metadata about an Certificate Manager certificate.
CertificateArn (string) --
The Amazon Resource Name (ARN) of the certificate.
CertificateSerial (string) --
The serial number of the certificate.
Status (string) --
The status of the certificate.
StatusMessage (string) --
Contains details about the certificate status, including information about certificate errors.
CertificateAuthority (dict) --
Contains metadata about an Certificate Manager certificate.
CertificateArn (string) --
The Amazon Resource Name (ARN) of the certificate.
CertificateSerial (string) --
The serial number of the certificate.
Status (string) --
The status of the certificate.
StatusMessage (string) --
Contains details about the certificate status, including information about certificate errors.