AWS GuardDuty

AWS GuardDuty findings are alerts generated by the service when it detects potential security threats or unusual behavior in your AWS environment. You can integrate InsightIDR with AWS GuardDuty to receive third-party alerts. AWS GuardDuty produces data in the form of EventBridge events, which are then sent to InsightIDR using an Amazon Simple Queue Service (SQS) queue.

There are two ways to send data from your AWS GuardDuty account to InsightIDR: event collection through the Cloud or through an on-premises Rapid7 Collector.

To set up AWS GuardDuty:

  1. Read the requirements and complete any prerequisite steps.
  2. Configure AWS GuardDuty to send data to InsightIDR.
  3. Configure InsightIDR to collect data from the event source.
  4. Test the configuration.

You can also:

Visit the third-party vendor's documentation

For the most accurate information about preparing your event source product for integration with InsightIDR, we recommend that you visit the Amazon GuardDuty product documentation.

Requirements

Before InsightIDR can start ingesting data from AWS GuardDuty, you must:

  • Set up and enable AWS GuardDuty
  • Set up EventBridge events

To learn more about EventBridge events, refer to the Amazon EventBridge user guide.

Configure AWS GuardDuty to send data to InsightIDR

To ensure InsightIDR can retrieve data from AWS GuardDuty, there are a few components that must be set up within the AWS Management Console.

Before configuring the event source in InsightIDR you must:

  1. Enable AWS GuardDuty.
  2. Generate an AWS Key for the SQS queue.
  3. Set up an SQS queue for data moving between GuardDuty and InsightIDR.
  4. Create an IAM Policy and User for HTTP requests from Rapid7.
  5. Set up encrypted SQS queue user permissions.
  6. Create an EventBridge event rule for data transfer to the SQS queue.

Task 1: Enable AWS GuardDuty

From the AWS Management Console, go to GuardDuty > Enable GuardDuty. For detailed instructions, see the AWS documentation.

Task 2: Generate the AWS Key

Go to Key Management Service > Create a key. For detailed instructions, see the AWS documentation.

Task 3: Set up the SQS queue

The SQS queue allows AWS GuardDuty to send data to and from InsightIDR, which will read and remove messages once they are processed, as it polls periodically.

  1. Go to Simple Queue Service > Create queue and create a new SQS queue, ensuring the queue is dedicated for use by InsightIDR.
  2. Under Type, select Standard.
  3. Enter the remaining configuration information.
  4. Click Create queue.

Store the queue URL in a secure place for later use when configuring the AWS GuardDuty event source in InsightIDR.

Task 4: Create the IAM Policy and IAM User

The IAM policy and user you create will be used in making HTTP requests to an SQS queue.

  1. Go to IAM > Policies > Create policy.
  2. Add this to the JSON of the policy:
New IAM Policy
1
{
2
    "Version": "2012-10-17",
3
    "Statement": [
4
        {
5
            "Effect": "Allow",
6
            "Action": [
7
                "sqs:ReceiveMessage",
8
                "sqs:DeleteMessage"
9
            ],
10
            "Resource": [
11
                "arn:aws:sqs:*:YourAccountId:GuardDutySqsQueueNameGoesHere"
12
            ]
13
        }
14
    ]
15
}

  1. Go to Users and create an IAM User. This user should have permissions to make receiveMessage and deleteMessage calls from the SQS queue. Learn more information about IAM in the AWS documentation.

    Store the Role ARN in a secure place for later use when configuring the AWS GuardDuty event source in InsightIDR.

Limit user access

Because this IAM User will have access to your data, it is recommended to limit access.

  1. Create an access key for the user.

    Store the users' access and secret key in a secure place for later use when configuring the AWS GuardDuty event source in InsightIDR.

  2. Attach the created IAM User to the IAM policy created in step 1.

Task 5: Set up encrypted SQS queue user permissions

Users need to have the relevant permissions that will allow them to access the queue created in Task 3: Set up the SQS queue.

If the SQS queue is encrypted, you must add the following JSON to the key policy created earlier in AWS Key Management Service. For more information on adding policy keys, see the AWS documentation.

Key Policy
1
{
2
  "Sid": "Allow use of the key",
3
  "Effect": "Allow",
4
  "Principal": 
5
    {"AWS": "arn:aws:iam::AWS ACCOUNT NUMBER:user/IAM USER NAME"}
6


7
,
8
 "Action": [
9
    "kms:Decrypt",
10
    "kms:GenerateDataKey"
11
  ],
12
  "Resource": "*"
13
 },
14
 {
15
"Sid": "Allow CWE to use the key",
16
  "Effect": "Allow",
17
"Principal": 
18
    {"Service": "events.amazonaws.com"}
19
 
20
,
21
"Action": [
22
  "kms:Decrypt",
23
    "kms:GenerateDataKey"
24
  ],
25
  "Resource": "*"
26
}

Task 6: Create an EventBridge Event rule

EventBridge takes events from AWS GuardDuty and moves them into the SQS queue that InsightIDR uses for its request calls.

  1. Go to Amazon EventBridge > Rules to create a new rule with the following event pattern. For more detailed instructions, see the AWS documentation
 
1
{
2
"source": ["aws.guardduty"],
3
"detail-type": ["GuardDuty Finding"]
4
}
  1. Under Targets, enter the SQS queue you previously created.

For troubleshooting information, see the Amazon EventBridge documentation.

Configure InsightIDR to collect data from the event source

After you complete the prerequisite steps and configure the event source to send data, you must add the event source in InsightIDR.

Task 1: Select GuardDuty

  1. Go to Data Collection and click Setup Event Source > Add Event Source.
  2. Do one of the following:
    • Search for AWS GuardDuty in the event sources search bar.
    • In the Product Type filter, select Third Party Alerts.
  3. Select the AWS GuardDuty event source tile.

Task 2: Set up your collection method

There are two methods of collecting data from AWS GuardDuty: through a cloud connection or through a collector.

New credentials are required for cloud event sources

You must create new credentials to create a cloud connection with this event source. You cannot reuse existing on-premise credentials.

Use the Collector method

To configure the new event source in InsightIDR:

  1. Select your collector.
  2. Select an event source type.
  3. Name your event source.
  4. Select if you want to send unparsed data.
  5. Select an AWS Authentication option.
  6. Select your AWS GuardDuty credentials, or optionally create a new credential. The credentials you enter will be the access key and secret key that corresponds to an AWS IAM User that has permissions to make receiveMessage and deleteMessage calls from the above SQS queue.
    • Access Key: the username you created with IAM permissions
    • Secret Key: the password you created that corresponds with the username with IAM permissions
  7. Enter the SQS Queue URL. This is visible when you select the queue in the AWS console. This will look similar to: https://sqs.us-east-1.amazonaws.com/your-queue-name.
  8. You can instead choose to use EC2 IAM Roles.
  9. Click Save.

Test the configuration

After you set up the configuration, when GuardDuty produces an alert, the alert will go to the SQS queue through EventBridge.

If you currently have no alerts and want to verify this, go to AWS Management Console > GuardDuty > Settings > Generate Sample Findings.

Delete sample messages before configuring this event source

Before you proceed, it is highly recommended that you manually delete these sample messages off of the queue because they will generate false alarms in the InsightIDR platform.

The event type that InsightIDR parses from this event source, for both methods, is GuardDuty Findings.

To test that event data is flowing into InsightIDR:

  1. From the Data Collection Management page, open the Event Sources tab.
  2. Find the event source you created and click View raw log. If the Raw Logs tab displays raw log entries, logs are successfully flowing to the Collector or Cloud connection.
  3. Wait approximately 7 minutes, then open Log Search.

Next, verify that log entries are appearing in Log Search:

  1. From the left menu, go to Log Search.
  2. In the Log Search filter panel, search for the event source you named in step 4 of Configure InsightIDR to collect data from the event source. GuardDuty logs should flow into this log set:
    • Third Party Alerts
  3. Select the log set and the logs within them.
  4. Set the time range to Last 10 minutes and click Run.

The Results table displays all events that flowed into InsightIDR in the last 10 minutes. The displayed keys and values are helpful when you want to build a query and search your logs.

Sample logs

In Log Search, the log that is generated uses the name of your event source by default. The log appears under the log set: Third Party Alerts.

Here is a typical raw log entry that is created by the event source:

GuardDuty Findings

 
1
{
2
  "version": "0",
3
  "id": "c8c4daa7-a20c-2f03-0070-b7393dd542ad",
4
  "detail-type": "GuardDuty Finding",
5
  "source": "aws.guardduty",
6
  "account": "123456789012",
7
  "time": "1970-01-01T00:00:00Z",
8
  "region": "us-east-1",
9
  "resources": [],
10
  "detail": {
11
    "schemaVersion": "2.0",
12
    "accountId": "123456789012",
13
    "region": "us-east-1",
14
    "partition": "aws",
15
    "id": "16afba5c5c43e07c9e3e5e2e544e95df",
16
    "arn": "arn:aws:guardduty:us-east-1:123456789012:detector/123456789012/finding/16afba5c5c43e07c9e3e5e2e544e95df",
17
    "type": "Canary:EC2/Stateless.IntegTest",
18
    "resource": {
19
      "resourceType": "Instance",
20
      "instanceDetails": {
21
        "instanceId": "i-05746eb48123455e0",
22
        "instanceType": "t2.micro",
23
        "launchTime": 1492735675000,
24
        "productCodes": [],
25
        "networkInterfaces": [{
26
          "ipv6Addresses": [],
27
          "privateDnsName": "ip-0-0-0-0.us-east-1.compute.internal",
28
          "privateIpAddress": "0.0.0.0",
29
          "privateIpAddresses": [{
30
            "privateDnsName": "ip-0-0-0-0.us-east-1.compute.internal",
31
            "privateIpAddress": "0.0.0.0"
32
          }],
33
          "subnetId": "subnet-d58b7123",
34
          "vpcId": "vpc-34865123",
35
          "securityGroups": [{
36
            "groupName": "launch-wizard-1",
37
            "groupId": "sg-9918a123"
38
          }],
39
          "publicDnsName": "ec2-11-111-111-1.us-east-1.compute.amazonaws.com",
40
          "publicIp": "11.111.111.1"
41
        }],
42
        "tags": [{
43
          "key": "Name",
44
          "value": "ssh-22-open"
45
        }],
46
        "instanceState": "running",
47
        "availabilityZone": "us-east-1b",
48
        "imageId": "ami-4836a123",
49
        "imageDescription": "Amazon Linux AMI 2017.03.0.20170417 x86_64 HVM GP2"
50
      }
51
    },
52
    "service": {
53
      "serviceName": "guardduty",
54
      "detectorId": "3caf4e0aaa46ce4ccbcef949a8785353",
55
      "action": {
56
        "actionType": "NETWORK_CONNECTION",
57
        "networkConnectionAction": {
58
          "connectionDirection": "OUTBOUND",
59
          "remoteIpDetails": {
60
            "ipAddressV4": "0.0.0.0",
61
            "organization": {
62
              "asn": -1,
63
              "isp": "GeneratedFindingISP",
64
              "org": "GeneratedFindingORG"
65
            },
66
            "country": {
67
              "countryName": "United States"
68
            },
69
            "city": {
70
              "cityName": "GeneratedFindingCityName"
71
            },
72
            "geoLocation": {
73
              "lat": 0,
74
              "lon": 0
75
            }
76
          },
77
          "remotePortDetails": {
78
            "port": 22,
79
            "portName": "SSH"
80
          },
81
          "localPortDetails": {
82
            "port": 2000,
83
            "portName": "Unknown"
84
          },
85
          "protocol": "TCP",
86
          "blocked": false
87
        }
88
      },
89
      "resourceRole": "TARGET",
90
      "additionalInfo": {
91
        "unusualProtocol": "UDP",
92
        "threatListName": "GeneratedFindingCustomerListName",
93
        "unusual": 22
94
      },
95
      "eventFirstSeen": "2017-10-31T23:16:23Z",
96
      "eventLastSeen": "2017-10-31T23:16:23Z",
97
      "archived": false,
98
      "count": 1
99
    },
100
    "severity": 5,
101
    "createdAt": "2017-10-31T23:16:23.824Z",
102
    "updatedAt": "2017-10-31T23:16:23.824Z",
103
    "title": "Canary:EC2/Stateless.IntegTest",
104
    "description": "Canary:EC2/Stateless.IntegTest"
105
  }
106
}