Merge pull request #2903 from 1seal/hardening/require-explicit-bootstrap

feat(ngclient): require explicit bootstrap argument

Author: jku

.github/scripts/conformance-client.py

@@ -27,6 +27,7 @@ def refresh(metadata_url: str, metadata_dir: str) -> None:
     updater = Updater(
         metadata_dir,
         metadata_url,
+        bootstrap=None,
     )
     updater.refresh()
     print(f"python-tuf test client: Refreshed metadata in {metadata_dir}")
@@ -46,6 +47,7 @@ def download_target(
         metadata_url,
         download_dir,
         target_base_url,
+        bootstrap=None,
     )
     target_info = updater.get_targetinfo(target_name)
     if not target_info:

docs/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+### Changed
+
+* ngclient: `Updater()` now requires an explicit `bootstrap` argument
+  * This is a breaking change: callers must pass `bootstrap=<root_bytes>` or `bootstrap=None`
+  * `bootstrap=None` explicitly opts into using cached `root.json` as trust anchor
+
 ## v6.0.0
 
 This release is not strictly speaking an API break from 5.1 but it does contain some

docs/INSTALLATION.rst

@@ -53,6 +53,39 @@ from GitHub, change into the project root directory, and install with pip
    python3 -m pip install -r requirements/dev.txt
 
 
+Application deployment
+----------------------
+
+The initial trusted root metadata (``root.json``) is the trust anchor for all
+subsequent metadata verification. Applications should deploy a trusted root
+with the application and provide it to :class:`tuf.ngclient.Updater`.
+
+Recommended storage locations for bootstrap root metadata include:
+
+* a system-wide read-only path (e.g. ``/usr/share/your-app/root.json``)
+* an application bundle with appropriate permissions
+* a read-only mounted volume in containerized deployments
+
+Not recommended:
+
+* ``metadata_dir`` (the metadata cache) since it is writable by design
+* user-writable install paths (e.g. a user site-packages directory)
+* any location writable by the account running the updater
+
+Example::
+
+   from tuf.ngclient import Updater
+
+   with open("/usr/share/your-app/root.json", "rb") as f:
+       bootstrap = f.read()
+
+   updater = Updater(
+       metadata_dir="/var/lib/your-app/tuf/metadata",
+       metadata_base_url="https://example.com/metadata/",
+       bootstrap=bootstrap,
+   )
+
+
 Verify release signatures
 -------------------------
 

examples/client/client

@@ -79,14 +79,15 @@ def download(base_url: str, target: str) -> bool:
     print(f"Using trusted root in {metadata_dir}")
 
     try:
-        # NOTE: initial root should be provided with ``bootstrap``  argument:
-        # This examples uses unsafe Trust-On-First-Use initialization so it is
-        # not possible here.
+        # NOTE: production deployments should provide embedded root metadata
+        # bytes via the ``bootstrap`` argument. This example uses Trust-On-First-Use
+        # initialization, so it explicitly opts into using cached root.json.
         updater = Updater(
             metadata_dir=metadata_dir,
             metadata_base_url=f"{base_url}/metadata/",
             target_base_url=f"{base_url}/targets/",
             target_dir=DOWNLOAD_DIR,
+            bootstrap=None,
         )
         updater.refresh()
 

examples/uploader/_localrepo.py

@@ -47,6 +47,7 @@ def __init__(self, metadata_dir: str, key_dir: str, base_url: str):
         self.updater = Updater(
             metadata_dir=metadata_dir,
             metadata_base_url=f"{base_url}/metadata/",
+            bootstrap=None,
         )
         self.updater.refresh()
 

tests/repository_simulator.py

@@ -36,8 +36,10 @@
     updater = Updater(
         dir,
         "https://example.com/metadata/",
+        dir,
         "https://example.com/targets/",
-        sim
+        sim,
+        bootstrap=sim.signed_roots[0],
     )
     updater.refresh()
 """

tests/test_updater_consistent_snapshot.py

@@ -74,10 +74,6 @@ def _init_repo(
         sim.publish_root()
         sim.prefix_targets_with_hash = prefix_targets
 
-        # Init trusted root with the latest consistent_snapshot
-        with open(os.path.join(self.metadata_dir, "root.json"), "bw") as f:
-            f.write(sim.signed_roots[-1])
-
         return sim
 
     def _init_updater(self) -> Updater:
@@ -88,6 +84,7 @@ def _init_updater(self) -> Updater:
             self.targets_dir,
             "https://example.com/targets/",
             self.sim,
+            bootstrap=self.sim.signed_roots[-1],
         )
 
     def _assert_metadata_files_exist(self, roles: Iterable[str]) -> None:

tests/test_updater_delegation_graphs.py

@@ -120,16 +120,13 @@ def _init_repo(self, test_case: DelegationsTestCase) -> None:
 
     def _init_updater(self) -> Updater:
         """Create a new Updater instance"""
-        # Init trusted root for Updater
-        with open(os.path.join(self.metadata_dir, "root.json"), "bw") as f:
-            f.write(self.sim.signed_roots[0])
-
         return Updater(
             self.metadata_dir,
             "https://example.com/metadata/",
             self.targets_dir,
             "https://example.com/targets/",
             self.sim,
+            bootstrap=self.sim.signed_roots[0],
         )
 
     def _assert_files_exist(self, roles: Iterable[str]) -> None:

tests/test_updater_fetch_target.py

@@ -40,10 +40,8 @@ def setUp(self) -> None:
         os.mkdir(self.metadata_dir)
         os.mkdir(self.targets_dir)
 
-        # Setup the repository, bootstrap client root.json
+        # Setup the repository
         self.sim = RepositorySimulator()
-        with open(os.path.join(self.metadata_dir, "root.json"), "bw") as f:
-            f.write(self.sim.signed_roots[0])
 
         if self.dump_dir is not None:
             # create test specific dump directory
@@ -65,6 +63,7 @@ def _init_updater(self) -> Updater:
             self.targets_dir,
             "https://example.com/targets/",
             self.sim,
+            bootstrap=self.sim.signed_roots[0],
         )
 
     targets = {

tests/test_updater_key_rotations.py

@@ -72,13 +72,12 @@ def _run_refresh(self) -> None:
 
         # bootstrap with initial root
         self.metadata_dir = tempfile.mkdtemp(dir=self.temp_dir.name)
-        with open(os.path.join(self.metadata_dir, "root.json"), "bw") as f:
-            f.write(self.sim.signed_roots[0])
 
         updater = Updater(
             self.metadata_dir,
             "https://example.com/metadata/",
             fetcher=self.sim,
+            bootstrap=self.sim.signed_roots[0],
         )
         updater.refresh()