Optional top-level attributes

These top-level attributes are optional in the AWS Security Finding Format. For more information about these attributes, see AwsSecurityFinding in the AWS Security Hub API Reference.

Action

The Action object provides details about an action that affects or that was taken on a resource.

Example


"Action": {
    "ActionType": "PORT_PROBE",
    "PortProbeAction": {
        "PortProbeDetails": [
            {
                "LocalPortDetails": {
                    "Port": 80,
                    "PortName": "HTTP"
                  },
                "LocalIpDetails": {
                     "IpAddressV4": "192.0.2.0"
                 },
                "RemoteIpDetails": {
                    "Country": {
                        "CountryName": "Example Country"
                    },
                    "City": {
                        "CityName": "Example City"
                    },
                   "GeoLocation": {
                       "Lon": 0,
                       "Lat": 0
                   },
                   "Organization": {
                       "AsnOrg": "ExampleASO",
                       "Org": "ExampleOrg",
                       "Isp": "ExampleISP",
                       "Asn": 64496
                   }
                }
            }
        ],
        "Blocked": false
    }
}

CompanyName

The name of the company for the product that generated the finding. For control-based findings, the company is AWS.

Security Hub populates this attribute automatically for each finding. You cannot update it using BatchImportFindings or BatchUpdateFindings. The exception to this is when you use a custom integration. See Using custom product integrations to send findings to AWS Security Hub.

When you use the Security Hub console to filter findings by company name, you use this attribute.When you use the Security Hub API to filter findings by company name, you use the aws/securityhub/CompanyName attribute under ProductFields. Security Hub does not synchronize those two attributes.

Example


"CompanyName": "AWS"

Compliance

The Compliance object provides finding details related to a control. This attribute is only returned for findings generated from a Security Hub control.

Example


"Compliance": {
    "RelatedRequirements": ["Req1", "Req2"],
    "Status": "PASSED",
    "StatusReasons": [
        {
            "ReasonCode": "CLOUDWATCH_ALARMS_NOT_PRESENT",
            "Description": "CloudWatch alarms do not exist in the account"
        }
    ]
}

Confidence

The likelihood that a finding accurately identifies the behavior or issue that it was intended to identify.

Confidence should only be updated using BatchUpdateFindings.

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

Confidence is scored on a 0–100 basis using a ratio scale, where 0 means 0-percent confidence and 100 means 100-percent confidence. For example, a data exfiltration detection based on a statistical deviation of network traffic has low confidence because an actual exfiltration hasn't been verified.

Example


"Confidence": 42

Criticality

The level of importance that is assigned to the resources that are associated with a finding.

Criticality should only be updated by calling the BatchUpdateFindings API operation. You should not update this object with BatchImportFindings.

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

Criticality is scored on a 0–100 basis, using a ratio scale that supports only full integers. A score of 0 means that the underlying resources have no criticality, and a score of 100 is reserved for the most critical resources.

For each resource, consider the following when assigning Criticality:

Does the affected resource contain sensitive data (for example, an S3 bucket with PII)?
Does the affected resource enable an adversary to deepen their access or extend their capabilities to carry out additional malicious activity (for example, a compromised sysadmin account)?
Is the resource a business-critical asset (for example, 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–74 range.
A resource powering unimportant systems or containing nonsensitive data should be scored in the 0–24 range.

Example


"Criticality": 99

FindingProviderFields

FindingProviderFields includes the following attributes:

Confidence
Criticality
RelatedFindings
Severity
Types

You can updateFindingProviderFields by using theBatchImportFindings API operation. You cannot update it with BatchUpdateFindings.

For details on how Security Hub handles updates from BatchImportFindings to FindingProviderFields and to the corresponding top-level attributes, see Using FindingProviderFields.

Example


"FindingProviderFields": {
    "Confidence": 42,
    "Criticality": 99,
    "RelatedFindings":[
      { 
        "ProductArn": "arn:aws:securityhub:us-west-2::product/aws/guardduty", 
        "Id": "123e4567-e89b-12d3-a456-426655440000" 
      }
    ],
    "Severity": {
        "Label": "MEDIUM", 
        "Original": "MEDIUM"
    },
    "Types": [ "Software and Configuration Checks/Vulnerabilities/CVE" ]
}

FirstObservedAt

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

This timestamp reflects the time of when the event or vulnerability was first observed. Consequently, 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 is determined.

Example


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

LastObservedAt

Indicates when the potential security issue that was captured by a finding was most recently observed by the security findings product.

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

You can provide this timestamp, but it isn't required upon first observation. If you provide this field upon first observation, the timestamp should be the same as the FirstObservedAt timestamp. You should update this field to reflect the last or most recently observed timestamp each time a finding is observed.

Example


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

Malware

The Malware object provides a list of malware related to a finding.

Example


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

Network (Deprecated)

The Network object provides network-related information about a finding.

This object is deprecated. To provide this data, you can either map the data to a resource in Resources, or use the Action object.

Example


"Network": {
    "Direction": "IN",
    "OpenPortRange": {
        "Begin": 443,
        "End": 443
    },
    "Protocol": "TCP",
    "SourceIpV4": "1.2.3.4",
    "SourceIpV6": "FE80:CD00:0000:0CDE:1257:0000:211E:729C",
    "SourcePort": "42",
    "SourceDomain": "example1.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": "example2.com"
}

NetworkPath

The NetworkPath object provides information about a network path that is related to a finding. Each entry in NetworkPath represents a component of the path.

Example


"NetworkPath" : [
    {
        "ComponentId": "abc-01a234bc56d8901ee",
        "ComponentType": "AWS::EC2::InternetGateway",
        "Egress": {
            "Destination": {
                "Address": [ "192.0.2.0/24" ],
                "PortRanges": [
                    {
                        "Begin": 443,
                        "End": 443
                    }
                ]
            },
            "Protocol": "TCP",
            "Source": {
                "Address": ["203.0.113.0/24"]
            }
        },
        "Ingress": {
            "Destination": {
                "Address": [ "198.51.100.0/24" ],
                "PortRanges": [
                    {
                        "Begin": 443,
                        "End": 443
                    }
                 ]
            },
            "Protocol": "TCP",
            "Source": {
                "Address": [ "203.0.113.0/24" ]
            }
        }
     }
]

Note

The Note object specifies a user-defined note that you can add to a finding.

A finding provider can provide an initial note for a finding, but cannot add notes after that. You can only update a note using BatchUpdateFindings.

Example


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

PatchSummary

The PatchSummary object provides a summary of the patch compliance status for an instance against a selected compliance standard.

Example


"PatchSummary" : {
    "FailedCount" : 0,
    "Id" : "pb-123456789098",
    "InstalledCount" : 100,
    "InstalledOtherCount" : 1023,
    "InstalledPendingReboot" : 0,
    "InstalledRejectedCount" : 0,
    "MissingCount" : 100,
    "Operation" : "Install",
    "OperationEndTime" : "2018-09-27T23:39:31Z",
    "OperationStartTime" : "2018-09-27T23:37:31Z",
    "RebootOption" : "RebootIfNeeded"
}

Process

The Process object provides process-related details about a finding.

Example:


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

ProductFields

A data type where security findings products can include additional solution-specific details that are not part of the defined AWS Security Finding Format.

For findings generated by Security Hub controls, ProductFields includes information about the control. See Generating and updating control findings.

This field should not contain redundant data and must not contain data that conflicts with AWS Security Finding Format fields.

The "aws/" prefix represents a reserved namespace for AWS products and services only and must not be submitted with findings from third-party integrations.

Although 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.

Example


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

ProductName

Provides the name of the product that generated the finding. For control-based findings, the product name is Security Hub.

When you use the Security Hub console to filter findings by product name, you use this attribute.

When you use the Security Hub API to filter findings by product name, you use the aws/securityhub/ProductName attribute under ProductFields.

Security Hub does not synchronize those two attributes.

RecordState

Provides the record state of a finding.

By default, when initially generated by a service, findings are considered ACTIVE.

The ARCHIVED state indicates that a finding should be hidden from view. Archived findings are not immediately deleted. You can search, review, and report on them. Security Hub automatically archives control-based findings if the associated resource is deleted, the resource does not exist, or the control is disabled.

RecordState is intended for finding providers, and can only be updated by BatchImportFindings. You cannot update it using BatchUpdateFindings.

To track the status of your investigation into a finding, use Workflow instead of RecordState.

If the record state changes from ARCHIVED to ACTIVE, and the workflow status of the finding is either NOTIFIED or RESOLVED, then Security Hub automatically sets the workflow status to NEW.

Example


"RecordState": "ACTIVE"

Region

Specifies the AWS Region from which the finding was generated.

Security Hub populates this attribute automatically for each finding. You cannot update it using BatchImportFindings or BatchUpdateFindings.

Example


"Region": "us-west-2"

RelatedFindings

Provides a list of findings that are related to the current finding.

RelatedFindings should only be updated with the BatchUpdateFindings API operation. You should not update this object with BatchImportFindings.

For BatchImportFindings requests, finding providers should use the RelatedFindings object under FindingProviderFields.

To view descriptions of RelatedFindings attributes, see RelatedFinding in the AWS Security Hub API Reference.

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" }
]

Remediation

The Remediation object provides information about recommended remediation steps to address the finding.

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"
    }
}

Sample

Specifies whether the finding is a sample finding.


"Sample": true

SourceUrl

The SourceUrl object provides a URL that links to a page about the current finding in the finding product.


"SourceUrl": "http://sourceurl.com"

ThreatIntelIndicators

The ThreatIntelIndicator object provides threat intelligence details that are related to a finding.

Example


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

Threats

The Threats object provides details about the threat detected by a finding.

Example


"Threats": [{
    "FilePaths": [{
        "FileName": "b.txt",
        "FilePath": "/tmp/b.txt",
        "Hash": "sha256",
        "ResourceId": "arn:aws:ec2:us-west-2:123456789012:volume/vol-032f3bdd89aee112f"
    }],
    "ItemCount": 3,
    "Name": "Iot.linux.mirai.vwisi",
    "Severity": "HIGH"
}]

UserDefinedFields

Provides a list of name-value string pairs that are associated with the finding. These are custom, user-defined fields that are added to a finding. These fields can be generated automatically through your specific configuration.

Finding providers should not use this field for data that the product generates. Instead, finding providers can use the ProductFields field for data that does not map to any standard AWS Security Finding Format field.

These fields can only be updated using BatchUpdateFindings.

Example


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

VerificationState

Provides the veracity of a finding. Findings products can provide a value of UNKNOWN for this field. A findings product should provide a value for this field if there is a meaningful analog in the findings product's system. This field is typically populated by a user determination or action after investigating a finding.

A finding provider can provide an initial value for this attribute, but cannot update it after that. You can only update this attribute by using BatchUpdateFindings.


"VerificationState": "Confirmed"

Vulnerabilities

The Vulnerabilities object provides a list of vulnerabilities that are associated with a finding.

Example


"Vulnerabilities" : [
    {
        "Cvss": [
            {
                "BaseScore": 4.7,
                "BaseVector": "AV:N/AC:L/PR:N/UI:N/S:U/C:L/I:N/A:N",
                "Version": "V3"
            },
            {
                "BaseScore": 4.7,
                "BaseVector": "AV:L/AC:M/Au:N/C:C/I:N/A:N",
                "Version": "V2"
            }
        ],
        "Id": "CVE-2020-12345",
        "ReferenceUrls":[
           "http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2019-12418",
            "http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2019-17563"
        ],
        "RelatedVulnerabilities": ["CVE-2020-12345"],
        "Vendor": {
            "Name": "Alas",
            "Url":"https://alas.aws.amazon.com/ALAS-2020-1337.html",
            "VendorCreatedAt":"2020-01-16T00:01:43Z",
            "VendorSeverity":"Medium",
            "VendorUpdatedAt":"2020-01-16T00:01:43Z"
        },
        "VulnerablePackages": [
            {
                "Architecture": "x86_64",
                "Epoch": "1",
                "Name": "openssl",
                "Release": "16.amzn2.0.3",
                "Version": "1.0.2k"
            }
        ]
    }
]

Workflow

The Workflow object provides information about the status of the investigation into a finding.

This field is intended for customers to use with remediation, orchestration, and ticketing tools. It is not intended for finding providers.

You can only update the Workflow field with BatchUpdateFindings. Customers can also update it from the console. See Setting the workflow status for findings.

Example


"Workflow": {
    "Status": "NEW"
}

WorkflowState (Deprecated)

This object is deprecated and has been replaced by the Status field of the Workflow object.

This field provides the workflow state of a finding. Findings products can provide the value of NEW for this field. A findings product can provide a value for this field if there is a meaningful analog in the findings product's system.

Example


"WorkflowState": "NEW"

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Types taxonomy for ASFF

Resources