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

     1  Verifiable Maps
     2  ===============
     3  
     4  The verifiable map in this firmware transparency demonstrates how annotations (also known as attestations) about a piece of firmware can be verifiably presented to clients.
     5  The naive way of doing this would be to simply give the client inclusion proofs to the annotations in the log.
     6  The problem with this approach is that there is no way to prove to the client that they have been presented *all* relevant annotations; logs do not support proofs of non-inclusion.
     7  
     8  The map is constructed *exclusively from the data in the log*, which means that the state of a map at a given size depends only on:
     9   * The number of entries it consumes from the log
    10   * The map and reduce functions that are applied to convert the log entries into map entries
    11  
    12  Map Checkpoints contain the Log Checkpoint they were constructed from, along with the number of entries the map consumed.
    13  The functions used in the map are deterministic, and public knowledge.
    14  These two facts mean that anybody with sufficient computing power to process the log can verify the map state by running the same map building calculation, and comparing root hashes.
    15  
    16  The map in this demonstration creates two types of entry in the map:
    17   * A log of all firmware for each device
    18   * For each logged piece of firmware, the aggregation of all corresponding annotations
    19  
    20  The first of these is a proof of concept and isn't currently read by clients (TODO(mhutchinson): remove this if needed for simplicity).
    21  The second of these is used as an additional check when flashing firmware to check that no scanners have found malware in it, if the `map_url` argument is provided to the flash tool.
    22  
    23  TODO(mhutchinson): make the map and reduce functions super clear in the code and refer to them from here.
    24  
    25  Preconditions
    26  -------------
    27  
    28  There are some pre-requisites to running this part of the demo:
    29   1. Have set up the environment and successfully run the [Trillian batchmap demo](https://github.com/google/trillian/tree/master/experimental/batchmap)
    30   2. Keep the Python Portable Beam Runner listening on port `8099`
    31   3. Have deployed the FT demo above using Docker, and have some firmware in there
    32  
    33  Example Workflow
    34  ----------------
    35  
    36  First add some good and bad firmware to the log, and then ensure the malware annotator has seen this and pushed its findings to the log.
    37  The workflow script in the README in the `firmware` directory does this, but if you're short on time the following is a minimum set of client calls:
    38  
    39  ```bash
    40  # Put a good piece of firmware in the log
    41  go run ./cmd/publisher/publish.go --logtostderr --v=2 --timestamp="2021-10-10T15:30:20.19Z" --binary_path=./testdata/firmware/dummy_device/example.wasm --output_path=/tmp/update.ota --device=dummy
    42  
    43  # Put a bad piece of firmware in the log
    44  go run ./cmd/publisher/publish.go --logtostderr --v=2 --timestamp="2020-10-10T23:00:00.00Z" --binary_path=./testdata/firmware/dummy_device/hacked.wasm --output_path=/tmp/bad_update.ota --device=dummy
    45  
    46  # Run the monitor to annotate
    47  go run ./cmd/ft_monitor/ --logtostderr --v=1 --keyword="H4x0r3d" --state_file=/tmp/ftmon.state --annotate
    48  ```
    49  
    50  Now generate the map from the log, storing the resulting data in a sqlite DB at ~/ftmap.db:
    51  
    52  * `go run ./cmd/ftmap --alsologtostderr --v=2 --runner=universal --endpoint=localhost:8099 --environment_type=LOOPBACK --map_db ~/ftmap.db --trillian_mysql="test:zaphod@tcp(127.0.0.1:3336)/test"`
    53  
    54  The map server can now be run to serve from this DB:
    55  
    56  * `go run ./cmd/ftmapserver --map_db ~/ftmap.db --alsologtostderr --v=1 &`
    57  
    58  The map server will now be running at `localhost:8001`. We can point the flash tool at this server to perform additional checks by passing `--map_url=http://localhost:8001` when flashing to the device, e.g:
    59  
    60  * `go run ./cmd/flash_tool/ --logtostderr --update_file=/tmp/update.ota --device_storage=/tmp/dummy_device --device=dummy --map_url=http://localhost:8001`
    61  
    62  After performing all of the other checks, this will verifiably read the aggregated findings for the candidate firmware from the map and check that no malware has been reported for it.