Skip to content

Risk History

Introduction

The risk_history module allows you to interact with the Recorded Future Risk API to retrieve the historical changes of an entity. The changes are determined by the risk score and risk rules mutations over time.

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: Display the risk score changes of two entities over time

In this example you start by fetching all the history for the last 20 days of two entities represented by their ID. To find the entity ID, if not known, you can use the Entity Match module, more information here. You then create a table of 4 columns, and a row for each risk change.

Before adding the data to the table, you convert the datetime values to string. You can use the TIMESTAMP_STR constant defined in psengine.constants.

To run this example, first add the rich package to your virtual environment:

1
pip install rich

Once installed the example can be executed. 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
from psengine.constants import TIMESTAMP_STR
from psengine.risk_history import RiskHistoryMgr
from rich.console import Console
from rich.table import Table

mgr = RiskHistoryMgr()

data = mgr.search(
    entities=['gVd1R', 'EJXkx'], from_='-20d', to='-1d'
)

console = Console()
table = Table(title='Score Summary')

table.add_column('Entity', justify='right')
table.add_column('Score', justify='right')
table.add_column('Added', justify='right')
table.add_column('Removed', justify='right')


table_data = []
for entity in data:
    for score in entity.scores:
        removed = (
            score.removed.strftime(TIMESTAMP_STR)
            if score.removed
            else 'Not removed'
        )
        table.add_row(
            entity.entity.name,
            str(score.score),
            score.added.strftime(TIMESTAMP_STR),
            removed,
        )


console.print(table)

The output of the example will be similar to:

1
2
3
4
5
6
7
8
9
┏━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┓
┃                   Entity ┃ Score ┃               Added ┃             Removed ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━┩
│ Red Hat Enterprise Linux │    10 │ 2025-09-16 16:30:56 │ 2025-09-27 16:14:20 │
│ Red Hat Enterprise Linux │    81 │ 2025-09-27 16:14:20 │         Not removed │
│                     Sudo │    72 │ 2025-09-19 16:08:43 │ 2025-09-30 02:18:45 │
│                     Sudo │    77 │ 2025-09-30 02:18:45 │ 2025-09-30 16:28:08 │
│                     Sudo │    82 │ 2025-09-30 16:28:08 │         Not removed │
└──────────────────────────┴───────┴─────────────────────┴─────────────────────┘