# guardduty

Enables a GuardDuty detector and protection features in the current provider region, and optionally configures organization-wide member auto-enable. Run from the **delegated administrator account** only.

## Prerequisites

| Step | Module                    | Account      | Action                                                |
| ---- | ------------------------- | ------------ | ----------------------------------------------------- |
| 1    | `governance/organization` | Management   | `delegated_administrators["guardduty.amazonaws.com"]` |
| 2    | `governance/guardduty`    | Admin/Master | Detector + org features                               |

## Usage

```hcl
module "guardduty" {
  source = "hcassc.jfrog.io/iac-tf-modules-virtual__governance/guardduty/aws"
  version = "1.0.0"

  enable                       = true
  finding_publishing_frequency = "FIFTEEN_MINUTES"

  detector_features = {
    S3_DATA_EVENTS         = { status = "ENABLED" }
    EKS_AUDIT_LOGS         = { status = "ENABLED" }
    EBS_MALWARE_PROTECTION = { status = "ENABLED" }
    RDS_LOGIN_EVENTS       = { status = "DISABLED" }
    LAMBDA_NETWORK_LOGS    = { status = "DISABLED" }
    AI_PROTECTION          = { status = "DISABLED" }
    RUNTIME_MONITORING = {
      status = "ENABLED"
      additional_configuration = {
        EKS_ADDON_MANAGEMENT         = { status = "DISABLED" }
        ECS_FARGATE_AGENT_MANAGEMENT = { status = "DISABLED" }
        EC2_AGENT_MANAGEMENT         = { status = "DISABLED" }
      }
    }
  }

  detector_organization_configuration = {
    auto_enable_org_members = "NEW"
    features = {
      S3_DATA_EVENTS         = { auto_enable = "NONE" }
      EKS_AUDIT_LOGS         = { auto_enable = "NONE" }
      EBS_MALWARE_PROTECTION = { auto_enable = "NONE" }
      RDS_LOGIN_EVENTS       = { auto_enable = "NONE" }
      LAMBDA_NETWORK_LOGS    = { auto_enable = "NONE" }
      AI_PROTECTION          = { auto_enable = "NONE" }
      EKS_RUNTIME_MONITORING = { auto_enable = "NONE" }
      RUNTIME_MONITORING = {
        auto_enable = "NONE"
        additional_configuration = {
          EKS_ADDON_MANAGEMENT         = { auto_enable = "NONE" }
          ECS_FARGATE_AGENT_MANAGEMENT = { auto_enable = "NONE" }
          EC2_AGENT_MANAGEMENT         = { auto_enable = "NONE" }
        }
      }
    }
  }

  tags = {
    Environment = "prod"
    Team        = "AWS Infra"
  }
}
```

Set `detector_organization_configuration = null` to enable only the detector and its features without org-level config.

## Feature names

### `detector_features`

`S3_DATA_EVENTS`, `EKS_AUDIT_LOGS`, `EBS_MALWARE_PROTECTION`, `RDS_LOGIN_EVENTS`, `LAMBDA_NETWORK_LOGS`, `AI_PROTECTION`, `RUNTIME_MONITORING`, `EKS_RUNTIME_MONITORING`

Only one of `RUNTIME_MONITORING` or `EKS_RUNTIME_MONITORING` may be used — they are mutually exclusive.

Detector features use `ENABLED` / `DISABLED`.

### `detector_organization_configuration.features`

`S3_DATA_EVENTS`, `EKS_AUDIT_LOGS`, `EBS_MALWARE_PROTECTION`, `RDS_LOGIN_EVENTS`, `LAMBDA_NETWORK_LOGS`, `AI_PROTECTION`, `EKS_RUNTIME_MONITORING`, `RUNTIME_MONITORING`

Note: `AI_ANALYST` is not supported by the Terraform provider for org configuration features even though it appears in the AWS API — omit it.

Organization features use `ALL` / `NEW` / `NONE`.

## Runtime monitoring

Requires AWS provider **>= 6.0** — provider 5.x has a known issue ([#36400](https://github.com/hashicorp/terraform-provider-aws/issues/36400)) where `additional_configuration` block ordering causes perpetual replace on plan.

`RUNTIME_MONITORING` and `EKS_RUNTIME_MONITORING` are mutually exclusive. `RUNTIME_MONITORING` provides broader coverage (EC2, ECS, EKS) and is preferred.

Sub-options for `RUNTIME_MONITORING`:

- `EKS_ADDON_MANAGEMENT`
- `ECS_FARGATE_AGENT_MANAGEMENT`
- `EC2_AGENT_MANAGEMENT`

Sub-options for `EKS_RUNTIME_MONITORING`:

- `EKS_ADDON_MANAGEMENT`

<!-- BEGIN_TF_DOCS — DO NOT EDIT BELOW THIS LINE -->

## Requirements

| Name                                                                     | Version            |
| ------------------------------------------------------------------------ | ------------------ |
| <a name="requirement_terraform"></a> [terraform](#requirement_terraform) | >= 1.15.0, < 2.0.0 |
| <a name="requirement_aws"></a> [aws](#requirement_aws)                   | >= 6.0, < 7.0      |

## Providers

| Name                                             | Version       |
| ------------------------------------------------ | ------------- |
| <a name="provider_aws"></a> [aws](#provider_aws) | >= 6.0, < 7.0 |

## Resources

| Name                                                                                                                                                                              | Type     |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| [aws_guardduty_detector.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/guardduty_detector)                                                     | resource |
| [aws_guardduty_detector_feature.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/guardduty_detector_feature)                                     | resource |
| [aws_guardduty_organization_configuration.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/guardduty_organization_configuration)                 | resource |
| [aws_guardduty_organization_configuration_feature.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/guardduty_organization_configuration_feature) | resource |

## Inputs

| Name                                                                                                                                       | Description                                                                                                                                                     | Type                                                                                                                                                                                                                            | Default             | Required |
| ------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | :------: |
| <a name="input_detector_features"></a> [detector_features](#input_detector_features)                                                       | Detector protection features. Key = feature name, status = ENABLED or DISABLED. RUNTIME_MONITORING and EKS_RUNTIME_MONITORING support additional_configuration. | <pre>map(object({<br/> status = string<br/> additional_configuration = optional(map(object({<br/> status = string<br/> })), {})<br/> }))</pre>                                                                                  | n/a                 |   yes    |
| <a name="input_detector_organization_configuration"></a> [detector_organization_configuration](#input_detector_organization_configuration) | Organization-wide GuardDuty settings. Set to null to skip. auto_enable_org_members = ALL, NEW, or NONE.                                                         | <pre>object({<br/> auto_enable_org_members = string<br/> features = map(object({<br/> auto_enable = string<br/> additional_configuration = optional(map(object({<br/> auto_enable = string<br/> })), {})<br/> }))<br/> })</pre> | `null`              |    no    |
| <a name="input_enable"></a> [enable](#input_enable)                                                                                        | Enable or suspend the GuardDuty detector                                                                                                                        | `bool`                                                                                                                                                                                                                          | `true`              |    no    |
| <a name="input_finding_publishing_frequency"></a> [finding_publishing_frequency](#input_finding_publishing_frequency)                      | Frequency of findings export — FIFTEEN_MINUTES, ONE_HOUR, or SIX_HOURS                                                                                          | `string`                                                                                                                                                                                                                        | `"FIFTEEN_MINUTES"` |    no    |
| <a name="input_tags"></a> [tags](#input_tags)                                                                                              | Resource tags to apply to all resources                                                                                                                         | `map(string)`                                                                                                                                                                                                                   | `{}`                |    no    |

## Outputs

| Name                                                              | Description                |
| ----------------------------------------------------------------- | -------------------------- |
| <a name="output_account_id"></a> [account_id](#output_account_id) | Account ID of the detector |
| <a name="output_arn"></a> [arn](#output_arn)                      | GuardDuty detector ARN     |
| <a name="output_id"></a> [id](#output_id)                         | GuardDuty detector ID      |

<!-- END_TF_DOCS — DO NOT EDIT ABOVE THIS LINE -->