AWS guardduty documentation change
Summary
Major restructuring of GuardDuty list documentation to introduce entity lists (supporting IPs/domains) alongside legacy IP lists. Added details about list formats, statuses, migration paths, multi-account considerations, and expanded threat detection capabilities.
Security assessment
The changes enhance documentation about security features (custom threat detection lists) but do not address a specific disclosed vulnerability. Introduces entity lists as recommended approach with domain support, improving threat detection scope.
Diff
diff --git a/guardduty/latest/ug/guardduty_upload-lists.md b/guardduty/latest/ug/guardduty_upload-lists.md index 49ba44973..8847898f4 100644 --- a//guardduty/latest/ug/guardduty_upload-lists.md +++ b//guardduty/latest/ug/guardduty_upload-lists.md @@ -5 +5 @@ -List formatsPermissions required to upload trusted IP lists and threat listsUsing server-side encryption for trusted IP lists and threat listsAdding and activating a trusted IP list or a threat IP listUpdating trusted IP lists and threat listsDe-activating or deleting a trusted IP list or threat list +Understanding entity lists and IP address listsImportant considerations for GuardDuty listsList formatsUnderstanding list statuses @@ -7 +7 @@ List formatsPermissions required to upload trusted IP lists and threat listsUsin -# Working with trusted IP lists and threat lists +# Customizing threat detection with entity lists and IP address lists @@ -9 +9 @@ List formatsPermissions required to upload trusted IP lists and threat listsUsin -Amazon GuardDuty monitors the security of your AWS environment by analyzing and processing VPC Flow Logs, AWS CloudTrail event logs, and DNS logs. You can customize this monitoring scope by configuring GuardDuty to stop alerts for trusted IPs from your own _trusted IP lists_ and alert on known malicious IPs from your own _threat lists_. +Amazon GuardDuty monitors the security of your AWS environment by analyzing and processing VPC Flow Logs, AWS CloudTrail event logs, and DNS logs. By enabling one or more [Use-case focused GuardDuty protection plans](https://docs.aws.amazon.com/guardduty/latest/ug/what-is-guardduty.html#features-of-guardduty) (except [Runtime Monitoring](./runtime-monitoring.html), you can expand the monitoring capabilities within GuardDuty. @@ -11 +11 @@ Amazon GuardDuty monitors the security of your AWS environment by analyzing and -Trusted IP lists and threat lists apply only to traffic destined for publicly routable IP addresses. The effects of a list apply to all VPC Flow Log and CloudTrail findings, but do not apply to DNS findings. +With lists, GuardDuty helps you customize the scope of threat detection in your environment. You can configure GuardDuty to stop generating findings from your trusted sources and generate findings for known malicious sources from your threat lists. GuardDuty continues to support legacy IP address lists and extends support to entity lists (recommended) that can contain IP addresses, domains, or both. @@ -13 +13 @@ Trusted IP lists and threat lists apply only to traffic destined for publicly ro -GuardDuty can be configured to use the following types of lists. +###### Topics @@ -15 +15 @@ GuardDuty can be configured to use the following types of lists. -**Trusted IP list** + * Understanding entity lists and IP address lists @@ -16,0 +17 @@ GuardDuty can be configured to use the following types of lists. + * Important considerations for GuardDuty lists @@ -18 +19 @@ GuardDuty can be configured to use the following types of lists. -Trusted IP lists consist of IP addresses that you have trusted for secure communication with your AWS infrastructure and applications. GuardDuty does not generate VPC flow log or CloudTrail findings for IP addresses on trusted IP lists. You can include a maximum of 2000 IP addresses and CIDR ranges in a single trusted IP list. At any given time, you can have only one uploaded trusted IP list per AWS account per Region. + * List formats @@ -20 +21 @@ Trusted IP lists consist of IP addresses that you have trusted for secure commun -**Threat IP list** + * Understanding list statuses @@ -21,0 +23 @@ Trusted IP lists consist of IP addresses that you have trusted for secure commun + * [Setting up prerequisites for entity lists and IP address lists](./guardduty-lists-prerequisites.html) @@ -23 +25,22 @@ Trusted IP lists consist of IP addresses that you have trusted for secure commun -Threat lists consist of known malicious IP addresses. This list can be supplied by third-party threat intelligence or created specifically for your organization. In addition to generating findings because of a potentially suspicious activity, GuardDuty also generates findings based on these threat lists. You can include a maximum of 250,000 IP addresses and CIDR ranges in a single threat list. GuardDuty only generates findings based on an activity that involves IP addresses and CIDR ranges in your threat lists; the findings are not generated based on the domain names. At any given point in time, you can have up to six uploaded threat lists per AWS account per each Region. + * [Adding and activating an entity list or IP list](./guardduty-lists-create-activate.html) + + * [Updating an entity list or IP address list](./guardduty-lists-update-procedure.html) + + * [De-activating entity list or IP address list](./guardduty-lists-deactivate-procedure.html) + + * [Deleting entity list or IP address list](./guardduty-lists-delete-procedure.html) + + + + +## Understanding entity lists and IP address lists + +GuardDuty offers two implementation approaches: entity lists (recommended) and IP lists. Both approaches help you specify trusted sources, which stop GuardDuty from generate findings and known threats, which GuardDuty uses to generate findings. + +**Entity lists** support both IP addresses and domain names. They use direct Amazon Simple Storage Service (Amazon S3) access with a single IAM permission that doesn' impact IAM policy size limits across multiple Regions. + +**IP lists** support only IP addresses and use [GuardDuty service-linked role (SLR)](./slr-permissions.html) (SLR), requiring IAM policy updates per Region, which may impact IAM policy size limits. + +Trusted lists (both entity lists and IP address lists) include entries that you trust for secure communication with your AWS infrastructure. GuardDuty does not generate findings for entries listed in trusted sources. At any given time, you can add only one trusted entity list and one trusted IP address list per AWS account per Region. + +Threat lists (both entity lists and IP address lists) include entries that you have identified as known malicious sources. When GuardDuty detects an activity involving these sources, it generates findings to alert you of potential security issues. You can create your own threat lists or incorporate third-party threat intelligence feeds. This list can be supplied by third-party threat intelligence or created specifically for your organization. In addition to generating findings because of a potentially suspicious activity, GuardDuty also generates findings based on an activity that involves entries from your threat lists. At any given time, you can upload up to six threat entity lists and threat IP address lists per AWS account per Region. @@ -27 +50,27 @@ Threat lists consist of known malicious IP addresses. This list can be supplied -If you include the same IP on both a trusted IP list and threat list it will be processed by the trusted IP list first, and will not generate a finding. +To migrate from IP address lists to entity lists, follow [Prerequisites for entity lists](./guardduty-lists-prerequisites.html#guardduty-entity-list-prerequisites), then add and activate the required entity list. After this, you can choose to deactivate or delete the corresponding IP address list. + +## Important considerations for GuardDuty lists + +Before you begin working with lists, read the following considerations: + + * IP address lists and entity lists apply only to traffic destined for publicly routable IP addresses and domains. + + * In an entity list, the entries apply to CloudTrail, VPC Flow Logs in Amazon VPC, and Route53 Resolver DNS query logs findings. + +In an IP address list, the entries apply to CloudTrail and VPC Flow Logs in Amazon VPC findings, but not to Route53 Resolver DNS query logs findings. + + * If you include the same IP address or domain in both trusted and threat lists, then this entry in the trusted list will take precedence. GuardDuty will not generate a finding if there is an activity associated with this entry. + + * In a multi-account environment, only the GuardDuty administrator account can manage lists. This setting automatically applies to the member accounts. GuardDuty generates findings based on an activity that involves known malicious IP addresses (and domains) from the administrator account's threat sources, and doesn't generate findings based on activity that involves IP addresses (and domains) from the administrator account's trusted sources. For more information, see [Multiple accounts in Amazon GuardDuty](./guardduty_accounts.html). + + * Only IPv4 addresses are accepted. IPv6 addresses are not supported. + + * After you activate, deactivate, or delete an entity list or IP address list, the process is estimated to complete within 15 minutes. In certain scenarios, it may take up to 40 minutes for this process to complete. + + * GuardDuty uses a list for threat detection only when the status of the list becomes **Active**. + + * Whenever you add or update an entry in the list's S3 bucket location, you must activate the list again. For more information, see [Updating an entity list or IP address list](./guardduty-lists-update-procedure.html). + + * Entity lists and IP addresses have different quotas. For more information, see [GuardDuty quotas](./guardduty_limits.html). + + @@ -29 +77,0 @@ If you include the same IP on both a trusted IP list and threat list it will be -In multi-account environments, only users from GuardDuty administrator account accounts can add and manage trusted IP lists and threat lists. Trusted IP lists and threat lists that are uploaded by the administrator account account are imposed on GuardDuty functionality in its member accounts. In other words, in member accounts GuardDuty generates findings based on activity that involves known malicious IP addresses from the administrator account's threat lists and does not generate findings based on activity that involves IP addresses from the administrator account's trusted IP lists. For more information, see [Multiple accounts in Amazon GuardDuty](./guardduty_accounts.html). @@ -33 +81 @@ In multi-account environments, only users from GuardDuty administrator account a -GuardDuty accepts lists in the following formats. +GuardDuty accepts multiple file formats for your lists and entity lists, with a maximum of 35 MB per file. Each format has specific requirements and capabilities. @@ -35 +83 @@ GuardDuty accepts lists in the following formats. -The maximum size of each file that hosts your trusted IP list or threat IP list is 35MB. In your trusted IP lists and threat IP lists, IP addresses and CIDR ranges must appear one per line. Only IPv4 addresses are accepted. IPv6 addresses are not supported. +This format supports IP addresses, CIDR ranges, and domain names. Each entry must appear on a separate line. @@ -37 +85,10 @@ The maximum size of each file that hosts your trusted IP list or threat IP list - * Plaintext (TXT) +###### **Example for entity list** + + + 192.0.2.1 + 192.0.2.0/24 + example.com + example.org + *.example.org + +###### **Example for IP address list** @@ -39 +95,0 @@ The maximum size of each file that hosts your trusted IP list or threat IP list -This format supports both CIDR block and individual IP addresses. The following sample list uses the Plaintext (TXT) format. @@ -45 +101,37 @@ This format supports both CIDR block and individual IP addresses. The following - * Structured Threat Information Expression (STIX) +This format supports IP addresses, CIDR block, and domain names. STIX allows you to include additional context with your threat intelligence. GuardDuty processes IP addresses, CIDR ranges, and domain names from the STIX indicators. + +###### **Example for an entity list** + + + <?xml version="1.0" encoding="UTF-8"?> + <stix:STIX_Package + xmlns:cyboxCommon="http://cybox.mitre.org/common-2" + xmlns:cybox="http://cybox.mitre.org/cybox-2" + xmlns:cyboxVocabs="http://cybox.mitre.org/default_vocabularies-2" + xmlns:stix="http://stix.mitre.org/stix-1" + xmlns:indicator="http://stix.mitre.org/Indicator-2" + xmlns:stixCommon="http://stix.mitre.org/common-1" + xmlns:stixVocabs="http://stix.mitre.org/default_vocabularies-1" + xmlns:DomainNameObj="http://cybox.mitre.org/objects#DomainNameObject-1" + id="example:Package-a1b2c3d4-1111-2222-3333-444455556666" + version="1.2"> + <stix:Indicators> + <stix:Indicator + id="example:indicator-a1b2c3d4-aaaa-bbbb-cccc-ddddeeeeffff" + timestamp="2025-08-12T00:00:00Z" + xsi:type="indicator:IndicatorType" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> + <indicator:Title>Malicious domain observed Example</indicator:Title> + <indicator:Type xsi:type="stixVocabs:IndicatorTypeVocab-1.1">Domain Watchlist</indicator:Type> + <indicator:Observable id="example:Observable-0000-1111-2222-3333"> + <cybox:Object id="example:Object-0000-1111-2222-3333"> + <cybox:Properties xsi:type="DomainNameObj:DomainNameObjectType"> + <DomainNameObj:Value condition="Equals">bad.example.com</DomainNameObj:Value> + </cybox:Properties> + </cybox:Object> + </indicator:Observable> + </stix:Indicator> + </stix:Indicators> + </stix:STIX_Package> + +###### **Example for an IP address list** @@ -47 +138,0 @@ This format supports both CIDR block and individual IP addresses. The following -This format supports both CIDR block and individual IP addresses. The following sample list uses the STIX format. @@ -94 +185,3 @@ This format supports both CIDR block and individual IP addresses. The following - * Open Threat Exchange (OTX)TM CSV +This format supports CIDR block, individual IP addresses, and domains. This file format has comma-separated values. + +###### **Example for entity list** @@ -96 +188,0 @@ This format supports both CIDR block and individual IP addresses. The following -This format supports both CIDR block and individual IP addresses. The following sample list uses the `OTXTM` CSV format. @@ -101,0 +194 @@ This format supports both CIDR block and individual IP addresses. The following + Domain name, example.net, example @@ -103,83 +196 @@ This format supports both CIDR block and individual IP addresses. The following - * FireEyeTM iSIGHT Threat Intelligence CSV - -This format supports both CIDR block and individual IP addresses. The following sample list uses a `FireEyeTM` CSV format. - - reportId, title, threatScape, audience, intelligenceType, publishDate, reportLink, webLink, emailIdentifier, senderAddress, senderName, sourceDomain, sourceIp, subject, recipient, emailLanguage, fileName, fileSize, fuzzyHash, fileIdentifier, md5, sha1, sha256, description, fileType, packer, userAgent, registry, fileCompilationDateTime, filePath, asn, cidr, domain, domainTimeOfLookup, networkIdentifier, ip, port, protocol, registrantEmail, registrantName, networkType, url, malwareFamily, malwareFamilyId, actor, actorId, observationTime - - 01-00000001, Example, Test, Operational, threat, 1494944400, https://www.example.com/report/01-00000001, https://www.example.com/report/01-00000001, , , , , , , , , , , , , , , , , , , , , , , , 192.0.2.0/24, , , Related, , , , , , network, , Ursnif, 21a14673-0d94-46d3-89ab-8281a0466099, , , 1494944400 - - 01-00000002, Example, Test, Operational, threat, 1494944400, https://www.example.com/report/01-00000002, https://www.example.com/report/01-00000002, , , , , , , , , , , , , , , , , , , , , , , , , , , Related, 198.51.100.1, , , , , network, , Ursnif, 12ab7bc4-62ed-49fa-99e3-14b92afc41bf, , ,1494944400 - - 01-00000003, Example, Test, Operational, threat, 1494944400, https://www.example.com/report/01-00000003, https://www.example.com/report/01-00000003, , , , , , , , , , , , , , , , , , , , , , , , , , , Related, 203.0.113.1, , , , , network, , Ursnif, 8a78c3db-7bcb-40bc-a080-75bd35a2572d, , , 1494944400 - - * ProofpointTM ET Intelligence Feed CSV - -This format supports only individual IP addresses. The following sample list uses the `Proofpoint` CSV format. The `ports` parameter is optional. If you skip the port, ensure to leave a trailing comma (,) at the end. - - ip, category, score, first_seen, last_seen, ports (|) - 198.51.100.1, 1, 100, 2000-01-01, 2000-01-01, - 203.0.113.1, 1, 100, 2000-01-01, 2000-01-01, 80 - - * AlienVaultTM Reputation Feed - -This format supports only individual IP addresses. The following sample list uses the `AlienVault` format. - - 198.51.100.1#4#2#Malicious Host#US##0.0,0.0#3 - 203.0.113.1#4#2#Malicious Host#US##0.0,0.0#3 - - - - -## Permissions required to upload trusted IP lists and threat lists - -Various IAM identities require special permissions to work with trusted IP lists and threat lists in GuardDuty. An identity with the attached [AmazonGuardDutyFullAccess](./security-iam-awsmanpol.html#security-iam-awsmanpol-AmazonGuardDutyFullAccess) managed policy can only rename and deactivate uploaded trusted IP lists and threat lists. - -To grant various identities full access to working with trusted IP lists and threat lists (in addition to renaming and deactivating, this includes adding, activating, deleting, and updating the location or name of the lists), make sure that the following actions are present in the permissions policy attached to a user, group, or role: - - - { - "Effect": "Allow", - "Action": [ - "iam:PutRolePolicy", - "iam:DeleteRolePolicy"