Registry / auth-security / tuf
library7.0.0pypypi✓ verified 86d ago

python-tuf is the Python reference implementation of The Update Framework (TUF), a framework for securing software update systems against various supply chain attacks. It provides APIs for both client-side artifact verification (`tuf.ngclient`) and repository-side metadata management (`tuf.api.metadata`). The library is actively maintained and currently at version 6.0.0, with a release cadence that addresses security fixes and implements new specification features.

pip install tuf
INSTALL
IMPORT
SIG · TUF
T
tuf
auth-securitypythonv7.0.0
Install
2.2s avg
Import
327ms
Disk
37MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v7.0.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.920 runs
installs and imports cleanly · install 0.0s · import 0.335s · 38.7MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 2.2s · import 0.319s · 39MB
37MB installed
● package 37MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Updater
from tuf.ngclient import Updater
Metadata
from tuf.api.metadata import Metadata
Used for low-level metadata object manipulation.
Root
from tuf.api.metadata import Root
Represents the Root metadata role object.
TargetFile
from tuf.api.metadata import TargetFile
Represents information about a target file.

This quickstart demonstrates how to initialize a TUF client (`tuf.ngclient.Updater`) to securely fetch and verify a target file from a TUF repository. It assumes a `root.json` file is available out-of-band for initial trust bootstrapping and that a repository is serving metadata and targets. For a runnable example, you would need to set up a dummy TUF repository (e.g., using `tuf.repository` utilities, though it's not stable API, or a dedicated repository service like RSTUF) and provide a valid initial `root.json`.

import os import shutil from pathlib import Path from tuf.ngclient import Updater # --- Configuration (replace with your actual repository details) --- REPO_METADATA_URL = os.environ.get('TUF_METADATA_URL', 'http://localhost:8000/metadata/') REPO_TARGETS_URL = os.environ.get('TUF_TARGETS_URL', 'http://localhost:8000/targets/') # Ensure a clean client state for demonstration LOCAL_CACHE_DIR = Path('./client_cache') LOCAL_DOWNLOAD_DIR = Path('./client_downloads') ROOT_METADATA_PATH = Path('./initial_root.json') if LOCAL_CACHE_DIR.exists(): shutil.rmtree(LOCAL_CACHE_DIR) if LOCAL_DOWNLOAD_DIR.exists(): shutil.rmtree(LOCAL_DOWNLOAD_DIR) LOCAL_CACHE_DIR.mkdir(parents=True, exist_ok=True) LOCAL_DOWNLOAD_DIR.mkdir(parents=True, exist_ok=True) # --- Simulate pre-packaged initial root metadata --- # In a real application, this 'root.json' would be securely bundled # with your application and stored in a read-only location. # For this example, let's create a dummy one if it doesn't exist. # You would typically copy a valid initial_root.json here. if not ROOT_METADATA_PATH.exists(): print("WARNING: Creating a dummy initial_root.json. " "In production, this file must be a trusted, pre-packaged root metadata.") with open(ROOT_METADATA_PATH, 'w') as f: f.write('{}') # Placeholder, will cause errors if not a real root. print(f"Initializing TUF Updater with metadata_url='{REPO_METADATA_URL}' and targets_url='{REPO_TARGETS_URL}'") print(f"Local cache: {LOCAL_CACHE_DIR}, Downloads: {LOCAL_DOWNLOAD_DIR}") try: # Initialize TUF Updater updater = Updater( repository_dir=str(LOCAL_CACHE_DIR), # Local directory for storing metadata metadata_base_url=REPO_METADATA_URL, target_base_url=REPO_TARGETS_URL, initial_root_metadata=ROOT_METADATA_PATH.read_bytes() # Bootstrap trust from bundled root ) # Refresh top-level metadata (root, timestamp, snapshot, targets) print("Refreshing top-level metadata...") updater.refresh() print("Metadata refreshed successfully.") # Get information about a target file TARGET_NAME = "example_target.txt" # Replace with an actual target name on your repo print(f"Getting target info for '{TARGET_NAME}'...") target_info = updater.get_targetinfo(TARGET_NAME) if target_info: print(f"Found target '{TARGET_NAME}' (size: {target_info.length} bytes, hashes: {target_info.hashes}).") # Download the target file target_path = LOCAL_DOWNLOAD_DIR / TARGET_NAME print(f"Downloading target to '{target_path}'...") updater.download_target(target_info, str(target_path)) print(f"Target '{TARGET_NAME}' downloaded and verified successfully!") else: print(f"Target '{TARGET_NAME}' not found or could not be verified.") except Exception as e: print(f"An error occurred: {e}") print("Please ensure a TUF repository is running at the configured URLs " "and that 'initial_root.json' is a valid, trusted root metadata file.")
Debug
Known issues
breakingAs of v6.0.0, `tuf.ngclient` uses `urllib3` as the default HTTP library instead of `requests`. This change removes implicit dependencies on `requests`, `idna`, `charset-normalizer`, and `certifi`.
fix
If you relied on `requests` being implicitly installed or want to continue using it, you must explicitly install `requests` and configure `Updater` to use the `RequestsFetcher` implementation. Otherwise, no action is needed for basic client usage.
affects: >=6.0.0
breakingtuf v5.0.0 introduced `securesystemslib v1.0.0` as a minimum requirement. This caused a minor break in the DSSE (Dead Simple Signing Envelope) API, particularly affecting users who directly depend on `securesystemslib`.
fix
Review the `securesystemslib` v1.0.0 release notes and `python-tuf` examples for updated DSSE API usage. The `ngclient` API was largely backwards-compatible for this change.
affects: >=5.0.0
breakingTUF v4.0.0 changed the API for `Metadata API` users, specifically `Root.get_verification_result()` and `Targets.get_verification_result()`.
fix
If directly interacting with these methods in `tuf.api.metadata`, consult the v4.0.0 changelog and documentation to adapt to the new method signatures.
affects: >=4.0.0
gotchaThe `tuf.repository` module is explicitly stated in the GitHub README as *not* being part of the `python-tuf` stable API.
fix
Avoid using `tuf.repository` in production systems where API stability is critical. Consider higher-level repository applications like RSTUF or `tuf-on-ci` for managing TUF repositories, or implement custom repository logic on top of `tuf.api.metadata`.
affects: All versions
gotchaThe initial trusted root metadata (`root.json`) is the critical trust anchor. It should be provided to the client application and stored in a *read-only* location to prevent tampering.
fix
Deploy `root.json` to system-wide read-only paths (e.g., `/usr/share/your-app/root.json`), application bundles, or read-only mounted volumes. Do *not* store it in the client's metadata cache directory as it is writable by design.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'requests'
Upgrading to `tuf` v6.0.0 without accounting for the switch from `requests` to `urllib3` as the default HTTP client for `ngclient`.
fix
If your application explicitly relies on the `RequestsFetcher` (which is now deprecated), install `requests` explicitly: `pip install requests`. Otherwise, `tuf.ngclient` will use `urllib3` by default.
RepositoryError: Local root.json is invalid.
The initial root metadata file provided to the `Updater` is malformed, corrupted, or not a valid TUF root metadata file.
fix
Ensure the `initial_root_metadata` argument to `Updater` (or the file path provided) points to a correctly formatted and trusted `root.json` file. Validate the JSON structure and its contents against the TUF specification.
Permission denied: '.../.sigstore/root.json'
The TUF client attempts to write or update metadata in a directory where the running user lacks write permissions, or the cached root metadata is in a read-only location.
fix
Ensure the `repository_dir` provided to `Updater` is writable by the user running the client. For the initial trusted `root.json`, store it in a securely managed, typically read-only, path and pass its content via `initial_root_metadata`.
ValueError: unrecognized metadata type "<UNKNOWN_TYPE>"
Attempting to load or parse a TUF metadata file (`root.json`, `targets.json`, etc.) with an invalid `_type` field within its signed payload, or a corrupted file.
fix
Verify the integrity and correctness of the metadata file. Ensure it conforms to the TUF specification for the respective role (e.g., `_type` should be 'root', 'targets', 'snapshot', or 'timestamp').
Upgrade
Version history
7.0.0latest on PyPI · released May 18, 2026
Audit
Dependencies
securesystemslibrequiredProvides core cryptographic routines; minimum v1.0.0 is required since tuf v5.0.0 for repository operations and full cryptographic capabilities.
urllib3requiredDefault HTTP library used by ngclient since v6.0.0.
requestsoptionalRequired only if explicitly using the deprecated RequestsFetcher for the ngclient.
Agent activity
20 hits · last 30 days
node
18
OpenAI (training)
1
Resources
tuf — pip install tuf · libregistry