This page documents the steps taken by the OpenEXR project to implement security policies recommended by GitHub and OpenSSF, offered here as a guide for other projects to follow.
- OSS-Fuzz - https://google.github.io/oss-fuzz/: probably the single best thing you can do to harden your project!
- You need a “fuzzer”, a simple program that reads input files. The files are generally small and the input random. The purpose is to ensure that your library rejects invalid input, so expect the unexpected. The fuzzing code lives in your repo’s test suite. The OpenEXR fuzzer is here: https://github.com/AcademySoftwareFoundation/openexr/tree/main/src/test/OpenEXRFuzzTest
- Follow the instructions at https://google.github.io/oss-fuzz/getting-started/ to create an account and register notification emails. You’ll submit a PR to https://github.com/google/oss-fuzz with a build script that builds the library and fuzzer in Google’s system. The OpenEXR setup is here: https://github.com/google/oss-fuzz/tree/master/projects/openexr
- You’ll get occasional emails with bug reports that include an input file that reproduces the issue (e.g. https://bugs.chromium.org/p/oss-fuzz/issues/detail?id=67239&q=openexr&can=41020642&sort=-reported)
- When a bug fix is committed, the issue at https://bugs.chromium.org is automatically closed.
- Issues are kept private, and you have 90 days to fix them before they’re made public. Our experience is that issues are generally easy to fix since you have a test case.
- Expect a flurry of emails to start but that should taper off quickly. Also expect occasional emails after a freshly-merged PR introduces a new bug.
- After they’re closed, the issues are made public, so release notes should mention which issues the release resolves (e.g. https://github.com/AcademySoftwareFoundation/openexr/releases/tag/v3.1.6). It’s convenient to mention the oss-fuzz issue in the comment of the PR that fixes it (e.g. https://github.com/AcademySoftwareFoundation/openexr/pull/1268)
- When a release goes out, edit the issues at https://bugs.chromium.org to note the release.
- Signed release tags: adds a level of assurance that release tags were made by project maintainers.
- Create a tag in advance of a release with the -s option, which associates a GPG key with it. (Don’t let the GitHub release process create the tag, you need to create the release from an already-created tag).
- Follow the instructions here: https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits
- Whoever does the signing needs to generate a GPG key for their GitHub account, described here: https://docs.github.com/en/authentication/managing-commit-signature-verification/generating-a-new-gpg-key
- Signed release artifacts: allows users to verify that downloaded source libraries have the expected contents.
- The process uploads <project>.tar.gz tarballs to the release page along with an associated signature. Users concerned about security download that rather than the standard GitHub download buttons (.tar.gz or .zip).
- Use this as a template: https://github.com/AcademySoftwareFoundation/openexr/blob/main/.github/workflows/release-sign.yml
- This uses Sigstore to manage the GPG keys, and its GitHub action does the signing. No further configuration is necessary!
- Mention the verification process in SECURITY.md
- Dependabot: keep GitHub actions up to date.
- Enable through GitHub settings
- It automatically files PRs to update GitHub actions when new versions are released.
- Set up StepSecurity on your repo: https://app.stepsecurity.io/securerepo
- This creates PRs that implement several security measures, primarily applying to GitHub Actions
- pin GitHub Action version to a specific SHA rather than a tag, since tags are technically mutable and vulnerable to tampering.
- Set permissions on jobs: read only at the top level, write only on specific jobs as necessary
- Adds a "Harden Runner" step that monitors jobs. Note that this does not work with the ASWF images, so skip them.
- This creates PRs that implement several security measures, primarily applying to GitHub Actions
- Security policy statement: SECURITY.md should list:
- Vulnerability notification process:
- security@<project>.com is good, but also consider recommending GitHub Security Advisories. OpenEXR once had someone email a vulnerability notice to security@openexr.com but their address was blocked by groups.io, so we never received it, leading them to file a public CVE.
- Enable GitHub security advisories through the Code Security and Analysis settings page
- Known vulnerabilities
- Supported versions and patching expectations
- Document the artifact signing process
- Security expectations
- State a policy that commits to addressing vulnerabilities within, say 14 days.
- Describe the nature of the project and what features could be potential attack vectors.
- Vulnerability notification process: