diff --git a/.github/workflows/cargo-vet-pr-comment.yml b/.github/workflows/cargo-vet-pr-comment.yml new file mode 100644 index 0000000..ba9caa4 --- /dev/null +++ b/.github/workflows/cargo-vet-pr-comment.yml @@ -0,0 +1,137 @@ +# This workflow triggers after cargo-vet workflow has run. +# It adds a comment to the PR with the results of the cargo vet run. +# It first adds a comment if the cargo vet run fails, +# and updates the comment if the cargo vet run succeeds after having failed at least once. + +name: Cargo vet PR comment + +on: + workflow_run: + workflows: [cargo-vet] + types: + - completed + +permissions: + contents: read + pull-requests: write + +concurrency: + group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }} + cancel-in-progress: true + +jobs: + + find-pr-comment: + # This job runs when the cargo-vet job fails or succeeds + # It will download the artifact from the failed job and post a comment on the PR + runs-on: ubuntu-latest + outputs: + comment-id: ${{ steps.get-comment-id.outputs.comment-id }} + pr-number: ${{ steps.get-pr-number.outputs.pr_number }} + if: github.event.workflow_run.event == 'pull_request' + steps: + - name: 'Download artifact' + uses: actions/download-artifact@v4 + with: + github-token: ${{ secrets.GITHUB_TOKEN }} + name: pr + path: pr/ + run-id: ${{ github.event.workflow_run.id }} + + - name: 'Get PR number' + id: get-pr-number + run: echo "pr_number=$(cat ./pr/NR)" >> $GITHUB_OUTPUT + + - name: 'Find existing comment' + id: find-comment + uses: peter-evans/find-comment@v3 + with: + issue-number: ${{ steps.get-pr-number.outputs.pr_number }} + comment-author: 'github-actions[bot]' + body-includes: 'comment-tag: [cargo-vet]' + + - name: 'Get comment ID' + id: get-comment-id + if: ${{ steps.find-comment.outputs.comment-id != '' }} + run: echo "comment-id=${{ steps.find-comment.outputs.comment-id }}" >> $GITHUB_OUTPUT + + post-comment-failure: + # This job runs when the cargo-vet job fails + # It will download the artifact from the failed job and post a comment on the PR + runs-on: ubuntu-latest + needs: find-pr-comment + if: github.event.workflow_run.conclusion == 'failure' + steps: + - name: 'Comment on PR - Failure' + uses: peter-evans/create-or-update-comment@v4 + with: + comment-id: ${{ needs.find-pr-comment.outputs.comment-id }} + issue-number: ${{ needs.find-pr-comment.outputs.pr-number }} + body: | + # Cargo Vet Audit Failed + + `cargo vet` has failed in this PR. Please run `cargo vet --locked` locally to check for new or updated unvetted dependencies. + Details about the vetting process can be found in [supply-chain/README.md](../blob/main/supply-chain/README.md) + + ## If the unvetted dependencies are not needed + Please modify Cargo.toml file to avoid including the dependencies. + + ## If the unvetted dependencies are needed + Post a new comment with the questionnaire below to the PR to help the auditors vet the dependencies. + After the auditors have vetted the dependencies, the PR will need to be rebased to pick up the new audits and pass this check. + + ### Copy and paste the questionnaire as a new comment and provide your answers: + + **1. What crates (with version) need to be audited?** + + **2. How many of the crates are version updates vs new dependencies?** + + **3. To confirm none of the already included crates serve your needs, please provide a brief description of the purpose of the new crates.** + + **4. Any extra notes to the auditors to help with their audits.** + + + edit-mode: replace + + - name: 'Label PR' + uses: actions/github-script@v7 + with: + script: | + github.rest.issues.addLabels({ + issue_number: ${{ needs.find-pr-comment.outputs.pr-number }}, + owner: context.repo.owner, + repo: context.repo.repo, + labels: ['cargo vet'] + }) + + post-comment-success: + # This job runs when the cargo-vet job succeeds + # It will update the comment on the PR with a success message + runs-on: ubuntu-latest + needs: find-pr-comment + if: github.event.workflow_run.conclusion == 'success' + steps: + - name: 'Comment on PR - Success' + # Only update the comment if it exists + # This is to avoid creating a new comment if the cargo-vet job has never failed before + if: ${{ needs.find-pr-comment.outputs.comment-id }} + uses: peter-evans/create-or-update-comment@v4 + with: + comment-id: ${{ needs.find-pr-comment.outputs.comment-id }} + issue-number: ${{ needs.find-pr-comment.outputs.pr-number }} + body: | + # Cargo Vet Audit Passed + `cargo vet` has passed in this PR. No new unvetted dependencies were found. + + + edit-mode: replace diff --git a/.github/workflows/cargo-vet.yml b/.github/workflows/cargo-vet.yml new file mode 100644 index 0000000..8d825aa --- /dev/null +++ b/.github/workflows/cargo-vet.yml @@ -0,0 +1,53 @@ +# This workflow runs whenever a PR is opened or updated. It runs cargo vet to check for unvetted dependencies in the Cargo.lock file. +permissions: + contents: read +on: + pull_request: + +concurrency: + group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }} + cancel-in-progress: true + +name: cargo-vet +jobs: + vet: + # cargo-vet checks for unvetted dependencies in the Cargo.lock file + # This is to ensure that new dependencies are vetted before they are added to the project + name: vet-dependencies + runs-on: ubuntu-latest + env: + CARGO_VET_VERSION: 0.10.1 + + steps: + - uses: actions/checkout@v4 + with: + submodules: true + + - uses: actions/cache@v4 + with: + path: ${{ runner.tool_cache }}/cargo-vet + key: cargo-vet-bin-${{ env.CARGO_VET_VERSION }} + + - name: Add the tool cache directory to the search path + run: echo "${{ runner.tool_cache }}/cargo-vet/bin" >> $GITHUB_PATH + + - name: Ensure that the tool cache is populated with the cargo-vet binary + run: cargo install --root ${{ runner.tool_cache }}/cargo-vet --version ${{ env.CARGO_VET_VERSION }} cargo-vet + + - name: Invoke cargo-vet + run: cargo vet --locked + + - name: Save PR number + # PR number is saved as an artifact so it can be used to determine the PR to comment on by the vet-pr-comment workflow + # vet-pr-comment workflow is triggered by the workflow_run event so it runs in the context of the base branch and not the PR branch + if: ${{ failure() }} || ${{ success() }} + run: | + mkdir -p ./pr + echo ${{ github.event.number }} > ./pr/NR + - uses: actions/upload-artifact@v4 + # Need to upload the artifact in both success and failure cases so comment can be updated in either case + if: ${{ failure() }} || ${{ success() }} + with: + name: pr + path: pr/ + overwrite: true diff --git a/supply-chain/README.md b/supply-chain/README.md new file mode 100644 index 0000000..07d41ff --- /dev/null +++ b/supply-chain/README.md @@ -0,0 +1,83 @@ +# Working with cargo vet + +## Introduction + +`cargo vet` is a tool to help ensure that third-party Rust dependencies have been audited by a trusted entity. +It matches all dependencies against a set of audits conducted by the authors of the project or entities they trust. +To learn more, visit [mozilla/cargo-vet](https://github.com/mozilla/cargo-vet) + +--- + +## Adding a new dependency + +When updating or adding a new dependency, we need to ensure it's audited before being merged into main. +For our repositories, we have designated experts who are responsible for vetting any new dependencies being added to their repository. +_It is the shared responsibility of the developer creating the PR and the auditors to conduct a successful audit._ +Follow the process below to ensure compliance: + +### For Developers +1. **Respond to `cargo vet` failures**: + - If your PR fails the `cargo vet` step, the cargo-vet workflow will add a comment to the PR with a template questionnaire + - Copy the questionnaire, fill it out and paste it as a new comment on the PR. This greatly helps the auditors get some context of the changes requiring the new dependencies + +2. **Engage with auditors**: + - Respond to any questions that the auditors might have regarding the need of any new dependencies + +3. **Rebase and verify**: + - At their discretion, auditors will check in their audits into either [rust-crate-audits](https://github.com/OpenDevicePartnership/rust-crate-audits) or into the same repository + - Once the new audits have been merged, rebase your branch on main and verify it passes `cargo vet` + ```bash + git fetch upstream + git rebase upstream/main + cargo vet + ``` + +4. **Update PR**: + - If the audits were checked into rust-crate-audits, they will show up in _imports.lock_ on running `cargo vet`. In this case add the updated _imports.lock_ to your PR + - If the audits were checked into the same repository, they will be present in _audits.toml_ after rebase and you can simply force push to your PR after rebase + ```bash + git push -f + ``` + +5. **Check PR status**: + - The existing PR comment from the previous failure will be updated with a success message once the check passes + +### For Auditors + +1. **Review the questionnaire**: + - Check the filled questionnaire on the PR once the developer responds to the `cargo vet` failure + - Respond to the developer comment in case more information is needed + +2. **Audit new dependencies**: + - Inspect the `cargo vet` failures using your preferred method + - Use [gh pr checkout](https://cli.github.com/manual/gh_pr_checkout) to checkout the PR and run `cargo vet --locked` + - Use [Github Pull Requests for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-pull-request-github) to checkout the PR and run `cargo vet --locked` + - For more suggestions: [Checking out pull requests locally](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/checking-out-pull-requests-locally) + +3. **Follow `cargo vet` recommendations**: + - Follow the recommendations of the `cargo vet` command output, either `cargo vet diff` for version update or `cargo vet inspect` for new dependencies + +4. **Record audits**: + - Use `cargo vet certify` to add new audits to _audits.toml_ + - Verify all dependencies pass using `cargo vet` + +5. **Decide audit location**: + - **Shared audits**: New audits should ideally be shared across ODP repositories to reduce the overhead of multiple audits for the same dependencies. To facilitate this, it's recommended to cut and paste the new audits and submit as a separate PR to the _audits.toml_ in [rust-crate-audits](https://github.com/OpenDevicePartnership/rust-crate-audits) + - If due to business reasons, the audits are not to be shared across repositories, copy the updated _audits.toml_ to a new branch off main in the same repository and submit the PR to update the audits + +6. **Communicate successful audit**: + - Communicate to the PR developer via a PR comment so they can update the PR and get `cargo vet` to pass + +--- + +## Tips for using `cargo vet`: + +- **Update _imports.lock_**: + - Import trusted third party audits to reduce the number of new audits to be performed. Running `cargo vet` without `--locked` fetches new imports and updates _imports.lock_ with any audits that are helpful for our project. + +- **Add exemptions**: + - If an audit cannot be performed for some dependency due to time sensitivity or business justified reasons, use `cargo vet add-exemption ` to add the dependency to exemptions in _config.toml_ + - To add all remaining audits to exemptions at once, use `cargo vet regenerate exemptions` + +- **Prune unnecessary entries**: + - Remove unnecessary exemptions and imports using `cargo vet prune` diff --git a/supply-chain/audits.toml b/supply-chain/audits.toml new file mode 100644 index 0000000..2772ccb --- /dev/null +++ b/supply-chain/audits.toml @@ -0,0 +1,4 @@ + +# cargo-vet audits file + +[audits] diff --git a/supply-chain/config.toml b/supply-chain/config.toml new file mode 100644 index 0000000..55618c2 --- /dev/null +++ b/supply-chain/config.toml @@ -0,0 +1,14 @@ + +# cargo-vet config file + +[cargo-vet] +version = "0.10" + +[imports.OpenDevicePartnership] +url = "https://raw.githubusercontent.com/OpenDevicePartnership/rust-crate-audits/main/audits.toml" + +[imports.google] +url = "https://raw.githubusercontent.com/google/rust-crate-audits/main/audits.toml" + +[imports.mozilla] +url = "https://raw.githubusercontent.com/mozilla/supply-chain/main/audits.toml" diff --git a/supply-chain/imports.lock b/supply-chain/imports.lock new file mode 100644 index 0000000..219dba4 --- /dev/null +++ b/supply-chain/imports.lock @@ -0,0 +1,8 @@ + +# cargo-vet imports lock + +[audits.OpenDevicePartnership.audits] + +[audits.google.audits] + +[audits.mozilla.audits]