[UI/UX support for attestations] RubyGems Audit

[nlhkabu]

Attestations on RubyGems

Summary

RubyGems effectively presents provenance information using a UI pattern similar to npm, providing verifiable links to the source code, build process, and a transparency log entry. However, unlike npm, RubyGems does not expose any warning states to help users understand if the details of a previously verified package have changed.

The primary opportunity for RubyGems is to restructure its documentation, including new sections targeted to users consuming packages (and attestations).

Attestations discoverability

Attestations are located at the bottom of a GemFile page.
Unlike both npm and PyPI, RubyGems does not expose the package readme in its UI, so this content is not pushed too far down the screen.

Attestations content

Attestations on RubyGems are diplayed using the similar pattern as on npm:

Left Side

• Build icon:
  • This provides a visual indicator that the information is about the build process of the package
• Built and signed on GitHub Actions:
  • This indicates the platform where the software was compiled/packaged and cryptographically signed.
• View build summary link
  • This links to the automated workflow (in this case GitHub actions) that produced the package

Right Side

Provides the verifiable links that tie the final package back to its origins:

• Source Commit:
  • This links to the exact version of the source code that was used for this build, identified by a unique Git commit hash (06cd267)
• Build File:
  • This is a link to the configuration file (.github/workflows/release.yml) that defined the build steps for GitHub Actions.
• Transparency log entry:
  • This links to the entry ID in Sigstore's public, immutable transparency log (Rekor). Anyone can use this ID to look up and verify that this attestation was recorded and has not been altered.
  • Note that unlike npm, RubyGems does not display a "Public Ledger" title next to the link to the Rekor log.

How users are likely to understand this interface

The Security Architect (Concerned / Informed)

• Likely to understand all fields
• Likely to appreciate the link to the "Transparency log entry", and probably click on it

The Pragmatic Developer (Somewhat Concerned / Informed)

• Likely to understand the "Source Commit" link
• Likely to understand "built and signed on" indicates the way the package was created and signed by an automated process.
• Unlikely to understand the significance of the Rekor log, nor click on it

The Incidental Consumer (Not Concerned / Not Informed)

• Likely to understand the term "Provenance", and therefore conceptually understand that the content below is about the origin/history of the package
• Likely to understand "built and signed on" indicates that the package was created and signed by an official process.
• May recognise "GitHub" as a common (and trustworthy) software tool
• Unlikely to understand "Source Commit," "Build File" or "Transparency Log Entry" nor click on any of the links

Other security features on RubyGems

Compared to PyPI and npm, RubyGems exposes fewer security signals within its UI.

• Does not highlight when the user is viewing an older version
• Does not "verify" package metadata in the sidebar
• Does not expose its workflow for reporting malware
• Does not expose package dependencies and dependents

RubyGem displays the package checksum directly above the attestation content:

Supporting Documentation

Attestations are not documented in the Security Practices documentation, nor is the security documentation linked to from the main Installing Gems content on the RubyGems basics page.

Security content is mixed throughout the RubyGems documentation, without a clear information architecture to guide users to essential information.

The guides would benefit from restructuring, including creating a new top-level "Gem Security" section to consolidate existing articles and add new attestations content, to help users understand and mitigate security risks.