# GuardDuty

Collects security findings from AWS GuardDuty threat detection service to monitor malicious activity and unauthorized behavior across your AWS environment.

**Sync Type: Incremental**

## Details

AWS GuardDuty is a threat detection service that continuously monitors your AWS accounts and workloads for malicious activity. This input connector retrieves security findings from all GuardDuty detectors in your AWS account.

## Functionality

On initialization, Monad discovers all GuardDuty detectors in the specified region. For each detector, the connector retrieves findings and maintains state to ensure incremental updates on subsequent runs. Only new findings since the last sync are collected, minimizing duplicates and API calls.

## Requirements
- [IAM Role Assumption / Static Credentials](./index.mdx#authentication-methods)
- Example permission to attach to the role/user:
```json 
{
	"Version": "2012-10-17",
	"Statement": [
		{
			"Sid": "",
			"Effect": "Allow",
			"Action": [
				"guardduty:GetFindings",
				"guardduty:ListDetectors",
				"guardduty:ListFindings"
			],
			"Resource": "*"
		}
	]
}
```

## Configuration

The following configuration defines the input parameters. Each field's specifications, such as type, requirements, and descriptions, are detailed below.

#### Settings

| Setting  | Type   | Required | Description                                                                                                                                                     |
| -------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Region   | string | Yes      | The AWS region where GuardDuty is enabled.                                                                                                                      |
| Role ARN | string | Yes      | The ARN of the IAM role to assume for accessing GuardDuty.                                                                                                      |
| Severity | string | Yes      | Minimum severity level of findings to fetch. Accepts one value: `Critical`, `High`, `Medium`, or `Low`. All findings at this level and above will be collected. |
| Backfill Start Time | string | No | The date to start fetching data from. If not specified, no past records will be fetched. |

### Secrets (Static Credentials Only)

| Setting | Type | Required | Description |
|---------|------|----------|-------------|
| **Access Key** | string | Conditional | AWS Access Key ID |
| **Secret Key** | string | Conditional | AWS Secret Access Key |

> ⚠️ **Authentication**: Choose either Role ARN (recommended) or static credentials. See [AWS Authentication Guide](./index.mdx#authentication-methods) for setup instructions.

### Related Articles
- [AWS GuardDuty User Guide](https://docs.aws.amazon.com/guardduty/latest/ug/what-is-guardduty.html)
- [GuardDuty API Reference](https://docs.aws.amazon.com/guardduty/latest/APIReference/Welcome.html)

## Sample Record

```json
{
  "AccountId": "998877665544",
  "Arn": "arn:aws:guardduty:eu-west-1:998877665544:detector/c5087e90-cd82-2916-f70f-8cccceb44c69/finding/3d1268ce-a9f5-8fca-43ed-9fa26c0176d7",
  "AssociatedAttackSequenceArn": null,
  "Confidence": null,
  "CreatedAt": "2025-08-11T23:46:54.78859Z",
  "Description": "The user system:serviceaccount:deployment-system:deploy-controller has launched a Workload in an unusual way in namespace apps and cluster production-cluster.",
  "Id": "80b675a8-cb39-f3a1-c6b0-dce9acb3ac70",
  "Partition": "aws",
  "Region": "eu-west-1",
  "Resource": {
    "AccessKeyDetails": {
      "AccessKeyId": null,
      "PrincipalId": "",
      "UserName": null,
      "UserType": null
    },
    "ContainerDetails": null,
    "EbsVolumeDetails": null,
    "EcsClusterDetails": null,
    "EksClusterDetails": {
      "Arn": "arn:aws:eks:us-east-1:381492277049:cluster/test-cluster",
      "CreatedAt": "2025-08-11T23:46:54.78868Z",
      "Name": "staging-cluster",
      "Status": "UPDATING",
      "Tags": [
        {
          "Key": "Environment",
          "Value": "devops-team"
        }
      ],
      "VpcId": "vpc-7d1f8b8c-74e7-567b-18d2-ebfb9d65a06f"
    },
    "InstanceDetails": null,
    "KubernetesDetails": {
      "KubernetesUserDetails": {
        "Groups": [
          "system:authenticated",
          "system:serviceaccounts:ingress-system"
        ],
        "ImpersonatedUser": null,
        "SessionName": null,
        "Uid": "e65c4432-cb24-53a1-d90d-e4935db14191",
        "Username": "system:serviceaccount:deployment-system:deploy-controller"
      },
      "KubernetesWorkloadDetails": {
        "Containers": [
          {
            "ContainerRuntime": null,
            "Id": null,
            "Image": "quay.io/monitoring/prometheus:v1.0.0",
            "ImagePrefix": "quay.io/monitoring",
            "Name": "api-service-init",
            "SecurityContext": {
              "AllowPrivilegeEscalation": false,
              "Privileged": true
            },
            "VolumeMounts": []
          }
        ],
        "HostIPC": null,
        "HostNetwork": null,
        "HostPID": null,
        "Name": "config-loader",
        "Namespace": "services",
        "ServiceAccountName": "database",
        "Type": "deployments",
        "Uid": "f3e820e4-943d-db0b-7df8-d67ab7487330",
        "Volumes": []
      }
    },
    "LambdaDetails": null,
    "RdsDbInstanceDetails": null,
    "RdsDbUserDetails": null,
    "RdsLimitlessDbDetails": null,
    "ResourceType": "EKSCluster",
    "S3BucketDetails": null
  },
  "SchemaVersion": "2.0",
  "Service": {
    "Action": {
      "ActionType": "KUBERNETES_API_CALL",
      "AwsApiCallAction": null,
      "DnsRequestAction": null,
      "KubernetesApiCallAction": {
        "Namespace": "databases",
        "Parameters": null,
        "RemoteIpDetails": {
          "City": null,
          "Country": null,
          "GeoLocation": null,
          "IpAddressV4": null,
          "IpAddressV6": null,
          "Organization": null
        },
        "RequestUri": "/apis/batch/v1/namespaces/apps/pods/database-migration?fieldManager=metrics-controller",
        "Resource": "deployments",
        "ResourceName": "database-migration",
        "SourceIps": [
          "10.0.1.25"
        ],
        "StatusCode": 475,
        "Subresource": null,
        "UserAgent": "helm/v3.12.0",
        "Verb": "patch"
      },
      "KubernetesPermissionCheckedDetails": null,
      "KubernetesRoleBindingDetails": null,
      "KubernetesRoleDetails": null,
      "NetworkConnectionAction": null,
      "PortProbeAction": null,
      "RdsLoginAttemptAction": null
    },
    "AdditionalInfo": {
      "Type": "default",
      "Value": "{}"
    },
    "Archived": false,
    "Count": 9,
    "Detection": {
      "Anomaly": {
        "Profiles": {
          "account": {
            "api": [
              {
                "Observations": {
                  "Text": [
                    "update:deployments:null:success"
                  ]
                },
                "ProfileSubtype": "INFREQUENT",
                "ProfileType": "FREQUENCY"
              }
            ],
            "image": [
              {
                "Observations": {
                  "Text": [
                    "quay.io/monitoring/prometheus"
                  ]
                },
                "ProfileSubtype": "UNSEEN",
                "ProfileType": "FREQUENCY"
              }
            ],
            "namespace": [
              {
                "Observations": {
                  "Text": [
                    "monitoring"
                  ]
                },
                "ProfileSubtype": "RARE",
                "ProfileType": "FREQUENCY"
              }
            ]
          }
        },
        "Unusual": {
          "Behavior": {
            "account": {
              "api": {
                "Observations": {
                  "Text": [
                    "patch:jobs:null:success"
                  ]
                },
                "ProfileSubtype": "UNSEEN",
                "ProfileType": "FREQUENCY"
              },
              "image": {
                "Observations": {
                  "Text": [
                    "registry.company.com/web-app"
                  ]
                },
                "ProfileSubtype": "UNSEEN",
                "ProfileType": "FREQUENCY"
              },
              "serviceAccountName": {
                "Observations": {
                  "Text": [
                    "database"
                  ]
                },
                "ProfileSubtype": "UNSEEN",
                "ProfileType": "FREQUENCY"
              }
            }
          }
        }
      },
      "Sequence": null
    },
    "DetectorId": "f8d2f166-189c-6253-8ba2-08b73ac1a37e",
    "EbsVolumeScanDetails": null,
    "EventFirstSeen": "2025-08-11T23:46:54.789345Z",
    "EventLastSeen": "2025-08-11T23:46:54.789347Z",
    "Evidence": null,
    "FeatureName": null,
    "MalwareScanDetails": null,
    "ResourceRole": null,
    "RuntimeDetails": null,
    "ServiceName": "guardduty",
    "UserFeedback": null
  },
  "Severity": 1,
  "Title": "Anomalous container deployment detected in kubernetes environment.",
  "Type": "PrivilegeEscalation:Kubernetes/AnomalousServiceAccount",
  "UpdatedAt": "2025-08-11T23:46:54.789393Z"
}
```

## Sync frequency

By default this input polls approximately every 10 seconds, with each sync beginning after the previous one completes. A cron schedule configured on the pipeline overrides this cadence. See [Input Sync Frequency](../../guides/sync-frequency) for details.