[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

• 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.

[haydentherapper]

cc Sigstore TSC @bobcallaway @trevrosen @SantiagoTorres @lukehinds @priyawadhwa, who reviewed this proposal as well.

[sevansdell]

This sounds like an excellent use of TI funds, and I don't have any followup questions. I support this, and would do so in a TAC vote. I will be out for the TAC meeting June 11; this comment of support could be my support vote if needed.

[steiza]

I support this proposal.

This is a larger requests for funds than we've seen previously, but I think the impact is also large and the project is mature - both in terms of being a graduated TI, but also in terms of ecosystem adoption (npm provenance using Sigstore GA'd September 2023, Homebrew provenance using Sigstore went into beta May 2024). Several additional ecosystems have expressed interest in using Sigstore, and we know enterprises are using it internally as well.

[SecurityCRob]

I support this effort to help embiggen sigstore's docs which should help make it more clear and simpler for downstream consumers to evaluate and adopt sigstore.

[lehors]

Per the 11 June 2024 TAC call, this has been approved:
"6 yes (+2 offline), 0 no. Passes"
https://docs.google.com/document/d/1-zrtagRnPd75TDT1zRxrtxE9SpMIBJdPmaolaw4woQA/edit#heading=h.oagtpc4joqjt

[lehors]

This is reflected on the dashboard: https://github.com/orgs/ossf/projects/25

[hythloda]

Thanks for the TAC recommendation.

As documented in the TI Funding Process
For this level of funding the next step is the OpenSSF General Manager, @omkhar, or his delegate will review this proposal.

[haydentherapper]

Thanks all! Please let us know if there is any other information needed.

[hythloda]

Contract has been signed and work can begin.
All invoices need to be sent to us per the instructions for execution.

[haydentherapper]

Thanks everyone! We will be starting the work this week.

[haydentherapper]

Closing this issue as work is underway.