Fact Database

Aranya’s Fact Database (FactDB) is a key-value store that tracks the state of executed operations within the system. Each fact in the database is a key-value pair, called “fact”, that represents a piece of information relevant to the system’s operations. These facts can only be created, mutated, or deleted by a policy command, ensuring that the history of operations is preserved and auditable.

The FactDB works in conjunction with Aranya’s graph, which stores policy commands at its nodes. Together, the graph and FactDB form the storage module that the control plane relies on to keep track of previous executions, represent the current state, and assess the authorization of new executions. This setup enables Aranya to enforce policies and maintain a consistent and verifiable state across all peers in the network.

Fact Mutations

Executing a series of commands will produce a set of facts that depends on the order of execution. That is, if the commands are executed in a different order, they could result in a different set of facts. Hence, Aranya’s deterministic algorithm for ordering commands comes into play to ensure a consistent FactDB state across all syncronized devices, ultimately creating producing a reliable source of truth that can be used for policy evaluations.

Policy evaluation in Aranya relies on the set of facts stored in the FactDB to determine whether an operation defined by a command should be permitted to occur. If evaluation is successful, then the command gets fully executed and stored in the graph. Otherwise, the command may be either rejected or recalled. A command can only mutate the FactDB if it is either accepted or recalled. Rejected commands can never mutate the fact database and, thus, are never added to the graph nor executed.

Queries

Aranya provides a set of query APIs that allow a device to inspect the current state of the fact database. These APIs are useful for operations like querying for other devices that the current device knows about or query the roles for a specific device.

Useful Query API

• devices_on_team provides the application the ability to view a list of all devices current added to the team. This function only returns endpoints that the device knows about from the commands adding them to the team.
• device_role queries a specific device for its role. In order to use this endpoint, the caller needs to know the DeviceId of the target device.
• labels fetches a list of all labels that exist on the team (that the device knows about). There are other APIs for querying if specific labels exist.
• device_label_assignments

See the full list here

This functionality is also available in the C API, the main header file is available here.

How does the Query API work?

The query API utilizes “session commands” to retrieve data from the fact database. Session commands allow Aranya to execute a command and observe the effects of that command without adding it to the graph. Using this feature, specialized commands can be defined in the policy to access the data contained in specific facts. Additional information is available in the Aranya sessions note.