Required top-level ASFF attributes - Amazon Security Hub
AwsAccountIdCreatedAtDescriptionGeneratorIdIdProductArnResourcesSchemaVersionSeverityTitleTypesUpdatedAt
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).

Required top-level ASFF attributes

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

AwsAccountId

The Amazon Web Services account ID that the finding applies to.

Example

"AwsAccountId": "111111111111"

CreatedAt

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

Example

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

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 CSPM 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 Amazon control checks whether Amazon 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 CSPM 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 CSPM 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-cn: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 CSPM that uniquely identifies a third-party findings product after the product is registered with Security Hub CSPM.

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

  • For Amazon Web Services services that are integrated with Security Hub CSPM, the company-id must be "aws", and the product-id must be the Amazon public service name. Because Amazon products and services aren't associated with an account, the account-id section of the ARN is empty. Amazon Web Services services that are not yet integrated with Security Hub CSPM 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-cn:securityhub:us-east-1:111111111111:product/111111111111/default"

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

Resources

The Resources array of objects provides a set of resource data types that describe the Amazon resources that the finding refers to. For details about the fields that a Resources object might contain, including which fields are required, see Resource in the Amazon Security Hub API Reference. For examples of Resources objects for specific Amazon Web Services services, see Resources ASFF object.

Example

"Resources": [
  {
    "ApplicationArn": "arn:aws-cn: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-cn: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-cn: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 Amazon. In the current release, the Amazon 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 Amazon 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 be updated only by using 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, Security Hub CSPM automatically populates the value of the other field. 
The Product and Original fields may also be populated.

If the top-level Finding.Severity object is present but Finding.FindingProviderFields is not present, Security Hub CSPM creates the FindingProviderFields.Severity object and copies the entire Finding.Severity object into it. This ensures that the original, provider-supplied details are retained within the FindingProviderFields.Severity structure, even if the top-level Severity object is overwritten.

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": "Amazon 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 be updated only by using the BatchUpdateFindings API.

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

    • Amazon Security Best Practices

      • Network Reachability

      • Runtime Behavior Analysis

    • Industry and Regulatory Standards

      • Amazon Foundational Security Best Practices

      • CIS Host Hardening Benchmarks

      • CIS Amazon 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 operation. You can update it only by using BatchImportFindings operation.

Example

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