2023/02/24 - AWS SecurityHub - 5 new 3 updated api methods
Changes New Security Hub APIs and updates to existing APIs that help you consolidate control findings and enable and disable controls across all supported standards
Provides details about a batch of security controls for the current Amazon Web Services account and Amazon Web Services Region.
See also: AWS API Documentation
Request Syntax
client.batch_get_security_controls(
SecurityControlIds=[
'string',
]
)
list
[REQUIRED]
A list of security controls (identified with SecurityControlId , SecurityControlArn , or a mix of both parameters). The security control ID or Amazon Resource Name (ARN) is the same across standards.
(string) --
dict
Response Syntax
{
'SecurityControls': [
{
'SecurityControlId': 'string',
'SecurityControlArn': 'string',
'Title': 'string',
'Description': 'string',
'RemediationUrl': 'string',
'SeverityRating': 'LOW'|'MEDIUM'|'HIGH'|'CRITICAL',
'SecurityControlStatus': 'ENABLED'|'DISABLED'
},
],
'UnprocessedIds': [
{
'SecurityControlId': 'string',
'ErrorCode': 'INVALID_INPUT'|'ACCESS_DENIED'|'NOT_FOUND'|'LIMIT_EXCEEDED',
'ErrorReason': 'string'
},
]
}
Response Structure
(dict) --
SecurityControls (list) --
An array that returns the identifier, Amazon Resource Name (ARN), and other details about a security control. The same information is returned whether the request includes SecurityControlId or SecurityControlArn .
(dict) --
A security control in Security Hub describes a security best practice related to a specific resource.
SecurityControlId (string) --
The unique identifier of a security control across standards. Values for this field typically consist of an Amazon Web Service name and a number, such as APIGateway.3.
SecurityControlArn (string) --
The Amazon Resource Name (ARN) for a security control across standards, such as arn:aws:securityhub:eu-central-1:123456789012:security-control/S3.1 . This parameter doesn't mention a specific standard.
Title (string) --
The title of a security control.
Description (string) --
The description of a security control across standards. This typically summarizes how Security Hub evaluates the control and the conditions under which it produces a failed finding. This parameter doesn't reference a specific standard.
RemediationUrl (string) --
A link to Security Hub documentation that explains how to remediate a failed finding for a security control.
SeverityRating (string) --
The severity of a security control. For more information about how Security Hub determines control severity, see Assigning severity to control findings in the Security Hub User Guide .
SecurityControlStatus (string) --
The status of a security control based on the compliance status of its findings. For more information about how control status is determined, see Determining the overall status of a control from its findings in the Security Hub User Guide .
UnprocessedIds (list) --
A security control (identified with SecurityControlId , SecurityControlArn , or a mix of both parameters) for which details cannot be returned.
(dict) --
Provides details about a security control for which a response couldn't be returned.
SecurityControlId (string) --
The control (identified with SecurityControlId , SecurityControlArn , or a mix of both parameters) for which a response couldn't be returned.
ErrorCode (string) --
The error code for the unprocessed security control.
ErrorReason (string) --
The reason why the security control was unprocessed.
For a batch of security controls and standards, this operation updates the enablement status of a control in a standard.
See also: AWS API Documentation
Request Syntax
client.batch_update_standards_control_associations(
StandardsControlAssociationUpdates=[
{
'StandardsArn': 'string',
'SecurityControlId': 'string',
'AssociationStatus': 'ENABLED'|'DISABLED',
'UpdatedReason': 'string'
},
]
)
list
[REQUIRED]
Updates the enablement status of a security control in a specified standard.
(dict) --
An array of requested updates to the enablement status of controls in specified standards. The objects in the array include a security control ID, the Amazon Resource Name (ARN) of the standard, the requested enablement status, and the reason for updating the enablement status.
StandardsArn (string) -- [REQUIRED]
The Amazon Resource Name (ARN) of the standard in which you want to update the control's enablement status.
SecurityControlId (string) -- [REQUIRED]
The unique identifier for the security control whose enablement status you want to update.
AssociationStatus (string) -- [REQUIRED]
The desired enablement status of the control in the standard.
UpdatedReason (string) --
The reason for updating the control's enablement status in the standard.
dict
Response Syntax
{
'UnprocessedAssociationUpdates': [
{
'StandardsControlAssociationUpdate': {
'StandardsArn': 'string',
'SecurityControlId': 'string',
'AssociationStatus': 'ENABLED'|'DISABLED',
'UpdatedReason': 'string'
},
'ErrorCode': 'INVALID_INPUT'|'ACCESS_DENIED'|'NOT_FOUND'|'LIMIT_EXCEEDED',
'ErrorReason': 'string'
},
]
}
Response Structure
(dict) --
UnprocessedAssociationUpdates (list) --
A security control (identified with SecurityControlId , SecurityControlArn , or a mix of both parameters) whose enablement status in a specified standard couldn't be updated.
(dict) --
Provides details about which control's enablement status could not be updated in a specified standard when calling the BatchUpdateStandardsControlAssociations API. This parameter also provides details about why the request was unprocessed.
StandardsControlAssociationUpdate (dict) --
An array of control and standard associations for which an update failed when calling BatchUpdateStandardsControlAssociations.
StandardsArn (string) --
The Amazon Resource Name (ARN) of the standard in which you want to update the control's enablement status.
SecurityControlId (string) --
The unique identifier for the security control whose enablement status you want to update.
AssociationStatus (string) --
The desired enablement status of the control in the standard.
UpdatedReason (string) --
The reason for updating the control's enablement status in the standard.
ErrorCode (string) --
The error code for the unprocessed update of the control's enablement status in the specified standard.
ErrorReason (string) --
The reason why a control's enablement status in the specified standard couldn't be updated.
Lists all of the security controls that apply to a specified standard.
See also: AWS API Documentation
Request Syntax
client.list_security_control_definitions(
StandardsArn='string',
NextToken='string',
MaxResults=123
)
string
The Amazon Resource Name (ARN) of the standard that you want to view controls for.
string
Optional pagination parameter.
integer
An optional parameter that limits the total results of the API response to the specified number. If this parameter isn't provided in the request, the results include the first 25 security controls that apply to the specified standard. The results also include a NextToken parameter that you can use in a subsequent API call to get the next 25 controls. This repeats until all controls for the standard are returned.
dict
Response Syntax
{
'SecurityControlDefinitions': [
{
'SecurityControlId': 'string',
'Title': 'string',
'Description': 'string',
'RemediationUrl': 'string',
'SeverityRating': 'LOW'|'MEDIUM'|'HIGH'|'CRITICAL',
'CurrentRegionAvailability': 'AVAILABLE'|'UNAVAILABLE'
},
],
'NextToken': 'string'
}
Response Structure
(dict) --
SecurityControlDefinitions (list) --
An array of controls that apply to the specified standard.
(dict) --
Provides metadata for a security control, including its unique standard-agnostic identifier, title, description, severity, availability in Amazon Web Services Regions, and a link to remediation steps.
SecurityControlId (string) --
The unique identifier of a security control across standards. Values for this field typically consist of an Amazon Web Service name and a number (for example, APIGateway.3). This parameter differs from SecurityControlArn , which is a unique Amazon Resource Name (ARN) assigned to a control. The ARN references the security control ID (for example, arn:aws:securityhub:eu-central-1:123456789012:security-control/APIGateway.3).
Title (string) --
The title of a security control.
Description (string) --
The description of a security control across standards. This typically summarizes how Security Hub evaluates the control and the conditions under which it produces a failed finding. This parameter doesn't reference a specific standard.
RemediationUrl (string) --
A link to Security Hub documentation that explains how to remediate a failed finding for a security control.
SeverityRating (string) --
The severity of a security control. For more information about how Security Hub determines control severity, see Assigning severity to control findings in the Security Hub User Guide .
CurrentRegionAvailability (string) --
Specifies whether a security control is available in the current Amazon Web Services Region.
NextToken (string) --
A pagination parameter that's included in the response only if it was included in the request.
For a batch of security controls and standards, identifies whether each control is currently enabled or disabled in a standard.
See also: AWS API Documentation
Request Syntax
client.batch_get_standards_control_associations(
StandardsControlAssociationIds=[
{
'SecurityControlId': 'string',
'StandardsArn': 'string'
},
]
)
list
[REQUIRED]
An array with one or more objects that includes a security control (identified with SecurityControlId , SecurityControlArn , or a mix of both parameters) and the Amazon Resource Name (ARN) of a standard. This field is used to query the enablement status of a control in a specified standard. The security control ID or ARN is the same across standards.
(dict) --
An array with one or more objects that includes a security control (identified with SecurityControlId , SecurityControlArn , or a mix of both parameters) and the Amazon Resource Name (ARN) of a standard. The security control ID or ARN is the same across standards.
SecurityControlId (string) -- [REQUIRED]
The unique identifier (identified with SecurityControlId , SecurityControlArn , or a mix of both parameters) of a security control across standards.
StandardsArn (string) -- [REQUIRED]
The ARN of a standard.
dict
Response Syntax
{
'StandardsControlAssociationDetails': [
{
'StandardsArn': 'string',
'SecurityControlId': 'string',
'SecurityControlArn': 'string',
'AssociationStatus': 'ENABLED'|'DISABLED',
'RelatedRequirements': [
'string',
],
'UpdatedAt': datetime(2015, 1, 1),
'UpdatedReason': 'string',
'StandardsControlTitle': 'string',
'StandardsControlDescription': 'string',
'StandardsControlArns': [
'string',
]
},
],
'UnprocessedAssociations': [
{
'StandardsControlAssociationId': {
'SecurityControlId': 'string',
'StandardsArn': 'string'
},
'ErrorCode': 'INVALID_INPUT'|'ACCESS_DENIED'|'NOT_FOUND'|'LIMIT_EXCEEDED',
'ErrorReason': 'string'
},
]
}
Response Structure
(dict) --
StandardsControlAssociationDetails (list) --
Provides the enablement status of a security control in a specified standard and other details for the control in relation to the specified standard.
(dict) --
Provides details about a control's enablement status in a specified standard.
StandardsArn (string) --
The Amazon Resource Name (ARN) of a security standard.
SecurityControlId (string) --
The unique identifier of a security control across standards. Values for this field typically consist of an Amazon Web Service name and a number, such as APIGateway.3.
SecurityControlArn (string) --
The ARN of a security control across standards, such as arn:aws:securityhub:eu-central-1:123456789012:security-control/S3.1 . This parameter doesn't mention a specific standard.
AssociationStatus (string) --
Specifies whether a control is enabled or disabled in a specified standard.
RelatedRequirements (list) --
The requirement that underlies a control in the compliance framework related to the standard.
(string) --
UpdatedAt (datetime) --
The time at which the enablement status of the control in the specified standard was last updated.
UpdatedReason (string) --
The reason for updating the enablement status of a control in a specified standard.
StandardsControlTitle (string) --
The title of a control. This field may reference a specific standard.
StandardsControlDescription (string) --
The description of a control. This typically summarizes how Security Hub evaluates the control and the conditions under which it produces a failed finding. This parameter may reference a specific standard.
StandardsControlArns (list) --
Provides the input parameter that Security Hub uses to call the UpdateStandardsControl API. This API can be used to enable or disable a control in a specified standard.
(string) --
UnprocessedAssociations (list) --
A security control (identified with SecurityControlId , SecurityControlArn , or a mix of both parameters) whose enablement status in a specified standard cannot be returned.
(dict) --
Provides details about which control's enablement status couldn't be retrieved in a specified standard when calling BatchUpdateStandardsControlAssociations. This parameter also provides details about why the request was unprocessed.
StandardsControlAssociationId (dict) --
An array with one or more objects that includes a security control (identified with SecurityControlId , SecurityControlArn , or a mix of both parameters) and the Amazon Resource Name (ARN) of a standard. This parameter shows the specific controls for which the enablement status couldn't be retrieved in specified standards when calling BatchUpdateStandardsControlAssociations.
SecurityControlId (string) --
The unique identifier (identified with SecurityControlId , SecurityControlArn , or a mix of both parameters) of a security control across standards.
StandardsArn (string) --
The ARN of a standard.
ErrorCode (string) --
The error code for the unprocessed standard and control association.
ErrorReason (string) --
The reason why the standard and control association was unprocessed.
Specifies whether a control is currently enabled or disabled in each enabled standard in the calling account.
See also: AWS API Documentation
Request Syntax
client.list_standards_control_associations(
SecurityControlId='string',
NextToken='string',
MaxResults=123
)
string
[REQUIRED]
The identifier of the control (identified with SecurityControlId , SecurityControlArn , or a mix of both parameters) that you want to determine the enablement status of in each enabled standard.
string
Optional pagination parameter.
integer
An optional parameter that limits the total results of the API response to the specified number. If this parameter isn't provided in the request, the results include the first 25 standard and control associations. The results also include a NextToken parameter that you can use in a subsequent API call to get the next 25 associations. This repeats until all associations for the specified control are returned. The number of results is limited by the number of supported Security Hub standards that you've enabled in the calling account.
dict
Response Syntax
{
'StandardsControlAssociationSummaries': [
{
'StandardsArn': 'string',
'SecurityControlId': 'string',
'SecurityControlArn': 'string',
'AssociationStatus': 'ENABLED'|'DISABLED',
'RelatedRequirements': [
'string',
],
'UpdatedAt': datetime(2015, 1, 1),
'UpdatedReason': 'string',
'StandardsControlTitle': 'string',
'StandardsControlDescription': 'string'
},
],
'NextToken': 'string'
}
Response Structure
(dict) --
StandardsControlAssociationSummaries (list) --
An array that provides the enablement status and other details for each security control that applies to each enabled standard.
(dict) --
An array that provides the enablement status and other details for each control that applies to each enabled standard.
StandardsArn (string) --
The Amazon Resource Name (ARN) of a standard.
SecurityControlId (string) --
A unique standard-agnostic identifier for a control. Values for this field typically consist of an Amazon Web Service and a number, such as APIGateway.5. This field doesn't reference a specific standard.
SecurityControlArn (string) --
The ARN of a control, such as arn:aws:securityhub:eu-central-1:123456789012:security-control/S3.1 . This parameter doesn't mention a specific standard.
AssociationStatus (string) --
The enablement status of a control in a specific standard.
RelatedRequirements (list) --
The requirement that underlies this control in the compliance framework related to the standard.
(string) --
UpdatedAt (datetime) --
The last time that a control's enablement status in a specified standard was updated.
UpdatedReason (string) --
The reason for updating the control's enablement status in a specified standard.
StandardsControlTitle (string) --
The title of a control.
StandardsControlDescription (string) --
The description of a control. This typically summarizes how Security Hub evaluates the control and the conditions under which it produces a failed finding. The parameter may reference a specific standard.
NextToken (string) --
A pagination parameter that's included in the response only if it was included in the request.
{'ControlFindingGenerator': 'STANDARD_CONTROL | SECURITY_CONTROL'}
Returns details about the Hub resource in your account, including the HubArn and the time when you enabled Security Hub.
See also: AWS API Documentation
Request Syntax
client.describe_hub(
HubArn='string'
)
string
The ARN of the Hub resource to retrieve.
dict
Response Syntax
{
'HubArn': 'string',
'SubscribedAt': 'string',
'AutoEnableControls': True|False,
'ControlFindingGenerator': 'STANDARD_CONTROL'|'SECURITY_CONTROL'
}
Response Structure
(dict) --
HubArn (string) --
The ARN of the Hub resource that was retrieved.
SubscribedAt (string) --
The date and time when Security Hub was enabled in the account.
AutoEnableControls (boolean) --
Whether to automatically enable new controls when they are added to standards that are enabled.
If set to true , then new controls for enabled standards are enabled automatically. If set to false , then new controls are not enabled.
ControlFindingGenerator (string) --
Specifies whether the calling account has consolidated control findings turned on. If the value for this field is set to SECURITY_CONTROL , Security Hub generates a single finding for a control check even when the check applies to multiple enabled standards.
If the value for this field is set to STANDARD_CONTROL , Security Hub generates separate findings for a control check when the check applies to multiple enabled standards.
The value for this field in a member account matches the value in the administrator account. For accounts that aren't part of an organization, the default value of this field is SECURITY_CONTROL if you enabled Security Hub on or after February 9, 2023.
{'ControlFindingGenerator': 'STANDARD_CONTROL | SECURITY_CONTROL'}
Enables Security Hub for your account in the current Region or the Region you specify in the request.
When you enable Security Hub, you grant to Security Hub the permissions necessary to gather findings from other services that are integrated with Security Hub.
When you use the EnableSecurityHub operation to enable Security Hub, you also automatically enable the following standards:
Center for Internet Security (CIS) Amazon Web Services Foundations Benchmark v1.2.0
Amazon Web Services Foundational Security Best Practices
Other standards are not automatically enabled.
To opt out of automatically enabled standards, set EnableDefaultStandards to false .
After you enable Security Hub, to enable a standard, use the BatchEnableStandards operation. To disable a standard, use the BatchDisableStandards operation.
To learn more, see the setup information in the Security Hub User Guide .
See also: AWS API Documentation
Request Syntax
client.enable_security_hub(
Tags={
'string': 'string'
},
EnableDefaultStandards=True|False,
ControlFindingGenerator='STANDARD_CONTROL'|'SECURITY_CONTROL'
)
dict
The tags to add to the hub resource when you enable Security Hub.
(string) --
(string) --
boolean
Whether to enable the security standards that Security Hub has designated as automatically enabled. If you do not provide a value for EnableDefaultStandards , it is set to true . To not enable the automatically enabled standards, set EnableDefaultStandards to false .
string
This field, used when enabling Security Hub, specifies whether the calling account has consolidated control findings turned on. If the value for this field is set to SECURITY_CONTROL , Security Hub generates a single finding for a control check even when the check applies to multiple enabled standards.
If the value for this field is set to STANDARD_CONTROL , Security Hub generates separate findings for a control check when the check applies to multiple enabled standards.
The value for this field in a member account matches the value in the administrator account. For accounts that aren't part of an organization, the default value of this field is SECURITY_CONTROL if you enabled Security Hub on or after February 9, 2023.
dict
Response Syntax
{}
Response Structure
(dict) --
{'ControlFindingGenerator': 'STANDARD_CONTROL | SECURITY_CONTROL'}
Updates configuration options for Security Hub.
See also: AWS API Documentation
Request Syntax
client.update_security_hub_configuration(
AutoEnableControls=True|False,
ControlFindingGenerator='STANDARD_CONTROL'|'SECURITY_CONTROL'
)
boolean
Whether to automatically enable new controls when they are added to standards that are enabled.
By default, this is set to true , and new controls are enabled automatically. To not automatically enable new controls, set this to false .
string
Updates whether the calling account has consolidated control findings turned on. If the value for this field is set to SECURITY_CONTROL , Security Hub generates a single finding for a control check even when the check applies to multiple enabled standards.
If the value for this field is set to STANDARD_CONTROL , Security Hub generates separate findings for a control check when the check applies to multiple enabled standards.
For accounts that are part of an organization, this value can only be updated in the administrator account.
dict
Response Syntax
{}
Response Structure
(dict) --