AwsSecurityFinding - Amazon Security Hub
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

AwsSecurityFinding

Provides a consistent format for Security Hub findings. AwsSecurityFinding format allows you to share findings between Amazon security services and third-party solutions.

Note

A finding is a potential security issue generated either by Amazon services or by the integrated third-party solutions and standards checks.

Contents

AwsAccountId

The Amazon Web Services account ID that a finding is generated in.

Type: String

Pattern: .*\S.*

Required: Yes

CreatedAt

Indicates when the security findings provider created the potential security issue that a finding captured.

This field accepts only the specified formats. Timestamps can end with Z or ("+" / "-") time-hour [":" time-minute]. The time-secfrac after seconds is limited to a maximum of 9 digits. The offset is bounded by +/-18:00. Here are valid timestamp formats with examples:

  • YYYY-MM-DDTHH:MM:SSZ (for example, 2019-01-31T23:00:00Z)

  • YYYY-MM-DDTHH:MM:SS.mmmmmmmmmZ (for example, 2019-01-31T23:00:00.123456789Z)

  • YYYY-MM-DDTHH:MM:SS+HH:MM (for example, 2024-01-04T15:25:10+17:59)

  • YYYY-MM-DDTHH:MM:SS-HHMM (for example, 2024-01-04T15:25:10-1759)

  • YYYY-MM-DDTHH:MM:SS.mmmmmmmmm+HH:MM (for example, 2024-01-04T15:25:10.123456789+17:59)

Type: String

Pattern: .*\S.*

Required: Yes

Description

A finding's description.

Note

In this release, Description is a required property.

Type: String

Pattern: .*\S.*

Required: Yes

GeneratorId

The identifier for the solution-specific component (a discrete unit of logic) that generated a finding. In various security findings providers' solutions, this generator can be called a rule, a check, a detector, a plugin, etc.

Type: String

Pattern: .*\S.*

Required: Yes

Id

The security findings provider-specific identifier for a finding.

Type: String

Pattern: .*\S.*

Required: Yes

ProductArn

The ARN generated by Security Hub that uniquely identifies a product that generates findings. This can be the ARN for a third-party product that is integrated with Security Hub, or the ARN for a custom integration.

Type: String

Pattern: .*\S.*

Required: Yes

Resources

A set of resource data types that describe the resources that the finding refers to.

Type: Array of Resource objects

Required: Yes

SchemaVersion

The schema version that a finding is formatted for.

Type: String

Pattern: .*\S.*

Required: Yes

Title

A finding's title.

Note

In this release, Title is a required property.

Type: String

Pattern: .*\S.*

Required: Yes

UpdatedAt

Indicates when the security findings provider last updated the finding record.

This field accepts only the specified formats. Timestamps can end with Z or ("+" / "-") time-hour [":" time-minute]. The time-secfrac after seconds is limited to a maximum of 9 digits. The offset is bounded by +/-18:00. Here are valid timestamp formats with examples:

  • YYYY-MM-DDTHH:MM:SSZ (for example, 2019-01-31T23:00:00Z)

  • YYYY-MM-DDTHH:MM:SS.mmmmmmmmmZ (for example, 2019-01-31T23:00:00.123456789Z)

  • YYYY-MM-DDTHH:MM:SS+HH:MM (for example, 2024-01-04T15:25:10+17:59)

  • YYYY-MM-DDTHH:MM:SS-HHMM (for example, 2024-01-04T15:25:10-1759)

  • YYYY-MM-DDTHH:MM:SS.mmmmmmmmm+HH:MM (for example, 2024-01-04T15:25:10.123456789+17:59)

Type: String

Pattern: .*\S.*

Required: Yes

Action

Provides details about an action that affects or that was taken on a resource.

Type: Action object

Required: No

AwsAccountName

The name of the Amazon Web Services account from which a finding was generated.

Type: String

Pattern: .*\S.*

Required: No

CompanyName

The name of the company for the product that generated the finding.

Security Hub populates this attribute automatically for each finding. You cannot update this attribute with BatchImportFindings or BatchUpdateFindings. The exception to this is a custom integration.

When you use the Security Hub console or API to filter findings by company name, you use this attribute.

Type: String

Pattern: .*\S.*

Required: No

Compliance

This data type is exclusive to findings that are generated as the result of a check run against a specific rule in a supported security standard, such as CIS Amazon Foundations. Contains security standard-related finding details.

Type: Compliance object

Required: No

Confidence

A finding's confidence. Confidence is defined as the likelihood that a finding accurately identifies the behavior or issue that it was intended to identify.

Confidence is scored on a 0-100 basis using a ratio scale, where 0 means zero percent confidence and 100 means 100 percent confidence.

Type: Integer

Required: No

Criticality

The level of importance assigned to the resources associated with the finding.

A score of 0 means that the underlying resources have no criticality, and a score of 100 is reserved for the most critical resources.

Type: Integer

Required: No

FindingProviderFields

In a BatchImportFindings request, finding providers use FindingProviderFields to provide and update their own values for confidence, criticality, related findings, severity, and types.

Type: FindingProviderFields object

Required: No

FirstObservedAt

Indicates when the security findings provider first observed the potential security issue that a finding captured.

This field accepts only the specified formats. Timestamps can end with Z or ("+" / "-") time-hour [":" time-minute]. The time-secfrac after seconds is limited to a maximum of 9 digits. The offset is bounded by +/-18:00. Here are valid timestamp formats with examples:

  • YYYY-MM-DDTHH:MM:SSZ (for example, 2019-01-31T23:00:00Z)

  • YYYY-MM-DDTHH:MM:SS.mmmmmmmmmZ (for example, 2019-01-31T23:00:00.123456789Z)

  • YYYY-MM-DDTHH:MM:SS+HH:MM (for example, 2024-01-04T15:25:10+17:59)

  • YYYY-MM-DDTHH:MM:SS-HHMM (for example, 2024-01-04T15:25:10-1759)

  • YYYY-MM-DDTHH:MM:SS.mmmmmmmmm+HH:MM (for example, 2024-01-04T15:25:10.123456789+17:59)

Type: String

Pattern: .*\S.*

Required: No

GeneratorDetails

Provides metadata for the Amazon CodeGuru detector associated with a finding. This field pertains to findings that relate to Amazon Lambda functions. Amazon Inspector identifies policy violations and vulnerabilities in Lambda function code based on internal detectors developed in collaboration with Amazon CodeGuru. Amazon Security Hub receives those findings.

Type: GeneratorDetails object

Required: No

LastObservedAt

Indicates when the security findings provider most recently observed the potential security issue that a finding captured.

This field accepts only the specified formats. Timestamps can end with Z or ("+" / "-") time-hour [":" time-minute]. The time-secfrac after seconds is limited to a maximum of 9 digits. The offset is bounded by +/-18:00. Here are valid timestamp formats with examples:

  • YYYY-MM-DDTHH:MM:SSZ (for example, 2019-01-31T23:00:00Z)

  • YYYY-MM-DDTHH:MM:SS.mmmmmmmmmZ (for example, 2019-01-31T23:00:00.123456789Z)

  • YYYY-MM-DDTHH:MM:SS+HH:MM (for example, 2024-01-04T15:25:10+17:59)

  • YYYY-MM-DDTHH:MM:SS-HHMM (for example, 2024-01-04T15:25:10-1759)

  • YYYY-MM-DDTHH:MM:SS.mmmmmmmmm+HH:MM (for example, 2024-01-04T15:25:10.123456789+17:59)

Type: String

Pattern: .*\S.*

Required: No

Malware

A list of malware related to a finding.

Type: Array of Malware objects

Required: No

Network

The details of network-related information about a finding.

Type: Network object

Required: No

NetworkPath

Provides information about a network path that is relevant to a finding. Each entry under NetworkPath represents a component of that path.

Type: Array of NetworkPathComponent objects

Required: No

Note

A user-defined note added to a finding.

Type: Note object

Required: No

PatchSummary

Provides an overview of the patch compliance status for an instance against a selected compliance standard.

Type: PatchSummary object

Required: No

Process

The details of process-related information about a finding.

Type: ProcessDetails object

Required: No

ProcessedAt

A imestamp that indicates when Amazon Security Hub received a finding and begins to process it.

This field accepts only the specified formats. Timestamps can end with Z or ("+" / "-") time-hour [":" time-minute]. The time-secfrac after seconds is limited to a maximum of 9 digits. The offset is bounded by +/-18:00. Here are valid timestamp formats with examples:

  • YYYY-MM-DDTHH:MM:SSZ (for example, 2019-01-31T23:00:00Z)

  • YYYY-MM-DDTHH:MM:SS.mmmmmmmmmZ (for example, 2019-01-31T23:00:00.123456789Z)

  • YYYY-MM-DDTHH:MM:SS+HH:MM (for example, 2024-01-04T15:25:10+17:59)

  • YYYY-MM-DDTHH:MM:SS-HHMM (for example, 2024-01-04T15:25:10-1759)

  • YYYY-MM-DDTHH:MM:SS.mmmmmmmmm+HH:MM (for example, 2024-01-04T15:25:10.123456789+17:59)

Type: String

Pattern: .*\S.*

Required: No

ProductFields

A data type where security findings providers can include additional solution-specific details that aren't part of the defined AwsSecurityFinding format.

Can contain up to 50 key-value pairs. For each key-value pair, the key can contain up to 128 characters, and the value can contain up to 2048 characters.

Type: String to string map

Key Pattern: .*\S.*

Value Pattern: .*\S.*

Required: No

ProductName

The name of the product that generated the finding.

Security Hub populates this attribute automatically for each finding. You cannot update this attribute with BatchImportFindings or BatchUpdateFindings. The exception to this is a custom integration.

When you use the Security Hub console or API to filter findings by product name, you use this attribute.

Type: String

Pattern: .*\S.*

Required: No

RecordState

The record state of a finding.

Type: String

Valid Values: ACTIVE | ARCHIVED

Required: No

Region

The Region from which the finding was generated.

Security Hub populates this attribute automatically for each finding. You cannot update it using BatchImportFindings or BatchUpdateFindings.

Type: String

Pattern: .*\S.*

Required: No

RelatedFindings

A list of related findings.

Type: Array of RelatedFinding objects

Required: No

Remediation

A data type that describes the remediation options for a finding.

Type: Remediation object

Required: No

Sample

Indicates whether the finding is a sample finding.

Type: Boolean

Required: No

Severity

A finding's severity.

Type: Severity object

Required: No

SourceUrl

A URL that links to a page about the current finding in the security findings provider's solution.

Type: String

Pattern: .*\S.*

Required: No

ThreatIntelIndicators

Threat intelligence details related to a finding.

Type: Array of ThreatIntelIndicator objects

Required: No

Threats

Details about the threat detected in a security finding and the file paths that were affected by the threat.

Type: Array of Threat objects

Required: No

Types

One or more finding types in the format of namespace/category/classifier that classify a finding.

Valid namespace values are: Software and Configuration Checks | TTPs | Effects | Unusual Behaviors | Sensitive Data Identifications

Type: Array of strings

Pattern: .*\S.*

Required: No

UserDefinedFields

A list of name/value string pairs associated with the finding. These are custom, user-defined fields added to a finding.

Type: String to string map

Key Pattern: .*\S.*

Value Pattern: .*\S.*

Required: No

VerificationState

Indicates the veracity of a finding.

Type: String

Valid Values: UNKNOWN | TRUE_POSITIVE | FALSE_POSITIVE | BENIGN_POSITIVE

Required: No

Vulnerabilities

Provides a list of vulnerabilities associated with the findings.

Type: Array of Vulnerability objects

Required: No

Workflow

Provides information about the status of the investigation into a finding.

Type: Workflow object

Required: No

WorkflowState

This member has been deprecated.

The workflow state of a finding.

Type: String

Valid Values: NEW | ASSIGNED | IN_PROGRESS | DEFERRED | RESOLVED

Required: No

See Also

For more information about using this API in one of the language-specific Amazon SDKs, see the following: