docs: update provenance tutorial #1110
Open
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
…ub attestation Signed-off-by: Ben Selwyn-Smith <[email protected]>
Signed-off-by: Ben Selwyn-Smith <[email protected]>
oracle-contributor-agreement
bot
added
the
OCA Verified
behnazh-w
reviewed
Jul 1, 2025
behnazh-w
reviewed
Jul 1, 2025
|
|
||
| For npm artifacts, Macaron makes use of available features provided by `npm <https://npmjs.com/>`_. Most importantly, npm allows developers to generate provenance files when publishing their artifacts. The `semver <https://www.npmjs.com/package/semver>`_ package is chosen as an example for this tutorial. | ||
| Currently, Macaron supports discovery of attestation for: npm artifacts using features provided by `npm <https://npmjs.com/>`_; PyPI artifacts using features provided by `Open Source Insights <https://deps.dev/>`_; and artifacts that have been published attestations to `GitHub <https://docs.github.com/en/rest/repos/repos?apiVersion=2022-11-28#list-attestations>`_. This tutorial uses two example packages to demonstrate these three discovery methods: The `semver <https://www.npmjs.com/package/semver>`_ npm package, and the `toga <https://pypi.org/pypi/toga>`_ PyPI package. |
There was a problem hiding this comment.
- We also support provenances published as release assets on GitHub. Please add that as well. You can use [email protected] which also has a CUE expectation.
- You should also mention that we support provenance files if they’re provided as input, as long as they use one of the supported
predicateTypeandbuildType(see the full list here). For reference, witness provenance is one supported example. You can find more details in the command-line options documentation. - I think it would be clearer to list the supported ecosystems as bullet points for better readability.
behnazh-w
reviewed
Jul 1, 2025
|
|
||
| In this particular case, the SHA256 hash of the toga 0.4.8 artifact is 0814a72abb0a9a5f22c32cc9479c55041ec30cdf4b12d73a0017aee58f9a1f00. A GitHub attestation can be found for this artifact `here <https://api.github.com/repos/beeware/toga/attestations/sha256:0814a72abb0a9a5f22c32cc9479c55041ec30cdf4b12d73a0017aee58f9a1f00>`_. | ||
|
|
||
| Attestation discovered through GitHub cannot be ascertained as verified at this time. However, we can still be sure that the repository URL and commit digest associated with the user provided PURL match what is found within the attestation. This is reported by Macaron in two checks: ``mcn_provenance_derived_repo_1`` and ``mcn_provenance_derived_commit_1``. |
There was a problem hiding this comment.
All attestations published on GitHub are signed, and their signatures are verified. Therefore, the verification check should pass for GitHub attestations, as long as we retrieve them directly from GitHub.
|
|
||
| ************************************** | ||
| Run ``verify-policy`` command (semver) | ||
| ************************************** | ||
|
|
||
| Another feature of Macaron is policy verification. This allows Macaron to report on whether an artifact meets the security requirements specified by the user. Policies are written using `Soufflé Datalog <https://souffle-lang.github.io/index.html>`_ , a language similar to SQL. Results collected by the ``analyze`` command can be checked via declarative queries in the created policy, which Macaron can then automatically check. |
There was a problem hiding this comment.
Suggested change
| Another feature of Macaron is policy verification. This allows Macaron to report on whether an artifact meets the security requirements specified by the user. Policies are written using `Soufflé Datalog <https://souffle-lang.github.io/index.html>`_ , a language similar to SQL. Results collected by the ``analyze`` command can be checked via declarative queries in the created policy, which Macaron can then automatically check. | |
| Another feature of Macaron is policy verification, which allows it to assess whether an artifact meets user-defined security requirements. This feature can also be integrated into CI/CD pipelines to automatically check policy compliance by returning appropriate error codes based on pass or fail status. Policies are written using `Soufflé Datalog <https://souffle-lang.github.io/index.html>`_ , a language similar to SQL. Results collected by the ``analyze`` command can be checked via declarative queries in the created policy, which Macaron can then automatically check. |
…test as tutorial; update tutorial wording; include tutorial sections for CI and local provenance; add input attestation predicate and build types Signed-off-by: Ben Selwyn-Smith <[email protected]>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
This PR updates the npm provenance discovery tutorial to include the newer discovery methods: PyPI and GitHub.
Description of changes
togaPyPI library, which has provenance of either type available for discovery depending on the exact version specified.7.7.2