AwsSecurityFinding
Provides a consistent format for Security Hub findings.
AwsSecurityFinding
format allows you to share findings between AWS
security services and third-party solutions.
Note
A finding is a potential security issue generated either by AWS services or by the integrated third-party solutions and standards checks.
Contents
- AwsAccountId
-
The AWS account ID that a finding is generated in.
Length Constraints: 12.
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 that you can send to Security Hub:-
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
)
If a finding provider sends a finding to Security Hub that contains a timestamp in nanoseconds, we round it to milliseconds. For example, we round
2024-10-31T23:00:00.123456789Z
to2024-10-31T23:00:00.123Z
.Type: String
Pattern:
.*\S.*
Required: Yes
-
- Description
-
A finding's description.
Description
is a required property.Length Constraints: Minimum length of 1. Maximum length of 1024.
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, or something else.
Length Constraints: Minimum length of 1. Maximum length of 512.
Type: String
Pattern:
.*\S.*
Required: Yes
- Id
-
The security findings provider-specific identifier for a finding.
Length Constraints: Minimum length of 1. Maximum length of 512.
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.
Length Constraints: Minimum length of 12. Maximum length of 2048.
Type: String
Pattern:
.*\S.*
Required: Yes
- Resources
-
A set of resource data types that describe the resources that the finding refers to.
Array Members: Minimum number of 1 item. Maximum number of 32 items.
Type: Array of Resource objects
Required: Yes
- SchemaVersion
-
The schema version that a finding is formatted for. The value is
2018-10-08
.Type: String
Pattern:
.*\S.*
Required: Yes
- Title
-
A finding's title.
Title
is a required property.Length Constraints: Minimum length of 1. Maximum length of 256.
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 that you can send to Security Hub:-
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
)
If a finding provider sends a finding to Security Hub that contains a timestamp in nanoseconds, we round it to milliseconds. For example, we round
2024-10-31T23:00:00.123456789Z
to2024-10-31T23:00:00.123Z
.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 AWS account from which a finding was generated.
Length Constraints: Minimum length of 1. Maximum length of 50.
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
orBatchUpdateFindings
. 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.
Length Constraints: Minimum length of 1. Maximum length of 128.
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 AWS 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
- Detection
-
Provides details about an Amazon GuardDuty Extended Threat Detection attack sequence. GuardDuty generates an attack sequence finding when multiple events align to a potentially suspicious activity. To receive GuardDuty attack sequence findings in AWS Security Hub, you must have GuardDuty enabled. For more information, see GuardDuty Extended Threat Detection in the Amazon GuardDuty User Guide.
Type: Detection object
Required: No
- FindingProviderFields
-
In a
BatchImportFindings
request, finding providers useFindingProviderFields
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 that you can send to Security Hub:-
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
)
If a finding provider sends a finding to Security Hub that contains a timestamp in nanoseconds, we round it to milliseconds. For example, we round
2024-10-31T23:00:00.123456789Z
to2024-10-31T23:00:00.123Z
.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 AWS Lambda functions. Amazon Inspector identifies policy violations and vulnerabilities in Lambda function code based on internal detectors developed in collaboration with Amazon CodeGuru. AWS 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 that you can send to Security Hub:-
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
)
If a finding provider sends a finding to Security Hub that contains a timestamp in nanoseconds, we round it to milliseconds. For example, we round
2024-10-31T23:00:00.123456789Z
to2024-10-31T23:00:00.123Z
.Type: String
Pattern:
.*\S.*
Required: No
-
- Malware
-
A list of malware related to a finding.
Array Members: Maximum number of 5 items.
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 timestamp that indicates when AWS 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 that you can send to Security Hub:-
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
)
If a finding provider sends a finding to Security Hub that contains a timestamp in nanoseconds, we round it to milliseconds. For example, we round
2024-10-31T23:00:00.123456789Z
to2024-10-31T23:00:00.123Z
.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
orBatchUpdateFindings
. 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.
Length Constraints: Minimum length of 1. Maximum length of 128.
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
orBatchUpdateFindings
.Length Constraints: Minimum length of 1. Maximum length of 16.
Type: String
Pattern:
.*\S.*
Required: No
- RelatedFindings
-
A list of related findings.
Array Members: Minimum number of 1 item. Maximum number of 10 items.
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.
Array Members: Minimum number of 1 item. Maximum number of 5 items.
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.
Array Members: Minimum number of 1 item. Maximum number of 32 items.
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
Array Members: Maximum number of 50 items.
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.
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 1024 characters.
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 AWS SDKs, see the following: