GuardDuty API changes in March 2023 - Amazon GuardDuty
Features compared to data sourcesUnderstanding how APIs with features workIncorporating feature changes in APIsMapped GuardDuty feature

GuardDuty API changes in March 2023

The GuardDuty APIs configure protection features that don't belong to the list of GuardDuty foundational data sources. A feature object contains feature details, such as feature name and status, and may contain additional configuration for some of the protection plans. This migration affects the following APIs in the Amazon GuardDuty API Reference:

Features compared to data sources

Historically, all GuardDuty features were passed through a dataSources object in the API. From March 2023, GuardDuty prefers features object instead of the dataSources object in the API. All earlier data sources have corresponding features, but newer features may not have corresponding data sources.

The following list shows the comparison between dataSources and features object when passed through an API:

  • The dataSources object contains objects for each protection type and its status. The features object is a list of available features that correspond to each protection type within GuardDuty.

    Starting March 2023, feature activation will be the only way to configure new GuardDuty features in your AWS environment.

  • The dataSources schema in the API request or response is the same in each AWS Region where GuardDuty is available. However, every feature may not be available in each Region. Therefore, the available feature names may differ based on the Region.

Understanding how APIs with features work

The GuardDuty APIs will continue to return a dataSources object as applicable, and they will also return a features object containing the same information in a different format. GuardDuty features launched before March 2023 will be available through dataSources object and features object. GuardDuty launched features since March 2023 will only be available through the features object. You can't create or update a detector, or describe your AWS Organizations using both dataSources and features object notation in the same API request. To enable GuardDuty protection types, you will need to migrate your existing data sources to the features object by using the same APIs that now include the features object too.

Note

GuardDuty will not add new data source after this modification.

GuardDuty has deprecated the use of data sources that are associated with the protection plans. However, it still supports the GuardDuty foundational data sources. The GuardDuty best practices recommend using features for enabling or editing the configuration for any protection plan in your account.

Incorporating feature changes in APIs

  • If you manage GuardDuty configurations through APIs, SDKs, or AWS CloudFormation template, and want to enable potential new GuardDuty features, you will need to modify your code and template, respectively. For more information, see the updated APIs in the Amazon GuardDuty API Reference.

  • For GuardDuty features configured prior to this upgrade, you can continue using the APIs, SDKs, or AWS CloudFormation template. However, we recommend that you switch to using feature object.

    All the data sources have an equivalent feature object. For more information, see Mapping dataSources to features.

  • Presently, additionalConfiguration in the features object is only available for certain protection types.

Mapping dataSources to features

The following table shows the mapping of protection types, dataSources, and features.

GuardDuty protection type Data source name* Feature name

VPC Flow Logs

flowLogs (read only; can't be modified)

FLOW_LOGS (read only; can't be modified)

Route53 Resolver DNS query logs

dnsLogs (read only; can't be modified)

DNS_LOGS (read only; can't be modified)

CloudTrail events

cloudTrail (read only; can't be modified)

CLOUD_TRAIL (read only; can't be modified)

S3

s3Logs

S3_DATA_EVENTS

EKS Protection

kubernetes.auditlogs

EKS_AUDIT_LOGS

Malware Protection for EC2

malwareProtection.scanEc2InstanceWithFindings.ebsVolumes

EBS_MALWARE_PROTECTION

RDS Login events

GuardDuty provides only feature activation support for these protection types.

RDS_LOGIN_EVENTS

EKS Runtime Monitoring

EKS_RUNTIME_MONITORING

Runtime Monitoring

RUNTIME_MONITORING

GuardDuty security agent for Amazon EKS clusters

EKS_RUNTIME_MONITORING.additionalConfiguration.EKS_ADDON_MANAGEMENT

RUNTIME_MONITORING.additionalConfiguration.EKS_ADDON_MANAGEMENT

GuardDuty security agent for Amazon ECS-Fargate clusters

RUNTIME_MONITORING.additionalConfiguration.ECS_FARGATE_AGENT_MANAGEMENT

GuardDuty security agent for Amazon EC2 instances

RUNTIME_MONITORING.additionalConfiguration.EC2_AGENT_MANAGEMENT

Lambda Protection

LAMBDA_NETWORK_LOGS

*GetUsageStatistics uses its own dataSource names. For more information, see Estimating GuardDuty usage cost or GetUsageStatistics.