Development

.github/workflows/nightly.yml

@@ -277,28 +277,23 @@ jobs:
 
       - name: pip-audit (transitive CVE scan)
         run: |
-          # pip-audit returns non-zero on any finding; capture the JSON
-          # and apply our own severity policy via tools/check_pip_audit.py.
+          # pip-audit captures every finding; tools/check_pip_audit.py
+          # applies ForgeLM's severity policy (HIGH → fail,
+          # MEDIUM → ::warning::, UNKNOWN → fail closed) on the JSON.
           #
-          # Vulnerability ignores (each ignore must carry a written
-          # justification + remove-after condition; review at every
-          # release cycle).  Issue #37 tracks the active set.
-          #
-          # CVE-2026-1839 — transformers, fix: 5.0.0rc3 (release candidate).
-          # ForgeLM's pyproject pins ``transformers>=4.38.0,<5.0.0`` and
-          # the 5.x branch is a major version bump that breaks downstream
-          # callers (TRL adapter signature changes + tokenizer-config
-          # API drift).  The CVE has no 4.x backport at the time of
-          # ignore (verified 2026-05-10).  Stop-gap until either (a)
-          # transformers ships a 4.x point release with the fix or
-          # (b) ForgeLM cuts a tracked major-version-bump cycle that
-          # raises the upper bound.  Re-evaluate at each release.
+          # Project-internal CVE suppressions live in
+          # tools/pip_audit_ignores.yaml; --ignores is opt-in so
+          # standalone deployer invocations of check_pip_audit.py
+          # inherit nothing (per docs/reference/supply_chain_security.md).
+          # Adding an entry to that file is a security-policy change;
+          # see the file header for the required schema (id, package,
+          # reason, threat_model, verified_at, reevaluate_after).
           pip-audit \
               --format json \
               --output /tmp/pip-audit.json \
-              --ignore-vuln CVE-2026-1839 \
               || true
-          python3 tools/check_pip_audit.py /tmp/pip-audit.json
+          python3 tools/check_pip_audit.py /tmp/pip-audit.json \
+              --ignores tools/pip_audit_ignores.yaml
 
       - name: bandit (static security analysis)
         run: |

docs/reference/supply_chain_security-tr.md

@@ -109,11 +109,33 @@ python3 tools/check_pip_audit.py /tmp/pip-audit.json
 
 ### Suppression (kasıtlı CVE kabulü)
 
-Bir CVE kabul edildiyse ama henüz düzeltilemiyorsa (upstream release
-beklemede, vb.), operatörün risk acceptance log'unda dokümante edip
-nightly run için bastırmak amacıyla `pip-audit --ignore-vuln <CVE-ID>`
-kullanın. ForgeLM proje-seviyesinde bir ignore listesi göndermez —
-her suppression operatör-tarafında ve quarterly-reviewed olmalıdır.
+ForgeLM varsayılan bir proje-seviyesi ignore listesi göndermez —
+`python3 tools/check_pip_audit.py /tmp/pip-audit.json`'u standalone
+çalıştıran bir deployer hiçbir suppression miras almaz ve tam
+filtresiz gate'i görür. Deployer-tarafı kabulleri kendi risk
+acceptance log'unuzda dokümante edin ve opt-in flag ile geçin:
+
+```bash
+python3 tools/check_pip_audit.py /tmp/pip-audit.json \
+    --ignores path/to/your_ignores.yaml
+```
+
+YAML dosyasındaki her giriş `id`, `package`, `reason`, `threat_model`,
+`verified_at`, ve `reevaluate_after` taşımalıdır (opsiyonel: `aliases`,
+`references`); herhangi bir zorunlu alanın eksikliği — ya da bir alanın
+hatalı değer taşıması (boş string, `YYYY-MM-DD` olmayan bir
+`verified_at`, ya da string listesi olmayan `aliases`) — gate'in
+kapalı fail etmesine yol açar; böylece dokümante edilmemiş bir
+suppression sessizce inemez. Her eşleşme run summary'de `::notice::`
+annotation olarak loglanır; audit trail görünür kalır.
+
+ForgeLM'in kendi nightly'si proje-içi triage için check-in edilmiş
+bir [`tools/pip_audit_ignores.yaml`](../../tools/pip_audit_ignores.yaml)
+taşır (şu an transformers `CVE-2026-1839` artı 2026-05-21 döngüsünden
+gelen dokuz no-fix torch advisory'si ve bir OSV-yanlış-sınıflandırılmış
+markdown kaydı). Bu dosya yalnız projenin kendi workflow'u tarafından
+`--ignores` ile tüketilir; deployer'lar miras almaz. Her release
+cycle'da gözden geçirilir.
 
 ## bandit (static security analysis)
 

docs/reference/supply_chain_security.md

@@ -109,12 +109,33 @@ python3 tools/check_pip_audit.py /tmp/pip-audit.json
 
 ### Suppression (intentional CVE acceptance)
 
-If a CVE is acknowledged but not yet fixable (upstream release
-pending, etc.), document it in the deployer's risk acceptance log
-and use `pip-audit --ignore-vuln <CVE-ID>` to suppress it for the
-nightly run. ForgeLM does NOT ship a project-level
-ignore list — every suppression should be deployer-side and
-quarterly-reviewed.
+ForgeLM does NOT ship a default project-level ignore list — a
+deployer running `python3 tools/check_pip_audit.py /tmp/pip-audit.json`
+standalone inherits no suppressions and sees the full unfiltered
+gate. Document any deployer-side acceptance in your own risk
+acceptance log and pass it via the opt-in flag:
+
+```bash
+python3 tools/check_pip_audit.py /tmp/pip-audit.json \
+    --ignores path/to/your_ignores.yaml
+```
+
+Each entry in the YAML file must carry `id`, `package`, `reason`,
+`threat_model`, `verified_at`, and `reevaluate_after` (optional:
+`aliases`, `references`); missing any required field — or giving one
+a malformed value (an empty string, a `verified_at` that is not a
+`YYYY-MM-DD` date, or `aliases` that is not a list of strings) —
+causes the gate to fail closed, so an undocumented suppression cannot
+land silently. Every match is logged as a `::notice::` annotation in
+the run summary so the audit trail stays visible.
+
+ForgeLM's own nightly does carry a checked-in
+[`tools/pip_audit_ignores.yaml`](../../tools/pip_audit_ignores.yaml) for
+project-internal triage (currently transformers `CVE-2026-1839` plus
+nine no-fix torch advisories and one OSV-misclassified markdown
+record from the 2026-05-21 cycle). That file is consumed only by the
+project's own workflow via `--ignores`; deployers do not inherit it.
+Review at every release cycle.
 
 ## bandit (static security analysis)
 

docs/usermanuals/en/operations/supply-chain.md

@@ -60,13 +60,27 @@ python3 tools/check_bandit.py /tmp/bandit.json
 
 ## When a CVE is acknowledged but not yet fixable
 
-If upstream has not yet released the fix and you've documented the CVE in your deployer-side risk acceptance log:
+If upstream has not yet released the fix and you've documented the CVE in your deployer-side risk acceptance log, write a YAML ignore file and pass it to `check_pip_audit.py` via the opt-in `--ignores` flag:
+
+```yaml
+# your_ignores.yaml
+ignores:
+  - id: CVE-2026-XXXX
+    package: some-pkg
+    reason: brief one-line summary
+    threat_model: why your deployment's surface does not expose the affected API
+    verified_at: '2026-05-21'
+    reevaluate_after: each quarter, or when upstream ships the fix
+```
 
 ```bash
-pip-audit --ignore-vuln <CVE-ID> --strict --format json --output /tmp/pip-audit.json
+pip-audit --strict --format json --output /tmp/pip-audit.json
+python3 tools/check_pip_audit.py /tmp/pip-audit.json --ignores your_ignores.yaml
 ```
 
-ForgeLM does **not** ship a project-level ignore list — every suppression is deployer-side and should be quarterly-reviewed.
+Missing any required field (`id`, `package`, `reason`, `threat_model`, `verified_at`, `reevaluate_after`) — or giving one a malformed value (empty string, a non-`YYYY-MM-DD` `verified_at`, or an `aliases` that is not a list of strings) — causes the gate to fail closed, so undocumented suppressions cannot land silently. Every match is logged as a `::notice::` annotation in the run summary.
+
+ForgeLM does **not** ship a default project-level ignore list. The project's own nightly carries a checked-in `tools/pip_audit_ignores.yaml` (for project-internal triage), but `check_pip_audit.py` reads no ignores at all without `--ignores`, so deployers running the tool standalone inherit nothing. Every deployer-side suppression is documented in your own risk acceptance log and quarterly-reviewed.
 
 ## Where to read more
 

docs/usermanuals/tr/operations/supply-chain.md

@@ -60,13 +60,27 @@ python3 tools/check_bandit.py /tmp/bandit.json
 
 ## Bir CVE kabul edildiğinde ama henüz düzeltilemediğinde
 
-Upstream henüz düzeltmeyi yayınlamadıysa ve CVE'yi operatör-tarafı risk acceptance log'unuzda belgelediyseniz:
+Upstream henüz düzeltmeyi yayınlamadıysa ve CVE'yi operatör-tarafı risk acceptance log'unuzda belgelediyseniz, bir YAML ignore dosyası yazıp `check_pip_audit.py`'ye opt-in `--ignores` flag'i üzerinden geçirin:
+
+```yaml
+# your_ignores.yaml
+ignores:
+  - id: CVE-2026-XXXX
+    package: some-pkg
+    reason: tek satırlık kısa özet
+    threat_model: deployment yüzeyinizin etkilenen API'yi neden açığa çıkarmadığı
+    verified_at: '2026-05-21'
+    reevaluate_after: her quarter, ya da upstream fix gönderdiğinde
+```
 
 ```bash
-pip-audit --ignore-vuln <CVE-ID> --strict --format json --output /tmp/pip-audit.json
+pip-audit --strict --format json --output /tmp/pip-audit.json
+python3 tools/check_pip_audit.py /tmp/pip-audit.json --ignores your_ignores.yaml
 ```
 
-ForgeLM proje-seviyesi bir ignore listesi yayınlamaz **— her suppression operatör-tarafı olmalı ve quarterly-review yapılmalıdır**.
+Zorunlu alanlardan birinin (`id`, `package`, `reason`, `threat_model`, `verified_at`, `reevaluate_after`) eksikliği — ya da bir alanın hatalı değer taşıması (boş string, `YYYY-MM-DD` olmayan `verified_at`, ya da string listesi olmayan `aliases`) — gate'in kapalı fail etmesine yol açar; böylece dokümante edilmemiş bir suppression sessizce inemez. Her eşleşme run summary'de `::notice::` annotation olarak loglanır.
+
+ForgeLM **varsayılan proje-seviyesi bir ignore listesi yayınlamaz**. Projenin kendi nightly'si check-in edilmiş bir `tools/pip_audit_ignores.yaml` taşır (proje-içi triage için), ama `check_pip_audit.py` `--ignores` olmadan hiçbir ignore okumaz; bu yüzden tool'u standalone çalıştıran deployer'lar hiçbir şey miras almaz. Her operatör-tarafı suppression kendi risk acceptance log'unuzda dokümante edilir ve quarterly-review yapılır.
 
 ## Daha fazla okumak için nereye