AWS API Changes

2021/10/20 - AWS SecurityHub - 5 new api methods

Changes Added support for cross-Region finding aggregation, which replicates findings from linked Regions to a single aggregation Region. Added operations to view, enable, update, and delete the finding aggregation.

GetFindingAggregator (new)

Link ¶

Returns the current finding aggregation configuration.

See also: AWS API Documentation

Request Syntax

client.get_finding_aggregator(
    FindingAggregatorArn='string'
)

type FindingAggregatorArn:

string

param FindingAggregatorArn:

[REQUIRED]

The ARN of the finding aggregator to return details for. To obtain the ARN, use ListFindingAggregators.

rtype:

dict

returns:

Response Syntax

{
    'FindingAggregatorArn': 'string',
    'FindingAggregationRegion': 'string',
    'RegionLinkingMode': 'string',
    'Regions': [
        'string',
    ]
}

Response Structure

(dict) --
- FindingAggregatorArn (string) --
  
  The ARN of the finding aggregator.
- FindingAggregationRegion (string) --
  
  The aggregation Region.
- RegionLinkingMode (string) --
  
  Indicates whether to link all Regions, all Regions except for a list of excluded Regions, or a list of included Regions.
- Regions (list) --
  
  The list of excluded Regions or included Regions.
  - (string) --

ListFindingAggregators (new)

Link ¶

If finding aggregation is enabled, then ListFindingAggregators returns the ARN of the finding aggregator. You can run this operation from any Region.

See also: AWS API Documentation

Request Syntax

client.list_finding_aggregators(
    NextToken='string',
    MaxResults=123
)

type NextToken:

string

param NextToken:

The token returned with the previous set of results. Identifies the next set of results to return.

type MaxResults:

integer

param MaxResults:

The maximum number of results to return. This operation currently only returns a single result.

rtype:

dict

returns:

Response Syntax

{
    'FindingAggregators': [
        {
            'FindingAggregatorArn': 'string'
        },
    ],
    'NextToken': 'string'
}

Response Structure

(dict) --
- FindingAggregators (list) --
  
  The list of finding aggregators. This operation currently only returns a single result.
  - (dict) --
    
    A finding aggregator. A finding aggregator contains the configuration for finding aggregation.
    - FindingAggregatorArn (string) --
      
      The ARN of the finding aggregator. You use the finding aggregator ARN to retrieve details for, update, and delete the finding aggregator.
- NextToken (string) --
  
  If there are more results, this is the token to provide in the next call to ListFindingAggregators.
  
  This operation currently only returns a single result.

DeleteFindingAggregator (new)

Link ¶

Deletes a finding aggregator. When you delete the finding aggregator, you stop finding aggregation.

When you stop finding aggregation, findings that were already aggregated to the aggregation Region are still visible from the aggregation Region. New findings and finding updates are not aggregated.

See also: AWS API Documentation

Request Syntax

client.delete_finding_aggregator(
    FindingAggregatorArn='string'
)

type FindingAggregatorArn:

string

param FindingAggregatorArn:

[REQUIRED]

The ARN of the finding aggregator to delete. To obtain the ARN, use ListFindingAggregators.

rtype:

dict

returns:

Response Syntax

{}

Response Structure

(dict) --

UpdateFindingAggregator (new)

Link ¶

Updates the finding aggregation configuration. Used to update the Region linking mode and the list of included or excluded Regions. You cannot use UpdateFindingAggregator to change the aggregation Region.

You must run UpdateFindingAggregator from the current aggregation Region.

See also: AWS API Documentation

Request Syntax

client.update_finding_aggregator(
    FindingAggregatorArn='string',
    RegionLinkingMode='string',
    Regions=[
        'string',
    ]
)

type FindingAggregatorArn:

string

param FindingAggregatorArn:

[REQUIRED]

The ARN of the finding aggregator. To obtain the ARN, use ListFindingAggregators.

type RegionLinkingMode:

string

param RegionLinkingMode:

[REQUIRED]

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.

The options 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.

type Regions:

list

param Regions:

If RegionLinkingMode is ALL_REGIONS_EXCEPT_SPECIFIED, then this is a comma-separated list of Regions that do not aggregate findings to the aggregation Region.

If RegionLinkingMode is SPECIFIED_REGIONS, then this is a comma-separated list of Regions that do aggregate findings to the aggregation Region.

(string) --

rtype:

dict

returns:

Response Syntax

{
    'FindingAggregatorArn': 'string',
    'FindingAggregationRegion': 'string',
    'RegionLinkingMode': 'string',
    'Regions': [
        'string',
    ]
}

Response Structure

(dict) --
- FindingAggregatorArn (string) --
  
  The ARN of the finding aggregator.
- FindingAggregationRegion (string) --
  
  The aggregation Region.
- RegionLinkingMode (string) --
  
  Indicates whether to link all Regions, all Regions except for a list of excluded Regions, or a list of included Regions.
- Regions (list) --
  
  The list of excluded Regions or included Regions.
  - (string) --

CreateFindingAggregator (new)

Link ¶

Used to enable finding aggregation. Must be called from the aggregation Region.

For more details about cross-Region replication, see Configuring finding aggregation in the Security Hub User Guide.

See also: AWS API Documentation

Request Syntax

client.create_finding_aggregator(
    RegionLinkingMode='string',
    Regions=[
        'string',
    ]
)

type RegionLinkingMode:

string

param RegionLinkingMode:

[REQUIRED]

The selected option also determines how to use the Regions provided in the Regions list.

The options 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.

type Regions:

list

param Regions:

If RegionLinkingMode is ALL_REGIONS_EXCEPT_SPECIFIED, then this is a comma-separated list of Regions that do not aggregate findings to the aggregation Region.

If RegionLinkingMode is SPECIFIED_REGIONS, then this is a comma-separated list of Regions that do aggregate findings to the aggregation Region.

(string) --

rtype:

dict

returns:

Response Syntax

{
    'FindingAggregatorArn': 'string',
    'FindingAggregationRegion': 'string',
    'RegionLinkingMode': 'string',
    'Regions': [
        'string',
    ]
}

Response Structure

(dict) --
- FindingAggregatorArn (string) --
  
  The ARN of the finding aggregator. You use the finding aggregator ARN to retrieve details for, update, and stop finding aggregation.
- FindingAggregationRegion (string) --
  
  The aggregation Region.
- RegionLinkingMode (string) --
  
  Indicates whether to link all Regions, all Regions except for a list of excluded Regions, or a list of included Regions.
- Regions (list) --
  
  The list of excluded Regions or included Regions.
  - (string) --