finding_aggregators

Creates, updates, deletes or gets a finding_aggregator resource or lists finding_aggregators in a region

Overview

Name	finding_aggregators
Type	Resource
Description	The AWS::SecurityHub::FindingAggregator resource enables cross-Region aggregation. When cross-Region aggregation is enabled, you can aggregate findings, finding updates, insights, control compliance statuses, and security scores from one or more linked Regions to a single aggregation Region. You can then view and manage all of this data from the aggregation Region. For more details about cross-Region aggregation, see Cross-Region aggregation in the User Guide This resource must be created in the Region that you want to designate as your aggregation Region. Cross-Region aggregation is also a prerequisite for using central configuration in ASH.
Id	awscc.securityhub.finding_aggregators

Fields

get (all properties)

Name	Datatype	Description
finding_aggregator_arn	string
region_linking_mode	string	Indicates whether to aggregate findings from all of the available Regions in the current partition. Also determines whether to automatically aggregate findings from new Regions as Security Hub supports them and you opt into them. The selected option also determines how to use the Regions provided in the Regions list. In CFN, the options for this property are as follows: + ALL_REGIONS - Indicates to aggregate findings from all of the Regions where Security Hub is enabled. When you choose this option, Security Hub also automatically aggregates findings from new Regions as Security Hub supports them and you opt into them. + ALL_REGIONS_EXCEPT_SPECIFIED - Indicates to aggregate findings from all of the Regions where Security Hub is enabled, except for the Regions listed in the Regions parameter. When you choose this option, Security Hub also automatically aggregates findings from new Regions as Security Hub supports them and you opt into them. + SPECIFIED_REGIONS - Indicates to aggregate findings only from the Regions listed in the Regions parameter. Security Hub does not automatically aggregate findings from new Regions.
regions	array	If RegionLinkingMode is ALL_REGIONS_EXCEPT_SPECIFIED, then this is a space-separated list of Regions that do not aggregate findings to the aggregation Region. If RegionLinkingMode is SPECIFIED_REGIONS, then this is a space-separated list of Regions that do aggregate findings to the aggregation Region.
region	string	AWS region.

list (identifiers only)

Name	Datatype	Description
finding_aggregator_arn	string
region	string	AWS region.

For more information, see AWS::SecurityHub::FindingAggregator.

Methods

Name	Resource	Accessible by	Required Params
create_resource	finding_aggregators	INSERT	RegionLinkingMode, region
delete_resource	finding_aggregators	DELETE	Identifier, region
update_resource	finding_aggregators	UPDATE	Identifier, PatchDocument, region
list_resources	finding_aggregators_list_only	SELECT	region
get_resource	finding_aggregators	SELECT	Identifier, region

SELECT examples

get (all properties)

Gets all properties from an individual finding_aggregator.

SELECT
  region,
  finding_aggregator_arn,
  region_linking_mode,
  regions,
  finding_aggregation_region
FROM awscc.securityhub.finding_aggregators
WHERE
  region = '{{ region }}' AND
  Identifier = '{{ finding_aggregator_arn }}';

list (identifiers only)

Lists all finding_aggregators in a region.

SELECT
  region,
  finding_aggregator_arn
FROM awscc.securityhub.finding_aggregators_list_only
WHERE
  region = '{{ region }}';

INSERT example

Use the following StackQL query and manifest file to create a new finding_aggregator resource, using stack-deploy.

Required Properties

/*+ create */
INSERT INTO awscc.securityhub.finding_aggregators (
  RegionLinkingMode,
  region
)
SELECT
  '{{ region_linking_mode }}',
  '{{ region }}'
RETURNING
  ErrorCode,
  EventTime,
  Identifier,
  Operation,
  OperationStatus,
  RequestToken,
  ResourceModel,
  RetryAfter,
  StatusMessage,
  TypeName
;

All Properties

/*+ create */
INSERT INTO awscc.securityhub.finding_aggregators (
  RegionLinkingMode,
  Regions,
  region
)
SELECT
  '{{ region_linking_mode }}',
  '{{ regions }}',
  '{{ region }}'
RETURNING
  ErrorCode,
  EventTime,
  Identifier,
  Operation,
  OperationStatus,
  RequestToken,
  ResourceModel,
  RetryAfter,
  StatusMessage,
  TypeName
;

Manifest

version: 1
name: stack name
description: stack description
providers:
- aws
globals:
- name: region
  value: '{{ vars.AWS_REGION }}'
resources:
- name: finding_aggregator
  props:
    - name: region_linking_mode
      value: '{{ region_linking_mode }}'
    - name: regions
      value:
        - '{{ regions[0] }}'

UPDATE example

Use the following StackQL query and manifest file to update a finding_aggregator resource, using stack-deploy.

/*+ update */
UPDATE awscc.securityhub.finding_aggregators
SET PatchDocument = string('{{ {
    "RegionLinkingMode": region_linking_mode,
    "Regions": regions
} | generate_patch_document }}')
WHERE
  region = '{{ region }}' AND
  Identifier = '{{ finding_aggregator_arn }}'
RETURNING
  ErrorCode,
  EventTime,
  Identifier,
  Operation,
  OperationStatus,
  RequestToken,
  ResourceModel,
  RetryAfter,
  StatusMessage,
  TypeName
;

DELETE example

/*+ delete */
DELETE FROM awscc.securityhub.finding_aggregators
WHERE
  Identifier = '{{ finding_aggregator_arn }}' AND
  region = '{{ region }}'
RETURNING
  ErrorCode,
  EventTime,
  Identifier,
  Operation,
  OperationStatus,
  RequestToken,
  ResourceModel,
  RetryAfter,
  StatusMessage,
  TypeName
;

Additional Parameters

Mutable resources in the Cloud Control provider support additional optional parameters which can be supplied with INSERT, UPDATE, or DELETE operations. These include:

Parameter	Description
ClientToken	A unique identifier to ensure the idempotency of the resource request. This allows the provider to accurately distinguish between retries and new requests. A client token is valid for 36 hours once used. After that, a resource request with the same client token is treated as a new request. If you do not specify a client token, one is generated for inclusion in the request.
RoleArn	The ARN of the IAM role used to perform this resource operation. The role specified must have the permissions required for this operation. If you do not specify a role, a temporary session is created using your AWS user credentials.
TypeVersionId	For private resource types, the type version to use in this resource operation. If you do not specify a resource version, the default version is used.

Permissions

To operate on the finding_aggregators resource, the following permissions are required:

Create

securityhub:CreateFindingAggregator

Read

securityhub:GetFindingAggregator

Update

securityhub:UpdateFindingAggregator

Delete

securityhub:DeleteFindingAggregator

List

securityhub:ListFindingAggregators