Sign In to the Console
AWS Security Hub
User Guide

AWS Documentation » AWS Security Hub » User Guide » Findings in AWS Security Hub » AWS Security Finding Format

AWS Security Finding Format

Important

Currently, AWS Security Hub is in Preview release.

Security Hub consumes, aggregates, organizes, and prioritizes findings from AWS security services and also from the integrated partner providers' solutions. Security Hub ingests these findings using a standard findings format called AWS Security Finding, thus eliminating the need for time-consuming data conversion efforts. It then correlates ingested findings across providers to prioritize the most important ones.

Syntax of the AWS Security Finding Format

The following is the syntax of the complete finding JSON presented in the AWS Security Finding format. 


		   "Findings": [ 
		      { 
		         "AwsAccountId": "string",
		         "Compliance": { 
		            "Status": "string"
		         },
		         "Confidence": number,
		         "CreatedAt": "string",
		         "Criticality": number,
		         "Description": "string",
		         "FirstObservedAt": "string",
		         "GeneratorId": "string",
		         "Id": "string",
		         "LastObservedAt": "string",
		         "Malware": [ 
		            { 
		               "Name": "string",
		               "Path": "string",
		               "State": "string",
		               "Type": "string"
		            }
		         ],
		         "Network": { 
		            "DestinationDomain": "string",
		            "DestinationIpV4": "string",
		            "DestinationIpV6": "string",
		            "DestinationPort": number,
		            "Direction": "string",
		            "Protocol": "string",
		            "SourceDomain": "string",
		            "SourceIpV4": "string",
		            "SourceIpV6": "string",
		            "SourceMac": "string",
		            "SourcePort": number
		         },
		         "Note": { 
		            "Text": "string",
		            "UpdatedAt": "string",
		            "UpdatedBy": "string"
		         },
		         "Process": { 
		            "LaunchedAt": "string",
		            "Name": "string",
		            "ParentPid": number,
		            "Path": "string",
		            "Pid": number,
		            "TerminatedAt": "string"
		         },
		         "ProductArn": "string",
		         "ProductFields": { 
		            "string" : "string" 
		         },
		         "RecordState": "string",
		         "RelatedFindings": [ 
		            { 
		               "Id": "string",
		               "ProductArn": "string"
		            }
		         ],
		         "Remediation": { 
		            "Recommendation": { 
		               "Text": "string",
		               "Url": "string"
		            }
		         },
		         "Resources": [ 
		            { 
		               "Details": { 
		                  "AwsEc2Instance": { 
		                     "IamInstanceProfileArn": "string",
		                     "ImageId": "string",
		                     "IpV4Addresses": [ "string" ],
		                     "IpV6Addresses": [ "string" ],
		                     "KeyName": "string",
		                     "LaunchedAt": "string",
		                     "SubnetId": "string",
		                     "Type": "string",
		                     "VpcId": "string"
		                  },
		                  "AwsIamAccessKey": { 
		                     "CreatedAt": "string",
		                     "Status": "string",
		                     "UserName": "string"
		                  },
		                  "AwsS3Bucket": { 
		                     "OwnerId": "string",
		                     "OwnerName": "string"
		                  },
		                  "Container": { 
		                     "ImageId": "string",
		                     "ImageName": "string",
		                     "LaunchedAt": "string",
		                     "Name": "string"
		                  },
		                  "Other": { 
		                     "string" : "string" 
		                  }
		               },
		               "Id": "string",
		               "Partition": "string",
		               "Region": "string",
		               "Tags": { 
		                  "string" : "string" 
		               },
		               "Type": "string"
		            }
		         ],
		         "SchemaVersion": "string",
		         "Severity": { 
		            "Normalized": number,
		            "Product": number
		         },
		         "SourceUrl": "string",
		         "ThreatIntelIndicators": [ 
		            { 
		               "Category": "string",
		               "LastObservedAt": "string",
		               "Source": "string",
		               "SourceUrl": "string",
		               "Type": "string",
		               "Value": "string"
		            }
		         ],
		         "Title": "string",
		         "Types": [ "string" ],
		         "UpdatedAt": "string",
		         "UserDefinedFields": { 
		            "string" : "string" 
		         },
		         "VerificationState": "string",
		         "WorkflowState": "string"
		      }
		   ]

Attributes of the AWS Security Finding Format

The following table provides descriptions and examples for the AWS Security Finding format attributes.

Attribute Required Description
AwsAccountId Yes

The AWS account ID where a finding is generated.

Type: string (12 digits max)

Example:

"AwsAccountId": "111111111111"
Compliance No Exclusive to findings that are generated as the result of a check run against a specific rule in a supported standard (for example, AWS CIS Foundations). Contains compliance-related finding details.

Type: object

Example:

"Compliance": {
									"Status": "PASSED"
									}
Compliance.Status No

Indicates the result of a compliance check.

Type: enum

  • Allowed values are:

    • PASSED – All resources that were checked evaluated in compliance with the check.

    • WARNING – There is configuration information that needs to be supplied that is lacking.

    • FAILED – All resources that were checked failed the check.

    • NOT_AVAILABLE – The check could not be performed due to a service outage or API error of some kind.

  • Example:

    "Status": "PASSED"
Confidence No

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. However, a data exfiltration detection based on a statistical deviation of network traffic will have a much lower confidence, because an actual exfiltration hasn't been verified.

Type: integer (ranger 0 to 100)

Example:

"Confidence": 42
CreatedAt Yes

An ISO8601-formatted timestamp (as defined in RFC-3339 Date and Time on the Internet: Timestamps) that indicates when the potential security issue captured by a finding was created by the security findings provider.

Because the CreatedAt timestamp reflects the time when the finding record was created, it can differ from the FirstObservedAt timestamp, which reflects the time when the event/vulnerability was first observed.

This timestamp MUST be provided on the first generation of the finding, and CANNOT be changed upon subsequent updates to the finding.

Type: timestamp

Example:

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

The level of importance assigned to the resources associated with the finding. A score of 0 means the underlying resources have no criticality, and a score of 100 is reserved for the most critical resources.

Type: integer (range 0 to 100)

Criticality is scored on a 0-100 basis, using a ratio scale, with only full integers supported. This means that you should assess not only which findings impact resources that are more critical than others, but also how much more critical those resources are compared to other resources. A score of 0 means the underlying resources have no criticality, and a score of 100 is reserved for the most critical resources.

When assessing criticality of a finding, consider the following:

  • Does the impacted resource contain sensitive data (e.g., an S3 bucket with PII)?

  • Does the impacted resource enable an adversary to deepen their access or extend their capabilities to carry out additional malicious activity (e.g., a compromised sysadmin account)?

  • Is the resource a business-critical asset (e.g., a key business system that if compromised could have significant revenue impact)?

You can use the following guidelines:

  • A resource powering mission-critical systems or containing highly sensitive data can be scored in the 75 - 100 range.

  • A resource powering important (but not critical systems) or containing moderately important data can be scored in the 25 - 75 range.

  • A resource powering non-important systems or containing non-sensitive data SHOULD be scored in the 0-24 range.

Example:

"Criticality": 99
Description Yes

A finding's description. This field can be non-specific boilerplate text or contain details specific to the instance of the finding.

Type: string (1,024 chars. max)

Example:

"Description": "The version of openssl found on instance i-abcd1234 is known to contain a vulnerability."
FirstObservedAt No

An ISO8601-formatted timestamp (as defined in RFC-3339 Date and Time on the Internet: Timestamps) that indicates when the potential security issue captured by a finding was first observed by the security findings provider.

Type: timestamp

Because this timestamp reflects the time of when the event/vulnerability was first observed, it can differ from the CreatedAt timestamp, which reflects the time this finding record was created.

This timestamp should be immutable between updates of the finding record, but can be updated if a more accurate timestamp has been determined.

Example:

FirstObservedAt": "2017-03-22T13:22:13.933Z"
GeneratorId Yes

This is the identifier for the solution-specific component (a discrete unit of logic) that generated a finding. In various solutions from security findings providers, this generator can be called a rule, a check, a detector, a plug-in, and so on.

Type: string (512 chars. max) or ARN

Example:

"GeneratorId": "acme-vuln-9ab348"
Id Yes

The finding provider-specific identifier for a finding.

Type: string (512 chars. max) or ARN

The finding ID must comply with the following constraints:

  • The ID must be globally unique within the product. To enforce uniqueness, you can incorporate the public AWS region name and AWS account ID in the identifier.

  • You CANNOT recycle identifiers regardless of whether the previous finding no longer exists.

  • The ID must only contain characters from the unreserved characters set defined in section 2.3 of RFC-3986 Uniform Resource Identifier (URI): Generic Syntax.

  • For non-AWS services, the ID CANNOT be prefixed with the literal string "arn:".

  • For AWS services, the ID MUST be the ARN of the finding if one is available. Otherwise, any other unique identifier can be used.

These constraints are expected to hold within a findings provider (product), but are not required to hold across findings providers.

Example:

"Id": "us-west-2/111111111111/98aebb2207407c87f51e89943f12b1ef"
LastObservedAt No

An ISO8601-formatted timestamp (as defined in RFC-3339 Date and Time on the Internet: Timestamps) that indicates when the potential security issue captured by a finding was most recently observed by the security findings provider.

Type: timestamp

Because this timestamp reflects the time of when the event/vulnerability was last/most-recently observed, it can differ from the UpdatedAt timestamp, which reflects the time this finding record was last/most-recently updated.

This timestamp can be provided, but isn't required upon the first observation. If the field is provided in this case, the timestamp should be the same as the FirstObservedAt timestamp. This field should be updated to reflect the last/most-recently observed timestamp each time a findings provider observes the event/vulnerability.

Example:

"LastObservedAt": "2017-03-23T13:22:13.933Z"
Malware No

A list of malware related to a finding.

Type: array of up to 5 malware objects

Example:

"Malware": [
	  								{
  	  								"Name": "Stringler",
  	  								"Type": "COIN_MINER",
  	  								"Path": "/usr/sbin/stringler",
  	  								"State": "OBSERVED"
  									}
									]
Malware.Name Yes

The name of the malware that was observed.

Type: string (64 chars. max)

Example:

"Name": "Stringler"
Malware.Path No

The filesystem path of the malware that was observed.

Type: string (512 chars. max)

Example:

"Path": "/usr/sbin/stringler"
Malware.State No

The state of the malware that was observed. Valid values are OBSERVED | REMOVAL_FAILED | REMOVED

Type:enum

Example:

"State": "OBSERVED"
Malware.Type No

The type of the malware that was observed. Valid values are ADWARE | BLENDED_THREAT | BOTNET_AGENT | COIN_MINER | EXPLOIT_KIT | KEYLOGGER | MACRO | POTENTIALLY_UNWANTED | SPYWARE | RANSOMWARE | REMOTE_ACCESS | ROOTKIT | TROJAN | VIRUS | WORM

Type: enum

Example:

"Type": "COIN_MINER"
Network No

The details of network-related information about a finding.

Type: object

Example:

"Network": {
									"Direction": "IN",
									"Protocol": "TCP",
									"SourceIpV4": "1.2.3.4",
									"SourceIpV6": "FE80:CD00:0000:0CDE:1257:0000:211E:729C",
									"SourcePort": "42",
									"SourceDomain": "here.com",
									"SourceMac": "00:0d:83:b1:c0:8e",
									"DestinationIpV4": "2.3.4.5",
									"DestinationIpV6": "FE80:CD00:0000:0CDE:1257:0000:211E:729C",
									"DestinationPort": "80",
									"DestinationDomain": "there.com"
									}
Network.DestinationDomain No

The destination domain of network-related information about a finding.

Type: string (128 char max)

Example:

"DestinationDomain": "there.com"
Network.DestinationIpV4 No

The destination IPv4 address of network-related information about a finding.

Type: IPv4

Example:

"DestinationIpV4": "2.3.4.5"
Network.DestinationIpV6 No

The destination IPv6 address of network-related information about a finding.

Type: IPv6

Example:

"DestinationIpV6": "FE80:CD00:0000:0CDE:1257:0000:211E:729C"
Network.DestinationPort No

The destination port of network-related information about a finding.

Type: number (range of 0 to 65535)

Example:

"DestinationPort": "80"
Network.Direction No

The direction of network traffic associated with a finding. Valid values are IN | OUT.

Type: enum

Example:

"Direction": "IN"
Network.Protocol No

The protocol of network-related information about a finding.

Type: string (16 char max)

The name should be the IANA registered name for the associated port except in the case the provider can determine a more accurate protocol.

Example:

"Protocol": "TCP"
Network.SourceDomain No

The source domain of network-related information about a finding.

Type: string (128 char max)

  • Example:

    "SourceDomain": "here.com"
Network.SourceIpV4 No

The source IPv4 address of network-related information about a finding.

Type: IPv4

  • Example:

    
"SourceIpV4": "1.2.3.4"
Network.SourceIpV6 No

The source IPv6 address of network-related information about a finding.

Type: IPv6

  • Example:

    
"SourceIpV6": "FE80:CD00:0000:0CDE:1257:0000:211E:729C"
Network.SourceMac No

The source media access control (MAC) address of network-related information about a finding.

Type: string (must match MM:MM:MM:SS:SS:SS)

  • Example:

    
"SourceMac": "00:0d:83:b1:c0:8e"
Network.SourcePort No

The source port of network-related information about a finding.

Type: number (range of 0 to 65535)

  • Example:

    
"SourcePort": "80"
Note No

A user-defined note added to a finding.

Type: object

  • Example:

    
"Note": {
  "Text": "Don't forget to check under the mat.",
  "UpdatedBy": "jsmith",
  "UpdatedAt": "2018-08-31T00:15:09Z"
}
Note.Text Yes

The text of a finding note.

Type: string (512 char max)

  • Example:

    
"Text": "Example text."
Note.UpdatedAt Yes

The timestamp of when the note was updated.

Type: timestamp

  • Example:

    
"UpdatedAt": "2018-08-31T00:15:09Z"
Note.UpdatedBy Yes

The principal that created a note.

Type: string (512 char max) or ARN

  • Example:

    
"UpdatedBy": "jsmith"
Process No

The details of process-related information about a finding.

Type: object

  • Example:

    
"Process": {
  "Name": "syslogd",
  "Path": "/usr/sbin/syslogd",
  "Pid": 12345,
  "ParentPid": 56789,
  "LaunchedAt": "2018-09-27T22:37:31Z",
  "TerminatedAt": "2018-09-27T23:37:31Z"
}
Process.LaunchedAt No

The timestamp for the date and time when the process was launched.

Type: timestamp

Example:

"LaunchedAt": "2018-09-27T22:37:31Z"
Process.Name No

The name of the process.

Type: string (64 char max)

  • Example:

    "Name": "syslogd"
Process.ParentPid No

The parent process ID.

Type: number

  • Example:

    "ParentPid": 56789
Process.Path No

The path to the process executable.

Type: string (512 char max)

  • Example:

    
"Path": "/usr/sbin/syslogd"
Process.Pid No

The process ID.

Type: number

  • Example:

    
"Pid": 12345
Process.TerminatedAt No

The timestamp for the date and time when the process was terminated.

Type: timestamp

Example:

"TerminatedAt": "2018-09-27T23:37:31Z"
ProductArn Yes

The ARN generated by Security Hub that uniquely identifies a third-party company (security findings provider) after this provider's product (solution that generates findings) is registered with Security Hub.

Type: ARN

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

  • For AWS services, the company-id must be "aws" and the product-id must be the AWS public service name. Because AWS products and services are not associated with an account, the account-id section of the ARN is empty.

  • 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 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"
ProductFields No

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

Type: map of up to 50 key/value pairs

This field should not contain redundant data and must not contain data that is conflicting with ASFF-defined fields. The "aws/" prefix represents a reserved namespace for AWS products and services only, and must not be submitted with findings from partner products. While not required, products should format field names as company-id/product-id/field-name, where the company-id and product-id match those supplied in the ProductArn of the finding. Fields names may be composed of alphanumeric characters, whitespace, and the following symbols: _ . / = + \ - @

Example:

"ProductFields": {
									"generico/secure-pro/Count": "6",
									"generico/secure-pro/Action.Type", "AWS_API_CALL",
									"API", "DeleteTrail",
									"Service_Name": "cloudtrail.amazonaws.com",
									"aws/inspector/AssessmentTemplateName": "My daily CVE assessment",
									"aws/inspector/AssessmentTargetName": "My prod env",
									"aws/inspector/RulesPackageName": "Common Vulnerabilities and Exposures"
									}
RecordState No

The record state of a finding. Valid values are ACTIVE and ARCHIVED.

Type: enum

By default, findings when initially generated by a service are considered to be ACTIVE. The ARCHIVED state is used to indicate that a finding should be hidden from view. Archived findings are not deleted and remain in the service historically. They can be searched, reviewed, and reported against at any time.

Example:

"RecordState": "ACTIVE"
RelatedFindings No

A list of related findings.

Type: array of up to 10 RelatedFinding objects

Example:

"RelatedFindings": [
									{ "ProductArn": "arn:aws:securityhub:us-west-2::product/aws/guardduty", "Id": "123e4567-e89b-12d3-a456-426655440000" },
									{ "ProductArn": "arn:aws:securityhub:us-west-2::product/aws/guardduty", "Id": "AcmeNerfHerder-111111111111-x189dx7824" }
									]
RelatedFindings.Id Yes

The product-generated identifier for a related finding.

Type: string (512 char max) or ARN

Example:

"Id": "123e4567-e89b-12d3-a456-426655440000"
RelatedFindings.ProductArn Yes

The ARN of the product that generated a related finding.

Type: ARN

Example:

"ProductArn": "arn:aws:securityhub:us-west-2::product/aws/guardduty"
Remediation No

The remediation options for a finding.

Type: object

Example:

"Remediation": {
									"Recommendation": {
									"Text": "Run sudo yum update and cross your fingers and toes.",
									"Url": "http://myfp.com/recommendations/dangerous_things_and_how_to_fix_them.html"
									  }
									}
Remediation.Recommendation No

A recommendation on how to remediate the issue identified within a finding.

If the recommendation object is present, then either the Text or Url field must be present and populated, though both can be present and populated. The Recommendation field is meant to facilitate manual instruction/details to resolve a finding.

Type:object

Example:

"Recommendation": {
									"Text": "Example text.",
									"Url": "http://myfp.com/recommendations/dangerous_things_and_how_to_fix_them.html"
									}
Recommendation.Text No

A freeform string that is used as the recommendation of what to do about the finding when presented to a user. This field can contain non-specific boilerplate text or contain details specific to this instance of the finding.

Type: string (512 char max)

Example:

"Text": "Example text."
Recommendation.Url No

A URL to link to general remediation information for the finding type of a finding.

This URL must not require credentials to access. This URL must be accessible from the public Internet and must not expect any context or session.

Type: URL

  • Example:

    
"Url": "http://myfp.com/recommendations/example_domain.html"
Resources Yes

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

Type: array of up to 10 resource objects

Example:

"Resources": [
  {
    "Type": "AwsEc2Instance",
    "Id": "i-cafebabe",
    "Partition": "aws",
    "Region": "us-west-2",
    "Tags": {
      "billingCode": "Lotus-1-2-3",
      "needsPatching": "true"
    },
    "Details": {
      "AwsEc2Instance": {
        "Type": "i3.xlarge",
        "ImageId": "ami-abcd1234",
        "IpV4Addresses": [ "54.194.252.215", "192.168.1.88" ],
        "IpV6Addresses": [ "2001:db8:1234:1a2b::123" ],
        "KeyName": "my_keypair",
        "IamInstanceProfileArn": "arn:aws:iam::111111111111:instance-profile/AdminRole",
        "VpcId": "vpc-11112222",
        "SubnetId": "subnet-56f5f633",
        "LaunchedAt": "2018-05-08T16:46:19.000Z"
      }  
    }
  }
]
Resource.Details No

This field provides additional details about the resource through one (and only one) of its subfields. The Resource.Type field indicates which of the subfields should contain data. Since this field is optional, there may be a Resource.Type value set, but no details provided in any subfields. If a subfield is defined, the Resource.Type must match the subfield name. For example, if the AwsS3Bucket subfield is populated, the Resource.Type must be set to "AwsS3Bucket".

Only one subfield can be defined in a finding. All other subfields that contain finding details (except the subfield defined in Resource.Type) are ignored by all processors.

If multiple resources are present, such as an EC2 instance and an S3 bucket, two separate Resource objects must be created in the Resources field.

If a resource doesn't fit into one of the existing subfields, the Other field can be used to provide the resource details. The Resource.Type then must be set to "Other", when providing details in the Other subfield. The Other field must NOT be used when an existing subfield is more appropriate for the resource that is being defined. The Other field must NOT be used in conjunction with any other subfield. For example, additional details about an EC2 instance must NOT be provided in the Other field when the AwsEc2Instance field is used. Additionally, the Other field cannot be used in place of the AwsEc2Instance field when providing details about an EC2 instance.

Type: object

Example:


"Details": {
  "AwsEc2Instance": {
    "Type": "i3.xlarge",
    "ImageId": "ami-abcd1234",
    "IpV4Addresses": [ "54.194.252.215", "192.168.1.88" ],
    "IpV6Addresses": [ "2001:db8:1234:1a2b::123" ],
    "KeyName": "my_keypair",
    "IamInstanceProfileArn": "arn:aws:iam::111111111111:instance-profile/AdminRole",
    "VpcId": "vpc-11112222",
    "SubnetId": "subnet-56f5f633",
    "LaunchedAt": "2018-05-08T16:46:19.000Z"
  },
  "AwsS3Bucket": {
    "OwnerId": "da4d66eac431652a4d44d490a00500bded52c97d235b7b4752f9f688566fe6de",
    "OwnerName": "acmes3bucketowner"
  },
  "Other": [
    { "Key": "LightPen", "Value": "blinky" },
    { "Key": "SerialNo", "Value": "1234abcd" }
  ]
}
Resource.Details.AwsEc2Instance No

The details of an AWS Amazon EC2 instance.

Type: object
Resource.Details.AwsEc2Instance.IamInstanceProfileArn No

The IAM profile Amazon Resource Number (ARN) of the instance.

Resource.Details.AwsEc2Instance.ImageId No

The Amazon Machine Image (AMI) ID of the instance.

Type: string (64 char max)
Resource.Details.AwsEc2Instance.IpV4Addresses No

The IPv4 addresses associated with the instance.

Type: array of up to 10 IPv4 addresses
Resource.Details.AwsEc2Instance.IpV6Addresses No

The IPv6 addresses associated with the instance.

Type: array of up to 10 IPv6 addresses
Resource.Details.AwsEc2Instance.KeyName No

The key name associated with the instance.

Type: string (128 char max)
Resource.Details.AwsEc2Instance.LaunchedAt No

The date and time when the instance was launched.

Type: timestamp
Resource.Details.AwsEc2Instance.SubnetId No

The identifier of the subnet in which the instance was launched.

Type: string (32 character max)
Resource.Details.AwsEc2Instance.Type No

The instance type of the instance. This must be a valid EC2 instance type.

Type: string (16 character max)
Resource.Details.AwsEc2Instance.VpcId No

The identifier of the VPC where the instance was launched.

Type: string (32 character max)
Resource.Details.AwsIamAccessKey No

AWS IAM access key details related to a finding.

Type: object
Resource.Details.AwsIamAccessKey.CreatedAt No

The creation date/time of the IAM access key related to a finding.

Type: timestamp
Resource.Details.AwsIamAccessKey.Status No

The status of the IAM access key related to a finding. Valid values are ACTIVE and INACTIVE.

Type: enum

Resource.Details.AwsIamAccessKey.UserName No

The user associated with the IAM access key related to a finding.

Type: string (128 char max)

Resource.Details.AwsS3Bucket No

The details of an Amazon S3 bucket.

Type: object
Resource.Details.AwsS3Bucket.OwnerId No

The canonical user ID of the owner of the S3 bucket.

Type: string (64 char max)
Resource.Details.AwsS3Bucket.OwnerName No

The display name of the owner of the S3 bucket.

Type: string (128 char max)
Resource.Details.Container No

Container details related to a finding.

Type: object

  • Example:

    
"Container": {
"Name": "Secret Service Container",
"ImageId": "image12",
"ImageName": "SecSvc v1.2 Image",
"LaunchedAt": "2018-09-29T01:25:54Z"
}
Resource.Details.Container.ImageId No

The identifier of the image related to a finding.

Type: string (128 char max)
Resource.Details.Container.ImageName No

The name of the image related to a finding.

Type: string (128 char max)
Resource.Details.Container.LaunchedAt No

The date and time that the container was started.

Type: timestamp
Resource.Details.Container.Name No

The name of the container related to a finding.

Type: string (128 char max)
Resource.Details.Other No

The details of a resource that does not have a specific subfield for the resource type defined under Resource.Details. Resource.Type must set to "Other" in order for this field to be populated.

Type: map of up to 50 key/value pairs

Resource.Id Yes

The canonical identifier for the given resource type. For AWS resources that are identified by ARNs, this must be the ARN. For all other AWS resource types that lack ARNs, this must be the identifier as defined by the AWS service that created the resource. For non-AWS resources, this should be a unique identifier associated with the resource.

Type: string (512 char max) or ARN

  • Example:

    
"Id": "arn:aws:s3:::example-bucket"
Resource.Partition No

The canonical AWS partition name to which the region is assigned.

Type: enum

Valid values include the following:

Partition Description
aws Public
aws-cn China
aws-us-gov US GovCloud

  • Example:

    
"Partition": "aws"
Resource.Region No

The canonical AWS external region name where this resource is located.

Type: string (16 char max)

Example:


"Region": "us-west-2"
Resource.Tags No

A list of AWS tags associated with a resource at the time the finding was processed.

Type: map of up to 50 tags (values are limited to 256 char max)

The following basic restrictions apply to tags:

  • Only tags that actually exist on an AWS resource CAN be provided in this field. For providing data for a resource type not defined in the ASFF, use the Resource.Detail.Other field.

  • Values are limited to: alphanumeric characters, whitespace, +, -, =, ., _, :, /, and @.

  • Values are limited to the AWS Tag value length of 256 char max.

  • Example:

    
"Tags": {
  "billingCode": "Lotus-1-2-3",
  "needsPatching": "true"
}
Resource.Type Yes

Specifies the type of the resource for which details are provided.

Type: string (32 char max)

Valid values are:

  • AwsEc2Instance

  • AwsS3Bucket

  • Container

  • AwsIamAccessKey

  • AwsIamUser

  • AwsAccount

  • AwsIamPolicy

  • AwsCloudTrailTrail

  • AwsKmsKey

  • AwsEc2Vpc

  • AwsEc2SecurityGroup

  • Other

  • Example:

    
"Type": "AwsS3Bucket"
SchemaVersion Yes

The schema version for which a finding is formatted. 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.

Type: string (10 char max, conforms to yyyy-mm-dd)

  • Example:

    
"SchemaVersion": "2018-10-08"
Severity Yes

A finding's severity.

Type: object

  • Example:

    
"Severity": {
  "Product": 8.3,
  "Normalized": 25
}
Severity.Normalized Yes The normalized severity of a finding. For findings generated by the supported AWS services, Security Hub automatically translates the native severity into the normalized severity based on the guidance below. For findings generated by the supported third-party partner products, partners can use this guidance to determine the normalized severity required by the AWS Security Finding Format before sending these findings to Security Hub:

Note

In AWS Security Finding Format, a finding severity does not include consideration of the criticality of the assets involved in the activity that resulted in this finding. Findings that are associated with actual data loss or denial of service are considered most severe. Findings that are associated with an active compromise, but that do not indicate that data loss or other negative effects have occurred are considered second most severe. Findings associated with issues that indicate potential for a future compromise are considered third most severe.

Severity is scored on a 0-100 basis using a ratio scale with only full integers supported. This means that when determining the normalized severity, you should assess not only which findings are more severe than others, but also how more severe one finding is than another. "0" means that no severity applies (e.g. the severity is "Informational") and "100" means that the finding has the maximum possible severity. It is recommends that you utilize the following guidance when translating findings' native severity scores to normalized severity for the AWS Security Finding Format:

  • Informational Findings (e.g., a finding associated with a “Passed” compliance check or a sensitive data identification). Suggested score: 0. These findings should receive a "Low" severity label.

  • Findings associated with issues that could result in future compromises (e.g., vulnerabilities, configuration weaknesses, exposed passwords). This generally aligns to the "Software and Configuration Checks" namespace under a finding's Type. Suggested score: 1-39. These findings should receive a "Low" severity label.

  • Findings associated with issues that indicate there is an active compromise, but no indication that an adversary has completed their objectives (e.g., malware activity, hacking activity, unusual behavior detection). This generally aligns to the "Threat Detections and Unusual Behavior" namespaces under a finding's Type. Suggested score: 40-69. These findings should receive a "Medium" severity label.

  • Findings associated with an adversary completing their objectives, such as active data loss/compromise or denial of service. This generally aligns to the "Effects" namespace under a finding's Type. Suggested score: 70-100. These findings should receive a high or critical severity label.

In Security Hub the normalized severity scores are available both in their numeric form and in a translated severity label using the translation table below. The severity labels can be used within Filters and Group By statements when managing insights using Severity.Label.

Severity Label Severity Score Range
Informational 0
Low 1-39
Medium 40 - 69
High 70 - 89
Critical 90 - 100
Severity.Product No

The native severity as defined by the security findings provider's solution that generated the finding.

Type: number (single-precision 32-bit IEEE 754 floating point number, restricted to finite values)

SourceUrl No

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

Type: URL

ThreatIntelIndicators No

Threat intel details related to a finding.

Type: array of up to 5 threat intel indicator objects

  • Example:

    
"ThreatIntelIndicators": [
  {
    "Type": "IPV4_ADDRESS",
    "Value": "8.8.8.8",
    "Category": "BACKDOOR",
    "LastObservedAt": "2018-09-27T23:37:31Z",
    "Source": "Threat Intel Weekly",
    "SourceUrl": "http://threatintelweekly.org/backdoors/8888"
  }
]
ThreatIntelIndicators.Category No

The category of a threat intel indicator. Valid values are BACKDOOR | CARD_STEALER | COMMAND_AND_CONTROL | DROP_SITE | EXPLOIT_SITE | KEYLOGGER.

Type: enum
ThreatIntelIndicators.LastObservedAt No

The date/time of the last observation of a threat intel indicator.

Type: timestamp
ThreatIntelIndicators.Source No

The source of the threat intel.

Type: string (64 chars. max)
ThreatIntelIndicators.SourceUrl No

The URL for more details from the source of the threat intel.

Type: URL
ThreatIntelIndicators.Type No

The type of a threat intel indicator. Valid values are DOMAIN | EMAIL_ADDRESS | HASH_MD5 | HASH_SHA1 | HASH_SHA256 | HASH_SHA512 | IPV4_ADDRESS | IPV6_ADDRESS | MUTEX | PROCESS | URL.

Type: enum
ThreatIntelIndicators.Value No

The value of a threat intel indicator.

Type: string (512 char max)
Title Yes

A finding's title. This field can be non-specific boilerplate text or it can contain details specific to this instance of the finding.

Type: string (256 char max)

Types Yes

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

Type: array of 50 strings max

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

  • Namespace must be a value from the predefined set of namespace values.

  • Category might be any value, but it's recommended that findings providers use categories from the finding type taxonomy in Type Taxonomy of the AWS Security Finding.

  • Classifier might be any value, but it's recommended that FPs use the identifier verbatim defined by published standards whenever possible.

Namespaces are required for all finding types, but categories and classifiers are optional. If a classifier is specified, a category must be specified as well. The '/' character is reserved and must NOT be used within a category or classifier. Escaping the '/' character is not supported.

  • Example:

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

An ISO8601-formatted timestamp (as defined in RFC-3339 Date and Time on the Internet: Timestamps) that indicates when the finding record was last updated by the findings provider. Because this timestamp reflects the time when the finding record was last/most-recently updated, it can differ from the LastObservedAt timestamp, which reflects when the event/vulnerability was last/most-recently observed.

This timestamp must be updated to the current timestamp when the finding record is updated. Upon creation of a finding record, the CreatedAt and UpdatedAt timestamps must be the same timestamp. Upon finding record update, the value of this field must be greater than all of the previous values that it contained

Type: timestamp

UserDefinedFields No

A list of name/value string pairs associated with the finding. These are custom, user-defined fields added to a finding. These fields can be generated automatically via your specific configuration. Findings providers must NOT use this field for data generated by the product. Instead, findings providers can use the ProductFields field for data that does not map to any standard AWS Security Finding Format field.

Type: map of up to 50 key/value pairs

  • Example:

    
"UserDefinedFields": {
    "reviewedByCio": "true",
    "comeBackToLater": "Check this again on Monday"
}
VerificationState No

Indicates the veracity of a finding. Findings providers can provide the value of UNKNOWN for this field. A findings providers should provide this value if there is a meaningful analog in the findings provider's system. This field is typically populated by a user determination/action after they have investigated a finding.

Type: enum

Valid values are:

  • UNKNOWN – The default disposition of a security finding unless changed by a user.

  • TRUE_POSITIVE – A user will set this value if the security finding has been confirmed.

  • FALSE_POSITIVE – A user will set this value if the security finding has been determined to be a false alarm.

  • BENIGN_POSITIVE – A user will set this value as a special case of TRUE_POSITIVE where the finding does not pose any threat and/or is expected.

WorkflowState No

The workflow state of a finding. Findings providers can provide the value of NEW for this field. A findings provider can provide a value for this field if there is a meaningful analog in the findings provider's system.

Type: enum

Valid value are:

  • NEW - this can be associated with findings in the Active record state. This is the default workflow state for any new finding.

  • ASSIGNED - this can be associated with findings in the Active record state. The finding has been acknowledged and give to someone to review / or address.

  • IN_PROGRESS - this can be associated with findings in the Active record state. The finding is actively being worked on by team members.

  • RESOLVED - this can be associated with findings in the Archive record state. This differs from ‘Deferred’ findings in that if the finding were to occur again (be updated by the native service) OR any new finding matching this, the finding is displayed to customers as an active, new finding.

  • DEFERRED - this can be associated with findings in the Archive record state, and it means that any additional findings that match this finding will not be shown for a set amount of time or indefinitely. The customer does not either consider the finding to be applicable OR it is a known issue they do not want included in the active data set.

  • DUPLICATE - this can be associated with findings in the Archive record state, and it means that the finding is a duplicate of another finding.

  • Example:

    
"WorkflowState": "NEW"

Type Taxonomy of the AWS Security Finding

The following information describes the first three levels of the Types path. The top-level bullets are namespaces, the second-level bullets are categories, and the third-level bullets (shown only for Software and Configuration Checks) are Classifiers.

  • Namespaces

    • Categories

      • Classifiers

Classifiers can be self-defined by findings providers. A findings provider might define a partial path. For example, the following finding Types are all valid: TTPs, TTPs/Defense Evasion, TTPs/Defense Evasion/CloudTrailStopped, and TTPs//CloudTrailStopped.

Note

TTPs stands for Tactics, Techniques, and Procedures. The TTP categories in the following list align to the MITRE ATT&CK MatrixTM. Unusual Behaviors are different from TTPs in that they reflect general unusual behavior (e.g., general statistical anomalies) and aren't aligned with a specific TTP. However, if desired, a finding could be classified with both Unusual Behaviors and TTPs finding types.

  • Software and Configuration Checks

    • Vulnerabilities

      • CVE

    • AWS Security Best Practices

      • Network Reachability

      • Runtime Behavior Analysis

    • Industry and Regulatory Standards

      • CIS Host Hardening Benchmarks

      • CIS AWS Foundations Benchmark

      • PCI-DSS Controls

      • 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)

  • 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