Adding information on Python Language Client #333
Conversation
Signed-off-by: hayleycd <[email protected]>
Signed-off-by: hayleycd <[email protected]>
Signed-off-by: hayleycd <[email protected]>
✅ Deploy Preview for docssigstore ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
Signed-off-by: hayleycd <[email protected]>
Signed-off-by: hayleycd <[email protected]>
|
@hayleycd it looks like this is marked as a draft again, feel free to add me as a reviewer or @ me when you're ready for feedback. |
Signed-off-by: hayleycd <[email protected]>
Signed-off-by: hayleycd <[email protected]>
Signed-off-by: hayleycd <[email protected]>
| ### SLSA Provenance | ||
| This project emits a SLSA provenance on its release! This enables you to verify the integrity of the downloaded artifacts and ensured that the binary's code really comes from this source code. | ||
|
|
||
| To do so, please follow the instructions [here](https://github.com/slsa-framework/slsa-github-generator#verification-of-provenance). |
There was a problem hiding this comment.
I think this link is out of date (it's wrong in the sigstore-python readme too) - I think it's supposed to be https://github.com/slsa-framework/slsa-github-generator#verify-provenance
|
|
||
| This project emits a SLSA provenance on its release! This enables you to verify the integrity of the downloaded artifacts and ensured that the binary's code really comes from this source code. | ||
|
|
||
| To do so, please follow the instructions [here](https://github.com/slsa-framework/slsa-github-generator#verification-of-provenance). |
There was a problem hiding this comment.
I think this link is out of date (it's wrong in the sigstore-python readme too) - I think it's supposed to be https://github.com/slsa-framework/slsa-github-generator#verify-provenance
It's not very clear from the README, but I think this section about verifying provenance is more closely aligned with the installation section, since it's about verifying the sigstore-python release artifact, not about using it. But they also don't really explain how to find the artifact and attestation. I would almost suggest omitting this section entirely from the docs site because it's not really relevant unless you came across the repo in github and were exploring its release artifacts.
There was a problem hiding this comment.
My 0.02c is that this can be dropped entirely: the SLSA provenance note is a bit of a red herring in this context, since sigstore-python also emits bundles of its own creation as part of the release process.
(I would like to remove that SLSA provenance step from the release workflow entirely in the near future, since it doesn't currently generate valid SLSA documents - per slsa-framework/slsa-github-generator#3876 - and has been a source of release process breakdowns in the past. I'll likely replace it with GitHub's own attestation actions.)
There was a problem hiding this comment.
Agreed that this should be in installation.
I would add more details on how to verify the binary, and like Colleen said, where the attestation is (i.e. attached to the release). I'd provide a command using slsa-verifier demonstrating how to verify the provenance. Roughly:
- Download slsa-verifier
- Download the sigstore-python binary and attestation from a given release
slsa-verifier verify-artifact <path to binary> --provenance-path <path to attestation.intoto.jsonl> --source-uri github.com/sigstore/sigstore-python --source-tag <release tag>(double check this works)
Edit: Ignore in favor of the above comments
| ``` | ||
| <!-- @end-sigstore-verify-github-help@ --> | ||
|
|
||
| ## Advanced verification use cases |
There was a problem hiding this comment.
It looks like this section might be a bit out of date compared to the current README, I was looking for these sections and couldn't find them:
https://github.com/sigstore/sigstore-python/tree/main?tab=readme-ov-file#verifying-against-a-bundle (previously called "Verifying against a signature and certificate"?)
https://github.com/sigstore/sigstore-python/tree/main?tab=readme-ov-file#offline-verification
https://github.com/sigstore/sigstore-python/tree/main?tab=readme-ov-file#verifying-a-digest-instead-of-a-file
There was a problem hiding this comment.
Yeah, we're removing/deprioritizing these since detached material support is on the chopping block -- we're likely going to require bundles only with the next major release. sigstore/sigstore-python#1183 has some more context there 🙂
| jobs: | ||
| sigstore-python: | ||
| steps: | ||
| - uses: sigstore/[email protected] |
There was a problem hiding this comment.
This is referencing a really old version of the action -- is there a reason for that?
If not, I'd suggest the latest tag instead:
| - uses: sigstore/gh-action-sigstore-python@v0.2.0 | |
| - uses: sigstore/gh-action-sigstore-python@v3.0.0 |
There was a problem hiding this comment.
Oh, I see the ancient version is also in sigstore-python's README 🤦 -- I'll fix that.
| weight: 5 | ||
| --- | ||
|
|
||
| `sigstore` requires Python 3.8 or newer, and can be installed directly via `pip`: |
There was a problem hiding this comment.
Requires 3.9 as of release 3.4:
| `sigstore` requires Python 3.8 or newer, and can be installed directly via `pip`: | |
| `sigstore` requires Python 3.9 or newer, and can be installed directly via `pip`: |
There was a problem hiding this comment.
This looks like a verbatim (or close to verbatim) copy of the README, which makes me worry that it'll diverge/desync over time. Is there a way we can automatically keep it up to date?
If not, I suppose having a periodic reminder (or automatic issue trigger that runs on new sigstore-python releases) to periodically update these docs wouldn't be the worst thing.
(In particular, things like the <!-- @begin-sigstore-help@ --> blocks are tracked automatically by sigstore-python's own CI processes.)
There was a problem hiding this comment.
@woodruffw this is a good point. I originally intended to open a PR in the sigstore-python repo that removed repetition and linked to the docs on the main sigstore docs site. I am in conversation with the @haydentherapper and @cmurphy about this issue and may pivot towards most of the documentation staying in the sigstore-python repo and a a fairly lean page on the main sigstore docs which will link back to the repo's readme. Do you have a preference?
There was a problem hiding this comment.
No strong preference from me! If the plan is to have the main Sigstore site be the "global" source of documentation for all clients, then I'm happy to have the majority of the current sigstore-python README get deleted and live there instead.
OTOH the self-updating --help sections might be hard to track on the main Sigstore site. So those might make sense to leave in the repo's README while the rest moves to the Sigstore site.
There was a problem hiding this comment.
@woodruffw it sounds like @cmurphy and @haydentherapper are on board with a more abridged version on this site. It will mean that the information between the different language clients can be a little more uniform. I am going to close this PR for now and will tag you in the lighter PR that I am opening now. Thanks for your review and feedback!
Summary
Addresses #324
This PR brings documentation for the Python language client into the main sigstore docs. An overview of language clients is also included.