Working with trusted IP lists and threat lists - Amazon GuardDuty
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
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Working with trusted IP lists and threat lists

Amazon GuardDuty monitors the security of your Amazon environment by analyzing and processing VPC Flow Logs, Amazon 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.

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.

GuardDuty can be configured to use the following types of lists.

Trusted IP list

Trusted IP lists consist of IP addresses that you have trusted for secure communication with your Amazon 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 Amazon account per Region.

Threat IP list

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 Amazon Web Services account per each Region.

Note

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.

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 Managing multiple accounts in Amazon GuardDuty.

List formats

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.

  • Plaintext (TXT)

    This format supports both CIDR block and individual IP addresses. The following sample list uses the Plaintext (TXT) format.

    192.0.2.0/24
198.51.100.1
203.0.113.1

  • Structured Threat Information Expression (STIX)

    This format supports both CIDR block and individual IP addresses. The following sample list uses the STIX format.

    <?xml version="1.0" encoding="UTF-8"?>
<stix:STIX_Package
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:stix="http://stix.mitre.org/stix-1"
    xmlns:stixCommon="http://stix.mitre.org/common-1"
    xmlns:ttp="http://stix.mitre.org/TTP-1"
    xmlns:cybox="http://cybox.mitre.org/cybox-2"
    xmlns:AddressObject="http://cybox.mitre.org/objects#AddressObject-2"
    xmlns:cyboxVocabs="http://cybox.mitre.org/default_vocabularies-2"
    xmlns:stixVocabs="http://stix.mitre.org/default_vocabularies-1"
    xmlns:example="http://example.com/"
    xsi:schemaLocation="
    http://stix.mitre.org/stix-1 http://stix.mitre.org/XMLSchema/core/1.2/stix_core.xsd
    http://stix.mitre.org/Campaign-1 http://stix.mitre.org/XMLSchema/campaign/1.2/campaign.xsd
    http://stix.mitre.org/Indicator-2 http://stix.mitre.org/XMLSchema/indicator/2.2/indicator.xsd
    http://stix.mitre.org/TTP-2 http://stix.mitre.org/XMLSchema/ttp/1.2/ttp.xsd
    http://stix.mitre.org/default_vocabularies-1 http://stix.mitre.org/XMLSchema/default_vocabularies/1.2.0/stix_default_vocabularies.xsd
    http://cybox.mitre.org/objects#AddressObject-2 http://cybox.mitre.org/XMLSchema/objects/Address/2.1/Address_Object.xsd"
    id="example:STIXPackage-a78fc4e3-df94-42dd-a074-6de62babfe16"
    version="1.2">
    <stix:Observables cybox_major_version="1" cybox_minor_version="1">
        <cybox:Observable id="example:observable-80b26f43-dc41-43ff-861d-19aff31e0236">
            <cybox:Object id="example:object-161a5438-1c26-4275-ba44-a35ba963c245">
                <cybox:Properties xsi:type="AddressObject:AddressObjectType" category="ipv4-addr">
                    <AddressObject:Address_Valuecondition="InclusiveBetween">192.0.2.0##comma##192.0.2.255</AddressObject:Address_Value>
                </cybox:Properties>
            </cybox:Object>
        </cybox:Observable>
        <cybox:Observable id="example:observable-b442b399-aea4-436f-bb34-b9ef6c5ed8ab">
            <cybox:Object id="example:object-b422417f-bf78-4b34-ba2d-de4b09590a6d">
                <cybox:Properties xsi:type="AddressObject:AddressObjectType" category="ipv4-addr">
                    <AddressObject:Address_Value>198.51.100.1</AddressObject:Address_Value>
                </cybox:Properties>
            </cybox:Object>
        </cybox:Observable>
        <cybox:Observable id="example:observable-1742fa06-8b5e-4449-9d89-6f9f32595784">
            <cybox:Object id="example:object-dc73b749-8a31-46be-803f-71df77565391">
                <cybox:Properties xsi:type="AddressObject:AddressObjectType" category="ipv4-addr">
                    <AddressObject:Address_Value>203.0.113.1</AddressObject:Address_Value>
                </cybox:Properties>
            </cybox:Object>
        </cybox:Observable>
    </stix:Observables>
</stix:STIX_Package>

  • Open Threat Exchange (OTX)TM CSV

    This format supports both CIDR block and individual IP addresses. The following sample list uses the OTXTM CSV format.

    Indicator type, Indicator, Description
CIDR, 192.0.2.0/24, example
IPv4, 198.51.100.1, example
IPv4, 203.0.113.1, example

  • 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 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"
    ],
    "Resource": "arn:aws-cn:iam::555555555555:role/aws-service-role/guardduty.amazonaws.com/AWSServiceRoleForAmazonGuardDuty"
}
Important

These actions are not included in the AmazonGuardDutyFullAccess managed policy.

Using server-side encryption for trusted IP lists and threat lists

GuardDuty supports the following encryption types for lists: SSE-AES256 and SSE-KMS. SSE-C is not supported. For more information on encryption types for S3 see Protecting data using server-side encryption.

If your list is encrypted using server-side encryption SSE-KMS you must grant the GuardDuty service-linked role AWSServiceRoleForAmazonGuardDuty permission to decrypt the file in order to activate the list. Add the following statement to the KMS key policy and replace the account ID with your own: 

{
    "Sid": "AllowGuardDutyServiceRole",
    "Effect": "Allow",
    "Principal": {
    "AWS": "arn:aws-cn:iam::123456789123:role/aws-service-role/guardduty.amazonaws.com/AWSServiceRoleForAmazonGuardDuty"
    },
    "Action": "kms:Decrypt*",
    "Resource": "*"
}

Adding and activating a trusted IP list or a threat IP list

Choose one of the following access methods to add and activate a trusted IP list or a threat IP list.

Console
(Optional) step 1: Fetching location URL of your list

  1. Open the Amazon S3 console at https://console.amazonaws.cn/s3/.

  2. In the navigation pane, choose Buckets.

  3. Choose the Amazon S3 bucket name that contains the specific list that you want to add.

  4. Choose the object (list) name to view its details.

  5. Under the Properties tab, copy the S3 URI for this object.

Step 2: Adding a trusted IP list or a threat list
Important

By default, at any given point in time, you can have only one trusted IP list. Similarly, you can have up to six threat lists.

  1. Open the GuardDuty console at https://console.amazonaws.cn/guardduty/.

  2. In the navigation pane, choose Lists.

  3. On the List management page, choose Add a trusted IP list or Add a threat list.

  4. Based on your selection, a dialog box will appear. Do the following steps:

    1. For List name, enter a name for your list.

      List naming constraints – The name of your list can include lowercase letters, uppercase letters, numbers, dash (-), and underscore (_).

    2. For Location, provide the location where you have uploaded your list. If you don't already have it, see Step 1: Fetching location URL of your list.

      Format of location URL

      • https://s3.amazonaws.com/bucket.name/file.txt

      • https://s3-aws-region.amazonaws.com/bucket.name/file.txt

      • http://bucket.s3.amazonaws.com/file.txt

      • http://bucket.s3-aws-region.amazonaws.com/file.txt

      • s3://bucket.name/file.txt

    3. Select the I agree check box.

    4. Choose Add list. By default, the Status of the added list is Inactive. For the list to be effective, you must activate the list.

Step 3: Activating a trusted IP list or a threat list

  1. Open the GuardDuty console at https://console.amazonaws.cn/guardduty/.

  2. In the navigation pane, choose Lists.

  3. On the List management page, select the list that you want to activate.

  4. Choose Actions, and then choose Activate. It may take up to 15 min for the list to be effective.

API/CLI
For trusted IP lists

  • Run CreateIPSet. Make sure to provide the detectorId of the member account for which you want to create this trusted IP list.

    List naming constraints – The name of your list can include lowercase letters, uppercase letters, numbers, dash (-), and underscore (_).

    • Alternatively, you can do this by running the following Amazon Command Line Interface command and make sure to replace the detector-id with the detector ID of the member account for which you will update the trusted IP list.

      aws guardduty create-ip-set --detector-id 12abc34d567e8fa901bc2d34e56789f0 --name AnyOrganization List --format Plaintext --location https://s3.amazonaws.com/DOC-EXAMPLE-BUCKET2/DOC-EXAMPLE-SOURCE-FILE.format --activate
For threat lists

  • Run CreateThreatIntelSet. Make sure to provide the detectorId of the member account for which you want to create this threat list.

    • ALternatively, you can do this by running the following Amazon Command Line Interface command. Make sure to provide the detectorId of the member account for which you want to create a threat list.

      aws guardduty create-threat-intel-set --detector-id 12abc34d567e8fa901bc2d34e56789f0 --name AnyOrganization List --format Plaintext --location https://s3.amazonaws.com/DOC-EXAMPLE-BUCKET2/DOC-EXAMPLE-SOURCE-FILE.format --activate
Note

After you activate or update any IP list, GuardDuty might take up to 15 minutes to sync the list.

Updating trusted IP lists and threat lists

You can update the name of a list or the IP addresses added to a list that has already been added and activated. If you update a list, you must activate it again for GuardDuty to use the latest version of the list.

Choose one of the access methods to update a trusted IP or threat list.

Console

  1. Open the GuardDuty console at https://console.amazonaws.cn/guardduty/.

  2. In the navigation pane, choose Lists.

  3. On the List management page, select the trusted IP set or a threat list that you want to update.

  4. Choose Actions, and then choose Edit.

  5. In the Update list dialog box, update the information as needed.

    List naming constraints – The name of your list can include lowercase letters, uppercase letters, numbers, dash (-), and underscore (_).

  6. Choose the I agree check box, and then choose Update list. The value in the Status column will change to Inactive.

  7. Reactivating the updated list

    1. On the List management page, select the list that you want to activate again.

    2. Choose Actions, and then choose Activate.

API/CLI

  1. Run UpdateIPSet to update a trusted IP list.

    • Alternatively, you can run the following Amazon CLI command to update a trusted IP list and make sure to replace the detector-id with the detector ID of the member account for which you will update the trusted IP list.

      aws guardduty update-ip-set --detector-id 12abc34d567e8fa901bc2d34e56789f0 --name AnyOrganization List --ip-set-id d4b94fc952d6912b8f3060768example --activate

  2. Run UpdateThreatIntelSet to update a threat list

    • Alternatively, you can run the following Amazon CLI command to update a threat list and make sure to replace the detector-id with the detector ID of the member account for which you will update the threat list.

      aws guardduty update-threatintel-set --detector-id 12abc34d567e8fa901bc2d34e56789f0 --name AnyOrganization List --threat-intel-set-id d4b94fc952d6912b8f3060768example --activate

De-activating or deleting a trusted IP list or threat list

Choose one of the access methods to delete (by using the console) or deactivate (by using API/CLI) a trusted IP list, or a threat list.

Console

  1. Open the GuardDuty console at https://console.amazonaws.cn/guardduty/.

  2. In the navigation pane, choose Lists.

  3. On the List management page, select the list that you want to delete.

  4. Choose Actions, and then choose Delete.

  5. Confirm the action and choose Delete. The specific list will no longer be available in the table.

API/CLI
  1. For a trusted IP list

    Run UpdateIPSet to update a trusted IP list.

    • Alternatively, you can run the following Amazon CLI command to update a trusted IP list and make sure to replace the detector-id with the detector ID of the member account for which you will update the trusted IP list.

      To find the detectorId for your account and current Region, see Settings page in the https://console.amazonaws.cn/guardduty/ console.

      aws guardduty update-ip-set --detector-id 12abc34d567e8fa901bc2d34e56789f0 --name AnyOrganization List --ip-set-id d4b94fc952d6912b8f3060768example --no-activate
  2. For a threat list

    Run UpdateThreatIntelSet to update a threat list

    • Alternatively, you can run the following Amazon CLI command to update a trusted IP list and make sure to replace the detector-id with the detector ID of the member account for which you will update the threat list.

      aws guardduty update-threatintel-set --detector-id 12abc34d567e8fa901bc2d34e56789f0 --name AnyOrganization List --threat-intel-set-id d4b94fc952d6912b8f3060768example --no-activate