Amazon GuardDuty policy syntax and examples

Amazon GuardDuty policies follow a standardized JSON syntax that defines how GuardDuty is enabled and configured across your organization. A GuardDuty policy is a plaintext file structured according to the rules of JSON, and its syntax follows the syntax for all declarative policy types. For a complete discussion of that general syntax, see Understanding declarative policy inheritance. This topic applies that general syntax to the specific requirements of the GuardDuty policy type: it defines which features GuardDuty automatically enables, and in which Regions, for the organizational entities the policy is attached to.

Key considerations

Before creating GuardDuty policies, understand these key points about policy syntax:

• GuardDuty uses a default with Regional override model. The optional default block defines the baseline feature configuration applied to every Region where GuardDuty is available. Optional Region-specific blocks, keyed by Region name, apply to that Region only.

• A policy must contain at least one block (a default, a Region-specific block, or both).

• A Region-specific block fully replaces the default for that Region; it is not merged with it. List every feature you want in that Region, because any feature omitted from a Region block is not inherited from default.

• A Region that has neither a default block nor a Region-specific block is unmanaged. The policy neither enables nor disables GuardDuty there, and existing settings are left unchanged.

• Within any block, foundational must be enabled if any other feature in that same block is enabled.

• Each feature is set with a status of enabled or disabled. The runtime_monitoring feature additionally supports an additional_configuration object for its agent-management sub-features.

• Child policies set values using the @@assign inheritance operator. The authored form (for example {"status": {"@@assign": "enabled"}}) is distinct from the effective form returned by DescribeEffectivePolicy (which resolves to plain {"status": "enabled"}).

• Region names must be valid AWS Regions where GuardDuty is supported. A feature listed in a Region where it is not available is ignored for that Region.

Basic policy structure

A GuardDuty policy uses this basic structure:

{
  "guardduty": {
    "enablement": {
      "default": {
        "foundational": {
          "status": { "@@assign": "enabled" }
        }
      },
      "us-east-1": {
        "foundational": {
          "status": { "@@assign": "enabled" }
        },
        "runtime_monitoring": {
          "status": { "@@assign": "enabled" },
          "additional_configuration": {
            "ec2_agent_management": {
              "status": { "@@assign": "enabled" }
            }
          }
        }
      }
    }
  }
}

Policy components

GuardDuty policies contain these key components:

guardduty

The top-level key for GuardDuty policy documents.

Required for all GuardDuty policies.

enablement

Defines how GuardDuty is enabled across the organization.

Maps default or a Region name to a feature block.

Must contain at least one block.

default

Optional baseline feature block applied to every Region where GuardDuty is available.

<region-name> (for example us-east-1)

Optional Region-specific feature block that fully replaces the default for that Region.

status

Set on each feature to enabled or disabled.

additional_configuration

Optional object on runtime_monitoring for its agent-management sub-features, each with its own status.

Features

The following table lists the features you can manage in a GuardDuty policy. Each feature is optional, and foundational threat detection must be enabled whenever any other feature in the same block is enabled.

GuardDuty policy features

Feature	Key	Sub-features
Foundational threat detection	foundational	None
S3 protection	s3_data_events	None
EKS audit log monitoring	eks_audit_logs	None
EBS malware protection	ebs_malware_protection	None
RDS login activity monitoring	rds_login_events	None
Lambda network activity monitoring	lambda_network_logs	None
Runtime monitoring	runtime_monitoring	additional_configuration: eks_addon_management, ec2_agent_management, ecs_fargate_agent_management
GuardDuty AI protection	ai_protection	None

Note

Feature availability varies by Region and partition. A feature listed in a Region where it is not yet available has no effect in that Region.

Amazon GuardDuty policy examples

The following examples demonstrate common GuardDuty policy configurations.

Example 1: Enable GuardDuty organization-wide

The following policy enables foundational threat detection and S3 protection in every Region for all accounts, using a single default block. When attached to the organization root, all accounts automatically enable these GuardDuty features, and their findings are available to the GuardDuty delegated administrator. Any new account joining the organization inherits enablement automatically.

{
  "guardduty": {
    "enablement": {
      "default": {
        "foundational": {
          "status": { "@@assign": "enabled" }
        },
        "s3_data_events": {
          "status": { "@@assign": "enabled" }
        }
      }
    }
  }
}

Example 2: Override a specific Region

The following policy enables a broad feature set everywhere through default, but overrides us-east-1 to disable EBS malware protection there. Because a Region block fully replaces the default, the us-east-1 block re-lists every feature it wants active in that Region.

{
  "guardduty": {
    "enablement": {
      "default": {
        "foundational": {
          "status": { "@@assign": "enabled" }
        },
        "s3_data_events": {
          "status": { "@@assign": "enabled" }
        },
        "ebs_malware_protection": {
          "status": { "@@assign": "enabled" }
        }
      },
      "us-east-1": {
        "foundational": {
          "status": { "@@assign": "enabled" }
        },
        "s3_data_events": {
          "status": { "@@assign": "enabled" }
        },
        "ebs_malware_protection": {
          "status": { "@@assign": "disabled" }
        }
      }
    }
  }
}

When attached to an OU, all accounts in it get the default feature set in every Region except us-east-1, where EBS malware protection is disabled. Accounts outside the OU are unaffected.

Example 3: Enable runtime monitoring with sub-features

The runtime_monitoring feature supports an additional_configuration object for its agent-management sub-features. The following policy enables runtime monitoring with automated agent management for EKS, EC2, and Fargate.

{
  "guardduty": {
    "enablement": {
      "default": {
        "foundational": {
          "status": { "@@assign": "enabled" }
        },
        "runtime_monitoring": {
          "status": { "@@assign": "enabled" },
          "additional_configuration": {
            "eks_addon_management": {
              "status": { "@@assign": "enabled" }
            },
            "ec2_agent_management": {
              "status": { "@@assign": "enabled" }
            },
            "ecs_fargate_agent_management": {
              "status": { "@@assign": "enabled" }
            }
          }
        }
      }
    }
  }
}

When attached, all accounts in scope enable runtime monitoring and have GuardDuty manage the runtime agents automatically across the supported compute types.

Example 4: Manage specific Regions only, with no default

The default block is optional. The following policy omits it and configures only two Regions: us-east-1 and eu-west-1. Every other Region is left unmanaged; the policy neither enables nor disables GuardDuty there, and existing settings in those Regions are unchanged.

{
  "guardduty": {
    "enablement": {
      "us-east-1": {
        "foundational": {
          "status": { "@@assign": "enabled" }
        },
        "s3_data_events": {
          "status": { "@@assign": "enabled" }
        }
      },
      "eu-west-1": {
        "foundational": {
          "status": { "@@assign": "enabled" }
        }
      }
    }
  }
}

Because there is no default, only the two named Regions are managed. Use this pattern when you want a policy to govern GuardDuty in a specific set of Regions without asserting any baseline for the rest.