findings
Creates, updates, deletes, gets or lists a findings resource.
Overview
| Name | findings |
| Type | Resource |
| Id | aws.securityhub.findings |
Fields
The following fields are returned by SELECT queries:
- get_findings
| Name | Datatype | Description |
|---|---|---|
action | object | Provides details about an action that affects or that was taken on a resource. |
aws_account_id | string | The Amazon Web Services account ID that a finding is generated in. Length Constraints: 12. (pattern: <code>.\S.</code>) |
aws_account_name | string | The name of the Amazon Web Services account from which a finding was generated. Length Constraints: Minimum length of 1. Maximum length of 50. (pattern: <code>.\S.</code>) |
company_name | string | The name of the company for the product that generated the finding. Security Hub CSPM 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 CSPM console or API to filter findings by company name, you use this attribute. Length Constraints: Minimum length of 1. Maximum length of 128. (pattern: <code>.\S.</code>) |
compliance | object | 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 Web Services Foundations. Contains security standard-related finding details. |
confidence | integer | 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. |
created_at | string | Indicates when the security findings provider created the potential security issue that a finding captured. For more information about the validation and formatting of timestamp fields in Security Hub CSPM, see Timestamps. (pattern: <code>.\S.</code>) |
criticality | integer | 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. |
description | string | A finding's description. Description is a required property. Length Constraints: Minimum length of 1. Maximum length of 1024. (pattern: <code>.\S.</code>) |
detection | object | 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 Security Hub CSPM, you must have GuardDuty enabled. For more information, see GuardDuty Extended Threat Detection in the Amazon GuardDuty User Guide. |
finding_provider_fields | object | In a BatchImportFindings request, finding providers use FindingProviderFields to provide and update their own values for confidence, criticality, related findings, severity, and types. |
first_observed_at | string | Indicates when the security findings provider first observed the potential security issue that a finding captured. For more information about the validation and formatting of timestamp fields in Security Hub CSPM, see Timestamps. (pattern: <code>.\S.</code>) |
generator_details | object | Provides metadata for the Amazon CodeGuru detector associated with a finding. This field pertains to findings that relate to Lambda functions. Amazon Inspector identifies policy violations and vulnerabilities in Lambda function code based on internal detectors developed in collaboration with Amazon CodeGuru. Security Hub CSPM receives those findings. |
generator_id | string | 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. (pattern: <code>.\S.</code>) |
id | string | The security findings provider-specific identifier for a finding. Length Constraints: Minimum length of 1. Maximum length of 512. (pattern: <code>.\S.</code>) |
last_observed_at | string | Indicates when the security findings provider most recently observed a change in the resource that is involved in the finding. For more information about the validation and formatting of timestamp fields in Security Hub CSPM, see Timestamps. (pattern: <code>.\S.</code>) |
malware | array | A list of malware related to a finding. Array Members: Maximum number of 5 items. |
network | object | The details of network-related information about a finding. |
network_path | array | Provides information about a network path that is relevant to a finding. Each entry under NetworkPath represents a component of that path. |
note | object | A user-defined note added to a finding. |
patch_summary | object | Provides an overview of the patch compliance status for an instance against a selected compliance standard. |
process | object | The details of process-related information about a finding. |
processed_at | string | A timestamp that indicates when Security Hub CSPM received a finding and begins to process it. For more information about the validation and formatting of timestamp fields in Security Hub CSPM, see Timestamps. (pattern: <code>.\S.</code>) |
product_arn | string | The ARN generated by Security Hub CSPM that uniquely identifies a product that generates findings. This can be the ARN for a third-party product that is integrated with Security Hub CSPM, or the ARN for a custom integration. Length Constraints: Minimum length of 12. Maximum length of 2048. (pattern: <code>.\S.</code>) |
product_fields | object | 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. |
product_name | string | The name of the product that generated the finding. Security Hub CSPM 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 CSPM console or API to filter findings by product name, you use this attribute. Length Constraints: Minimum length of 1. Maximum length of 128. (pattern: <code>.\S.</code>) |
record_state | string | The record state of a finding. (ACTIVE, ARCHIVED) |
region | string | The Region from which the finding was generated. Security Hub CSPM populates this attribute automatically for each finding. You cannot update it using BatchImportFindings or BatchUpdateFindings. Length Constraints: Minimum length of 1. Maximum length of 16. (pattern: <code>.\S.</code>) |
related_findings | array | A list of related findings. Array Members: Minimum number of 1 item. Maximum number of 10 items. |
remediation | object | A data type that describes the remediation options for a finding. |
resources | array | 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. |
sample | boolean | Indicates whether the finding is a sample finding. |
schema_version | string | The schema version that a finding is formatted for. The value is 2018-10-08. (pattern: <code>.\S.</code>) |
severity | object | A finding's severity. |
source_url | string | A URL that links to a page about the current finding in the security findings provider's solution. (pattern: <code>.\S.</code>) |
threat_intel_indicators | array | Threat intelligence details related to a finding. Array Members: Minimum number of 1 item. Maximum number of 5 items. |
threats | array | 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. |
title | string | A finding's title. Title is a required property. Length Constraints: Minimum length of 1. Maximum length of 256. (pattern: <code>.\S.</code>) |
types | array | 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. |
updated_at | string | Indicates when the security findings provider last updated the finding record. For more information about the validation and formatting of timestamp fields in Security Hub CSPM, see Timestamps. (pattern: <code>.\S.</code>) |
user_defined_fields | object | 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. |
verification_state | string | Indicates the veracity of a finding. (UNKNOWN, TRUE_POSITIVE, FALSE_POSITIVE, BENIGN_POSITIVE) |
vulnerabilities | array | Provides a list of vulnerabilities associated with the findings. |
workflow | object | Provides information about the status of the investigation into a finding. |
workflow_state | string | The workflow state of a finding. (NEW, ASSIGNED, IN_PROGRESS, DEFERRED, RESOLVED) |
Methods
The following methods are available for this resource:
| Name | Accessible by | Required Params | Optional Params | Description |
|---|---|---|---|---|
get_findings | select | region | Returns a list of findings that match the specified criteria. If cross-Region aggregation is enabled, then when you call GetFindings from the home Region, the results include all of the matching findings from both the home Region and linked Regions. | |
update_findings | update | region, Filters | UpdateFindings is a deprecated operation. Instead of UpdateFindings, use the BatchUpdateFindings operation. The UpdateFindings operation updates the Note and RecordState of the Security Hub CSPM aggregated findings that the filter attributes specify. Any member account that can view the finding can also see the update to the finding. Finding updates made with UpdateFindings aren't persisted if the same finding is later updated by the finding provider through the BatchImportFindings operation. In addition, Security Hub CSPM doesn't record updates made with UpdateFindings in the finding history. | |
batch_import_findings | exec | region, Findings | Imports security findings generated by a finding provider into Security Hub CSPM. This action is requested by the finding provider to import its findings into Security Hub CSPM. BatchImportFindings must be called by one of the following: The Amazon Web Services account that is associated with a finding if you are using the default product ARN or are a partner sending findings from within a customer's Amazon Web Services account. In these cases, the identifier of the account that you are calling BatchImportFindings from needs to be the same as the AwsAccountId attribute for the finding. An Amazon Web Services account that Security Hub CSPM has allow-listed for an official partner integration. In this case, you can call BatchImportFindings from the allow-listed account and send findings from different customer accounts in the same batch. The maximum allowed size for a finding is 240 Kb. An error is returned for any finding larger than 240 Kb. After a finding is created, BatchImportFindings cannot be used to update the following finding fields and objects, which Security Hub CSPM customers use to manage their investigation workflow. Note UserDefinedFields VerificationState Workflow Finding providers also should not use BatchImportFindings to update the following attributes. Confidence Criticality RelatedFindings Severity Types Instead, finding providers use FindingProviderFields to provide values for these attributes. | |
batch_update_findings | exec | region, FindingIdentifiers | Used by Security Hub CSPM customers to update information about their investigation into one or more findings. Requested by administrator accounts or member accounts. Administrator accounts can update findings for their account and their member accounts. A member account can update findings only for their own account. Administrator and member accounts can use this operation to update the following fields and objects for one or more findings: Confidence Criticality Note RelatedFindings Severity Types UserDefinedFields VerificationState Workflow If you use this operation to update a finding, your updates don’t affect the value for the UpdatedAt field of the finding. Also note that it can take several minutes for Security Hub CSPM to process your request and update each finding specified in the request. You can configure IAM policies to restrict access to fields and field values. For example, you might not want member accounts to be able to suppress findings or change the finding severity. For more information see Configuring access to BatchUpdateFindings in the Security Hub CSPM User Guide. |
Parameters
Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.
| Name | Datatype | Description |
|---|---|---|
region | string | AWS region (default: us-east-1) |
SELECT examples
- get_findings
Returns a list of findings that match the specified criteria. If cross-Region aggregation is enabled, then when you call GetFindings from the home Region, the results include all of the matching findings from both the home Region and linked Regions.
SELECT
action,
aws_account_id,
aws_account_name,
company_name,
compliance,
confidence,
created_at,
criticality,
description,
detection,
finding_provider_fields,
first_observed_at,
generator_details,
generator_id,
id,
last_observed_at,
malware,
network,
network_path,
note,
patch_summary,
process,
processed_at,
product_arn,
product_fields,
product_name,
record_state,
region,
related_findings,
remediation,
resources,
sample,
schema_version,
severity,
source_url,
threat_intel_indicators,
threats,
title,
types,
updated_at,
user_defined_fields,
verification_state,
vulnerabilities,
workflow,
workflow_state
FROM aws.securityhub.findings
WHERE region = '{{ region }}' -- required
;
UPDATE examples
- update_findings
UpdateFindings is a deprecated operation. Instead of UpdateFindings, use the BatchUpdateFindings operation. The UpdateFindings operation updates the Note and RecordState of the Security Hub CSPM aggregated findings that the filter attributes specify. Any member account that can view the finding can also see the update to the finding. Finding updates made with UpdateFindings aren't persisted if the same finding is later updated by the finding provider through the BatchImportFindings operation. In addition, Security Hub CSPM doesn't record updates made with UpdateFindings in the finding history.
UPDATE aws.securityhub.findings
SET
Filters = '{{ Filters }}',
Note = '{{ Note }}',
RecordState = '{{ RecordState }}'
WHERE
region = '{{ region }}' --required
AND Filters = '{{ Filters }}' --required;
Lifecycle Methods
- batch_import_findings
- batch_update_findings
Imports security findings generated by a finding provider into Security Hub CSPM. This action is requested by the finding provider to import its findings into Security Hub CSPM. BatchImportFindings must be called by one of the following: The Amazon Web Services account that is associated with a finding if you are using the default product ARN or are a partner sending findings from within a customer's Amazon Web Services account. In these cases, the identifier of the account that you are calling BatchImportFindings from needs to be the same as the AwsAccountId attribute for the finding. An Amazon Web Services account that Security Hub CSPM has allow-listed for an official partner integration. In this case, you can call BatchImportFindings from the allow-listed account and send findings from different customer accounts in the same batch. The maximum allowed size for a finding is 240 Kb. An error is returned for any finding larger than 240 Kb. After a finding is created, BatchImportFindings cannot be used to update the following finding fields and objects, which Security Hub CSPM customers use to manage their investigation workflow. Note UserDefinedFields VerificationState Workflow Finding providers also should not use BatchImportFindings to update the following attributes. Confidence Criticality RelatedFindings Severity Types Instead, finding providers use FindingProviderFields to provide values for these attributes.
EXEC aws.securityhub.findings.batch_import_findings
@region='{{ region }}' --required
@@json=
'{
"Findings": "{{ Findings }}"
}'
;
Used by Security Hub CSPM customers to update information about their investigation into one or more findings. Requested by administrator accounts or member accounts. Administrator accounts can update findings for their account and their member accounts. A member account can update findings only for their own account. Administrator and member accounts can use this operation to update the following fields and objects for one or more findings: Confidence Criticality Note RelatedFindings Severity Types UserDefinedFields VerificationState Workflow If you use this operation to update a finding, your updates don’t affect the value for the UpdatedAt field of the finding. Also note that it can take several minutes for Security Hub CSPM to process your request and update each finding specified in the request. You can configure IAM policies to restrict access to fields and field values. For example, you might not want member accounts to be able to suppress findings or change the finding severity. For more information see Configuring access to BatchUpdateFindings in the Security Hub CSPM User Guide.
EXEC aws.securityhub.findings.batch_update_findings
@region='{{ region }}' --required
@@json=
'{
"FindingIdentifiers": "{{ FindingIdentifiers }}",
"Note": "{{ Note }}",
"Severity": "{{ Severity }}",
"VerificationState": "{{ VerificationState }}",
"Confidence": {{ Confidence }},
"Criticality": {{ Criticality }},
"Types": "{{ Types }}",
"UserDefinedFields": "{{ UserDefinedFields }}",
"Workflow": "{{ Workflow }}",
"RelatedFindings": "{{ RelatedFindings }}"
}'
;