Skip to content

Commit 3cf8e09

Browse files
josecelanojosecelano
committed
docs: add issue specification for #439 
1 parent 4daa4df commit 3cf8e09

1 file changed

Lines changed: 161 additions & 0 deletions

File tree

‎docs/issues/439-cargo-audit-security-automation-and-remediation.md‎

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
# Automate Cargo Audit Security Scanning and Dependency Remediation
2+
3+
**Issue**: #439
4+
**Parent Epic**: N/A (standalone security task)
5+
**Related**:
6+
7+
- Existing Docker security workflow: `.github/workflows/docker-security-scan.yml`
8+
- Docker scan reports index: `docs/security/docker/scans/README.md`
9+
- RustSec audit action: https://github.com/rustsec/audit-check
10+
11+
## Overview
12+
13+
Introduce a Rust dependency security workflow based on `cargo audit` that runs periodically and can be triggered manually, document scan results under `docs/security/dependencies`, and remediate vulnerabilities where feasible.
14+
15+
This task also defines a clear process for unresolved findings: if vulnerabilities cannot be fixed quickly (for example, blocked by upstream releases), create follow-up issues with context, impact, and tracking details.
16+
17+
## Goals
18+
19+
- [ ] Add an automated GitHub Actions workflow for periodic Rust dependency security scans
20+
- [ ] Produce a manually generated dependency security report in `docs/security/dependencies`
21+
- [ ] Fix dependency vulnerabilities where updates or replacements are available and safe
22+
- [ ] Open follow-up issue(s) for findings blocked by upstream or high-effort refactors
23+
24+
## 🏗️ Architecture Requirements
25+
26+
**DDD Layer**: Infrastructure (CI/CD), Documentation, and dependency management
27+
**Module Path**: `.github/workflows/`, `docs/security/dependencies/`, Cargo workspace manifests and lockfile
28+
**Pattern**: Security scanning workflow + remediation and tracking process
29+
30+
### Module Structure Requirements
31+
32+
- [ ] Keep CI logic inside `.github/workflows/`
33+
- [ ] Keep human-readable scan reports under `docs/security/dependencies/`
34+
- [ ] Keep dependency updates consistent across workspace crates
35+
- [ ] Reference related issue(s) and report files for traceability
36+
37+
### Architectural Constraints
38+
39+
- [ ] Workflow should support periodic scanning and manual execution (`workflow_dispatch`)
40+
- [ ] Workflow should follow the style and clarity of `.github/workflows/docker-security-scan.yml`
41+
- [ ] Dependency reports must be reproducible from documented commands
42+
- [ ] Vulnerability handling must be actionable (fix now or tracked follow-up)
43+
44+
### Anti-Patterns to Avoid
45+
46+
- ❌ Silent failures where scan output is not discoverable
47+
- ❌ Ad-hoc local-only fixes without documentation
48+
- ❌ Leaving unresolved vulnerabilities without a tracking issue
49+
- ❌ Mixing unrelated refactors into security remediation commits
50+
51+
## Specifications
52+
53+
### 1. Add Scheduled Cargo Audit Workflow
54+
55+
Create a new workflow in `.github/workflows/` that:
56+
57+
- Runs on `schedule` (periodic scans), `workflow_dispatch`, and optionally on dependency file changes (`Cargo.toml`, `Cargo.lock`)
58+
- Uses `RustSec/audit-check@v2.0.0` (or current stable release) with `token: ${{ secrets.GITHUB_TOKEN }}`
59+
- Uses explicit permissions required by the action (`issues: write`, `checks: write`, and minimum required repository permissions)
60+
- Documents why scheduled execution is needed (new advisories may appear without repository changes)
61+
62+
Implementation notes from RustSec action documentation:
63+
64+
- Scheduled workflows can create issues for new advisories
65+
- Non-scheduled runs should still fail checks when vulnerabilities are found
66+
- The action supports `ignore` and `working-directory` inputs when needed
67+
68+
### 2. Generate Manual Dependency Security Report
69+
70+
Re-run `cargo audit` manually and document results in a new report under:
71+
72+
- `docs/security/dependencies/README.md` (index and process)
73+
- One date-stamped report file (for example `docs/security/dependencies/scans/2026-04-10-cargo-audit.md`)
74+
75+
Report format should mirror Docker security documentation conventions:
76+
77+
- Scan date, tool version, command used
78+
- Summary counts by severity/status
79+
- Detailed findings with package, advisory ID, status, and recommended fix
80+
- Risk notes for unmaintained crates and transitive dependencies
81+
- Next actions and owner tracking
82+
83+
### 3. Remediate Security Findings
84+
85+
Attempt practical fixes for current findings, including:
86+
87+
- Upgrading vulnerable dependencies to patched versions
88+
- Updating direct dependencies to versions that pull secure transitives
89+
- Replacing unmaintained dependencies when viable and low-risk
90+
- Regenerating lockfile and validating build/tests/lints after updates
91+
92+
Expected validation:
93+
94+
- `cargo audit`
95+
- `cargo build`
96+
- `cargo test`
97+
- `./scripts/pre-commit.sh`
98+
99+
### 4. Create Follow-up Issues for Hard Blockers
100+
101+
If a vulnerability cannot be resolved quickly:
102+
103+
- Create a follow-up issue per blocker (or one grouped issue with clear subtasks)
104+
- Include advisory ID(s), affected dependency tree, why blocked, and mitigation options
105+
- Add review cadence and closure criteria (for example, upgrade when upstream releases fix)
106+
- Link follow-up issue(s) from the main issue specification/report
107+
108+
## Implementation Plan
109+
110+
### Phase 1: CI Workflow Setup (estimated time: 1-2 hours)
111+
112+
- [ ] Task 1.1: Create `.github/workflows/cargo-audit.yml`
113+
- [ ] Task 1.2: Configure schedule + manual trigger + permissions
114+
- [ ] Task 1.3: Validate workflow configuration and alignment with existing workflow style
115+
116+
### Phase 2: Manual Security Reporting (estimated time: 1-2 hours)
117+
118+
- [ ] Task 2.1: Run `cargo audit` manually and capture results
119+
- [ ] Task 2.2: Create `docs/security/dependencies/` index and scan report
120+
- [ ] Task 2.3: Cross-link report from security documentation as needed
121+
122+
### Phase 3: Dependency Remediation (estimated time: 2-6 hours)
123+
124+
- [ ] Task 3.1: Identify direct vs transitive upgrade paths
125+
- [ ] Task 3.2: Apply safe dependency updates/replacements
126+
- [ ] Task 3.3: Re-run build, tests, lint, and `cargo audit`
127+
128+
### Phase 4: Follow-up Tracking (estimated time: 0.5-1 hour)
129+
130+
- [ ] Task 4.1: Create issue(s) for unresolved advisories/blockers
131+
- [ ] Task 4.2: Link follow-up issue(s) in main issue and report docs
132+
- [ ] Task 4.3: Document mitigation strategy and revisit timeline
133+
134+
## Acceptance Criteria
135+
136+
> **Note for Contributors**: These criteria define what the PR reviewer will check. Use this as your pre-review checklist before submitting the PR to minimize back-and-forth iterations.
137+
138+
**Quality Checks**:
139+
140+
- [ ] Pre-commit checks pass: `./scripts/pre-commit.sh`
141+
142+
**Task-Specific Criteria**:
143+
144+
- [ ] New workflow exists and runs on schedule + manual dispatch
145+
- [ ] Workflow uses RustSec audit action with appropriate permissions and token configuration
146+
- [ ] Manual dependency security report exists in `docs/security/dependencies/` and follows documented format
147+
- [ ] `cargo audit` was re-run and latest results are documented
148+
- [ ] Feasible dependency vulnerabilities are remediated and validated
149+
- [ ] Unresolved vulnerabilities have linked follow-up issue(s) with actionable next steps
150+
151+
## Related Documentation
152+
153+
- `docs/security/docker/scans/README.md`
154+
- `.github/workflows/docker-security-scan.yml`
155+
- `docs/contributing/roadmap-issues.md`
156+
- RustSec audit-check docs: https://github.com/rustsec/audit-check
157+
158+
## Notes
159+
160+
- Keep the first implementation focused on actionable security outcomes; avoid broad CI refactoring.
161+
- If dependency remediation impacts runtime behavior, document risk and testing scope explicitly.

0 commit comments

Comments
 (0)