Skip to content

Commit 91113ac

Browse files
josecelanojosecelano
committed
Merge #1958: feat(security): add docker security scanning workflow and documentation (#1459)
3ef9e32 ci(security): fix build timeout and use pre-built image for scheduled scans (Jose Celano) b523194 ci(security): fix SARIF upload to Code Scanning and add security-events permission (Jose Celano) 2975af4 docs(issue): update status to completed for docker security overhaul (#1459) (Jose Celano) 291a0ed docs(security): fix relative link to workflow file from docker scan docs (Jose Celano) 19b0d9b chore: fix alphabetical sort in cspell dictionary (Jose Celano) 0e02ee2 docs(issue): update issue spec with PR reference and status (#1459) (Jose Celano) f598e14 ci(security): add scheduled docker security scan workflow (#1459) (Jose Celano) f846218 docs(issue): mark completed acceptance criteria for security workflow (#1459) (Jose Celano) f21cb8c docs(security): add manual scan docs, baseline report, and CVE catalog (Jose Celano) 8076ea2 docs(issue): mark completed acceptance criteria for docker security overhaul (#1459) (Jose Celano) db7e701 docs(skill): add maintenance skill for manual docker security scans (Jose Celano) aadf1bc docs(issue): add issue spec for docker security overhaul (#1459) (Jose Celano) a4ee563 chore: add dictionary terms for security documentation (Jose Celano) Pull request description: ## Description Implements issue #1459 — Docker Security Overhaul: Set Up Security Scanning Workflow. ## Changes **7 commits** across 5 logical groups: | Group | Commits | |---|---| | Dictionary | `chore: add dictionary terms for security documentation` | | Issue spec | `docs(issue): add issue spec for docker security overhaul (#1459)` | | | `docs(issue): mark completed acceptance criteria for docker security overhaul (#1459)` | | | `docs(issue): mark completed acceptance criteria for security workflow (#1459)` | | Skill | `docs(skill): add maintenance skill for manual docker security scans` | | Security docs | `docs(security): add manual scan docs, baseline report, and CVE catalog` | | CI workflow | `ci(security): add scheduled docker security scan workflow (#1459)` | ## What's Included ### 🔒 Security Scan Workflow (`.github/workflows/security-scan.yaml`) - Daily scheduled scan (6 AM UTC) + push/PR triggers on `Containerfile` or workflow changes - Builds the Docker image and runs Trivy (HIGH,CRITICAL) - Table output in logs + SARIF for GitHub Code Scanning - SARIF artifact uploaded with 30-day retention - Manual dispatch support ### 📚 Security Documentation (`docs/security/`) - Top-level security overview with priority tiers - Docker scan instructions and scan history - Baseline scan report (Jun 29, 2026): **5 MEDIUM, 0 HIGH, 0 CRITICAL** - Per-CVE analysis files for all 5 MEDIUM CVEs (all non-affecting) - CVE catalog strategy and recheck policy ### 🛠️ Maintenance Skill - `.github/skills/dev/maintenance/run-manual-docker-security-scan/SKILL.md` - Standardizes manual scan process (build, triage, document, escalate) ### 📋 Issue Spec - `docs/issues/open/1459-docker-security-overhaul/ISSUE.md` - Full implementation plan with 8 steps and verification plan - All 12 acceptance criteria completed ### 🔖 README Badge - Security scan workflow badge added to README ## Verification Status - [ ] Automated checks (workflow syntax, schedule execution, Trivy output) — pending CI run - [ ] Manual verification — pending ## Related - Closes #1459 - Related: #1630 ACKs for top commit: josecelano: ACK 3ef9e32 Tree-SHA512: 4d5f42702dcd876c0c320e94cd6316cd368bc91ad471fe6da0c073d453f4b25282620430f2fd7abf3c5ab417993535a61547c3782c5ac3f185fa93241ed84ded
2 parents ec8336b + 3ef9e32 commit 91113ac

16 files changed

Lines changed: 884 additions & 28 deletions

File tree

‎.github/skills/dev/maintenance/run-manual-docker-security-scan/SKILL.md‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
---
2+
name: run-manual-docker-security-scan
3+
description: Guide for running a manual Docker security scan for the tracker runtime image and documenting results. Covers build, Trivy scan, CVE triage, per-CVE catalog updates, and scan history updates. Use when asked to run a manual container scan, triage Docker CVEs, or refresh security scan docs.
4+
metadata:
5+
author: torrust
6+
version: "1.0"
7+
semantic-links:
8+
related-artifacts:
9+
- Containerfile
10+
- docs/security/README.md
11+
- docs/security/docker/README.md
12+
- docs/security/docker/scans/README.md
13+
- docs/security/docker/scans/torrust-tracker.md
14+
- docs/security/analysis/README.md
15+
- docs/security/analysis/non-affecting/
16+
---
17+
18+
# Run Manual Docker Security Scan
19+
20+
Use this workflow to run and document manual security scans for the tracker production container.
21+
22+
## Scope
23+
24+
- Target image: tracker runtime image built from root `Containerfile`.
25+
- Main severity gate: `HIGH,CRITICAL`.
26+
- Documentation outputs:
27+
- `docs/security/docker/scans/torrust-tracker.md`
28+
- `docs/security/docker/scans/README.md`
29+
- `docs/security/analysis/non-affecting/CVE-*.md` (when non-affecting CVEs are analyzed)
30+
31+
## Quick Commands
32+
33+
```bash
34+
# 1) Build runtime image
35+
docker build -t torrust-tracker:local -f Containerfile .
36+
37+
# 2) Gate scan (primary)
38+
trivy image --severity HIGH,CRITICAL torrust-tracker:local
39+
40+
# 3) Full context scan (optional but recommended)
41+
trivy image --severity MEDIUM,HIGH,CRITICAL torrust-tracker:local
42+
```
43+
44+
## Workflow
45+
46+
### Step 1: Check Existing Catalog First
47+
48+
Before analyzing any CVE, search the existing catalog:
49+
50+
```bash
51+
grep -R "CVE-<id>" docs/security/analysis/non-affecting/
52+
```
53+
54+
If already present and `requires-recheck-when` conditions have not changed, reuse the existing verdict.
55+
56+
### Step 2: Build and Scan
57+
58+
- Build local runtime image from `Containerfile`.
59+
- Run the gate scan with `HIGH,CRITICAL`.
60+
- Run optional full scan (`MEDIUM,HIGH,CRITICAL`) to capture trend context.
61+
62+
### Step 3: Update Scan History Docs
63+
64+
Update:
65+
66+
- `docs/security/docker/scans/torrust-tracker.md` with:
67+
- date/time, Trivy version, totals by severity
68+
- notable CVEs and rationale
69+
- `docs/security/docker/scans/README.md` summary table with latest status and date.
70+
71+
### Step 4: Document New Non-Affecting CVEs
72+
73+
For any new non-affecting CVE, create `docs/security/analysis/non-affecting/CVE-<id>.md` with:
74+
75+
- frontmatter fields:
76+
- `cve-id`
77+
- `date-analyzed`
78+
- `source`
79+
- `status: non-affecting`
80+
- `review-cadence`
81+
- `requires-recheck-when`
82+
- evidence-based explanation tied to tracker architecture
83+
- conditions that would invalidate the current verdict
84+
85+
### Step 5: Escalate Affecting CVEs
86+
87+
If a CVE is affecting:
88+
89+
- create/update a tracking issue
90+
- include impact, affected component, exploitability context, and remediation plan
91+
- update scan docs with current status and owner
92+
93+
## Recheck Triggers
94+
95+
Re-evaluate catalog verdicts when any of these happen:
96+
97+
- `Containerfile` base image changes
98+
- new runtime/system dependency is introduced
99+
- code path changes that satisfy a CVE file's `requires-recheck-when` condition
100+
101+
## Completion Checklist
102+
103+
- [ ] `trivy` gate scan executed (`HIGH,CRITICAL`)
104+
- [ ] scan history files updated
105+
- [ ] new CVEs cataloged or linked to existing catalog entries
106+
- [ ] affecting CVEs escalated
107+
- [ ] `linter all` passes

‎.github/workflows/security-scan.yaml‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
name: Security Scan
2+
3+
on:
4+
push:
5+
branches: [main, develop]
6+
paths:
7+
- "Containerfile"
8+
- ".github/workflows/security-scan.yaml"
9+
10+
pull_request:
11+
paths:
12+
- "Containerfile"
13+
- ".github/workflows/security-scan.yaml"
14+
15+
# Scheduled scans are important because new CVEs appear
16+
# even if the code or images didn't change
17+
schedule:
18+
- cron: "0 6 * * *" # Daily at 6 AM UTC
19+
20+
workflow_dispatch:
21+
22+
env:
23+
CARGO_TERM_COLOR: always
24+
25+
jobs:
26+
security-scan:
27+
name: Security Scan
28+
runs-on: ubuntu-latest
29+
# Scheduled scans pull the pre-built image; push/PR triggers rebuild from
30+
# source (Containerfile change). Rust compilation can exceed 25 min.
31+
timeout-minutes: 45
32+
permissions:
33+
contents: read
34+
security-events: write
35+
36+
steps:
37+
- name: Checkout code
38+
uses: actions/checkout@v4
39+
40+
# Scheduled scans use the pre-built develop image from Docker Hub.
41+
# Push/PR triggers on Containerfile changes need to build from source.
42+
- name: Determine image source
43+
id: image-source
44+
run: |
45+
if [ "${{ github.event_name }}" = "schedule" ]; then
46+
echo "method=pull" >> "$GITHUB_OUTPUT"
47+
echo "image=torrust/tracker:develop" >> "$GITHUB_OUTPUT"
48+
else
49+
echo "method=build" >> "$GITHUB_OUTPUT"
50+
echo "image=torrust-tracker:local" >> "$GITHUB_OUTPUT"
51+
fi
52+
53+
- name: Pull or build Docker image
54+
run: |
55+
if [ "${{ steps.image-source.outputs.method }}" = "pull" ]; then
56+
docker pull "${{ steps.image-source.outputs.image }}"
57+
else
58+
docker build -t "${{ steps.image-source.outputs.image }}" -f Containerfile .
59+
fi
60+
61+
# Human-readable output in logs
62+
# This NEVER fails the job; it's only for visibility
63+
- name: Display vulnerabilities (table format)
64+
uses: aquasecurity/trivy-action@0.35.0
65+
with:
66+
image-ref: ${{ steps.image-source.outputs.image }}
67+
format: "table"
68+
severity: "HIGH,CRITICAL"
69+
exit-code: "0"
70+
71+
# SARIF generation for GitHub Code Scanning
72+
#
73+
# IMPORTANT:
74+
# - exit-code MUST be 0
75+
# - Trivy sometimes exits with 1 even when no vulns exist
76+
# - GitHub Security UI is responsible for enforcement
77+
- name: Generate SARIF (Code Scanning)
78+
uses: aquasecurity/trivy-action@0.35.0
79+
with:
80+
image-ref: ${{ steps.image-source.outputs.image }}
81+
format: "sarif"
82+
output: "trivy-results.sarif"
83+
severity: "HIGH,CRITICAL"
84+
exit-code: "0"
85+
scanners: "vuln"
86+
87+
- name: Upload SARIF to Code Scanning
88+
uses: github/codeql-action/upload-sarif@v4
89+
if: always()
90+
with:
91+
sarif_file: trivy-results.sarif

‎README.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Torrust Tracker
22

3-
[![container_wf_b]][container_wf] [![coverage_wf_b]][coverage_wf] [![deployment_wf_b]][deployment_wf] [![testing_wf_b]][testing_wf] [![os_compat_wf_b]][os_compat_wf] [![db_compat_wf_b]][db_compat_wf] [![db_bench_wf_b]][db_bench_wf] [![docs_lint_wf_b]][docs_lint_wf]
3+
[![container_wf_b]][container_wf] [![coverage_wf_b]][coverage_wf] [![deployment_wf_b]][deployment_wf] [![testing_wf_b]][testing_wf] [![os_compat_wf_b]][os_compat_wf] [![db_compat_wf_b]][db_compat_wf] [![db_bench_wf_b]][db_bench_wf] [![docs_lint_wf_b]][docs_lint_wf] [![security_scan_wf_b]][security_scan_wf]
44

55
**Torrust Tracker** is a [BitTorrent][bittorrent] Tracker that matchmakes peers and collects statistics. Written in [Rust Language][rust] with the [Axum] web framework. **This tracker aims to be respectful to established standards, (both [formal][BEP 00] and [otherwise][torrent_source_felid]).**
66

@@ -270,6 +270,8 @@ This project was a joint effort by [Nautilus Cyberneering GmbH][nautilus] and [D
270270
[db_bench_wf_b]: ../../actions/workflows/db-benchmarking.yaml/badge.svg
271271
[docs_lint_wf]: ../../actions/workflows/docs-lint.yaml
272272
[docs_lint_wf_b]: ../../actions/workflows/docs-lint.yaml/badge.svg
273+
[security_scan_wf]: ../../actions/workflows/security-scan.yaml
274+
[security_scan_wf_b]: ../../actions/workflows/security-scan.yaml/badge.svg
273275
[bittorrent]: http://bittorrent.org/
274276
[rust]: https://www.rust-lang.org/
275277
[axum]: https://github.com/tokio-rs/axum

‎docs/issues/open/1459-docker-security-overhaul/ISSUE.md‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
---
2+
doc-type: issue
3+
issue-type: task
4+
status: completed
5+
priority: p2
6+
github-issue: 1459
7+
spec-path: docs/issues/open/1459-docker-security-overhaul/ISSUE.md
8+
branch: 1459-docker-security-overhaul
9+
related-pr: "https://github.com/torrust/torrust-tracker/pull/1958"
10+
last-updated-utc: 2026-06-29
11+
semantic-links:
12+
skill-links:
13+
- create-issue
14+
related-artifacts:
15+
- .github/workflows/security-scan.yaml
16+
- Containerfile
17+
- .github/workflows/container.yaml
18+
- .github/skills/dev/maintenance/run-manual-docker-security-scan/SKILL.md
19+
- docs/security/README.md
20+
- docs/security/docker/scans/
21+
- docs/security/docker/README.md
22+
- docs/security/analysis/non-affecting/
23+
---
24+
25+
# Issue #1459 - Docker Security Overhaul: Set Up Security Scanning Workflow
26+
27+
## Problem
28+
29+
The torrust-tracker Docker image contains known vulnerabilities that need to be regularly scanned and monitored. As demonstrated by the Trivy scan results, the current image has multiple security vulnerabilities including critical, high, and medium severity issues.
30+
31+
## Goal
32+
33+
Implement a scheduled workflow to periodically scan Docker images for vulnerabilities and misconfigurations, ensuring the security posture of the application is maintained.
34+
35+
## Acceptance Criteria
36+
37+
- [x] A new GitHub Actions workflow is created in `.github/workflows/security-scan.yaml`
38+
- [x] The workflow runs on a schedule (daily) to scan the Docker image
39+
- [x] The workflow builds the Docker image and scans it with Trivy
40+
- [x] Vulnerability findings are reported in both human-readable and SARIF formats
41+
- [x] The workflow integrates with the existing container build process
42+
- [x] The README.md badge row includes the new security scan workflow badge
43+
- [x] `docs/security/docker/scans/` is created with the first baseline scan report
44+
- [x] `docs/security/docker/README.md` provides scanning instructions
45+
- [x] `docs/security/README.md` provides a priority-tier security overview
46+
- [x] Per-CVE analysis files created in `docs/security/analysis/non-affecting/` for each
47+
MEDIUM vulnerability found in the baseline scan
48+
- [x] `docs/security/analysis/README.md` documents the catalog strategy and recheck policy
49+
- [x] A maintenance skill exists at
50+
`.github/skills/dev/maintenance/run-manual-docker-security-scan/SKILL.md`
51+
documenting how to run and document manual Docker security scans
52+
53+
## Implementation Plan
54+
55+
### Step 1: Create Security Scan Workflow
56+
57+
Create a new workflow file `.github/workflows/security-scan.yaml` that:
58+
59+
- Runs on a schedule (daily at 6 AM UTC) and on push to main/develop branches
60+
- Builds the Docker image using the Containerfile
61+
- Scans the image with Trivy
62+
- Reports results in both table and SARIF formats
63+
64+
### Step 2: Configure Trivy Scanning
65+
66+
Configure the workflow to:
67+
68+
- Use Trivy to scan the Docker image
69+
- Report vulnerabilities in both human-readable table format and SARIF format for GitHub Code Scanning
70+
- Generate SARIF output for integration with GitHub Security features
71+
72+
### Step 3: Integrate with Existing Workflows
73+
74+
Ensure the security scan workflow integrates properly with the existing container workflow.
75+
76+
### Step 4: Add Workflow Badge to README.md
77+
78+
Add the security scan workflow badge to the README.md header row and consistent reference links at the bottom, following the same pattern as existing workflow badges.
79+
80+
### Step 5: Create Security Documentation and Run Baseline Scan
81+
82+
Create `docs/security/docker/` structure mirroring the deployer's security docs pattern:
83+
84+
- `docs/security/docker/README.md` — scanning instructions and context
85+
- `docs/security/docker/scans/README.md` — scan history index table
86+
- `docs/security/docker/scans/torrust-tracker.md` — detailed scan report with vulnerability analysis
87+
88+
Run the first manual baseline scan of the production `release` stage image and document all findings, including vulnerability analysis and severity assessment.
89+
90+
### Step 6: Create Top-Level Security Overview
91+
92+
Create `docs/security/README.md` providing a priority-tier overview of security areas for the project, mirroring the deployer's top-level security README pattern:
93+
94+
- Priority 1: Production Docker image (critical, internet-exposed)
95+
- Priority 2: Vulnerability analysis (evaluation and tracking)
96+
- Priority 3: Build chain security (lower-risk, build-time only)
97+
- Current security status summary
98+
- Scan tooling reference
99+
100+
### Step 7: Create Non-Affecting CVE Catalog
101+
102+
Create per-CVE analysis files in `docs/security/analysis/non-affecting/` for each
103+
vulnerability found in the baseline scan, following this pattern:
104+
105+
```text
106+
non-affecting/
107+
├── CVE-2026-5435.md # glibc TSIG
108+
├── CVE-2026-5450.md # glibc scanf
109+
├── CVE-2026-5928.md # glibc ungetwc
110+
├── CVE-2026-6238.md # glibc DNS response
111+
└── CVE-2026-27171.md # zlib CRC32
112+
```
113+
114+
Each file includes:
115+
116+
- Frontmatter with `cve-id`, `date-analyzed`, `source`, `status`, `review-cadence`,
117+
and `requires-recheck-when` conditions
118+
- Vulnerability description and severity
119+
- Evidence-based rationale for why it does not affect the tracker
120+
- Conditions that would change the verdict
121+
122+
Update `docs/security/analysis/README.md` to document the catalog strategy (one catalog
123+
for all vulnerability sources, per-CVE files preferred, with recheck policy).
124+
125+
### Step 8: Add Maintenance Skill for Manual Security Scans
126+
127+
Create a new skill at
128+
`.github/skills/dev/maintenance/run-manual-docker-security-scan/SKILL.md` to standardize
129+
how contributors run manual Docker security scans and maintain scan documentation.
130+
131+
The skill should include:
132+
133+
- build and scan commands (`docker build`, `trivy image`)
134+
- triage workflow (check catalog first, then analyze)
135+
- documentation update requirements (`docs/security/docker/scans/*` and
136+
`docs/security/analysis/non-affecting/CVE-*.md`)
137+
- recheck triggers and escalation path for affecting vulnerabilities
138+
139+
## References
140+
141+
- Original issue: https://github.com/torrust/torrust-tracker/issues/1459
142+
- Related issue #1630
143+
- Trivy documentation for GitHub Actions integration
144+
- Tracker Deployer security scan workflow for reference: https://github.com/torrust/torrust-tracker-deployer/blob/main/.github/workflows/docker-security-scan.yml
145+
146+
## Verification Plan
147+
148+
### Automatic Checks
149+
150+
- [ ] Workflow file is created and syntactically correct
151+
- [ ] Workflow runs successfully on schedule
152+
- [ ] Trivy scan produces expected output
153+
154+
### Manual Verification Scenarios
155+
156+
- [ ] Run workflow manually to verify it scans the image
157+
- [ ] Verify vulnerability reports are generated correctly
158+
- [ ] Confirm workflow integrates with existing container workflow

0 commit comments

Comments
 (0)