Skip to content

Commit 5566a72

Browse files
akshat2112akshat2112
authored
Initialize cargo vet (#30)
This PR initializes `cargo vet` on the repository as part of the effort to enhance the quality and promise of secure EC code in ODP and adds a new workflow to gate `cargo vet` in CI. It also updates the CODEOWNERS file to strengthen the EC team's ownership of the repository.
1 parent 289a72e commit 5566a72

File tree

6 files changed

+519
-0
lines changed

6 files changed

+519
-0
lines changed

‎.github/workflows/cargo-vet-pr-comment.yml‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
# This workflow triggers after cargo-vet workflow has run.
2+
# It adds a comment to the PR with the results of the cargo vet run.
3+
# It first adds a comment if the cargo vet run fails,
4+
# and updates the comment if the cargo vet run succeeds after having failed at least once.
5+
6+
name: Cargo vet PR comment
7+
8+
on:
9+
workflow_run:
10+
workflows: [cargo-vet]
11+
types:
12+
- completed
13+
14+
permissions:
15+
contents: read
16+
pull-requests: write
17+
18+
concurrency:
19+
group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
20+
cancel-in-progress: true
21+
22+
jobs:
23+
24+
find-pr-comment:
25+
# This job runs when the cargo-vet job fails or succeeds
26+
# It will download the artifact from the failed job and post a comment on the PR
27+
runs-on: ubuntu-latest
28+
outputs:
29+
comment-id: ${{ steps.get-comment-id.outputs.comment-id }}
30+
pr-number: ${{ steps.get-pr-number.outputs.pr_number }}
31+
if: github.event.workflow_run.event == 'pull_request'
32+
steps:
33+
- name: 'Download artifact'
34+
uses: actions/download-artifact@v4
35+
with:
36+
github-token: ${{ secrets.GITHUB_TOKEN }}
37+
name: pr
38+
path: pr/
39+
run-id: ${{ github.event.workflow_run.id }}
40+
41+
- name: 'Get PR number'
42+
id: get-pr-number
43+
run: echo "pr_number=$(cat ./pr/NR)" >> $GITHUB_OUTPUT
44+
45+
- name: 'Find existing comment'
46+
id: find-comment
47+
uses: peter-evans/find-comment@v3
48+
with:
49+
issue-number: ${{ steps.get-pr-number.outputs.pr_number }}
50+
comment-author: 'github-actions[bot]'
51+
body-includes: 'comment-tag: [cargo-vet]'
52+
53+
- name: 'Get comment ID'
54+
id: get-comment-id
55+
if: ${{ steps.find-comment.outputs.comment-id != '' }}
56+
run: echo "comment-id=${{ steps.find-comment.outputs.comment-id }}" >> $GITHUB_OUTPUT
57+
58+
post-comment-failure:
59+
# This job runs when the cargo-vet job fails
60+
# It will download the artifact from the failed job and post a comment on the PR
61+
runs-on: ubuntu-latest
62+
needs: find-pr-comment
63+
if: github.event.workflow_run.conclusion == 'failure'
64+
steps:
65+
- name: 'Comment on PR - Failure'
66+
uses: peter-evans/create-or-update-comment@v4
67+
with:
68+
comment-id: ${{ needs.find-pr-comment.outputs.comment-id }}
69+
issue-number: ${{ needs.find-pr-comment.outputs.pr-number }}
70+
body: |
71+
# Cargo Vet Audit Failed
72+
73+
`cargo vet` has failed in this PR. Please run `cargo vet --locked` locally to check for new or updated unvetted dependencies.
74+
Details about the vetting process can be found in [supply-chain/README.md](../blob/main/supply-chain/README.md)
75+
76+
## If the unvetted dependencies are not needed
77+
Please modify Cargo.toml file to avoid including the dependencies.
78+
79+
## If the unvetted dependencies are needed
80+
Post a new comment with the questionnaire below to the PR to help the auditors vet the dependencies.
81+
After the auditors have vetted the dependencies, the PR will need to be rebased to pick up the new audits and pass this check.
82+
83+
### Copy and paste the questionnaire as a new comment and provide your answers:
84+
85+
**1. What crates (with version) need to be audited?**
86+
87+
**2. How many of the crates are version updates vs new dependencies?**
88+
89+
**3. To confirm none of the already included crates serve your needs, please provide a brief description of the purpose of the new crates.**
90+
91+
**4. Any extra notes to the auditors to help with their audits.**
92+
93+
<!--
94+
This comment is auto-generated by the cargo-vet workflow.
95+
Please do not edit it directly.
96+
97+
comment-tag: [cargo-vet]
98+
-->
99+
edit-mode: replace
100+
101+
- name: 'Label PR'
102+
uses: actions/github-script@v7
103+
with:
104+
script: |
105+
github.rest.issues.addLabels({
106+
issue_number: ${{ needs.find-pr-comment.outputs.pr-number }},
107+
owner: context.repo.owner,
108+
repo: context.repo.repo,
109+
labels: ['cargo vet']
110+
})
111+
112+
post-comment-success:
113+
# This job runs when the cargo-vet job succeeds
114+
# It will update the comment on the PR with a success message
115+
runs-on: ubuntu-latest
116+
needs: find-pr-comment
117+
if: github.event.workflow_run.conclusion == 'success'
118+
steps:
119+
- name: 'Comment on PR - Success'
120+
# Only update the comment if it exists
121+
# This is to avoid creating a new comment if the cargo-vet job has never failed before
122+
if: ${{ needs.find-pr-comment.outputs.comment-id }}
123+
uses: peter-evans/create-or-update-comment@v4
124+
with:
125+
comment-id: ${{ needs.find-pr-comment.outputs.comment-id }}
126+
issue-number: ${{ needs.find-pr-comment.outputs.pr-number }}
127+
body: |
128+
# Cargo Vet Audit Passed
129+
`cargo vet` has passed in this PR. No new unvetted dependencies were found.
130+
131+
<!--
132+
This comment is auto-generated by the cargo-vet workflow.
133+
Please do not edit it directly.
134+
135+
comment-tag: [cargo-vet]
136+
-->
137+
edit-mode: replace

‎.github/workflows/cargo-vet.yml‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# This workflow runs whenever a PR is opened or updated. It runs cargo vet to check for unvetted dependencies in the Cargo.lock file.
2+
permissions:
3+
contents: read
4+
on:
5+
pull_request:
6+
7+
concurrency:
8+
group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
9+
cancel-in-progress: true
10+
11+
name: cargo-vet
12+
jobs:
13+
vet:
14+
# cargo-vet checks for unvetted dependencies in the Cargo.lock file
15+
# This is to ensure that new dependencies are vetted before they are added to the project
16+
name: vet-dependencies
17+
runs-on: ubuntu-latest
18+
env:
19+
CARGO_VET_VERSION: 0.10.1
20+
steps:
21+
- uses: actions/checkout@v4
22+
with:
23+
submodules: true
24+
- uses: actions/cache@v4
25+
with:
26+
path: ${{ runner.tool_cache }}/cargo-vet
27+
key: cargo-vet-bin-${{ env.CARGO_VET_VERSION }}
28+
- name: Add the tool cache directory to the search path
29+
run: echo "${{ runner.tool_cache }}/cargo-vet/bin" >> $GITHUB_PATH
30+
- name: Ensure that the tool cache is populated with the cargo-vet binary
31+
run: cargo install --root ${{ runner.tool_cache }}/cargo-vet --version ${{ env.CARGO_VET_VERSION }} cargo-vet
32+
- name: Invoke cargo-vet
33+
run: cargo vet --locked
34+
- name: Save PR number
35+
# 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
36+
# 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
37+
if: ${{ failure() }} || ${{ success() }}
38+
run: |
39+
mkdir -p ./pr
40+
echo ${{ github.event.number }} > ./pr/NR
41+
- uses: actions/upload-artifact@v4
42+
# Need to upload the artifact in both success and failure cases so comment can be updated in either case
43+
if: ${{ failure() }} || ${{ success() }}
44+
with:
45+
name: pr
46+
path: pr/
47+
overwrite: true

‎supply-chain/README.md‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
# Working with cargo vet
2+
3+
## Introduction
4+
5+
`cargo vet` is a tool to help ensure that third-party Rust dependencies have been audited by a trusted entity.
6+
It matches all dependencies against a set of audits conducted by the authors of the project or entities they trust.
7+
To learn more, visit [mozilla/cargo-vet](https://github.com/mozilla/cargo-vet)
8+
9+
---
10+
11+
## Adding a new dependency
12+
13+
When updating or adding a new dependency, we need to ensure it's audited before being merged into main.
14+
For our repositories, we have designated experts who are responsible for vetting any new dependencies being added to their repository.
15+
_It is the shared responsibility of the developer creating the PR and the auditors to conduct a successful audit._
16+
Follow the process below to ensure compliance:
17+
18+
### For Developers
19+
1. **Respond to `cargo vet` failures**:
20+
- If your PR fails the `cargo vet` step, the cargo-vet workflow will add a comment to the PR with a template questionnaire
21+
- 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
22+
23+
2. **Engage with auditors**:
24+
- Respond to any questions that the auditors might have regarding the need of any new dependencies
25+
26+
3. **Rebase and verify**:
27+
- 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
28+
- Once the new audits have been merged, rebase your branch on main and verify it passes `cargo vet`
29+
```bash
30+
git fetch upstream
31+
git rebase upstream/main
32+
cargo vet
33+
```
34+
35+
4. **Update PR**:
36+
- 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
37+
- 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
38+
```bash
39+
git push -f
40+
```
41+
42+
5. **Check PR status**:
43+
- The existing PR comment from the previous failure will be updated with a success message once the check passes
44+
45+
### For Auditors
46+
47+
1. **Review the questionnaire**:
48+
- Check the filled questionnaire on the PR once the developer responds to the `cargo vet` failure
49+
- Respond to the developer comment in case more information is needed
50+
51+
2. **Audit new dependencies**:
52+
- Inspect the `cargo vet` failures using your preferred method
53+
- Use [gh pr checkout](https://cli.github.com/manual/gh_pr_checkout) to checkout the PR and run `cargo vet --locked`
54+
- 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`
55+
- 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)
56+
57+
3. **Follow `cargo vet` recommendations**:
58+
- Follow the recommendations of the `cargo vet` command output, either `cargo vet diff` for version update or `cargo vet inspect` for new dependencies
59+
60+
4. **Record audits**:
61+
- Use `cargo vet certify` to add new audits to _audits.toml_
62+
- Verify all dependencies pass using `cargo vet`
63+
64+
5. **Decide audit location**:
65+
- **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)
66+
- 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
67+
68+
6. **Communicate successful audit**:
69+
- Communicate to the PR developer via a PR comment so they can update the PR and get `cargo vet` to pass
70+
71+
---
72+
73+
## Audit criteria
74+
`cargo vet` comes pre-equipped with two built-in criteria but supports adding new criteria to suit our needs.
75+
As defined [here](https://mozilla.github.io/cargo-vet/built-in-criteria.html), the default criteria are:
76+
77+
- **safe-to-run**
78+
This crate can be compiled, run, and tested on a local workstation or in
79+
controlled automation without surprising consequences, such as:
80+
* Reading or writing data from sensitive or unrelated parts of the filesystem.
81+
* Installing software or reconfiguring the device.
82+
* Connecting to untrusted network endpoints.
83+
* Misuse of system resources (e.g. cryptocurrency mining).
84+
85+
- **safe-to-deploy**
86+
This crate will not introduce a serious security vulnerability to production
87+
software exposed to untrusted input.
88+
89+
Auditors are not required to perform a full logic review of the entire crate.
90+
Rather, they must review enough to fully reason about the behavior of all unsafe
91+
blocks and usage of powerful imports. For any reasonable usage of the crate in
92+
real-world software, an attacker must not be able to manipulate the runtime
93+
behavior of these sections in an exploitable or surprising way.
94+
95+
Ideally, all unsafe code is fully sound, and ambient capabilities (e.g.
96+
filesystem access) are hardened against manipulation and consistent with the
97+
advertised behavior of the crate. However, some discretion is permitted. In such
98+
cases, the nature of the discretion should be recorded in the `notes` field of
99+
the audit record.
100+
101+
For crates which generate deployed code (e.g. build dependencies or procedural
102+
macros), reasonable usage of the crate should output code which meets the above
103+
criteria.
104+
105+
**Note: `safe-to-deploy` implies `safe-to-run`**
106+
107+
---
108+
109+
## Conducting an audit
110+
111+
When performing an audit for a new or updated dependency, auditors may consider the following criteria to ensure the safety, reliability, and suitability of the crate for use in our projects:
112+
113+
- **Security**:
114+
- Review the crate for known vulnerabilities or security advisories.
115+
- Check for unsafe code usage and ensure it is justified and well-documented.
116+
- Evaluate the crate’s history of security issues and responsiveness to reported problems.
117+
118+
- **Maintenance and Activity**:
119+
- Assess the frequency of updates and the responsiveness of maintainers to issues and pull requests.
120+
- Prefer crates that are actively maintained and have a healthy contributor base.
121+
122+
- **License Compliance**:
123+
- Verify that the crate’s license is compatible with our project’s licensing requirements.
124+
125+
- **Community Trust and Adoption**:
126+
- Consider the crate’s adoption in the wider Rust ecosystem.
127+
- Prefer crates that are widely used and trusted by the community.
128+
129+
- **Functionality and Suitability**:
130+
- Confirm that the crate provides the required functionality without unnecessary features or bloat.
131+
- Evaluate whether the crate’s API is stable and unlikely to introduce breaking changes unexpectedly.
132+
133+
- **Audit Trail**:
134+
- Record the audit decision, including any concerns, mitigations, or recommendations for future updates.
135+
- If exemptions are granted, document the justification and any follow-up actions required.
136+
137+
---
138+
139+
## Tips for using `cargo vet`:
140+
141+
- **Update _imports.lock_**:
142+
- 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.
143+
144+
- **Add exemptions**:
145+
- If an audit cannot be performed for some dependency due to time sensitivity or business justified reasons, use `cargo vet add-exemption <PACKAGE> <VERSION>` to add the dependency to exemptions in _config.toml_
146+
- To add all remaining audits to exemptions at once, use `cargo vet regenerate exemptions`
147+
148+
- **Prune unnecessary entries**:
149+
- Remove unnecessary exemptions and imports using `cargo vet prune`

‎supply-chain/audits.toml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
2+
# cargo-vet audits file
3+
4+
[audits]

0 commit comments

Comments
 (0)