AWS - Security Hub v2

This Integration is part of the AWS - Security Hub Pack.#

Supported versions

Available on Cortex XSOAR (versions 6.10.0 and later) and Cortex XSIAM.

Unified security and compliance findings management using the AWS Security Hub V2 API. This integration was integrated and tested with the AWS Security Hub V2 API.

Prerequisites#

AWS Security Hub V2 must be enabled in the target AWS account and region. You can enable it from the AWS console or with the aws-securityhub-v2-security-hub-enable command.
AWS credentials (an access key/secret key pair or an assumable IAM role) with the required Security Hub V2 permissions:
- securityhub:EnableSecurityHubV2
- securityhub:DisableSecurityHubV2
- securityhub:GetFindingsV2
- securityhub:BatchUpdateFindingsV2

Configure AWS - Security Hub v2 in Cortex#

Parameter	Description	Required
AWS Default Region		True
Access Key	The AWS Access Key ID (username) and Secret Access Key (password) paired together. If a 'Role Arn' is also provided, these credentials will be used to call AWS STS AssumeRole to obtain temporary credentials.	False
Role Arn	The full ARN of the role to assume via AWS STS, for example 'arn:aws:iam::123456789012:role/MyRole'.	False
Role Session Name	The role session name to use for authentication.	False
Role Session Duration	The maximum role session duration, in seconds.	False
Timeout	The time in seconds till a timeout exception is reached. You can specify just the read timeout (for example 60) or also the connect timeout followed after a comma (for example 60,10). If a connect timeout is not specified, a default of 10 seconds will be used.	False
Retries	The maximum number of retry attempts when connection or throttling errors are encountered. Set to 0 to disable retries. Note: Increasing the number of retries will increase the execution time.	False
PrivateLink service URL.		False
STS PrivateLink URL.		False
Trust any certificate (not secure)		False
Use system proxy settings		False
Fetch incidents		False
Incident type		False
First fetch time	The time range to consider for the initial data fetch, in the format <number> <unit> (for example, 3 days, 12 hours, 7 minutes).	False
Maximum number of incidents per fetch	The maximum number of findings to fetch per cycle. The maximum is 100.	False
Minimum severity to fetch	The minimum severity of findings to fetch, based on the OCSF severity_id. Findings with this severity or higher are fetched. Leave empty to fetch all severities.	False
Additional fetch filters	The extra string filters used to narrow the fetch, in the same format as the string_filters command argument: "field_name=<OCSF field>,value=<value>,comparison=<comparison>", multiple entries separated by ";". All entries are combined with the time and severity filters using AND. Defaults to excluding closed findings (status Resolved or Suppressed): "field_name=status,value=Resolved,comparison=NOT_EQUALS;field_name=status,value=Suppressed,comparison=NOT_EQUALS"; clear or edit this value to fetch closed findings.	False
Incident Mirroring Direction	The direction to mirror the finding: Incoming (from AWS - Security Hub to Cortex), Outgoing (from Cortex to AWS - Security Hub), or Incoming And Outgoing (from/to Cortex and AWS - Security Hub).	False
Resolve finding of closed incident from Cortex XSOAR in AWS Security Hub	Whether closing an incident in Cortex sets the corresponding finding's status to Resolved in AWS Security Hub (applies to outgoing mirroring).	False

Commands#

You can execute these commands from the CLI, as part of an automation, or in a playbook. After you successfully execute a command, a DBot message appears in the War Room with the command details.

aws-securityhub-v2-security-hub-enable#

Enables AWS Security Hub V2 for the configured account and region. Required IAM Permission: securityhub:EnableSecurityHubV2.

Base Command#

aws-securityhub-v2-security-hub-enable

Input#

Argument Name	Description	Required
tags	The tags to assign to the Security Hub V2 resource, in the format: key=key1,value=value1;key=key2,value=value2.	Optional

Context Output#

Path	Type	Description
AWS.SecurityHubV2.EnableHubV2.HubV2Arn	String	The ARN of the enabled Security Hub V2 resource.

Command example#

!aws-securityhub-v2-security-hub-enable tags=key=env,value=prod

Context Example#

{
    "AWS": {
        "SecurityHubV2": {
            "EnableHubV2": {
                "HubV2Arn": "arn:aws:securityhub:us-east-1:123456789012:hub/v2/default"
            }
        }
    }
}

Human Readable Output#

AWS Security Hub V2 successfully enabled.

aws-securityhub-v2-security-hub-disable#

Disables AWS Security Hub V2 for the configured account and region. Required IAM Permission: securityhub:DisableSecurityHubV2.

Base Command#

aws-securityhub-v2-security-hub-disable

Input#

There are no input arguments for this command.

Command example#

!aws-securityhub-v2-security-hub-disable

Human Readable Output#

AWS Security Hub V2 successfully disabled.

aws-securityhub-v2-findings-get#

Retrieves a list of OCSF-formatted findings from AWS Security Hub V2. Required IAM Permission: securityhub:GetFindingsV2.

Base Command#

aws-securityhub-v2-findings-get

Input#

Argument Name	Description	Required
string_filters	The string field filters. Each entry: "field_name=<OCSF field>,value=<value>,comparison=<EQUALS\|PREFIX\|NOT_EQUALS\|PREFIX_NOT_EQUALS\|CONTAINS_WORD>", multiple entries separated by ";". Comparison defaults to EQUALS. For substring matching use CONTAINS_WORD (CONTAINS/NOT_CONTAINS are not supported by this API). Example: field_name=severity,value=High,comparison=EQUALS;field_name=finding_info.title,value=root,comparison=CONTAINS_WORD.	Optional
date_filters	The date field filters. Each entry must use EITHER an absolute range ("field_name=<OCSF field>,start=<ISO8601>,end=<ISO8601>" - both start and end are required) OR a relative DateRange ("field_name=<OCSF field>,value=<number>,unit=<unit>,comparison=<comparison>" - value is required, unit defaults to DAYS, comparison is optional). "days=<number>" is accepted as a shorthand for "value=<number>,unit=DAYS". Multiple entries separated by ";". Examples: field_name=finding_info.created_time_dt,start=2024-01-01T00:00:00Z,end=2024-02-01T00:00:00Z OR field_name=finding_info.modified_time_dt,value=7,unit=DAYS OR field_name=finding_info.modified_time_dt,days=7.	Optional
boolean_filters	The boolean field filters. Each entry: "field_name=<OCSF field>,value=<true\|false>", multiple entries separated by ";".	Optional
number_filters	The number field filters. Each entry: "field_name=<OCSF field>,<operator>=<number>" where operator is one of eq/gt/gte/lt/lte. Multiple operators may be combined in a single entry, and multiple entries are separated by ";". Examples: field_name=severity_id,gte=4 OR field_name=severity_id,gte=4,lte=6.	Optional
map_filters	The map field filters. Each entry: "field_name=<OCSF field>,key=<key>,value=<value>,comparison=<EQUALS\|NOT_EQUALS>", multiple entries separated by ";". Comparison defaults to EQUALS.	Optional
ip_filters	The IP field filters. Each entry: "field_name=<field>,cidr=<IP address>", multiple entries separated by ";". Allowed field_name values: evidences.src_endpoint.ip, evidences.dst_endpoint.ip. The cidr value must be a plain IPv4 or IPv6 address (CIDR ranges like 10.0.0.0/8 are not accepted). Example: field_name=evidences.src_endpoint.ip,cidr=10.0.0.1.	Optional
filter_operator	The logical operator used to combine the filter conditions within the composite filter. Possible values are: AND, OR. Default is AND.	Optional
sort_field	The finding field to sort the results by.	Optional
sort_order	The order to sort the results by. Possible values are: asc, desc.	Optional
limit	The maximum number of findings to return. Default is 50.	Optional
next_token	The pagination token returned from a previous request, used to retrieve the next set of results.	Optional

Context Output#

Path	Type	Description
AWS.SecurityHubV2.Findings	Unknown	The list of OCSF-formatted findings returned by Security Hub V2. Each finding is a free-form OCSF object containing fields such as metadata, finding_info, severity, status, cloud, resources, and time.
AWS.SecurityHubV2.FindingsNextToken	String	The pagination token to use when requesting the next set of findings.

Command example#

!aws-securityhub-v2-findings-get string_filters="field_name=severity,value=High,comparison=EQUALS" limit=1

Context Example#

{
    "AWS": {
        "SecurityHubV2": {
            "Findings": [
                {
                    "metadata": {
                        "uid": "uid"
                    },
                    "class_name": "Compliance Finding",
                    "severity": "High",
                    "status": "New",
                    "resources": [
                        {
                            "uid": "arn:aws:s3:::my-example-bucket"
                        }
                    ]
                }
            ],
            "FindingsNextToken": "eyJuZXh0IjoxfQ=="
        }
    }
}

Human Readable Output#

AWS Security Hub V2 Findings#
uid severity status class_name resource_uid
uid High New Compliance Finding arn:aws:s3:::my-example-bucket

uid	severity	status	class_name	resource_uid
uid	High	New	Compliance Finding	arn:aws:s3:::my-example-bucket

aws-securityhub-v2-findings-batch-update#

Updates one or more AWS Security Hub V2 findings in a single batch request. Findings are targeted by metadata_uids and/or finding_identifiers. Required IAM Permission: securityhub:BatchUpdateFindingsV2.

Base Command#

aws-securityhub-v2-findings-batch-update

Input#

Argument Name	Description	Required
metadata_uids	A comma-separated list of OCSF finding metadata UIDs to update. Each UID must be a 64-character lowercase hexadecimal string (pattern ^[0-9a-z]{64}$), exactly as returned in the metadata.uid field by aws-securityhub-v2-findings-get.	Optional
finding_identifiers	The composite finding identifiers to update. Each entry: "cloud_account_uid=<id>,finding_info_uid=<id>,metadata_product_uid=<id>", multiple entries separated by ";".	Optional
comment	The reason for updating the findings.	Optional
severity_id	The new OCSF severity ID to assign to the findings (1=Informational, 2=Low, 3=Medium, 4=High, 5=Critical, 6=Fatal). Possible values are: 1, 2, 3, 4, 5, 6.	Optional
status_id	The new OCSF status ID to assign to the findings (1=New, 2=In Progress, 3=Suppressed, 4=Resolved). Possible values are: 1, 2, 3, 4.	Optional

Context Output#

Path	Type	Description
AWS.SecurityHubV2.BatchUpdateFindings.ProcessedFindings	Unknown	The list of findings that were successfully updated.
AWS.SecurityHubV2.BatchUpdateFindings.UnprocessedFindings	Unknown	The list of findings that could not be updated, including the error for each.

get-remote-data#

Returns the updated data of a single mirrored AWS Security Hub V2 finding. This command is used for mirroring and is not intended to be run manually.

Base Command#

get-remote-data

Input#

Argument Name	Description	Required
id	The finding metadata UID to retrieve.	Required
lastUpdate	The date string in local time representing the last time the incident was updated.	Optional

get-mapping-fields#

Returns the list of fields available for outgoing mirroring. This command is used for mirroring and is not intended to be run manually.

Base Command#

get-mapping-fields

Input#

There are no input arguments for this command.

update-remote-system#

Pushes local (Cortex XSOAR) incident changes to the corresponding AWS Security Hub V2 finding. This command is used for mirroring and is not intended to be run manually.

Base Command#

update-remote-system

Input#

Argument Name	Description	Required
remoteId	The remote finding metadata UID to update.	Optional

Incident Mirroring#

You can enable incident mirroring between Cortex incidents and AWS - Security Hub v2 corresponding findings. To set up the mirroring:

Enable Fetching incidents in your instance configuration.

In the Incident Mirroring Direction integration parameter, select in which direction the incidents should be mirrored:

Option	Description
None	Turns off incident mirroring.
Incoming	Any changes in AWS - Security Hub v2 findings (mirroring incoming fields) will be reflected in Cortex incidents.
Outgoing	Any changes in Cortex incidents will be reflected in AWS - Security Hub v2 findings (outgoing mirrored fields).
Incoming And Outgoing	Changes in Cortex incidents and AWS - Security Hub v2 findings will be reflected in both directions.

Newly fetched incidents will be mirrored in the chosen direction. However, this selection does not affect existing incidents. Important Note: To ensure the mirroring works as expected, mappers are required, both for incoming and outgoing, to map the expected fields in Cortex and AWS - Security Hub v2.

Close synchronization#

The integration syncs incident/finding closing in both directions:

Action	Result	Requires
Close an incident in Cortex XSOAR	The finding is set to Resolved (status_id 4) in AWS Security Hub.	Outgoing mirroring and the Resolve finding of closed incident from Cortex XSOAR in AWS Security Hub parameter enabled.
Resolve or Suppress a finding in AWS Security Hub	The corresponding Cortex XSOAR incident is closed.	Incoming mirroring.

Note: Reopening is not supported in either direction. Reopening a closed incident in Cortex XSOAR does not reopen the finding in AWS Security Hub, and reopening a resolved finding in AWS Security Hub does not reopen the corresponding Cortex XSOAR incident.