[Technical Initiative Funding Request]: Sigstore Documentation Modernization

[haydentherapper]

Problem Statement

Sigstore's documentation is primarily focused on developer signing, which is misaligned with Sigstore's MVSR and adoption strategy, automated signing through CI providers/trusted publishing.

Additionally, the documentation only discusses Cosign as a Sigstore client, ignoring the many new language clients (e.g sigstore-python, -js, -java, -rs, -go). This documentation is particularly critical for package repository maintainers who are integrating Sigstore into their repositories. Cosign is best as a tool rather than as an API, and integration should be through the per-language clients which have properly designed APIs.

Furthermore, the documentation focused on how to use the tools but not how to consume the metadata produced. The documentation touches on how to verify but not the threat model, particularly the importance of identity checks.

The documentation for Fulcio and Rekor is a mix of developer-focused and user-focused documentation, and needs to be reviewed as it's out of date and restructured.

Private deployments are not discussed in our documentation but are referenced in a number of blog posts. Trying to predict every environment in which Sigstore will be deployed is too difficult, but our documentation should give some suggestions and advice on how to deploy infrastructure and how to configure clients to interact with those deployments. We can reference the existing blog posts ("local way", "hard way", "bash way", etc) along with discussing the scaffolding and helm charts we maintain. We are also lacking documentation on TUF in private deployments, and should include suggestions on how to deploy TUF repositories and consume trusted metadata in Sigstore clients.

Who does this affect?

This affects users of Sigstore and integrators, such as package repository maintainers, and developers who are adopting Sigstore into their tools and platforms.

Have there been previous attempts to resolve the problem?

We have modernized the documentation twice, funded through Google Season of Docs, which updated the website infrastructure, and from work from Google's Open Source Security team, which restructured the Cosign documentation.

Why should it be tackled now and by this TI?

Sigstore is now a graduated OpenSSF project and would like its documentation to reflect the maturity of the project. Additionally Sigstore is being integrated into package registries such as npm, Homebrew and PyPI. It is critical to the growth and adoption of the project to have clear and up-to-date documentation for developers integrating with Sigstore and for the end users of Sigstore.

Give an idea of what is required to make the funding initiative happen

We are requesting $50,000 for the initiative. The contractor will ramp up on Sigstore as part of onboarding.

What is going to be needed to deliver this funding initiative?

Funding a contractor to modernize documentation, and a set of Sigstore maintainers to review the documentation updates.

Are there tools or tech that still need to be produced to facilitate the funding initiative?

No.

Give a summary of the requirements that contextualize the costs of the funding initiative

Cost is for a contractor to ramp up on Sigstore and make significant documentation contributions.

Who is responsible for doing the work of this funding initiative?

Hayley Denbraver

Who is accountable for doing the work of this funding initiative?

Sigstore TSC & Community Chair & Contractor

If the responsible or accountable parties are no longer available, what is the backup contact or plan?

Someone from the Sigstore TSC will be accountable

Which technical initiative will this funding initiative be associated with, and will it report to which WG or project?

Sigstore, reporting to the OpenSSF TAC

What license is this funding initiative being used under?

Community Specification License 1.0

Code of Conduct

• [X] I agree to follow the OpenSSF's Code of Conduct

List the major milestones by date and identify the overall timeline within which the technical initiative plans to accomplish their goals. Any payments for services, sponsorships, etc., will require LF Legal and Financial review.

Milestones will include: 1) Onboarding onto Sigstore, 2) Restructuring the client documentation to focus on signing on CI platforms and verifying with CI identities, 3) updating the client documentation to include the additional Sigstore clients other than Cosign, 4) updating the end-to-end flow to stress the need for verification, 5) an update of the services documentation, 6) improving documentation around private deployments.

We estimate 12 months of work at 10 hours a week.

If this is a request for funding to issue a contract, then OpenSSF will issue that contract. Please provide a Statement of Work (SOW) that we may review. Any contracting action will take 4-6 weeks to issue.

TBD, will work with contractor and OpenSSF to create SoW.