Skip to content

Entity List

Introduction

The EntityListMgr and EntityList classes of the entity_lists module allow you to manage and search Recorded Future lists. These lists can be Watch Lists or custom lists; they are specific to your organization and are the core foundation of Recorded Future alerts.

See the API Reference for internal details of the module.

Examples

Warning

The following examples demonstrate how to use this module. Be sure to add appropriate error handling as needed; all possible errors for each method or function are listed in the API Reference page.

Additionally, you must configure the RF_TOKEN environment variable before getting started. For instructions, see Learn.

1: Add a domain to your Domain Watch List using the Recorded Future ID

Tip

In a multi-organization enterprise, you need to find the Watch List of the sub‑org you need to access. You can do that by looking at the owner_name attribute of each EntityList object.

In this example, we start with the entity to add: idn:example.com. This syntax (idn:) identifies a Recorded Future entity ID for a domain (InternetDomainName).

We first use the EntityListMgr to find the list that we want to modify. The search method always returns a list of EntityList objects if at least one list is found; otherwise, it returns an empty list. Hence, we verify with an if statement whether the domain_watch_list variable has something inside. If it does, we extract the first element.

The domain_watch_list variable is an object of EntityList type, which allows us to add or remove entities from that specific list. We use the add method to add an entity. We know the Recorded Future ID, so we can directly pass it to the add method.

Once the entity has been added, we check that the result of the add operation is successful, and if it is, we list all the entities in the list with the entities method.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
from psengine.entity_lists import EntityListMgr

domain = 'idn:example.com'

mgr = EntityListMgr()
domain_watch_list = mgr.search(
    'Domain Watch List', 'domain'
)

if domain_watch_list:
    domain_watch_list = domain_watch_list[0]
    add_op = domain_watch_list.add(domain)

    if add_op.result == 'added':
        for entity in domain_watch_list.entities():
            print(entity)

    print(domain_watch_list.status())

The result after the print operation depends on the content of your list, but it will be similar to this:

1
2
InternetDomainName: reddit.com, added 2025-04-08 14:49:10
InternetDomainName: example.com, added 2025-08-27 07:04:31

As a last instruction, we print the status of the list. The status method shows the number of entities in the list and whether the add/remove operations previously done are completed. This is because add/remove operations might take a few minutes to be processed in the backend, so the list might not be in a ready state yet.

2: Add a domain to your Domain Watch List without using the Recorded Future ID

Tip

In a multi-organization enterprise, you need to find the Watch List of the sub‑org you need to access. You can do that by looking at the owner_name attribute of each EntityList object.

As in example 1, here we do not know the Recorded Future ID of the entity. Instead, we call the add method with a tuple containing the entity name (example2.com) and its type (InternetDomainName).

The method then uses EntityMatchMgr from the entity_match module to look up the ID.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
from psengine.entity_lists import EntityListMgr

domain = 'example2.com'

mgr = EntityListMgr()
domain_watch_list = mgr.search(
    'Domain Watch List', 'domain'
)

if domain_watch_list:
    domain_watch_list = domain_watch_list[0]
    add_op = domain_watch_list.add(
        (domain, 'InternetDomainName')
    )

    if add_op.result == 'added':
        for entity in domain_watch_list.entities():
            print(entity)

    print(domain_watch_list.status())

3: Remove domains in bulk from your Domain Watch List.

Tip

In a multi-organization enterprise, you need to find the Watch List of the sub‑org you need to access. You can do that by looking at the owner_name attribute of each EntityList object.

Similar to the previous examples, here we want to remove multiple domains. We use the bulk_remove method to do it.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
from psengine.entity_lists import EntityListMgr

domains = ['idn:example2.com', 'idn:reddit.com']

mgr = EntityListMgr()
domain_watch_list = mgr.search(
    'Domain Watch List', 'domain'
)

if domain_watch_list:
    domain_watch_list = domain_watch_list[0]
    remove_op = domain_watch_list.bulk_remove(
        [
            (domain, 'InternetDomainName')
            for domain in domains
        ]
    )

    print(remove_op)

The bulk operations return a dictionary that shows the result of each entity.

1
{'removed': [], 'unchanged': ['idn:example2.com', 'idn:reddit.com'], 'error': []}