Using Amazon EventBridge - Amazon GuardDuty
Set up EventBridge rules
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).

Using Amazon EventBridge

Amazon EventBridge is a serverless event bus service that makes it easy to connect your applications with data from a variety of sources. EventBridge delivers a stream of real-time data from your own applications, Software-as-a-Service (SaaS) applications, and Amazon services and routes that data to targets such as Lambda. This enables you to monitor events that happen in services, and build event-driven architectures. For more information, see the Amazon EventBridge User Guide.

As the owner account of an S3 bucket that is protected with Malware Protection for S3, GuardDuty publishes EventBridge notifications to the default event bus in the following scenarios:

  • Malware Protection plan resource status changes for any of your protected buckets. For information about various statuses, see Malware Protection plan resource status.

  • There is a tag event failure because of the following reasons:

    • Your IAM PassRole is missing permissions to tag the object.

      The Adding IAM policy permissions template includes the permission for GuardDuty to tag an object.

    • The bucket resource or object specified in the IAM PassRole no longer exists.

    • The associated S3 object has already reached the maximum tag limit. For more information about the tag limit, see Categorizing your storage using tags in the Amazon S3 User Guide.

  • The S3 object scan result gets published to your default EventBridge event bus.

Set up EventBridge rules

You can set up EventBridge rules in your account to send either resource status, post-scan tag failure events, or the S3 object scan result to another Amazon Web Service. As a delegated GuardDuty administrator account, you will receive the Malware Protection plan resource status notification when there is a change in the status.

Standard EventBridge pricing will apply. For more information, see Pricing for Malware Protection for S3.

All the values that show up in red are placeholders for the example. These values will change based on the scan result for your S3 object.

You can create an EventBridge event pattern based on the following scenarios:

Potential detail-type values

  • "GuardDuty Malware Protection Resource Status Active"

  • "GuardDuty Malware Protection Resource Status Warning"

  • "GuardDuty Malware Protection Resource Status Error"

Event pattern

{
      "detail-type": ["potential detail-type"],
      "source": ["aws.guardduty"]
}

Sample notification schema for GuardDuty Malware Protection Resource Status Active

{
    "version": "0",
    "id": "6a7e8feb-b491-4cf7-a9f1-bf3703467718",
    "detail-type": "GuardDuty Malware Protection Resource Status Active",
    "source": "aws.guardduty",
    "account": "111122223333",
    "time": "2017-12-22T18:43:48Z",
    "region": "us-east-1",
    "resources": ["arn:aws-cn:guardduty:us-east-1:111122223333:malware-protection-plan/b4c7f464ab3a4EXAMPLE"],
    "detail": {
        "schemaVersion": "1.0",
        "eventTime": "2024-02-28T01:01:01Z",
        "s3BucketDetails": {
            "bucketName": "DOC-EXAMPLE-BUCKET"
        },
        "resourceStatus": "ACTIVE"
    }
}

Sample notification schema for GuardDuty Malware Protection Resource Status Error or GuardDuty Malware Protection Resource Status Warning

{
    "version": "0",
    "id": "fc7a35b7-83bd-3c1f-ecfa-1b8de9e7f7d2",
    "detail-type": "GuardDuty Malware Protection Resource Status Error or Warning",
    "source": "aws.guardduty",
    "account": "111122223333",
    "time": "2017-12-22T18:43:48Z",
    "region": "us-east-1",
    "resources": ["arn:aws-cn:guardduty:us-east-1:111122223333:malware-protection-plan/b4c7f464ab3a4EXAMPLE"],
    "detail": {
        "schemaVersion": "1.0",
        "eventTime": "2024-02-28T01:01:01Z",
        "s3BucketDetails": {
            "bucketName": "DOC-EXAMPLE-BUCKET"
        },
        "resourceStatus": "ERROR",
        "statusReasons": [{
            "code": "EVENTBRIDGE_MANAGED_EVENTS_DELIVERY_DISABLED"
        }, {
            "code": "PROTECTED_RESOURCE_DELETED"
        }]
    }
}

The resourceStatus value can be either Warning or Error.

When the Status column of a protected bucket changes to either Warning or Error, the statusReasons value will get populated based on the underlying reason. For information about troubleshooting steps, see Troubleshooting Malware Protection plan status details.

Event pattern:

{
      "detail-type": "GuardDuty Malware Protection Post Scan Action Failed",
      "source": "aws.guardduty"
 }

Sample notification schema:

{
    "version": "0",
    "id": "746acd83-d75c-5b84-91d2-dad5f13ba0d7",
    "detail-type": "GuardDuty Malware Protection Post Scan Action Failed",
    "source": "aws.guardduty",
    "account": "111122223333",
    "time": "2024-06-10T16:16:08Z",
    "region": "us-east-1",
    "resources": ["arn:aws-cn:guardduty:us-east-1:111122223333:malware-protection-plan/b4c7f464ab3a4EXAMPLE"],
    "detail": {
        "schemaVersion": "1.0",
        "eventTime": "2024-06-10T16:16:08Z",
        "s3ObjectDetails": {
            "bucketName": "DOC-EXAMPLE-BUCKET",
            "objectKey": "2024-03-10-16-16-00-7D723DE8DBE9Y2E0",
            "eTag": "0e9eeec810ad8b61d69112c15c2a5hb6"
        },
        "postScanActions": [{
            "actionType": "TAGGING",
            "status": "FAILED",
            "failureReason": "ACCESS_DENIED"
        }]
    }
}

Potential failureReason values include ACCESS_DENIED and MAX_TAG_LIMIT_EXCEEDED.

{
  "detail-type": ["GuardDuty Malware Protection Object Scan Result"],
  "source": ["aws.guardduty"]
}

Sample notification schema for NO_THREATS_FOUND

{
    "version": "0",
    "id": "72c7d362-737a-6dce-fc78-9e27a0171419",
    "detail-type": "GuardDuty Malware Protection Object Scan Result",
    "source": "aws.guardduty",
    "account": "111122223333",
    "time": "2024-02-28T01:01:01Z",
    "region": "us-east-1",
    "resources": [arn:aws-cn:guardduty:us-east-1:111122223333:malware-protection-plan/b4c7f464ab3a4EXAMPLE],
    "detail": {
        "versionId": "1.0",
        "scanStatus": "COMPLETED",
        "resourceType": "S3_OBJECT",
        "s3ObjectDetails": {
            "bucketName": "DOC-EXAMPLE-BUCKET",
            "objectKey": "APKAEIBAERJR2EXAMPLE",
            "eTag": "ASIAI44QH8DHBEXAMPLE"
        },
        "scanResultDetails": {
            "scanResultStatus": "NO_THREATS_FOUND",
            "threats": null
        }
    }
}

Sample notification schema for THREATS_FOUND

{
    "version": "0",
    "id": "72c7d362-737a-6dce-fc78-9e27a0171419",
    "detail-type": "GuardDuty Malware Protection Object Scan Result",
    "source": "aws.guardduty",
    "account": "111122223333",
    "time": "2024-02-28T01:01:01Z",
    "region": "us-east-1",
    "resources": [arn:aws-cn:guardduty:us-east-1:111122223333:malware-protection-plan/b4c7f464ab3a4EXAMPLE],
    "detail": {
        "versionId": "1.0",
        "scanStatus": "COMPLETED",
        "resourceType": "S3_OBJECT",
        "s3ObjectDetails": {
            "bucketName": "DOC-EXAMPLE-BUCKET",
            "objectKey": "APKAEIBAERJR2EXAMPLE",
            "eTag": "ASIAI44QH8DHBEXAMPLE"
        },
        "scanResultDetails": {
            "scanResultStatus": "THREATS_FOUND",
            "threats": [
                {
                    "name": "EICAR-Test-File (not a virus)"
                }
            ]
        }
    }
}