Rules File

The rules file, besides the firmware itself, is one of the main drivers of EC. The rules file gives information about isolating the firmware and other metadata about the firmware that may not be easily inferrable by inspecting the firmware itself. Therefore, the main key element in the firmware is the firmware node, which contains all information about the given firmware. Support for multiple firmware is under development. The following list describes the different fields in the firmware node:

1. bc: The bitcode for the firmware.
2. symex_bc: The bitcode suitable for symbolic execution. Pieces support symbolic execution using KLEE, however, due to the limitation imposed by KLEE, we cannot use the same bitcode as used for compilation, as KLEE does not support inline assemblies. Pieces provides common runtimes, such as FreeRTOS, that can be used to minimize the complexity of firmware analysis. The full support for KLEE and RTOS integration is under development.
3. background_policy: Pieces support multiple policies for firmware compartmentalization. In other words, you can pick different policies for different components of the firmware. Background policy is the default policy of compartmentalization if a more specific policy is not described.
4. os: Pieces implement different heuristics to figure out the operating system used in the firmware. However, users can explicitly specify the OS used using this field. Several analyses, such as thread discovery, etc, use operating system information.
5. platform: Platform gives information about the platform for which the firmware is built. For instance, STMicro. This is a required field and is used to pick the correct SVD file.
6. svd: This field describes the SVD file for the particular variant of the platform. platform and svd are used in combination to find the correct SVD file. More information can be found here.
7. relaxed_pins: This configuration variable enables merging based on shared variables in pinned compartments (Look at cliques for pinned compartments).
8. cliques: As opposed to original EC paper, we soon realized using the same policy for the entire firmware may not lead to ideal compartmentalization. To this end, Pieces support multiple policies for firmware compartmentalization. If you want a different compartmentalization policy for some part of the firmware you can create a clique. Each clique node can have the following fields:
   1. name: Identifier for the clique
   2. policy: Compartmentalization policy for the clique. Policy for the clique.
   3. dir: Direcotry for which the clique is effective for.
   4. pins: Pins are a very strong compartmentalization concept. Pinned compartments are not affected by compartmentalization policies. All of the objects (functions and variables) in a pin are put in a separate compartment. Pins can effectively guide the compartmentalization process to achieve hand-picked compartments. The pins node may contain different key-values, where the key is the name of the pin and the value of the pin are the files you would want to place in that pinned compartment. YOu can have a list of files for a pin. The following line shows an example of pins.

    "pins" : {
        "pinned:memp_memory_UDP_PCB_base":["./Middlewares/Third_Party/LwIP/src/core/udp.c"],
        "pinned:memp_memory_TCP_SEG_base":["Middlewares/Third_Party/LwIP/src/core/tcp.c", "Middlewares/Third_Party/LwIP/src/core/tcp_out.c"]