Amazon Security Hub

Amazon Web Services

Overview

Integrates with AWS Security Hub to retrieve aggregated security findings across the configured AWS accounts and regions. Security Hub consolidates findings from AWS services (GuardDuty, Inspector, Macie, IAM Access Analyzer, security standards controls, etc.) and partner products into a normalized format. The connector reads those findings via either the classic GetFindings API (ASFF, the default) or GetFindingsV2 (OCSF 1.6), selected with the apiVersion configuration property, and emits two models: a Finding per (resource, finding) pair — so a single finding that references multiple resources produces one object per resource — and a FindingDefinition per distinct rule/control, which carries the authoritative severity, description and remediation shared by every finding of that rule.

Data retrieved from Amazon Security Hub

Connector Object	Required	Maps to Data Model
Finding	Yes	Finding
FindingDefinition	Yes	Finding Definition

note

For detailed steps on how to view the data retrieved from Amazon Security Hub in the Brinqa Platform, see How to view your data.

Setup

Connection settings

When setting up a data integration, select Amazon Security Hub from the Connector dropdown and provide the following:

Setting	Required	Default	Description
Access key ID	No	—	AWS user access key ID, if not specified, the connector consults the default credentials provider chain to try and determine the \
Secret access key	No	—	AWS user secret access key, if not specified, the connector consults the default credentials provider chain to try and determine the \
Default region	No	us-east-1	Default AWS region, if not specified, the connector consults the default region provider chain to try and determine the region to use.
Assume role	No	—	Amazon Resource Name for the role to assume.
External ID	No	—	Optional STS external ID, sent when assuming the role named in the Assume role \
Session duration	No	900	Assume role session duration in seconds.
API version	No	v1	Security Hub API used to retrieve findings: "v1" for the classic GetFindings API \
Page size	No	100	The maximum number of results to retrieve per operation.
Parallel requests	No	min(4, CPU cores)	Maximum number of parallel requests.

Authentication

Authentication is shared across the AWS connector bundle via the AwsConfiguration base class. The Security Hub sub-connector uses the AWS SDK for Java v2 SecurityHubClient, which signs every request with AWS SigV4 using credentials resolved through the following chain (in order):

1. STS AssumeRole — if assumeRoleARN is configured, the connector assumes that role (using the credentials below as the principal) and uses the resulting temporary session credentials. Set externalId as well if the role's trust policy enforces an ExternalId condition; it is sent on the AssumeRole call and is required for cross-account confused-deputy protection.
2. Static access keys — if accessKey / secretKey are configured, they are used directly.
3. Default credentials provider chain — environment variables, ~/.aws/credentials, container role, or EC2 instance metadata.

Assumed-role sessions use the configurable sessionDuration (default 900 s) with a unique session name per sync. A SecurityHubClient is constructed per role per region; each client is closed when its region has been fully synced.

Choosing an authentication path

The list above is the order the connector resolves credentials in. In terms of what to configure, three paths are supported:

Path	Configure	When to use
STS AssumeRole (recommended)	assumeRoleARN, plus externalId if the trust policy requires one	Cross-account access, and the only path that supports an ExternalId condition. Still needs a principal, from either of the paths below.
Default credentials provider chain (fully keyless)	nothing	The platform runs inside your AWS account on an EC2 instance profile or an EKS IRSA role. No long-lived keys exist anywhere.
Static access keys (optional)	accessKey, secretKey	The platform runs outside your AWS account and no role is available. Long-lived credentials — prefer either path above.

sts:AssumeRole is required only when assumeRoleARN is set.

Required AWS API permissions

Permission	Purpose
securityhub:GetFindings	List and page through security findings (apiVersion: v1)
securityhub:GetFindingsV2	Required when apiVersion: v2. AWS defines a separate action for the V2 API surface; grant both if you may switch between modes.
ec2:DescribeRegions	Discover the set of regions to query when no explicit region/regions option is supplied
sts:AssumeRole	Only when assumeRoleARN is set

API version

apiVersion	API called	Response format
v1 (default)	GetFindings	ASFF
v2	GetFindingsV2	OCSF 1.6

v1 is the default so existing deployments are unaffected. v2 requires the new Security Hub experience to be enabled on the AWS account and region, and credentials permitted to call GetFindingsV2. If either is missing, or the filter set is rejected, the connector fails with a message naming the AWS error code and listing those causes, rather than surfacing an opaque SDK error. An unrecognised apiVersion is rejected at configuration validation rather than silently falling back.

Both modes produce the same two models and the same record identities — the Uid is an MD5 of the resource and finding identifiers either way, so switching modes does not re-identify existing findings. Five attributes have no OCSF source and are therefore populated in classic mode only: Workflow status, Record state, Confidence, Rule ID, and the numeric fallback behind Source severity.

Three filter options have no OCSF equivalent and are therefore classic-mode only:

Option / behavior	Reason
RecordState (and its ACTIVE default)	OCSF has no record-state field
ProductArn	OCSF identifies products by name and uid, not by ARN — use ProductName in v2
Severity numeric value	OCSF reports a severity label; severity_id is a 1–6 scale, not ASFF's 0–100, so the numeric severity is not populated in v2

OCSF field mapping (v2)

Snapshot / attribute	OCSF path
Finding ID	finding_info.uid
Resource ID	resources[].uid (one Brinqa object per resource, as in v1)
Name / Description	finding_info.title / finding_info.desc
Source severity	severity
Provider status	compliance.status, else the top-level status
Types / Categories	finding_info.types
Product name / Company name	metadata.product.name / metadata.product.vendor_name
Control ID / Compliance requirements	compliance.control / compliance.standards
Recommendation	remediation.desc
Cloud account ID / Resource type / Region	cloud.account.uid / resources[].type / resources[].region, else cloud.region
Source created date / Source last modified	finding_info.created_time_dt / finding_info.modified_time_dt
First found / Last found	finding_info.first_seen_time_dt / finding_info.last_seen_time_dt
CVE IDs	vulnerabilities[].cve.uid and vulnerabilities[].related_vulnerabilities[]

In v2 the FindingDefinition key resolves as compliance.control → metadata.product.name + | + finding_info.title → finding_info.title → metadata.product.name → finding_info.uid. OCSF has no generatorId, but compliance.control is the stable control identifier that rung was standing in for.

Sync Behavior

The connector supports incremental sync. When a prior sync timestamp is available, it passes a since (Instant) value, computes the whole number of days between since and now, and — if that value is greater than zero — applies a lastObservedAt DateFilter (DateRange in DAYS) so only findings observed within that trailing window are returned. If since is null or the interval rounds down to zero days, no date filter is applied and every matching finding is returned (a full sync). The default ComplianceStatus = FAILED and RecordState = ACTIVE filters apply in both cases.

In v2 the same day-range window is applied as an OCSF DateFilter on finding_info.last_seen_time_dt, the OCSF equivalent of lastObservedAt.

Shared response cache

Both models are driven from a single pass over the API. Whichever model syncs first pages through the configured findings API and caches each (finding, resource) pair in a local key-value store scoped by the platform-supplied TRANSACTION_ID; the second model streams that cache instead of calling AWS again. A sync of both models therefore issues the GetFindings pages exactly once. If the walk is cancelled part-way (for example by the connection test, which stops after the first result), the partial cache is discarded so a later sync in the same transaction cannot mistake it for a complete capture.

How to obtain Amazon Security Hub credentials

Obtain the required credentials from your Amazon Security Hub administrator or the Amazon Security Hub admin console, then enter them in the connection settings above.

Data & mappings

Attribute mappings

Expand the sections below to view the mappings between the source and the Brinqa data model attributes:

Finding

Source Field Name	SDM Attribute
AwsSecurityFinding.awsAccountId	Cloud account ID
AwsSecurityFinding.compliance().status, else the OCSF top-level status (v2), else AwsSecurityFinding.recordState	Provider status
AwsSecurityFinding.confidence	Confidence
AwsSecurityFinding.createdAt	Source created date
AwsSecurityFinding.firstObservedAt	First found
AwsSecurityFinding.id	Finding ID
AwsSecurityFinding.lastObservedAt	Last found
AwsSecurityFinding.recordState	Record state
AwsSecurityFinding.title	Name
AwsSecurityFinding.updatedAt	Source last modified
AwsSecurityFinding.workflow().status	Workflow status
Constant AWS	Cloud provider
Definition key (see the FindingDefinition model)	Type
MD5 of Resource.id + AwsSecurityFinding.id	UID
Normalized from the value above	Source status
Resource.id	Targets
Resource.id	Resource ID
Resource.region	Region
Resource.type	Resource type
Sync time	Last captured

note

The Source Field column names the classic ASFF fields (apiVersion: v1). Under apiVersion: v2 the same attributes are filled from the OCSF equivalents listed in this connector's OCSF field mapping table; Workflow status, Record state and Confidence have no OCSF source and stay unset.

FindingDefinition

Source Field Name	SDM Attribute
AwsSecurityFinding.companyName	Company name
AwsSecurityFinding.compliance().relatedRequirements	Compliance requirements (multivalued)
AwsSecurityFinding.description	Description
AwsSecurityFinding.generatorId	Rule ID
AwsSecurityFinding.productFields["ControlId"]	Control ID
AwsSecurityFinding.productName	Product name
AwsSecurityFinding.remediation().recommendation().text	Recommendation
AwsSecurityFinding.severity().label	Source severity
AwsSecurityFinding.title	Name
AwsSecurityFinding.types	Categories
AwsSecurityFinding.types	Types
AwsSecurityFinding.vulnerabilities[].id and relatedVulnerabilities	CVE IDs (multivalued)
Constant AWS	Cloud provider
Definition key (see the notes below)	UID
Derived from the normalized severity	Severity score
Normalized from severity().label, else severity().normalized	Severity
productName, companyName	Tags
Same as CVE IDs	CVE records (multivalued)
Sync time	Last captured

note

Definitions are deduplicated last-wins: when several findings resolve to the same definition key, the last one processed supplies the definition's severity, description and remediation. For products whose generatorId embeds an account- or detector-specific ARN, definitions may be keyed more finely than the underlying rule. Under apiVersion: v2, a product that reports no title at all groups every one of its findings under a single product-named definition, whose rule-level attributes come from one arbitrary sample.

Operations & API

Operations & API

Expand each connector object to see its operation options, delta-sync behavior, and the API it uses. See connector operation options for how to apply operation options (keys and values are case-sensitive).

Finding

Operation options

Option	Type	Default	Description
region / regions	String (comma-separated)	All regions from ec2:DescribeRegions, falling back to the region configuration	Regions to query — one client per region. regions takes precedence over region.
pageSize	Integer	Shared pageSize configuration (100)	maxResults page size for each findings call.
Severity	String (comma-separated)	none (no severity filter)	Filters by severity label(s) (EQUALS match). In v2 this maps to the OCSF severity field.
ComplianceStatus	String (comma-separated)	FAILED	Filters by compliance status (EQUALS match). See the interaction note below.
RecordState	String (comma-separated)	ACTIVE	Filters by record state (EQUALS match). Classic mode only — OCSF has no record-state field, so no default is applied under apiVersion: v2.
WorkflowStatus	String (comma-separated)	none (no workflow filter)	Filters by workflow status (EQUALS match). In v2 this maps to the OCSF top-level status.
ProductName	String (comma-separated)	none	Filters by source product display name (EQUALS match). Supported in both API modes; in v2 it maps to OCSF metadata.product.name.
ProductArn	String (comma-separated)	none	Filters by source product ARN (EQUALS match). Classic mode only — it is ignored with a warning under apiVersion: v2.
TRANSACTION_ID	String	no transaction scoping	Supplied by the platform, not by the user; scopes the shared response cache so both models read one set of API responses.

Delta sync

Supported. The connector performs an incremental (delta) sync via the since sync token, filtering on lastObservedAt.

API

• Type: AWS SDK for Java v2 (SecurityHubClient) · Endpoint: securityhub:GetFindings
• Default filters: ComplianceStatus = FAILED and RecordState = ACTIVE (record state is applied in classic mode only — OCSF has no such field); each default is dropped when the matching operation option is supplied, and the compliance default is dropped entirely when ProductName (or, in classic mode, ProductArn) is set.

note

In v2, each multi-valued option becomes one OCSF filter per value within a single composite filter, and the service accepts at most 20 filters of one type. An option carrying more than 20 values is rejected up front with a message naming the option, rather than failing inside AWS.

info

Product filters and the ComplianceStatus default interact. The default ComplianceStatus = FAILED matches only findings that carry a Compliance object — that is, security-standards control findings. Findings from non-control products such as GuardDuty or Macie typically have no compliance status at all.

To stop that default from silently excluding everything you asked for, the connector does not apply the ComplianceStatus default when ProductName is set — in either API mode — or when ProductArn is set in classic mode. ProductArn is not applied at all under apiVersion: v2, so letting it drop the default there would widen the sync instead of scoping it. Setting ComplianceStatus explicitly always takes precedence over both behaviors, so you can still scope a product filter to failed control findings if that is what you want.

FindingDefinition

Operation options

Option	Type	Default	Description
region / regions	String (comma-separated)	All regions from ec2:DescribeRegions, falling back to the region configuration	Regions to query — one client per region. regions takes precedence over region.
pageSize	Integer	Shared pageSize configuration (100)	maxResults page size for each findings call.
Severity	String (comma-separated)	none (no severity filter)	Filters by severity label(s) (EQUALS match). In v2 this maps to the OCSF severity field.
ComplianceStatus	String (comma-separated)	FAILED	Filters by compliance status (EQUALS match). See the interaction note below.
RecordState	String (comma-separated)	ACTIVE	Filters by record state (EQUALS match). Classic mode only — OCSF has no record-state field, so no default is applied under apiVersion: v2.
WorkflowStatus	String (comma-separated)	none (no workflow filter)	Filters by workflow status (EQUALS match). In v2 this maps to the OCSF top-level status.
ProductName	String (comma-separated)	none	Filters by source product display name (EQUALS match). Supported in both API modes; in v2 it maps to OCSF metadata.product.name.
ProductArn	String (comma-separated)	none	Filters by source product ARN (EQUALS match). Classic mode only — it is ignored with a warning under apiVersion: v2.
TRANSACTION_ID	String	no transaction scoping	Supplied by the platform, not by the user; scopes the shared response cache so both models read one set of API responses.

Delta sync

Supported. The connector performs an incremental (delta) sync via the since sync token, filtering on lastObservedAt.

API

• Type: AWS SDK for Java v2 (SecurityHubClient) — the same findings call as the Finding model, issued once per sync · Endpoint: securityhub:GetFindings
• Default filters: ComplianceStatus = FAILED and RecordState = ACTIVE (record state is applied in classic mode only), exactly as for the Finding model — the definitions produced are those of the findings the filters admitted.

note

In v2, each multi-valued option becomes one OCSF filter per value within a single composite filter, and the service accepts at most 20 filters of one type. An option carrying more than 20 values is rejected up front with a message naming the option, rather than failing inside AWS.

info

Product filters and the ComplianceStatus default interact. The default ComplianceStatus = FAILED matches only findings that carry a Compliance object — that is, security-standards control findings. Findings from non-control products such as GuardDuty or Macie typically have no compliance status at all.

To stop that default from silently excluding everything you asked for, the connector does not apply the ComplianceStatus default when ProductName is set — in either API mode — or when ProductArn is set in classic mode. ProductArn is not applied at all under apiVersion: v2, so letting it drop the default there would widen the sync instead of scoping it. Setting ComplianceStatus explicitly always takes precedence over both behaviors, so you can still scope a product filter to failed control findings if that is what you want.

note

Definition key. In classic mode (apiVersion: v1) the Uid resolves in this order:

1. AwsSecurityFinding.productFields["ControlId"] — the security-standard control identifier (e.g. S3.1); stable across accounts and regions.
2. AwsSecurityFinding.generatorId — the rule/generator that produced the finding.
3. productName + | + title — for products that expose neither of the above.
4. title alone.
5. AwsSecurityFinding.id — last resort, so the key is never blank. This degenerates to one definition per finding rather than breaking the link between the two models.

Under apiVersion: v2 the order is compliance.control → metadata.product.name + | + finding_info.title → finding_info.title → metadata.product.name → finding_info.uid. OCSF has no generatorId equivalent, but compliance.control is the stable control identifier that rung stood in for. Because the product name is itself a rung in v2, a titleless product collapses to a single definition instead of one per finding.

Changelog

Changelog

The Amazon Security Hub connector has undergone the following changes:

Version	Description	Migration Steps
3.2.3	New Features - The Amazon Security Hub connector is now available in this connector bundle. It can be selected and configured alongside the other Amazon Web Services connectors; previously it shipped only on the 2.x line. - Findings now have finding definitions. Every finding is paired with a definition record, one per Security Hub control or rule. Severity, description, remediation guidance, compliance requirements and CVE identifiers are stored once on the definition and shared by every finding that reports that control, instead of being repeated on each individual finding. - Findings can now be retrieved through the new Security Hub API. A new API version setting selects between the classic findings API (the default, unchanged) and GetFindingsV2, which returns findings in OCSF 1.6 format. Existing connectors keep using the classic API until you opt in. The new API requires the new Security Hub experience to be enabled on the AWS account; if it is not, the connector reports the AWS error and tells you how to proceed instead of failing obscurely. Both versions produce the same models and record identities, so switching does not re-identify existing findings; a few attributes that the classic API supplies have no equivalent in the new format and are left unset there. - Findings can now be filtered by source product. New Product name and Product ARN options limit ingestion to specific products — for example only GuardDuty, only Inspector, or a single partner integration — to control finding volume. Product name works with both API versions; product ARN applies to the classic API only, since OCSF identifies products by name rather than ARN. Because findings from non-control products such as GuardDuty and Macie carry no compliance status, the connector automatically stops applying its default ComplianceStatus = FAILED filter when a product filter applies, so filtering to those products returns their findings rather than nothing. Setting the compliance status option explicitly still takes precedence. - Roles that require an External ID can now be used. A new optional External ID setting is sent when assuming the role named in the connector's Assume role setting, so roles whose trust policy enforces an ExternalId condition — the standard protection against cross-account confused-deputy access — can now be assumed. Existing configurations are unaffected: leave it blank and the role is assumed exactly as before. The connector's authentication documentation now also describes all three supported paths — assuming a role, running fully keyless from an EC2 instance profile or EKS IRSA role, and static access keys. Improvements - Findings are linked to the resource they were detected on. Each finding now reports its affected resource as a target, so findings associate with the corresponding asset. - More detail on each finding. Findings now include both the provider's status and a normalized status, the cloud account, region and provider, and the created, last-modified, first-observed and last-observed timestamps as dates rather than raw numbers. - Findings and definitions are collected in a single pass. Synchronizing both models issues one set of Security Hub API calls instead of two, reducing API usage and sync time. Bug Fixes - A finding with an unreadable date no longer aborts the synchronization. Previously a malformed timestamp on any finding propagated a parsing error and ended the sync; the connector now omits just that value, records a warning identifying the finding, and continues.	• Finding: the attribute set changed. Severity, description, remediation guidance, compliance requirements, product and company names, and rule and control identifiers moved to the new finding definition model, and date attributes changed from numeric timestamps to date values. Action: re-sync the connector. Finding identities are unchanged, so no purge is required.
3.2.2	No changes in this release.	N/A
3.2.1	No changes in this release.	N/A
3.2.0	No changes in this release.	N/A
3.1.0	Improvements - Sync failures are now visible. Previously, certain AWS API errors (throttling, server errors, transient network failures, validation errors) could be silently swallowed during multi-region sync, producing empty results without indicating a problem. These now surface as sync failures with a clear log entry detailing the HTTP status, AWS error code, request id, and service name. Per-region permission gaps (HTTP 401 / 403) still allow the sync to continue across other regions, but are now visible in logs.	N/A