Skip to content

Commit b63535a

Browse files
committed
docs(security): publish CVE-scanning pipeline policy and scripts
Publish the pipeline's policy documents (SECURITY_PIPELINE_POLICY, SECURITY_TRIAGE_MATRIX, SECURITY_FINDING_STATUS_MODEL) and its discovery/scanning/reporting scripts under docs/security/pipeline/, so the method is auditable independently of the finding data. These hold no finding data; per-finding reports and triage state stay in the private cozystack/security-scanner repository. Example identifiers in the status model are illustrative placeholders. Signed-off-by: Timur Tukaev <[email protected]>
1 parent e3ab40e commit b63535a

10 files changed

Lines changed: 2021 additions & 0 deletions

File tree

‎docs/security/pipeline/README.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Cozystack security-scanning pipeline — published policy and scripts
2+
3+
These are published copies of the Cozystack CVE-scanning pipeline's policy documents and
4+
scripts, so that its method is auditable independently of the finding data it produces.
5+
The **source of truth is the private `cozystack/security-scanner` repository**, which also
6+
holds the per-finding reports and triage state that are **not** published here.
7+
8+
## Contents
9+
10+
- `SECURITY_PIPELINE_POLICY.md` — what the pipeline scans, on what schedule, and what is
11+
public vs private.
12+
- `SECURITY_TRIAGE_MATRIX.md` — severity levels, triage clocks and fix targets.
13+
- `SECURITY_FINDING_STATUS_MODEL.md` — the finding lifecycle and status model. The example
14+
identifiers in it are illustrative placeholders; real triage decisions live in the
15+
private state.
16+
- `scripts/` — the discovery, scanning and reporting scripts (`discover.sh`, `scan.sh`,
17+
`report.py`, `monthly.py`, `sync_issues.py`, `backfill_issues.py`), published so the
18+
method can be audited. These are reference copies; the runnable versions live in the
19+
private repository against organization-scoped credentials.
20+
21+
## Disclosure rule
22+
23+
Severity-level aggregate counts are published (see [`../reports/`](../reports/)); individual
24+
not-yet-fixed findings are not named, because a CVE ID plus an affected package plus this
25+
project's public, version-pinned component list is enough to locate unpatched exposure in a
26+
running deployment. That is why the per-finding reports and triage state in the private
27+
repository are not mirrored here.
Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# Security Finding Status Model
2+
3+
## Statuses
4+
5+
| Status | Meaning | Who sets it | Next action |
6+
|--------|---------|-------------|-------------|
7+
| `new` | Scanner found this CVE, no human has reviewed it yet | Automated (default) | Triage needed |
8+
| `confirmed` | Maintainer verified this is a real, applicable vulnerability | Maintainer | Assign owner, plan fix |
9+
| `in-progress` | Fix is being worked on | Maintainer / owner | Track to completion |
10+
| `fixed` | Fix has been released | Maintainer | Close, update advisory if needed |
11+
| `false-positive` | Scanner finding does not apply to our context | Maintainer | Document reason, no further action |
12+
| `accepted-risk` | Real vulnerability, but we consciously accept the risk | Maintainer | Document reason, review periodically |
13+
14+
## Lifecycle
15+
16+
```
17+
new → confirmed → in-progress → fixed
18+
new → false-positive
19+
new → accepted-risk
20+
confirmed → accepted-risk (if fix becomes impractical)
21+
accepted-risk → confirmed (if circumstances change)
22+
```
23+
24+
## Recording Triage Decisions
25+
26+
Triage decisions are stored in `state/triage-overrides.json`:
27+
28+
```json
29+
{
30+
"CVE-YYYY-NNNN1": {
31+
"status": "false-positive",
32+
"reason": "example: library CVE in a base image; the distribution has backported the fix",
33+
"decided_by": "maintainer-handle",
34+
"decided_at": "YYYY-MM-DD",
35+
"review_after": null
36+
},
37+
"CVE-YYYY-NNNN2": {
38+
"status": "accepted-risk",
39+
"reason": "example: CVE in a component or code path not exercised by Cozystack's usage",
40+
"decided_by": "maintainer-handle",
41+
"decided_at": "YYYY-MM-DD",
42+
"review_after": "YYYY-MM-DD"
43+
},
44+
"CVE-YYYY-NNNN3": {
45+
"status": "in-progress",
46+
"reason": "example: vulnerability with an upstream fix available; component bump in progress",
47+
"decided_by": "maintainer-handle",
48+
"decided_at": "YYYY-MM-DD",
49+
"fix_version": "x.y.z",
50+
"fix_pr": "https://github.com/cozystack/cozystack/pull/NNNN",
51+
"review_after": null
52+
}
53+
}
54+
```
55+
56+
> The identifiers above are illustrative placeholders showing the record shape only.
57+
> Live triage decisions are kept in the security pipeline's private state, since a real
58+
> CVE crossed with this project's public component list can locate unpatched exposure.
59+
60+
## Required Fields
61+
62+
| Field | Required | Description |
63+
|-------|----------|-------------|
64+
| `status` | Yes | One of: `confirmed`, `in-progress`, `fixed`, `false-positive`, `accepted-risk` |
65+
| `reason` | Yes | Human-readable explanation of the decision |
66+
| `decided_by` | Yes | GitHub handle of the maintainer |
67+
| `decided_at` | Yes | Date of the decision (YYYY-MM-DD) |
68+
| `review_after` | For `accepted-risk` | Date to re-evaluate (quarterly recommended) |
69+
| `fix_version` | For `fixed` | Version where the fix is included |
70+
| `fix_pr` | For `in-progress` / `fixed` | Link to the fix PR |
71+
72+
## Periodic Review
73+
74+
- `accepted-risk` findings must be reviewed every 90 days
75+
- If `review_after` date has passed, the finding is flagged in the weekly digest
76+
- `false-positive` findings are re-checked automatically when Trivy DB updates (if the CVE reappears with different metadata, it becomes `new` again)
Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
# Security Pipeline Policy
2+
3+
## Purpose
4+
5+
This document defines how the Cozystack project handles vulnerability findings from automated scanners, from initial detection through triage, remediation, and disclosure.
6+
7+
## Scope
8+
9+
This policy applies to:
10+
- All non-fork repositories in the `cozystack` GitHub organization
11+
- All container images shipped as part of Cozystack releases
12+
- All third-party dependencies (Go modules, base images, Helm chart components)
13+
14+
## Ownership
15+
16+
The security pipeline is maintained by the Cozystack security team (subset of project maintainers with write access to this repository).
17+
18+
Security contact: **[email protected]**
19+
20+
## Pipeline Overview
21+
22+
```
23+
Discovery → Scan → Normalize/Deduplicate → Triage → Route → Track → Fix → Disclose → Close
24+
```
25+
26+
### 1. Discovery (automated, every 6 hours)
27+
28+
The pipeline automatically discovers components across all organization repositories:
29+
- Go dependencies (`go.mod`)
30+
- Dockerfile base images (`FROM` directives)
31+
- Helm chart images (`values.yaml`, templates)
32+
- Packages from `packages/apps/*`, `packages/system/*`, `packages/core/*`
33+
34+
### 2. Scan (automated)
35+
36+
Trivy scans all discovered components against known vulnerability databases (NVD, vendor advisories, GitHub Advisory Database).
37+
38+
### 3. Normalize / Deduplicate (automated)
39+
40+
- Same CVE across multiple images → single finding with all affected components listed
41+
- Already-reported CVEs → skipped (tracked in `state/reported-cves.json`)
42+
- Triage overrides → applied from `state/triage-overrides.json`
43+
44+
### 4. Triage (manual, by maintainers)
45+
46+
Every new finding must be triaged by a maintainer. See [SECURITY_FINDING_STATUS_MODEL.md](SECURITY_FINDING_STATUS_MODEL.md) for available statuses.
47+
48+
Triage questions:
49+
1. Is this CVE in a **shipped artifact** or only in dev/build tooling?
50+
2. Is the vulnerable **code path actually reachable** in our usage?
51+
3. Has the OS distro already **backported** the fix?
52+
4. Is a **fix available** upstream?
53+
5. What is the **realistic impact** on a Cozystack deployment?
54+
55+
### 5. Routing (severity-based)
56+
57+
| Severity | Channel | Timing |
58+
|----------|---------|--------|
59+
| **Critical** | Individual report in `reports/critical/` + private notification to security team | Immediate (within 6 hours of detection) |
60+
| **High** | Included in weekly maintainer digest | Weekly (Tuesday 06:00 CET) |
61+
| **Medium** | Included in weekly maintainer digest | Weekly |
62+
| **Low** | Included in weekly maintainer digest | Weekly |
63+
| **Informational** | Monthly summary only | Monthly |
64+
65+
### 6. Fix Tracking
66+
67+
- CRITICAL: maintainer assigns owner within 1 business day
68+
- Fixes are tracked in `state/triage-overrides.json` with status `in-progress`
69+
- When fixed, status changes to `fixed` with the fix version noted
70+
71+
### 7. Disclosure
72+
73+
- **CRITICAL/HIGH (confirmed):** GitHub Security Advisory (draft, then published after fix)
74+
- **MEDIUM/LOW:** Mentioned in monthly public security summary
75+
- **Raw scanner output** is never published
76+
- **False positives and accepted risks** are documented internally but not published
77+
78+
## What Is Private
79+
80+
- Raw scan results
81+
- Unconfirmed CRITICAL/HIGH findings
82+
- Exploit details before fix is available
83+
- `state/` directory contents
84+
- Triage discussions
85+
86+
## What Is Public (after triage and remediation)
87+
88+
- GitHub Security Advisories (post-fix)
89+
- Monthly security summaries
90+
- Release notes mentioning security fixes
91+
- The existence of this security pipeline (not its internal reports)
92+
93+
## Maintainer Responsibilities
94+
95+
See [SECURITY_TRIAGE_MATRIX.md](SECURITY_TRIAGE_MATRIX.md) for detailed SLAs.
96+
97+
Maintainers must:
98+
1. Review the weekly digest within 3 business days
99+
2. Triage new CRITICAL findings within 1 business day
100+
3. Assign an owner for confirmed CRITICAL/HIGH findings
101+
4. Document triage decisions in `state/triage-overrides.json`
102+
5. Not disclose CRITICAL/HIGH details publicly before a fix is available
Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# Security Triage Matrix
2+
3+
## Severity → Action → SLA
4+
5+
| | Critical | High | Medium | Low | Informational |
6+
|---|---|---|---|---|---|
7+
| **Acknowledgment** | 4 hours | 1 business day | 3 business days | Weekly digest | Monthly summary |
8+
| **Triage** | 1 business day | 3 business days | 10 business days | 30 days | No action required |
9+
| **Owner assigned** | 1 business day | 5 business days | Best effort | Best effort | N/A |
10+
| **Remediation plan** | 2 business days | 10 business days | Next release | Best effort | N/A |
11+
| **Fix target** | 7 days | 30 days | 90 days | No hard deadline | N/A |
12+
| **Disclosure** | After fix + 7 days | After fix + 14 days | Monthly report | Monthly report | Monthly report |
13+
14+
## Routing
15+
16+
| Severity | Immediate action | Report location | Notification |
17+
|---|---|---|---|
18+
| **Critical** | Individual report saved to `reports/critical/` | `reports/critical/YYYY-MM-DD-CVE-XXXX.md` | Security team notified directly |
19+
| **High** | Added to weekly digest | `reports/weekly/YYYY-MM-DD-security-report.md` | Weekly maintainer digest |
20+
| **Medium** | Added to weekly digest | `reports/weekly/YYYY-MM-DD-security-report.md` | Weekly maintainer digest |
21+
| **Low** | Added to weekly digest | `reports/weekly/YYYY-MM-DD-security-report.md` | Weekly maintainer digest |
22+
| **Informational** | Logged only | Monthly summary | No direct notification |
23+
24+
## Triage Decision Tree
25+
26+
```
27+
New CVE found by scanner
28+
│
29+
├─ Is it in a shipped artifact (not dev/test only)?
30+
│ ├─ No → status: false-positive (reason: "dev dependency only")
31+
│ └─ Yes ↓
32+
│
33+
├─ Is the vulnerable code path reachable in our usage?
34+
│ ├─ No → status: accepted-risk (reason: "code path not reachable")
35+
│ └─ Yes / Uncertain ↓
36+
│
37+
├─ Has the distro already backported the fix?
38+
│ ├─ Yes → status: false-positive (reason: "distro backport applied")
39+
│ └─ No ↓
40+
│
41+
├─ Is a fix available upstream?
42+
│ ├─ Yes → status: confirmed, assign owner, schedule update
43+
│ └─ No ↓
44+
│
45+
└─ Is the CVE older than 365 days with no fix?
46+
├─ Yes → status: accepted-risk (reason: "unfixed upstream, monitoring")
47+
└─ No → status: confirmed, monitor upstream for fix
48+
```
49+
50+
## Escalation
51+
52+
- If a CRITICAL finding is not triaged within 1 business day → escalate to all maintainers
53+
- If a confirmed CRITICAL has no fix plan within 2 business days → discuss workaround/mitigation
54+
- If a HIGH finding is not triaged within 5 business days → auto-escalate in next digest

0 commit comments

Comments
 (0)