Skip to main content

firewalls

Creates, updates, deletes, gets or lists a firewalls resource.

Overview​

Namefirewalls
TypeResource
Idaws.network_firewall.firewalls

Fields​

The following fields are returned by SELECT queries:

NameDatatypeDescription
firewallobjectA 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.
firewall_statusobjectDetailed 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.
update_tokenstringAn 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. (pattern: <code>^([0-9a-f]{8})-([0-9a-f]{4}-){3}([0-9a-f]{12})$</code>)

Methods​

The following methods are available for this resource:

NameAccessible byRequired ParamsOptional ParamsDescription
describe_firewallselectregionReturns the data objects for the specified firewall.
list_firewallsselectregionRetrieves the metadata for the firewalls that you have defined. If you provide VPC identifiers in your request, this returns only the firewalls for those VPCs. Depending on your setting for max results and the number of firewalls, a single call might not return the full list.
create_firewallinsertregion, FirewallName, FirewallPolicyArnCreates 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.
update_firewall_delete_protectionupdateregion, DeleteProtectionModifies the flag, DeleteProtection, which indicates whether it is possible to delete the firewall. If the flag is set to TRUE, the firewall is protected against deletion. This setting helps protect against accidentally deleting a firewall that's in use.
update_firewall_analysis_settingsupdateregionEnables specific types of firewall analysis on a specific firewall you define.
delete_firewalldeleteregionDeletes 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.
start_flow_captureexecregion, FirewallArn, FlowFiltersBegins capturing the flows in a firewall, according to the filters you define. Captures are similar, but not identical to snapshots. Capture operations provide visibility into flows that are not closed and are tracked by a firewall's flow table. Unlike snapshots, captures are a time-boxed view. A flow is network traffic that is monitored by a firewall, either by stateful or stateless rules. For traffic to be considered part of a flow, it must share Destination, DestinationPort, Direction, Protocol, Source, and SourcePort. To avoid encountering operation limits, you should avoid starting captures with broad filters, like wide IP ranges. Instead, we recommend you define more specific criteria with FlowFilters, like narrow IP ranges, ports, or protocols.
start_flow_flushexecregion, FirewallArn, FlowFiltersBegins the flushing of traffic from the firewall, according to the filters you define. When the operation starts, impacted flows are temporarily marked as timed out before the Suricata engine prunes, or flushes, the flows from the firewall table. While the flush completes, impacted flows are processed as midstream traffic. This may result in a temporary increase in midstream traffic metrics. We recommend that you double check your stream exception policy before you perform a flush operation.
update_firewall_descriptionexecregionModifies the description for the specified firewall. Use the description to help you identify the firewall when you're working with it.
update_firewall_encryption_configurationexecregionA complex type that contains settings for encryption of your firewall resources.

Parameters​

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

NameDatatypeDescription
regionstringAWS region (default: us-east-1)

SELECT examples​

Returns the data objects for the specified firewall.

SELECT
firewall,
firewall_status,
update_token
FROM aws.network_firewall.firewalls
WHERE region = '{{ region }}' -- required
;

INSERT examples​

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.

INSERT INTO aws.network_firewall.firewalls (
FirewallName,
FirewallPolicyArn,
VpcId,
SubnetMappings,
DeleteProtection,
SubnetChangeProtection,
FirewallPolicyChangeProtection,
Description,
Tags,
EncryptionConfiguration,
EnabledAnalysisTypes,
TransitGatewayId,
AvailabilityZoneMappings,
AvailabilityZoneChangeProtection,
NatGatewayMappings,
ProxySettings,
NoSourcePreservation,
VpcEndpoint,
region
)
SELECT 
'{{ FirewallName }}' /* required */,
'{{ FirewallPolicyArn }}' /* required */,
'{{ VpcId }}',
'{{ SubnetMappings }}',
{{ DeleteProtection }},
{{ SubnetChangeProtection }},
{{ FirewallPolicyChangeProtection }},
'{{ Description }}',
'{{ Tags }}',
'{{ EncryptionConfiguration }}',
'{{ EnabledAnalysisTypes }}',
'{{ TransitGatewayId }}',
'{{ AvailabilityZoneMappings }}',
{{ AvailabilityZoneChangeProtection }},
'{{ NatGatewayMappings }}',
'{{ ProxySettings }}',
{{ NoSourcePreservation }},
'{{ VpcEndpoint }}',
'{{ region }}'
RETURNING
firewall,
firewall_status
;

UPDATE examples​

Modifies the flag, DeleteProtection, which indicates whether it is possible to delete the firewall. If the flag is set to TRUE, the firewall is protected against deletion. This setting helps protect against accidentally deleting a firewall that's in use.

UPDATE aws.network_firewall.firewalls
SET 
UpdateToken = '{{ UpdateToken }}',
FirewallArn = '{{ FirewallArn }}',
FirewallName = '{{ FirewallName }}',
DeleteProtection = {{ DeleteProtection }}
WHERE 
region = '{{ region }}' --required
AND DeleteProtection = {{ DeleteProtection }} --required
RETURNING
delete_protection,
firewall_arn,
firewall_name,
update_token;

DELETE examples​

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.

DELETE FROM aws.network_firewall.firewalls
WHERE region = '{{ region }}' --required
;

Lifecycle Methods​

Begins capturing the flows in a firewall, according to the filters you define. Captures are similar, but not identical to snapshots. Capture operations provide visibility into flows that are not closed and are tracked by a firewall's flow table. Unlike snapshots, captures are a time-boxed view. A flow is network traffic that is monitored by a firewall, either by stateful or stateless rules. For traffic to be considered part of a flow, it must share Destination, DestinationPort, Direction, Protocol, Source, and SourcePort. To avoid encountering operation limits, you should avoid starting captures with broad filters, like wide IP ranges. Instead, we recommend you define more specific criteria with FlowFilters, like narrow IP ranges, ports, or protocols.

EXEC aws.network_firewall.firewalls.start_flow_capture 
@region='{{ region }}' --required 
@@json=
'{
"FirewallArn": "{{ FirewallArn }}", 
"AvailabilityZone": "{{ AvailabilityZone }}", 
"VpcEndpointAssociationArn": "{{ VpcEndpointAssociationArn }}", 
"VpcEndpointId": "{{ VpcEndpointId }}", 
"MinimumFlowAgeInSeconds": {{ MinimumFlowAgeInSeconds }}, 
"FlowFilters": "{{ FlowFilters }}"
}'
;
Last updated on