Required top-level attributes - AWS Security Hub
AwsAccountIdCreatedAtDescriptionGeneratorIdIdProductArnResourcesSchemaVersionSeverityTitleTypesUpdatedAt

Required top-level attributes

The following top-level attributes in the AWS Security Finding Format (ASFF) are required for all findings in Security Hub. For more information about these required attributes, see AwsSecurityFinding in the AWS Security Hub API Reference.

AwsAccountId

The AWS account ID that the finding applies to.

Example

"AwsAccountId": "111111111111"

CreatedAt

Indicates when the potential security issue captured by a finding was created.

Example

"CreatedAt": "2017-03-22T13:22:13.933Z"
Note

Security Hub deletes findings 90 days after the most recent update or 90 days after the creation date if no update occurs. To store findings for longer than 90 days, you can configure a rule in Amazon EventBridge that routes findings to your S3 bucket.

Description

A finding's description. This field can be nonspecific boilerplate text or details that are specific to the instance of the finding.

For control findings that Security Hub generates, this field provides a description of the control.

This field doesn't reference a standard if you turn on consolidated control findings.

Example

"Description": "This AWS control checks whether AWS Config is enabled in the current account and Region."

GeneratorId

The identifier for the solution-specific component (a discrete unit of logic) that generated a finding.

For control findings that Security Hub generates, this field doesn't reference a standard if you turn on consolidated control findings.

Example

"GeneratorId": "security-control/Config.1"

Id

The product-specific identifier for a finding. For control findings that Security Hub generates, this field provides the Amazon Resource Name (ARN) of the finding.

This field doesn't reference a standard if you turn on consolidated control findings.

Example

"Id": "arn:aws:securityhub:eu-central-1:123456789012:security-control/iam.9/finding/ab6d6a26-a156-48f0-9403-115983e5a956

"

ProductArn

The Amazon Resource Name (ARN) generated by Security Hub that uniquely identifies a third-party findings product after the product is registered with Security Hub.

The format of this field is arn:partition:securityhub:region:account-id:product/company-id/product-id.

  • For AWS services that are integrated with Security Hub, the company-id must be "aws", and the product-id must be the AWS public service name. Because AWS products and services aren't associated with an account, the account-id section of the ARN is empty. AWS services that are not yet integrated with Security Hub are considered third-party products.

  • For public products, the company-id and product-id must be the ID values specified at the time of registration.

  • For private products, the company-id must be the account ID. The product-id must be the reserved word "default" or the ID that was specified at the time of registration.

Example

// Private ARN
    "ProductArn": "arn:aws:securityhub:us-east-1:111111111111:product/111111111111/default"

// Public ARN

    "ProductArn": "arn:aws:securityhub:us-west-2::product/aws/guardduty"
    "ProductArn": "arn:aws:securityhub:us-west-2:222222222222:product/generico/secure-pro"

Resources

The Resources object provides a set of resource data types that describe the AWS resources that the finding refers to.

Example

"Resources": [
  {
    "ApplicationArn": "arn:aws:resource-groups:us-west-2:123456789012:group/SampleApp/1234567890abcdef0",
    "ApplicationName": "SampleApp",
    "DataClassification": {
    "DetailedResultsLocation": "Path_to_Folder_Or_File",
    "Result": {
        "MimeType": "text/plain",
        "SizeClassified": 2966026,
        "AdditionalOccurrences": false,
        "Status": {
            "Code": "COMPLETE",
            "Reason": "Unsupportedfield"
        },
       "SensitiveData": [
            {
                "Category": "PERSONAL_INFORMATION",
                "Detections": [
                    {
                        "Count": 34,
                        "Type": "GE_PERSONAL_ID",
                        "Occurrences": {
                            "LineRanges": [
                                {
                                    "Start": 1,
                                    "End": 10,
                                    "StartColumn": 20
                                }
                            ],
                            "Pages": [],
                            "Records": [],
                            "Cells": []
                        }
                    },
                    {
                        "Count": 59,
                        "Type": "EMAIL_ADDRESS",
                        "Occurrences": {
                            "Pages": [
                                {
                                    "PageNumber": 1,
                                    "OffsetRange": {
                                        "Start": 1,
                                        "End": 100,
                                        "StartColumn": 10
                                     },
                                    "LineRange": {
                                        "Start": 1,
                                        "End": 100,
                                        "StartColumn": 10
                                    }
                                }
                            ]
                        }
                    },
                    {
                        "Count": 2229,
                        "Type": "URL",
                        "Occurrences": {
                           "LineRanges": [
                               {
                                   "Start": 1,
                                   "End": 13
                               }
                           ]
                       }
                   },
                   {
                       "Count": 13826,
                       "Type": "NameDetection",
                       "Occurrences": {
                            "Records": [
                                {
                                    "RecordIndex": 1,
                                    "JsonPath": "$.ssn.value"
                                }
                            ]
                        }
                   },
                   {
                       "Count": 32,
                       "Type": "AddressDetection"
                   }
               ],
               "TotalCount": 32
           }
        ],
        "CustomDataIdentifiers": {
            "Detections": [
                 {
                     "Arn": "1712be25e7c7f53c731fe464f1c869b8", 
                     "Name": "1712be25e7c7f53c731fe464f1c869b8", 
                     "Count": 2,
                 }
            ],
            "TotalCount": 2
        }
    }
},
	"Type": "AwsEc2Instance",
	"Id": "arn:aws:ec2:us-west-2:123456789012:instance/i-abcdef01234567890",
	"Partition": "aws",
	"Region": "us-west-2",
	"ResourceRole": "Target",
	"Tags": {
		"billingCode": "Lotus-1-2-3",
		"needsPatching": true
	},
	"Details": {
		"IamInstanceProfileArn": "arn:aws:iam::123456789012:role/IamInstanceProfileArn",
		"ImageId": "ami-79fd7eee",
		"IpV4Addresses": ["1.1.1.1"],
		"IpV6Addresses": ["2001:db8:1234:1a2b::123"],
		"KeyName": "testkey",
		"LaunchedAt": "2018-09-29T01:25:54Z",
		"MetadataOptions": {
			"HttpEndpoint": "enabled",
			"HttpProtocolIpv6": "enabled",
			"HttpPutResponseHopLimit": 1,
			"HttpTokens": "optional",
			"InstanceMetadataTags": "disabled"
		}
	},
		"NetworkInterfaces": [
		{
			"NetworkInterfaceId": "eni-e5aa89a3"
		}
		],
		"SubnetId": "PublicSubnet",
		"Type": "i3.xlarge",
		"VirtualizationType": "hvm",
		"VpcId": "TestVPCIpv6"
	}

]

SchemaVersion

The schema version that a finding is formatted for. The value of this field must be one of the officially published versions identified by AWS. In the current release, the AWS Security Finding Format schema version is 2018-10-08.

Example

"SchemaVersion": "2018-10-08"

Severity

Defines the importance of a finding. For details about this object, see Severity in the AWS Security Hub API Reference.

Severity is both a top-level object in a finding and nested under the FindingProviderFields object.

The value of the top-level Severity object for a finding should only be updated by the BatchUpdateFindings API.

To provide severity information, finding providers should update the Severity object under FindingProviderFields when making a BatchImportFindings API request.
 If a BatchImportFindings request for a new finding only provides Label or only provides Normalized, then Security Hub automatically populates the value of the other field. 
The Product field under FindingProviderFields is retired and isn't populated in current findings. Instead, use the Original field.

The finding severity does not consider the criticality of the involved assets or the underlying resource. Criticality is defined as the level of importance of the resources that are associated with the finding. For example, a resource that is associated with a mission critical application has higher criticality than one that is associated with nonproduction testing. To capture information about resource criticality, use the Criticality field.

We recommend using the following guidance when translating findings' native severity scores to the value of Severity.Label in the ASFF.

  • INFORMATIONAL – This category may include a finding for a PASSED, WARNING, or NOT AVAILABLE check or a sensitive data identification.

  • LOW – Findings that could result in future compromises. For example, this category may include vulnerabilities, configuration weaknesses, and exposed passwords.

  • MEDIUM – Findings that indicate an active compromise, but no indication that an adversary completed their objectives. For example, this category may include malware activity, hacking activity, and unusual behavior detection.

  • HIGH or CRITICAL – Findings that indicate that an adversary completed their objectives, such as active data loss or compromise or a denial of service.

Example

"Severity": {
    "Label": "CRITICAL",
    "Normalized": 90,
    "Original": "CRITICAL"
}

Title

A finding's title. This field can contain nonspecific boilerplate text or details that are specific to this instance of the finding.

For control findings, this field provides the title of the control.

This field doesn't reference a standard if you turn on consolidated control findings.

Example

"Title": "AWS Config should be enabled"

Types

One or more finding types in the format of namespace/category/classifier that classify a finding. This field doesn't reference a standard if you turn on consolidated control findings.

Types should only be updated using BatchUpdateFindings.

Finding providers who want to provide a value for Types should use the Types attribute under FindingProviderFields.

In the following list, the top-level bullets are namespaces, the second-level bullets are categories, and the third-level bullets are classifiers. We recommend that finding providers use defined namespaces to help sort and group findings. The defined categories and classifiers may also be used, but are not required. Only the Software and Configuration Checks namespace has defined classifiers.

You may define a partial path for namespace/category/classifier. For example, the following finding types are all valid:

  • TTPs

  • TTPs/Defense Evasion

  • TTPs/Defense Evasion/CloudTrailStopped

The tactics, techniques, and procedures (TTPs) categories in the following list align to the MITRE ATT&CK MatrixTM. The Unusual Behaviors namespace reflects general unusual behavior, such as general statistical anomalies, and are not aligned with a specific TTP. However, you could classify a finding with both Unusual Behaviors and TTPs finding types.

List of namespaces, categories, and classifiers:

  • Software and Configuration Checks

    • Vulnerabilities

      • CVE

    • AWS Security Best Practices

      • Network Reachability

      • Runtime Behavior Analysis

    • Industry and Regulatory Standards

      • AWS Foundational Security Best Practices

      • CIS Host Hardening Benchmarks

      • CIS AWS Foundations Benchmark

      • PCI-DSS

      • Cloud Security Alliance Controls

      • ISO 90001 Controls

      • ISO 27001 Controls

      • ISO 27017 Controls

      • ISO 27018 Controls

      • SOC 1

      • SOC 2

      • HIPAA Controls (USA)

      • NIST 800-53 Controls (USA)

      • NIST CSF Controls (USA)

      • IRAP Controls (Australia)

      • K-ISMS Controls (Korea)

      • MTCS Controls (Singapore)

      • FISC Controls (Japan)

      • My Number Act Controls (Japan)

      • ENS Controls (Spain)

      • Cyber Essentials Plus Controls (UK)

      • G-Cloud Controls (UK)

      • C5 Controls (Germany)

      • IT-Grundschutz Controls (Germany)

      • GDPR Controls (Europe)

      • TISAX Controls (Europe)

    • Patch Management

  • TTPs

    • Initial Access

    • Execution

    • Persistence

    • Privilege Escalation

    • Defense Evasion

    • Credential Access

    • Discovery

    • Lateral Movement

    • Collection

    • Command and Control

  • Effects

    • Data Exposure

    • Data Exfiltration

    • Data Destruction

    • Denial of Service

    • Resource Consumption

  • Unusual Behaviors

    • Application

    • Network Flow

    • IP address

    • User

    • VM

    • Container

    • Serverless

    • Process

    • Database

    • Data

  • Sensitive Data Identifications

    • PII

    • Passwords

    • Legal

    • Financial

    • Security

    • Business

Example

"Types": [
    "Software and Configuration Checks/Vulnerabilities/CVE"
				]

UpdatedAt

Indicates when the finding provider last updated the finding record.

This timestamp reflects the time when the finding record was last or most recently updated. Consequently, it can differ from the LastObservedAt timestamp, which reflects when the event or vulnerability was last or most recently observed.

When you update the finding record, you must update this timestamp to the current timestamp. Upon creation of a finding record, the CreatedAt and UpdatedAt timestamps must be the same. After an update to the finding record, the value of this field must be more recent than all of the previous values that it contained.

Note that UpdatedAt cannot be updated by using the BatchUpdateFindings API operation. You can only update it by using BatchImportFindings.

Example

"UpdatedAt": "2017-04-22T13:22:13.933Z"
Note

Security Hub deletes findings 90 days after the most recent update or 90 days after the creation date if no update occurs. To store findings for longer than 90 days, you can configure a rule in Amazon EventBridge that routes findings to your S3 bucket.