Skip to content

Commit efaa6fc

Browse files
josecelanojosecelano
committed
feat(security): add security analysis process and catalog non-affecting Containerfile CVEs
Introduce a structured process for evaluating Docker DX vulnerability warnings, with the initial catalog entry documenting why trixie-based Containerfile image CVEs do not affect us (build-time stages, production runtime is distroless). Added: - docs/security/analysis/README.md — process document and template - docs/security/analysis/non-affecting/2026-06-10_containerfile-trixie-cves.md — CVE catalog entry - .github/skills/dev/maintenance/catalog-security-vulnerabilities/SKILL.md — AI agent skill Enhanced: - docs/adrs/20260603000000_keep_unit_tests_inside_container_build.md — Security Rationale section Also updated project-words.txt with new dictionary entries. Closes #1898
1 parent 26cb6b7 commit efaa6fc

6 files changed

Lines changed: 456 additions & 3 deletions

File tree

‎.github/skills/dev/maintenance/catalog-security-vulnerabilities/SKILL.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
---
2+
name: catalog-security-vulnerabilities
3+
description: Guide for cataloging security vulnerability warnings (e.g. Docker DX CVEs) that do NOT affect the project. Covers the process of checking the existing catalog, creating a new analysis document with rationale, and escalating if a vulnerability is found to be affecting. Use when handling Docker DX warnings, CVE analysis, vulnerability scanning results, or security audit findings. Triggers on "Docker DX", "vulnerability warning", "CVE analysis", "security scan", "catalog vulnerability", "non-affecting CVE", or "container CVE".
4+
metadata:
5+
author: torrust
6+
version: "1.0"
7+
semantic-links:
8+
related-artifacts:
9+
- docs/security/analysis/README.md
10+
---
11+
12+
# Catalog Security Vulnerabilities
13+
14+
This skill guides you through evaluating and documenting security vulnerability warnings
15+
(such as Docker DX extension flags or scanner output) that appear in the project's
16+
dependencies or infrastructure.
17+
18+
The authoritative process document is `docs/security/analysis/README.md` — this skill
19+
provides a quick reference.
20+
21+
## Quick Reference
22+
23+
```text
24+
docs/security/analysis/
25+
README.md ← Process + template
26+
non-affecting/ ← CVEs that do NOT affect us (catalog)
27+
affecting/ ← CVEs that DO affect us (future)
28+
```
29+
30+
## Process (3 Steps)
31+
32+
### Step 1: Check the Catalog
33+
34+
Before analyzing a new warning, check `docs/security/analysis/non-affecting/` to see if
35+
it has already been evaluated. Every file there documents why a set of CVEs is
36+
non-affecting. If found, the analysis is already done — link the existing document in
37+
any related issue or PR comment.
38+
39+
### Step 2: Analyse and Document (if not cataloged)
40+
41+
If the vulnerability is **not yet cataloged**:
42+
43+
1. Determine whether it affects us (see criteria examples in the README).
44+
2. If **non-affecting**: create a dated file in `non-affecting/` following the template
45+
in the README. Include rationale, future actions, and review cadence.
46+
3. If **affecting**: escalate immediately (see Step 3).
47+
48+
### Step 3: Escalate if Affecting
49+
50+
If a vulnerability **does** affect us (rare — the runtime is distroless):
51+
52+
1. Create a file in `docs/security/analysis/affecting/` with the same template.
53+
2. Open a GitHub issue with the `security` and `bug` labels.
54+
3. Notify maintainers — these are high priority.
55+
56+
## Review Cadence
57+
58+
All analysis documents have a `review-cadence` field in their frontmatter. The default
59+
is `quarterly` — re-check whether upstream CVEs have been fixed and whether the
60+
assessment is still valid.
61+
62+
## Policy
63+
64+
- Never ignore a vulnerability warning without documenting why.
65+
- The runtime image (`gcr.io/distroless/cc-debian13:debug`) is the critical trust boundary.
66+
Build-stage CVEs are generally non-affecting unless they involve code execution during
67+
build that could compromise the output binary.

‎docs/adrs/20260603000000_keep_unit_tests_inside_container_build.md‎

Lines changed: 25 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@ semantic-links:
66
- .github/skills/dev/planning/create-adr/SKILL.md
77
- Containerfile
88
- .github/workflows/container.yaml
9+
- docs/security/analysis/non-affecting/2026-06-10_containerfile-trixie-cves.md
10+
- docs/security/analysis/README.md
911
---
1012

1113
# Keep unit tests inside the container build process
@@ -60,13 +62,33 @@ The three-layer strategy is therefore:
6062
3. **E2E tests against the distroless `release` image** (`container.yaml` `test` job) —
6163
the only layer that proves the binary works in the actual production runtime.
6264

65+
### Security Rationale
66+
67+
Keeping unit tests inside the container build also provides a **security-in-depth** benefit:
68+
69+
- The `tester` stage runs the **exact compiled binary** produced by `rust:trixie` — including
70+
all its runtime dependencies — in an environment that shares the same Debian trixie glibc
71+
as the production runtime. This acts as a **build-pipeline integrity check**: if a
72+
maliciously compromised build tool or compromised dependency introduced unexpected
73+
behavioural changes, unit test failures would likely surface them before the binary reaches
74+
the runtime image.
75+
- The unit tests exercise code paths that would be exercised in production, providing a
76+
baseline of expected behaviour against which anomalous test results could be detected.
77+
- This is a weaker guarantee than running in the distroless runtime itself (the unit tests
78+
run in `rust:slim-trixie`, not `distroless/cc-debian13`), but it is a strictly stronger
79+
guarantee than running tests on a separate GHA host with a different glibc and library set.
80+
81+
For a full security analysis of the Containerfile's build-stage vulnerabilities, see
82+
`docs/security/analysis/non-affecting/2026-06-10_containerfile-trixie-cves.md`.
83+
6384
### Alternatives Considered
6485

6586
**Move unit tests entirely to the GHA host and remove the `tester` stage.**
6687
This would make the container build significantly faster (eliminating ~50 fat-LTO binary
67-
compilations). However, it removes layer 2 above. The decision for now is to keep all three
68-
layers. If the build time becomes unacceptable, this option can be revisited as part of the
69-
LTO optimization work tracked in issue #1840.
88+
compilations), but would also remove the build-pipeline integrity check described in the
89+
Security Rationale above. The decision for now is to keep all three layers. If the build time
90+
becomes unacceptable, this option can be revisited as part of the LTO optimization work
91+
tracked in issue #1840.
7092

7193
### Consequences
7294

‎docs/issues/open/1898-document-security-analysis-process.md‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
---
2+
doc-type: issue
3+
issue-type: task
4+
status: draft
5+
priority: p3
6+
github-issue: 1898
7+
spec-path: docs/issues/open/1898-document-security-analysis-process.md
8+
branch: "1898-document-security-analysis-process"
9+
related-pr: null
10+
last-updated-utc: 2026-06-10 16:30
11+
semantic-links:
12+
skill-links:
13+
- create-issue
14+
related-artifacts:
15+
- docs/security/analysis/README.md
16+
- docs/security/analysis/non-affecting/2026-06-10_containerfile-trixie-cves.md
17+
- docs/issues/README.md
18+
- Containerfile
19+
- docs/adrs/20260603000000_keep_unit_tests_inside_container_build.md
20+
- docs/skills/semantic-skill-link-convention.md
21+
- https://github.com/torrust/torrust-tracker/issues/1457
22+
- https://github.com/torrust/torrust-tracker/issues/1460
23+
- https://github.com/torrust/torrust-tracker/issues/1463
24+
---
25+
26+
<!-- skill-link: create-issue -->
27+
28+
# Issue #1898 - Document security analysis process and catalog non-affecting Containerfile CVEs
29+
30+
## Goal
31+
32+
Establish a structured process for evaluating security warnings and create the initial
33+
catalog entry documenting why the trixie-based Containerfile image CVEs do not affect us.
34+
35+
## Background
36+
37+
The VS Code Docker DX extension flags vulnerabilities in the Containerfile's three
38+
trixie-based `FROM` images (`rust:trixie`, `rust:slim-trixie`, `gcc:trixie`). These are
39+
upstream CVEs in Docker Official Images. Before this issue, there was no documented process
40+
or central catalog to record such analyses, meaning every contributor seeing these warnings
41+
would need to re-do the same investigation.
42+
43+
### Related prior work
44+
45+
This issue builds on the **Docker Security Overhaul** EPIC
46+
([#1457](https://github.com/torrust/torrust-tracker/issues/1457)), which established
47+
a security baseline for the Containerfile and container workflows. Previous sub-issues
48+
include adding hadolint linting to CI
49+
([#1460](https://github.com/torrust/torrust-tracker/issues/1460)) and evaluating the
50+
`rust:slim-trixie` vs `rust:trixie` trade-off
51+
([#1463](https://github.com/torrust/torrust-tracker/issues/1463)). Issue #1463 already
52+
includes a Trivy scan of both the trixie build images and the distroless runtime,
53+
confirming the runtime has 0 critical/high CVEs.
54+
55+
The current VS Code Docker DX warnings are a new signal that needs to be systematically
56+
analyzed and cataloged, which this issue addresses by creating a permanent analysis
57+
process and catalog.
58+
59+
We need:
60+
61+
1. A `docs/security/analysis/` folder structure with a process document.
62+
2. The initial analysis cataloging these CVEs as non-affecting, with rationale.
63+
3. A subfolder for non-affecting vulnerabilities so they can be looked up quickly.
64+
4. A `.github/skills/dev/maintenance/catalog-security-vulnerabilities/` skill so AI agents
65+
auto-discover this process.
66+
67+
## Scope
68+
69+
### In Scope
70+
71+
- Create `docs/security/analysis/README.md` — index and process description.
72+
- Create `docs/security/analysis/non-affecting/` — subfolder for non-affecting vulnerabilities.
73+
- Create `docs/security/analysis/non-affecting/2026-06-10_containerfile-trixie-cves.md` — actual analysis.
74+
- Create `.github/skills/dev/maintenance/catalog-security-vulnerabilities/SKILL.md` — AI agent skill.
75+
- Update `docs/adrs/20260603000000_keep_unit_tests_inside_container_build.md` — add Security Rationale section.
76+
- Add semantic links between ADR, security analysis, and skill convention.
77+
- List notable CVEs, explain why non-affecting, define review cadence.
78+
79+
### Out of Scope
80+
81+
- Changing the Containerfile base images (separate concern if needed).
82+
- Fixing the upstream CVEs (they are in Docker Official Images, not our code).
83+
- Creating automation for vulnerability scanning (future enhancement).
84+
- Documenting affecting vulnerabilities (none found yet).
85+
86+
## Implementation Plan
87+
88+
Status values: `TODO`, `IN_PROGRESS`, `BLOCKED`, `DONE`.
89+
90+
| ID | Status | Task | Notes / Expected Output |
91+
| --- | ------ | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
92+
| T1 | DONE | Create `docs/security/analysis/` folder structure | `README.md` + `non-affecting/` subfolder |
93+
| T2 | DONE | Analyze trixie Containerfile CVEs | Document showing why they don't affect us |
94+
| T3 | DONE | Write the non-affecting analysis document | `2026-06-10_containerfile-trixie-cves.md` with full rationale |
95+
| T4 | DONE | Update ADR with security rationale | Added Security Rationale section to `docs/adrs/20260603000000_keep_unit_tests_inside_container_build.md` |
96+
| T5 | DONE | Add semantic links between all related docs | `semantic-links` updated in ADR, security analysis, and README |
97+
| T6 | DONE | Create security analysis skill | `.github/skills/dev/maintenance/catalog-security-vulnerabilities/SKILL.md` |
98+
| T7 | DONE | User reviews the draft issue spec | Approval before creating GitHub issue |
99+
| T8 | TODO | Create GitHub issue | Using `gh` CLI or MCP tools |
100+
| T9 | TODO | Rename spec from `drafts/` to `open/` with issue number | `git mv` + update frontmatter |
101+
| T10 | TODO | Commit and push | `git add`, `git commit -S`, push to fork |
102+
103+
## Progress Tracking
104+
105+
### Workflow Checkpoints
106+
107+
- [x] Spec drafted in `docs/issues/drafts/`
108+
- [x] Spec reviewed and approved by user/maintainer
109+
- [x] GitHub issue created and issue number added to this spec
110+
- [ ] Implementation completed
111+
- [ ] Automatic verification completed (`linter all`, relevant tests)
112+
- [ ] Manual verification scenarios executed and recorded
113+
- [ ] Acceptance criteria reviewed after implementation and updated with evidence
114+
- [ ] Issue closed and spec moved from `docs/issues/open/` to `docs/issues/closed/`
115+
116+
### Progress Log
117+
118+
- 2026-06-10 16:30 UTC - GitHub Copilot - Created security analysis skill in `.github/skills/dev/maintenance/catalog-security-vulnerabilities/`
119+
- 2026-06-10 16:00 UTC - GitHub Copilot - Drafted issue spec and created analysis documents in `docs/security/analysis/`
120+
121+
## Acceptance Criteria
122+
123+
- [ ] AC1: `docs/security/analysis/README.md` exists with process description and template
124+
- [ ] AC2: `docs/security/analysis/non-affecting/2026-06-10_containerfile-trixie-cves.md` exists with full analysis
125+
- [ ] AC3: The analysis document includes: vulnerability summary, rationale for non-affecting status, future actions, and references
126+
- [ ] AC4: `docs/adrs/20260603000000_keep_unit_tests_inside_container_build.md` has a Security Rationale section
127+
- [ ] AC5: Semantic links are consistent between ADR, security analysis documents, and related artifacts
128+
- [ ] AC6: `linter all` exits with code `0`
129+
- [ ] AC7: New documents are spell-checked (no false positives)
130+
- [ ] AC8: Documentation is updated when behavior/workflow changes
131+
- [ ] AC9: `.github/skills/dev/maintenance/catalog-security-vulnerabilities/SKILL.md` exists with process description and semantic-links
132+
133+
## Verification Plan
134+
135+
### Automatic Checks
136+
137+
- `linter all`
138+
- Spell check on new documents
139+
140+
### Manual Verification Scenarios
141+
142+
Status values: `TODO`, `IN_PROGRESS`, `DONE`, `FAILED`, `BLOCKED`.
143+
144+
| ID | Scenario | Command/Steps | Expected Result | Status | Evidence |
145+
| --- | ------------------------------------------ | ------------------------------------------------------------- | --------------------------------- | ------ | -------- |
146+
| M1 | Verify README renders correctly | Open `docs/security/analysis/README.md` in VS Code preview | All sections readable, links work | TODO | |
147+
| M2 | Verify analysis document renders correctly | Open analysis doc in VS Code preview | Tables render, rationale clear | TODO | |
148+
| M3 | Verify no broken internal links | Check all `semantic-links` and references point to real files | All refs resolve | TODO | |
149+
| M4 | Run linters | `linter all` | Exit code 0 | TODO | |

‎docs/security/analysis/README.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
---
2+
semantic-links:
3+
skill-links:
4+
- catalog-security-vulnerabilities
5+
related-artifacts:
6+
- Containerfile
7+
- docs/security/analysis/non-affecting/
8+
- docs/adrs/20260603000000_keep_unit_tests_inside_container_build.md
9+
---
10+
11+
# Security Analysis
12+
13+
This folder contains security analysis documents for the Torrust Tracker project.
14+
15+
## Purpose
16+
17+
When a security issue is detected (e.g., by Docker Scout, dependabot, manual audit, or
18+
container image vulnerability scanning), we create an analysis document here to:
19+
20+
1. **Evaluate** whether the vulnerability actually affects our project.
21+
2. **Document the decision** so other contributors seeing the same warning can quickly
22+
determine whether it has been analyzed before.
23+
3. **Track periodic review** — even non-affecting vulnerabilities should be re-evaluated
24+
periodically to check if the situation has changed.
25+
26+
## Folder Structure
27+
28+
```text
29+
docs/security/analysis/
30+
├── README.md # This file — index and process
31+
├── non-affecting/ # Vulnerabilities that do NOT affect us
32+
│ └── {date}_{descriptive-name}.md
33+
└── ... # (future) Affecting vulnerabilities go here
34+
```
35+
36+
## Process
37+
38+
### When a security warning appears
39+
40+
1. **Check the catalog**: search `docs/security/analysis/non-affecting/` to see if this
41+
vulnerability has already been analyzed. If it has, you're done — the document explains
42+
why it doesn't affect us and what to watch for.
43+
44+
2. **If not yet cataloged**: create a new analysis document in `non-affecting/` (or an
45+
appropriate subfolder) following the template below.
46+
47+
3. **If it DOES affect us**: escalate immediately. Create an issue and a fix. The analysis
48+
document should describe the impact, affected components, and remediation plan.
49+
50+
### Analysis Document Template
51+
52+
Each analysis document should include:
53+
54+
- **Date of analysis**
55+
- **Source of the warning** (tool, scanner, CVE database, etc.)
56+
- **Vulnerability summary** — what CVEs, what packages, what severity
57+
- **Why it does not affect us** — a clear rationale tied to our architecture
58+
- **Future actions** — periodic review cadence, conditions that would change the status
59+
- **References** — links to the original warning, Docker Hub layers, CVE entries, etc.
60+
61+
### Review Cadence
62+
63+
Non-affecting vulnerabilities should be reviewed:
64+
65+
- At least **quarterly** (or when the relevant base image is updated).
66+
- Immediately if the affected image begins being used in a **different context** (e.g., if
67+
a build-stage image becomes part of the runtime).

0 commit comments

Comments
 (0)