github.com/google/trillian-examples@v0.0.0-20240520080811-0d40d35cef0e/binary_transparency/firmware/cmd/ft_monitor/README.md (about)

     1  # FT Monitor
     2  
     3  ## Introduction
     4  FT Monitor is a tool to be used by actors with a verifying role in a Firmware Transparency world. Its main job is to closely observe the updates that happen in a Firmware Transparency Log, allowing the actor to flag any inappropriate behaviour by the log, or in the contents within it. For example, this role can be played by the Firmware Vendor who may decide to closely track the releases in a FT Log to monitor for unauthorized usage of their private key material. This same tool could also be used by an independent entity acting as a Verifier for the released firmware submission, which verifies all firmware releases for some kind of integrity (e.g. malware scanning).
     5  
     6  ## Monitor Verification
     7  
     8  Following are the sequence of actions that this example FT monitor performs in order to demonstrate a malware verifier: 
     9  
    10  * Monitor polls the FT log according to configured interval, to fetch latest checkpoint (i. e. most up to date index)  
    11  * It then fetches the consistency proof between its previous stored checkpoint and the new checkpoint (as above) and verifies
    12    locally that the head of the tree is consistent with previous head. 
    13  * It then iterates through each entry (from previously stored to latest checkpoint index) to fetch the Manifest statement (stored
    14    in the log) and its inclusion proof by querying the log. 
    15  * Decodes Firmware Hash from the Manifest statement
    16  * Fetches the firmware, using firmware hash as index from a separately stored Firmware Database, known as Content Addressable 
    17    Store (CAS).
    18  * Hashes the fetched Firmware Image to compare the same with the hash received from Manifest
    19  * Checks the Firmware Image for any Malware keyword mathces. If matches, can mark the annotation into the log indicating that the 
    20    found firmware is not good.
    21  * Once all the entries are verified as above, remembers the most up to date entry in a store (file as an example).
    22    This ensures that monitor has a golden checkpoint (reference) in order to follow one true evolution of the log (i.e. this `from` checkpoint is needed for consistency proofs). In addition to this, it also saves monitor from reverifying all the entries in case it needs a restart.
    23  
    24  
    25  ## Example Workflow
    26  
    27  Run the FT Monitor as indicated in the [Firmware Transparency](../../../firmware)
    28  
    29  ```bash
    30  # One can supply following optional arguments to control the various configuration parameters that are 
    31  # baked into the monitor operation.  
    32  1. Poll interval in seconds i. e. the time window when monitor wakes up to look for new entries in the log, example `--poll_interval=20`
    33  2. Keywords to look for the in the binary, example `--keyword=trojan`
    34  3. Add annotations to the log in addtion to local logging, example `--annotate=true`
    35  4. Persist Monitor state by supplying a file argument, example `--file_path=/tmp/mon_file.db`
    36  ```