Skip to content

Commit aa885c3

Browse files
committed
docs(security): re-sync published pipeline copies to the current hardened revision
The published copies trailed the upstream pipeline by several revisions, and that older revision carried defects since fixed upstream: a re-review stamp spent before its issue existed, so a failed issue creation could lose a CRITICAL for good; a sync ordering guard that never fired on stored records; and a re-review that the original issue's label would revert on the next sync. Publishing the method only helps an auditor if it is the method that runs. All ten copies are again byte-exact with the upstream head. The status model is now byte-exact as well rather than hand-sanitized, because upstream itself uses placeholder identifiers. The README says the copies, documents included, track the upstream head byte for byte, and that the "no upstream fix" naming exception is a maintainer decision in the written report, never the generator's. Assisted-by: LLM Signed-off-by: tym83 <[email protected]>
1 parent 6df1bc4 commit aa885c3

8 files changed

Lines changed: 283 additions & 113 deletions

File tree

‎docs/security/pipeline/README.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,8 @@ holds the per-finding reports and triage state that are **not** published here.
77

88
These copies correspond to `cozystack/security-scanner` PR #1004, the revision that carries
99
the state-integrity, HIGH-path, review_after and scan-failure hardening described below.
10-
They are kept byte-for-byte in step with its head; once #1004 merges they match
11-
`security-scanner` `main`, the revision that runs on schedule.
10+
Every copied file, documents included, is kept byte-for-byte in step with its head; once
11+
#1004 merges they match `security-scanner` `main`, the revision that runs on schedule.
1212

1313
## Contents
1414

@@ -36,3 +36,5 @@ One exception, consistent with [`../reports/README.md`](../reports/README.md): a
3636
with **no upstream fix available** is named, with mitigation guidance. There is nothing to
3737
wait for, and silence serves nobody — an adopter needs to know when a mitigation is the only
3838
available control. Findings awaiting a released fix stay aggregate-only until it ships.
39+
This exception is applied by maintainers when they write the published report; the monthly
40+
generator in `scripts/monthly.py` never names an unfixed finding on its own.

‎docs/security/pipeline/SECURITY_FINDING_STATUS_MODEL.md‎

Lines changed: 12 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -31,21 +31,24 @@ Triage decisions are stored in `state/triage-overrides.json`:
3131
"status": "false-positive",
3232
"reason": "example: library CVE in a base image; the distribution has backported the fix",
3333
"decided_by": "maintainer-handle",
34-
"decided_at": "YYYY-MM-DD",
34+
"decided_at": "YYYY-MM-DDTHH:MM:SS+00:00",
35+
"closed_at": "YYYY-MM-DDTHH:MM:SS+00:00",
3536
"review_after": null
3637
},
3738
"CVE-YYYY-NNNN2": {
3839
"status": "accepted-risk",
3940
"reason": "example: CVE in a component or code path not exercised by Cozystack's usage",
4041
"decided_by": "maintainer-handle",
41-
"decided_at": "YYYY-MM-DD",
42+
"decided_at": "YYYY-MM-DDTHH:MM:SS+00:00",
43+
"closed_at": "YYYY-MM-DDTHH:MM:SS+00:00",
4244
"review_after": "YYYY-MM-DD"
4345
},
4446
"CVE-YYYY-NNNN3": {
4547
"status": "in-progress",
4648
"reason": "example: vulnerability with an upstream fix available; component bump in progress",
4749
"decided_by": "maintainer-handle",
48-
"decided_at": "YYYY-MM-DD",
50+
"decided_at": "YYYY-MM-DDTHH:MM:SS+00:00",
51+
"closed_at": "YYYY-MM-DDTHH:MM:SS+00:00",
4952
"fix_version": "x.y.z",
5053
"fix_pr": "https://github.com/cozystack/cozystack/pull/NNNN",
5154
"review_after": null
@@ -61,16 +64,18 @@ Triage decisions are stored in `state/triage-overrides.json`:
6164

6265
| Field | Required | Description |
6366
|-------|----------|-------------|
64-
| `status` | Yes | One of: `confirmed`, `in-progress`, `fixed`, `false-positive`, `accepted-risk` |
67+
| `status` | Yes | One of: `new`, `confirmed`, `in-progress`, `fixed`, `false-positive`, `accepted-risk`. `new` is the lifecycle entry state — a freshly-surfaced or awaiting-triage finding, including one the pipeline re-surfaces when an `accepted-risk` review window elapses |
6568
| `reason` | Yes | Human-readable explanation of the decision |
6669
| `decided_by` | Yes | GitHub handle of the maintainer |
67-
| `decided_at` | Yes | Date of the decision (YYYY-MM-DD) |
70+
| `decided_at` | Yes | Record time — when the pipeline recorded the decision. Full ISO-8601 (`YYYY-MM-DDTHH:MM:SS+00:00`); a bare `YYYY-MM-DD` is still accepted for hand-written entries. This is what the monthly report buckets on |
71+
| `closed_at` | Yes | Event time — when the decision was actually made (the issue's close time for a synced decision, else the same as `decided_at`). Full ISO-8601. `sync_issues.py` orders decisions by this to break ties and reject a stale issue that reverts a newer decision, so a hand-written entry must carry it |
72+
| `issue_number` / `issue_url` | For a decision synced from an issue | The issue whose label the record reflects. A label change on this issue is applied by the next triage sync even though its close time is unchanged; a different issue applies only if it closed later. When a review window elapses the pipeline moves these to the new re-review issue (or drops them when no issue is filed), so the old issue's label cannot revert the re-review |
6873
| `review_after` | For `accepted-risk` | Date to re-evaluate (quarterly recommended) |
6974
| `fix_version` | For `fixed` | Version where the fix is included |
7075
| `fix_pr` | For `in-progress` / `fixed` | Link to the fix PR |
7176

7277
## Periodic Review
7378

7479
- `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)
80+
- If `review_after` date has passed, the finding re-surfaces: CRITICAL and HIGH get a new triage issue, MEDIUM and LOW appear in the weekly report. Its record returns to `new` only once that issue exists (a failed issue creation is retried on the next run), and from then on it is the new issue, not the original one, whose label decides it
81+
- `false-positive` is terminal: it carries no `review_after` and suppresses the finding indefinitely. There is no automatic re-check on Trivy database updates; if a false-positive needs revisiting (e.g. the finding's context changed), a maintainer re-opens or re-labels its issue and the next triage sync picks up the new decision.

‎docs/security/pipeline/SECURITY_PIPELINE_POLICY.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -71,9 +71,9 @@ Triage questions:
7171
### 7. Disclosure
7272

7373
- **CRITICAL/HIGH (confirmed):** GitHub Security Advisory (draft, then published after fix)
74-
- **MEDIUM/LOW:** Mentioned in monthly public security summary
74+
- **Monthly public summary:** a finding is named (CVE identifier, package, fixed version) only once its fix is released. **In-progress and accepted-risk findings are published as severity counts only — CVE identifiers and package names are withheld until a fix is released**, because a named unfixed CVE crossed with this project's public, version-pinned component list locates unpatched exposure in a running deployment. The monthly report generator enforces this.
7575
- **Raw scanner output** is never published
76-
- **False positives and accepted risks** are documented internally but not published
76+
- **False positives** are documented internally but not published
7777

7878
## What Is Private
7979

‎docs/security/pipeline/scripts/backfill_issues.py‎

Lines changed: 19 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -13,14 +13,13 @@
1313
"""
1414

1515
import argparse
16-
import json
1716
import os
18-
import re
1917
import subprocess
2018
import time
21-
from datetime import datetime, timezone
2219

23-
from statelib import load_json, save_json, override_suppresses, age_drops, cve_age_days
20+
from statelib import (
21+
load_json, save_json, filter_decision, cve_age_days, AGE_DROPPED,
22+
)
2423

2524
REPO_ROOT = os.path.join(os.path.dirname(__file__), "..")
2625
STATE_DIR = os.path.join(REPO_ROOT, "state")
@@ -39,14 +38,21 @@
3938

4039

4140
def should_skip(cve_id, data, triage):
42-
"""Apply the same filters as report.py — via the shared statelib helpers, so
43-
the CRITICAL/HIGH age carve-out and the review_after check cannot drift out of
44-
sync between the two scripts (which is exactly what happened before)."""
45-
if override_suppresses(cve_id, triage):
46-
return True, f"triaged as {triage[cve_id].get('status', '')}"
47-
if age_drops(data, cve_id):
48-
return True, f"unfixed {cve_age_days(cve_id)}d"
49-
return False, None
41+
"""The same decision as report.classify_filter: both call statelib.filter_decision,
42+
so they cannot drift.
43+
44+
dev_only is False because a reported-cves record keeps only target repositories,
45+
not the component paths that decide it; a record exists only because report.py
46+
already ruled the finding not dev-only when it reported it.
47+
48+
This is a repair tool: it only decides whether to create an issue. It neither
49+
performs the re-review transition for a review-due override nor persists an
50+
age-drop — report.py owns both on its next run, so there is no mutation to keep
51+
mirrored between the two scripts."""
52+
skip, reason = filter_decision(cve_id, data, triage, dev_only=False)
53+
if reason == AGE_DROPPED:
54+
reason = f"unfixed {cve_age_days(cve_id)}d"
55+
return skip, reason
5056

5157

5258
def create_issue(cve_id, data):
@@ -163,7 +169,7 @@ def main():
163169
# Rate limit: GitHub allows 100 requests/min for authenticated users
164170
time.sleep(1)
165171
else:
166-
print(f" Failed, stopping to avoid rate limit issues")
172+
print(" Failed, stopping to avoid rate limit issues")
167173
break
168174

169175
save_json(REPORTED_FILE, reported)

‎docs/security/pipeline/scripts/monthly.py‎

Lines changed: 15 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -10,12 +10,11 @@
1010
accepted as risk during the past month.
1111
"""
1212

13-
import json
1413
import os
1514
from collections import Counter
1615
from datetime import datetime, timezone, timedelta
1716

18-
from statelib import load_json
17+
from statelib import load_json, save_json, RESOLVED_STATUSES
1918

2019
REPO_ROOT = os.path.join(os.path.dirname(__file__), "..")
2120
STATE_DIR = os.path.join(REPO_ROOT, "state")
@@ -111,9 +110,15 @@ def main():
111110
# Separate human triage decisions from machine auto-dismissals: report.py writes
112111
# `decided_by: pipeline-auto` accepted-risk entries into the same file, and a
113112
# "Total triaged" figure the prose calls maintainer-reviewed must not silently
114-
# grow with findings nobody looked at.
113+
# grow with findings nobody looked at. Auto-suppressed counts only entries still
114+
# in a suppressing (resolved) status: once report.py surfaces a machine entry for
115+
# re-review its status leaves RESOLVED_STATUSES, so it is no longer suppressed and
116+
# must not be counted under "auto-suppressed, pending review".
115117
total_triaged = sum(1 for v in triage.values() if v.get("decided_by") != "pipeline-auto")
116-
total_auto_suppressed = sum(1 for v in triage.values() if v.get("decided_by") == "pipeline-auto")
118+
total_auto_suppressed = sum(
119+
1 for v in triage.values()
120+
if v.get("decided_by") == "pipeline-auto" and v.get("status") in RESOLVED_STATUSES
121+
)
117122

118123
# Build report
119124
new_summary_parts = []
@@ -219,10 +224,13 @@ def sev_counts(rows):
219224
},
220225
}
221226

227+
# Atomic write: latest.json is the public website payload, and a run killed
228+
# mid-dump must not leave a truncated file for the site to serve. save_json
229+
# writes to a temp file and renames over the target, like every other state
230+
# writer.
222231
json_path = os.path.join(REPORTS_DIR, "monthly", "latest.json")
223-
with open(json_path, "w") as f:
224-
json.dump(website_json, f, indent=2)
225-
print(f"Saved: reports/monthly/latest.json")
232+
save_json(json_path, website_json)
233+
print("Saved: reports/monthly/latest.json")
226234

227235
print(f"\nSummary for {month_label}:")
228236
print(f" New: {len(new_this_month)}, Fixed: {len(fixed_this_month)}, In-progress: {len(in_progress)}")

0 commit comments

Comments
 (0)