finding_aggregators

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

Overview

Name	finding_aggregators
Type	Resource
Id	aws.securityhub.finding_aggregators

Fields

The following fields are returned by SELECT queries:

get_finding_aggregator

Name	Datatype	Description
finding_aggregation_region	string	The home Region. Findings generated in linked Regions are replicated and sent to the home Region. (pattern: <code>.\S.</code>)
finding_aggregator_arn	string	The ARN of the finding aggregator. (pattern: <code>.\S.</code>)
region_linking_mode	string	Indicates whether to link all Regions, all Regions except for a list of excluded Regions, or a list of included Regions. (pattern: <code>.\S.</code>)
regions	array	The list of excluded Regions or included Regions.

list_finding_aggregators

Name	Datatype	Description
finding_aggregator_arn	string	The ARN of the finding aggregator. You use the finding aggregator ARN to retrieve details for, update, and delete the finding aggregator. (pattern: <code>.\S.</code>)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_finding_aggregator	select	finding_aggregator_arn, region		The aggregation Region is now called the home Region. Returns the current configuration in the calling account for cross-Region aggregation. A finding aggregator is a resource that establishes the home Region and any linked Regions.
list_finding_aggregators	select	region	NextToken, MaxResults	If cross-Region aggregation is enabled, then ListFindingAggregators returns the Amazon Resource Name (ARN) of the finding aggregator. You can run this operation from any Amazon Web Services Region.
create_finding_aggregator	insert	region, RegionLinkingMode		The aggregation Region is now called the home Region. Used to enable cross-Region aggregation. This operation can be invoked from the home Region only. For information about how cross-Region aggregation works, see Understanding cross-Region aggregation in Security Hub CSPM in the Security Hub CSPM User Guide.
update_finding_aggregator	update	region, FindingAggregatorArn, RegionLinkingMode		The aggregation Region is now called the home Region. Updates cross-Region aggregation settings. You can use this operation to update the Region linking mode and the list of included or excluded Amazon Web Services Regions. However, you can't use this operation to change the home Region. You can invoke this operation from the current home Region only.
delete_finding_aggregator	delete	finding_aggregator_arn, region		The aggregation Region is now called the home Region. Deletes a finding aggregator. When you delete the finding aggregator, you stop cross-Region aggregation. Finding replication stops occurring from the linked Regions to the home Region. When you stop cross-Region aggregation, findings that were already replicated and sent to the home Region are still visible from the home Region. However, new findings and finding updates are no longer replicated and sent to the home Region.

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.

Name	Datatype	Description
finding_aggregator_arn	string	The ARN of the finding aggregator to delete. To obtain the ARN, use ListFindingAggregators.
region	string	AWS region (default: us-east-1)
MaxResults	integer	The maximum number of results to return. This operation currently only returns a single result.
NextToken	string	The token returned with the previous set of results. Identifies the next set of results to return.

SELECT examples

get_finding_aggregator

The aggregation Region is now called the home Region. Returns the current configuration in the calling account for cross-Region aggregation. A finding aggregator is a resource that establishes the home Region and any linked Regions.

SELECT
finding_aggregation_region,
finding_aggregator_arn,
region_linking_mode,
regions
FROM aws.securityhub.finding_aggregators
WHERE finding_aggregator_arn = '{{ finding_aggregator_arn }}' -- required
AND region = '{{ region }}' -- required
;

list_finding_aggregators

If cross-Region aggregation is enabled, then ListFindingAggregators returns the Amazon Resource Name (ARN) of the finding aggregator. You can run this operation from any Amazon Web Services Region.

SELECT
finding_aggregator_arn
FROM aws.securityhub.finding_aggregators
WHERE region = '{{ region }}' -- required
AND NextToken = '{{ NextToken }}'
AND MaxResults = '{{ MaxResults }}'
;

INSERT examples

create_finding_aggregator

The aggregation Region is now called the home Region. Used to enable cross-Region aggregation. This operation can be invoked from the home Region only. For information about how cross-Region aggregation works, see Understanding cross-Region aggregation in Security Hub CSPM in the Security Hub CSPM User Guide.

INSERT INTO aws.securityhub.finding_aggregators (
RegionLinkingMode,
Regions,
region
)
SELECT 
'{{ RegionLinkingMode }}' /* required */,
'{{ Regions }}',
'{{ region }}'
RETURNING
finding_aggregation_region,
finding_aggregator_arn,
region_linking_mode,
regions
;

Manifest

# Description fields are for documentation purposes
- name: finding_aggregators
props:
  - name: region
    value: "{{ region }}"
    description: Required parameter for the finding_aggregators resource.
  - name: RegionLinkingMode
    value: "{{ RegionLinkingMode }}"
  - name: Regions
    value:
      - "{{ Regions }}"

UPDATE examples

update_finding_aggregator

The aggregation Region is now called the home Region. Updates cross-Region aggregation settings. You can use this operation to update the Region linking mode and the list of included or excluded Amazon Web Services Regions. However, you can't use this operation to change the home Region. You can invoke this operation from the current home Region only.

UPDATE aws.securityhub.finding_aggregators
SET 
FindingAggregatorArn = '{{ FindingAggregatorArn }}',
RegionLinkingMode = '{{ RegionLinkingMode }}',
Regions = '{{ Regions }}'
WHERE 
region = '{{ region }}' --required
AND FindingAggregatorArn = '{{ FindingAggregatorArn }}' --required
AND RegionLinkingMode = '{{ RegionLinkingMode }}' --required
RETURNING
finding_aggregation_region,
finding_aggregator_arn,
region_linking_mode,
regions;

DELETE examples

delete_finding_aggregator

The aggregation Region is now called the home Region. Deletes a finding aggregator. When you delete the finding aggregator, you stop cross-Region aggregation. Finding replication stops occurring from the linked Regions to the home Region. When you stop cross-Region aggregation, findings that were already replicated and sent to the home Region are still visible from the home Region. However, new findings and finding updates are no longer replicated and sent to the home Region.

DELETE FROM aws.securityhub.finding_aggregators
WHERE finding_aggregator_arn = '{{ finding_aggregator_arn }}' --required
AND region = '{{ region }}' --required
;