setup-uv

The setup-uv GitHub Action operates within a specific security model involving several trust boundaries. Understanding these is critical for users configuring workflows:

Trust Boundaries

• Maintainers & GitHub Infrastructure: Trusted for source code, bundles, workflows, and the runner protocol. Compromise of these is considered an infrastructure issue, not a repository bug.
• Consumer Workflow Authors: Control the action reference, triggers, runner, permissions, secrets, and inputs. These are trusted choices unless they are derived from untrusted event data.
• Project/Checkout Content: When using setup-uv, the action trusts the selected checkout, project authors, and pull-request contributors. This includes project/version files (like uv.toml or pyproject.toml), discovered Python interpreters, virtual environments, and symlinks. Note: Running setup-uv on an untrusted checkout with higher authority is a consumer trust decision; code in the checkout may inherit the action's environment.
• Remote Metadata: Official endpoints and TLS roots are trusted. If you use a custom manifest, you authorize its URLs and hashes.
• Cache and Runner State: State produced by the same principal is trusted by default. However, lower-authority references may be able to read higher-authority caches, which can lead to confidentiality leaks.

Security Invariants

To ensure a secure setup, setup-uv adheres to these principles:

• Executable Identity: The precedence for determining which uv to run is: 1. Workflow version, 2. Version file, 3. Project configuration, 4. latest.
• Credential Protection: Tokens and URL credentials are restricted to workflow-authorized origins, redirects, paths, and logs.
• Path Isolation: Changes to paths, environments, or virtual environments are designed to affect only authorized targets.
• Cache Integrity: Cache keys and scopes are managed to prevent lower-to-higher authority poisoning and higher-to-lower authority disclosure.

The project uses a specific calibration for security findings based on the attack graph and incremental capability. Severity is determined by the threshold of impact and the prerequisite required for an attacker to succeed:

• Critical: A low-prerequisite remote/lower-authority attacker compromises default distribution, publishes malicious artifacts, or gains broad runner control under safe defaults.
• High: A demonstrated lower-authority input crosses a boundary (execution, confidentiality, integrity, or persistence) in a privileged job and gains substantial capability (e.g., cache poisoning in a write/OIDC job).
• Medium: A constrained crossing causes limited impact, such as reliable remote DoS, scoped persistence, or disclosure of a usable read-only private token.
• Low: A weak boundary causes narrow disclosure, log spoofing, or limited resource waste (e.g., bounded job failure).

The cache key is automatically computed to ensure compatibility and prevent issues like binary incompatibility when runner images change. It is composed of the following elements:

• Architecture: CPU architecture (e.g., x86_64, aarch64)
• Platform: OS platform type (e.g., unknown-linux-gnu, apple-darwin, pc-windows-msvc)
• OS version: OS name and version (e.g., ubuntu-22.04, macos-14)
• Python version: The Python version in use
• Cache options: Whether pruning and Python caching are enabled
• Dependency hash: Hash of files matching the cache-dependency-glob pattern
• Suffix: An optional cache-suffix if provided

The resulting key is available via the cache-key output of the setup-uv step.

- name: Setup uv
  id: setup-uv
  uses: astral-sh/setup-uv@v9.0.0
  with:
    enable-cache: true
- name: Print cache key
  run: echo "Cache key: ${{ steps.setup-uv.outputs.cache-key }}"

The setup-uv repository identifies several key attack surfaces related to its function as a setup action. Security is maintained through specific mitigations across these areas:

• Supply Chain: Protects against unauthorized changes to published bundles or dependencies by verifying source/bundle alignment, lockfile integrity, and immutable action pins.
• Version & Manifest Selection: Prevents malicious version or URL selection by enforcing documented precedence, rejecting malformed records, and verifying HTTPS and checksums.
• Artifact & Tool Handling: Mitigates risks in URL, token, and checksum handling by ensuring mirror fallbacks preserve identity, stripping authorization on redirects, and requiring independent hashes before extraction.
• Environment & Interpreter: Manages risks associated with PATH, virtual environments, and interpreters by delegating these to project authority while ensuring explicit workflow choices are bound.
• Caching: Protects GitHub uv/Python caches by partitioning keys (platform, interpreter, dependency) to prevent cross-job persistence or unauthorized data exposure.
• CI & Automation: Secures PR workflows and updaters by verifying effective permissions, fork behavior, and ensuring unreviewed code cannot gain write or secret authority.
• Availability: Protects against resource exhaustion (disk/memory) and log manipulation by enforcing bounds on manifest parsing and remote string expansion.