Introducing the Frizbee GitHub Action to automate pinning actions and container images to digests
Frizbee is an open source command line utility that helps you automate pinning GitHub Actions and container images to their digests, to make your software projects more secure. We've created a Frizbee GitHub Action to make automation easier, and added new features to Frizbee.
We’re excited to release the latest version of Frizbee and a brand-new corresponding Frizbee GitHub Action. Frizbee is an open source project from Stacklok that helps you automate pinning your actions and container images to their digests (the former is a GitHub-recommended security best practice). In this post, we’ll walk through what’s new in Frizbee and what’s included in the Frizbee GitHub Action.
Why do you need to pin GitHub Actions and container images to their digests?
GitHub Actions, like open source dependencies, are vulnerable to attacks by hostile actors. Today, Actions are usually pinned to floating tags, which are mutable, meaning that the tags could be replaced at any time. This mutability poses a risk because a hostile actor who gains access to the action’s codebase could overwrite the tag with a malicious version of an image or action.
By contrast, digests, or checksums, uniquely reference a particular configuration. For example, for a container image, the digest is a unique identifier for the content of an image. Once an image is built, its digest will always refer to that specific build. The digest is immutable and cannot be changed, even if an attacker gains access to the repository. That’s why GitHub recommends pinning actions to digests vs. floating tags, because it’s a much more secure practice.
Unfortunately, this practice is not (yet) a very common one. Fabian Kammel at ControlPlane recently did some excellent analysis of public GitHub repositories and found that only 2% of repos using Actions are pinning them to full-length commit SHAs. While this research didn’t extend to pinning container image digests, with this data in mind, we could likely assume that the findings would be similar.
By pinning container images and GitHub Actions to their digests, you can guarantee that you're always using the exact version intended.
What is Frizbee, and how does it work?
One reason as to why actions and container images are usually pinned to floating tags is because it’s easier. Trying to fetch the checksum for every action referenced in your workflows gets tedious quickly. That’s where Frizbee comes in.
Frizbee is an open source command line utility that automates pinning GitHub Actions and container images to digests. We created Frizbee to remove the manual work involved with pinning actions to commit SHAs, and with figuring out what actions are being used in your project. Frizbee can scan your repository, find actions pinned to floating tags, and replace them with commit SHAs. It can also create an inventory of all of the actions used in your repository. For containers specifically, Frizbee can make sure that all of your Kubernetes manifests are referencing containers by their digest (another recommended security practice).
There are several ways you can use Frizbee:
Use Frizbee’s command line utility: Do frizbee actions on the root directory of your repository to parse all of your GitHub Action workflows and replace tags with the commit SHA
Use Frizbee’s new GitHub Action: Use Frizbee in your CI workflow
Use Frizbee’s API: Automate these tasks as part of your SDLC
Stacklok’s open source software supply chain security platform, Minder, includes a pre-configured policy that integrates with Frizbee’s API to perform these tasks. The benefit of using Minder here is that you can configure Frizbee and automatically enforce actions and container image pinning across all of your GitHub repositories, without doing any coding or API integration.
What's new in Frizbee’s latest CLI/API release
The latest release of Frizbee comes with several significant updates aimed at improving its functionality and user experience:
Improved design: The library code base is now grouped into two separate packages, one for parsing actions and another for parsing container images. This modular approach provides more maintainability and scalability.
Formatting preservation: An issue in which the formatting of the file was altered when replacing a reference has been fixed. Your files will now retain their original formatting.
Caching improvements: The caching mechanism for container images has been revamped to work per-instance of the replacer rather than per-operation, reducing overall API consumption and improving efficiency.
GitHub Actions via docker://: Support has been added for parsing GitHub Actions referenced by docker://, broadening the scope of actions Frizbee can manage.
Better CLI ergonomics: The command-line interface has been improved for better user experience.
More granular configuration: Frizbee can now be configured to skip pinning actions that are referred to by a branch name and not a tag. You can also list specific images or tags that should not be pinned. By default, Frizbee will not pin images that use the :latest tag or the scratch image.
Introducing the Frizbee GitHub Action
We’ve developed a new GitHub Action for Frizbee to make it easier to integrate Frizbee into your CI/CD pipelines. Here are the highlights of what this action can do, on top of Frizbee’s core capabilities:
Comprehensive file support: The action supports parsing GitHub Actions workflow files, Dockerfiles, and all YAML/YML files containing known container image references, such as docker-compose files and Kubernetes files.
Automated PRs: The action can open pull requests to suggest that repository owners pin their actions or container images. This automation helps maintain security best practices across your repositories.
Path configuration: The action can be configured to parse your entire repository, or only specific folders.
Getting Started with Frizbee
Both Frizbee and the Frizbee GitHub Action are open source. Frizbee is also designed to work across other source code management solutions, including GitLab and Bitbucket. If there are ways we can make these tools more helpful for you, please file an issue or feel free to open a pull request and contribute to them directly!
You can get started with Frizbee by visiting these GitHub repositories:
By pinning container images and GitHub Actions to their digests, you can mitigate significant risks and ensure the integrity of your CI/CD pipelines. We hope these tools can help you make your GitHub projects more secure!
Luke Hinds is the CTO of Stacklok. He is the creator of the open source project sigstore, which makes it easier for developers to sign and verify software artifacts. Prior to Stacklok, Luke was a distinguished engineer at Red Hat.
