From 3933c2c2bfb81463d79d3bbc172fa663ef022e21 Mon Sep 17 00:00:00 2001 From: Cemil ILIK Date: Sun, 18 Oct 2026 10:04:28 +0300 Subject: [PATCH] docs(compliance): stop saying the approval gate enforces segregation of duties The human-approval gate records who approved (FORGELM_OPERATOR, else the OS user) next to who trained, and writes both to the audit log. It does not compare the two, and both identities are self-asserted. Several documents said otherwise: - the ISO 27001 mapping ("enforces trainer != approver") and the SOC 2 mapping ("approval gate operator != trainer"); - the Statement of Applicability row for A.8.2 ("non-trainer operator"); - the deployer guide, the change-management SOP and the user manual ("dual-controlled", "two distinct operator IDs prove segregation of duties"); - the deployer guide's checklist, which said F-compliance-110 raises ConfigError if require_human_approval is missing for a strict risk tier. It only checks that the safety evaluation is enabled; the CLI wizard turns the approval gate on for those tiers, hand-written YAML is not checked. The same documents already said the right thing elsewhere (the SoA row for A.5.3, access_control.md, the approve reference); this brings the rest in line. English and Turkish. The design spec in docs/design is a record of intent and is left as written; the website copy that says "dual-controlled" is a separate change. Refs #73, #99, #90 Co-Authored-By: Claude Sonnet 5.5 --- CHANGELOG.md | 5 +++++ docs/guides/iso_soc2_deployer_guide-tr.md | 15 ++++++++++----- docs/guides/iso_soc2_deployer_guide.md | 15 ++++++++++----- docs/qms/sop_change_management-tr.md | 5 +++-- docs/qms/sop_change_management.md | 5 +++-- docs/qms/statement_of_applicability-tr.md | 2 +- docs/qms/statement_of_applicability.md | 2 +- docs/reference/iso27001_control_mapping-tr.md | 2 +- docs/reference/iso27001_control_mapping.md | 2 +- docs/reference/soc2_trust_criteria_mapping-tr.md | 2 +- docs/reference/soc2_trust_criteria_mapping.md | 2 +- .../en/operations/iso-soc2-deployer.md | 2 +- .../tr/operations/iso-soc2-deployer.md | 2 +- 13 files changed, 39 insertions(+), 22 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0d44dd02..c0a58adc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -68,6 +68,11 @@ All notable changes to ForgeLM are documented here. ### Fixed +- Stop describing the human-approval gate as enforcing segregation of duties (English and Turkish): it records the + trainer and approver identities and does not compare them, and both are self-asserted. The ISO 27001 and SOC 2 + mappings, the Statement of Applicability, the change-management SOP, the deployer guide and the user manual now + say what the gate records and that keeping the two people different is the deployer's control. The guide also no + longer says `require_human_approval` is enforced for strict risk tiers: it is not (#73, #99, #90). - Fix the KTO bullet on the Alignment overview user-manual page (English and Turkish): it named the fields `(prompt, response, good?)`, but the KTO loader reads `prompt`, `completion` and a boolean `label` (#965). diff --git a/docs/guides/iso_soc2_deployer_guide-tr.md b/docs/guides/iso_soc2_deployer_guide-tr.md index fd52e63e..aca46511 100644 --- a/docs/guides/iso_soc2_deployer_guide-tr.md +++ b/docs/guides/iso_soc2_deployer_guide-tr.md @@ -26,8 +26,10 @@ ForgeLM kanıtına sahip: 2. **Change control** — Madde 14 staging gate (`forgelm approve` / `reject`) + `human_approval.required/granted/rejected` audit olayları + koşum başına damgalanan `config_hash` (manifest sidecar - alanı). Her model promotion çift kontrollü ve forensic olarak - attribute edilmiştir. + alanı). Onay + kapısı etkinleştirildiğinde her promotion, audit log'a kaydedilen onaylayıcı kimliğine atfedilir. ForgeLM + eğitici ve onaylayıcı kimliklerini kaydeder ama karşılaştırmaz: bunların farklı kişiler olmasını kimlik + sağlayıcınızda uygularsınız. 3. **Data lineage** — `data_provenance.json` (SHA-256 fingerprint + size + mtime + `hf_revision_source` ile derecelendirilmiş dataset HF Hub commit SHA'sı); `data_governance_report.json` @@ -65,7 +67,9 @@ Denetçi sormadan **önce** indirmeniz gereken on iki madde. - [ ] **`evaluation.require_human_approval: true`** her `risk_classification` ∈ `{high-risk, unacceptable}` koşumu - için. Unutursanız F-compliance-110 `ConfigError` raise eder. + için. ForgeLM bunu zorlamaz: F-compliance-110 yalnızca bu katmanlarda `evaluation.safety.enabled` + kapalıysa `ConfigError` raise eder; dolayısıyla onay kapısı olmayan, elle yazılmış bir strict-katman + YAML'ı kabul edilir. CLI sihirbazı (`forgelm --wizard`) bu katmanlarda kapıyı açar. - [ ] **Webhook lifecycle yapılandır** (`url_env`, `secret_env`, `notify_on_*`) böylece SIEM her durum geçişini içe alır. - [ ] **`auto_revert: true` etkinleştir** üretim eğitimi için — @@ -155,8 +159,9 @@ jq -r 'select(.run_id == "X" and (.event == "training.started" or .event == "hum ./outputs/audit_log.jsonl | sort -u ``` -İki farklı operator ID görev ayrılığını kanıtlar (ISO A.5.3, SOC 2 -CC1.5). +`training.started` üzerindeki operatörü `human_approval.granted` üzerindeki onaylayıcıyla karşılaştırın. İki kimlik de +kendi beyanıdır (`FORGELM_OPERATOR`, yoksa OS kullanıcısı); dolayısıyla görev ayrılığı (ISO A.5.3, SOC 2 CC1.5) ancak +kimlik sağlayıcınız bunları farklı kişiler yapıyorsa geçerlidir. ### S3: "Data lineage göster" diff --git a/docs/guides/iso_soc2_deployer_guide.md b/docs/guides/iso_soc2_deployer_guide.md index 3132ef96..4c853926 100644 --- a/docs/guides/iso_soc2_deployer_guide.md +++ b/docs/guides/iso_soc2_deployer_guide.md @@ -25,8 +25,10 @@ direct ForgeLM evidence: `forgelm verify-audit` validates the chain end-to-end. 2. **Change control** — Article 14 staging gate (`forgelm approve` / `reject`) + `human_approval.required/granted/rejected` audit - events + `config_hash` (per-run manifest sidecar field) stamped per run. Every - model promotion is dual-controlled and forensically attributed. + events + `config_hash` (per-run manifest sidecar field) stamped per run. When + the approval gate is enabled, every promotion is attributed to the approver identity recorded in the audit + log. ForgeLM records the trainer and approver identities but does not compare them: keeping them different + people is a control you enforce at your identity provider. 3. **Data lineage** — `data_provenance.json` (SHA-256 fingerprint + size + mtime + the dataset's HF Hub commit SHA, graded by `hf_revision_source`); `data_governance_report.json` @@ -63,7 +65,9 @@ Twelve items to land **before** the auditor asks. - [ ] **`evaluation.require_human_approval: true`** for every `risk_classification` ∈ `{high-risk, unacceptable}` run. - F-compliance-110 raises `ConfigError` if you forget. + ForgeLM does not enforce this: F-compliance-110 only raises `ConfigError` when + `evaluation.safety.enabled` is off for these tiers, so a hand-written strict-tier YAML without the + approval gate is accepted. The CLI wizard (`forgelm --wizard`) switches the gate on for these tiers. - [ ] **Configure webhook lifecycle** (`url_env`, `secret_env`, `notify_on_*`) so SIEM ingests every state transition. - [ ] **Enable `auto_revert: true`** for production training so @@ -155,8 +159,9 @@ jq -r 'select(.run_id == "X" and (.event == "training.started" or .event == "hum ./outputs/audit_log.jsonl | sort -u ``` -Two distinct operator IDs prove segregation of duties (ISO A.5.3, -SOC 2 CC1.5). +Compare the operator on `training.started` with the approver on `human_approval.granted`. Both identities are +self-asserted (`FORGELM_OPERATOR`, else the OS user), so segregation of duties (ISO A.5.3, SOC 2 CC1.5) holds only +if your identity provider makes them different people. ### Q3: "Show me the data lineage" diff --git a/docs/qms/sop_change_management-tr.md b/docs/qms/sop_change_management-tr.md index c010fc36..2b1a545d 100644 --- a/docs/qms/sop_change_management-tr.md +++ b/docs/qms/sop_change_management-tr.md @@ -109,8 +109,9 @@ CAB'sıdır: retention süresi dolana kadar (`retention.staging_ttl_days` — config'te). -Bu, operatöre SOC 2 CC8.1 kanıtı verir: her model promotion -attribute, çift kontrollü ve forensic olarak kayıtlıdır. +Bu, operatöre SOC 2 CC8.1 kanıtı verir: onay kapısı etkinleştirildiğinde her +model promotion kaydedilen onaylayıcı kimliğine atfedilir ve forensic olarak kayıtlıdır. Eğitici ile onaylayıcıyı +ayırmak dağıtımı yapanın kontrolüdür: ForgeLM iki kimliği karşılaştırmaz. ### 4.2 Yapılandırma drift tespiti diff --git a/docs/qms/sop_change_management.md b/docs/qms/sop_change_management.md index 79336c3d..e774b141 100644 --- a/docs/qms/sop_change_management.md +++ b/docs/qms/sop_change_management.md @@ -104,8 +104,9 @@ in-pipeline CAB: in `final_model.staging./` for forensic review until retention expires (`retention.staging_ttl_days` in the config). -This gives a deployer SOC 2 CC8.1 evidence: every model promotion is -attributed, dual-controlled, and forensically recorded. +This gives a deployer SOC 2 CC8.1 evidence: when the approval gate is +enabled, every model promotion is attributed to the recorded approver identity and forensically recorded. +Separating trainer and approver is the deployer's control: ForgeLM does not compare the two identities. ### 4.2 Configuration drift detection diff --git a/docs/qms/statement_of_applicability-tr.md b/docs/qms/statement_of_applicability-tr.md index ac90f3c5..18d24d39 100644 --- a/docs/qms/statement_of_applicability-tr.md +++ b/docs/qms/statement_of_applicability-tr.md @@ -108,7 +108,7 @@ ForgeLM-spesifik kontrol envanteriyle ilgilidir. | Kontrol | Applicable? | ForgeLM kanıtı | Operatör-tarafı eylem | |---|---|---|---| | A.8.1 Kullanıcı uç cihazları | YES | `forgelm doctor` — Python / CUDA / GPU / extras / HF auth / disk / `FORGELM_OPERATOR` checks | Endpoint hardening | -| A.8.2 Ayrıcalıklı erişim hakları | YES | Operatör attribution; approval gate non-trainer operator | IdP'de RBAC | +| A.8.2 Ayrıcalıklı erişim hakları | YES | Operatör attribution; approval gate onaylayıcı kimliğini kaydeder | IdP'de RBAC | | A.8.3 Bilgi erişim kısıtlaması | YES | Salted identifier hashing; `forgelm reverse-pii` Md. 15 | DSAR workflow | | A.8.4 Kaynak koduna erişim | YES | `model.trust_remote_code=False` default; `model.revision` temel-model deposunu sabitler ve `trust_remote_code: true` ile çalıştırılacak depo-içi kodu sınırlar. `_fingerprint_hf_revision` yalnızca **dataset** deposunu kapsar | VCS erişim kontrolü; `trust_remote_code: true` onaylanan her yerde `model.revision` zorunlu tutun | | A.8.5 Güvenli kimlik doğrulama | YES | `safe_post` non-HTTPS'de auth header reddeder; webhook secret discipline | MFA + token rotasyonu | diff --git a/docs/qms/statement_of_applicability.md b/docs/qms/statement_of_applicability.md index b78bc887..7b871428 100644 --- a/docs/qms/statement_of_applicability.md +++ b/docs/qms/statement_of_applicability.md @@ -107,7 +107,7 @@ ForgeLM-specific control inventory. | Control | Applicable? | ForgeLM evidence | Deployer-side action | |---|---|---|---| | A.8.1 User endpoint devices | YES | `forgelm doctor` — Python / CUDA / GPU / extras / HF auth / disk / `FORGELM_OPERATOR` checks | Endpoint hardening | -| A.8.2 Privileged access rights | YES | Operator attribution; approval gate non-trainer operator | RBAC at IdP | +| A.8.2 Privileged access rights | YES | Operator attribution; approval gate records the approver identity | RBAC at IdP | | A.8.3 Information access restriction | YES | Salted identifier hashing; `forgelm reverse-pii` Article 15 | DSAR workflow | | A.8.4 Access to source code | YES | `model.trust_remote_code=False` default; `model.revision` pins the base-model repo, bounding the repo-bundled code `trust_remote_code: true` would run. `_fingerprint_hf_revision` covers the **dataset** repo only | VCS access control; require `model.revision` wherever `trust_remote_code: true` is approved | | A.8.5 Secure authentication | YES | `safe_post` rejects auth headers on non-HTTPS; webhook secret discipline | MFA + token rotation | diff --git a/docs/reference/iso27001_control_mapping-tr.md b/docs/reference/iso27001_control_mapping-tr.md index 57e78d96..dd5c6517 100644 --- a/docs/reference/iso27001_control_mapping-tr.md +++ b/docs/reference/iso27001_control_mapping-tr.md @@ -23,7 +23,7 @@ |---|---|---| | A.5.1 Bilgi güvenliği için politikalar | FL-helps | `audit_event_catalog.md` neyin loglandığını dokümante eder | | A.5.2 Bilgi güvenliği rolleri ve sorumlulukları | FL-helps | `FORGELM_OPERATOR` + `roles_responsibilities.md` | -| A.5.3 Görev ayrılığı | FL-helps | `human_approval.required/granted` trainer ≠ approver'ı zorlar | +| A.5.3 Görev ayrılığı | FL-helps | `human_approval.required/granted` onaylayıcı kimliğini (`FORGELM_OPERATOR`'dan, yoksa OS kullanıcısından) **kaydeder**, böylece eğitici ≠ onaylayıcı denetlenebilir; ForgeLM kendisi self-approval'ı reddetmez. Runner ve reviewer kimliklerini kimlik sağlayıcınızda ayrık tutun | | A.5.4 Yönetim sorumlulukları | FL-helps | `forgelm doctor`; `compliance_report.json`; `training_manifest.yaml` | | A.5.5 Yetkililerle iletişim | OOS | — | | A.5.6 Özel ilgi gruplarıyla iletişim | OOS | — | diff --git a/docs/reference/iso27001_control_mapping.md b/docs/reference/iso27001_control_mapping.md index 5f1885a2..519ebc8d 100644 --- a/docs/reference/iso27001_control_mapping.md +++ b/docs/reference/iso27001_control_mapping.md @@ -24,7 +24,7 @@ |---|---|---| | A.5.1 Policies for information security | FL-helps | `audit_event_catalog.md` documents what's logged | | A.5.2 Information security roles and responsibilities | FL-helps | `FORGELM_OPERATOR` + `roles_responsibilities.md` | -| A.5.3 Segregation of duties | FL-helps | `human_approval.required/granted` enforces trainer ≠ approver | +| A.5.3 Segregation of duties | FL-helps | `human_approval.required/granted` **records** the approver identity (from `FORGELM_OPERATOR`, else the OS user) so trainer ≠ approver is auditable; ForgeLM does not reject self-approval. Keep the runner and reviewer identities disjoint at your identity provider | | A.5.4 Management responsibilities | FL-helps | `forgelm doctor`; `compliance_report.json`; `training_manifest.yaml` | | A.5.5 Contact with authorities | OOS | — | | A.5.6 Contact with special interest groups | OOS | — | diff --git a/docs/reference/soc2_trust_criteria_mapping-tr.md b/docs/reference/soc2_trust_criteria_mapping-tr.md index 07c43f47..00195c8a 100644 --- a/docs/reference/soc2_trust_criteria_mapping-tr.md +++ b/docs/reference/soc2_trust_criteria_mapping-tr.md @@ -26,7 +26,7 @@ kategoriler engagement-bazında scoplanır. | CC | Başlık | ForgeLM kanıtı | |---|---|---| | CC1.1 | Bütünlüğe bağlılık göstergesi | `roles_responsibilities.md` QMS template; AI Officer rolü | -| CC1.2 | Yönetişim bağımsızlığı | Approval gate operator ≠ trainer | +| CC1.2 | Yönetişim bağımsızlığı | Approval gate onaylayıcı kimliğini kaydeder, böylece eğitici ≠ onaylayıcı denetlenebilir; ForgeLM bunu zorlamaz | | CC1.3 | Yapı, raporlama hatları kurma | `roles_responsibilities.md` AI Officer / ML Lead / DPO tanımlar | | CC1.4 | Yetkinliğe bağlılık göstergesi | Yıllık EU AI Act / GDPR eğitimi (operatör politikası) | | CC1.5 | Hesap verebilirliği uygular | `FORGELM_OPERATOR` attribution + audit chain | diff --git a/docs/reference/soc2_trust_criteria_mapping.md b/docs/reference/soc2_trust_criteria_mapping.md index 57ce25ed..29b48253 100644 --- a/docs/reference/soc2_trust_criteria_mapping.md +++ b/docs/reference/soc2_trust_criteria_mapping.md @@ -26,7 +26,7 @@ categories are scoped per-engagement. | CC | Title | ForgeLM evidence | |---|---|---| | CC1.1 | Demonstrates commitment to integrity | `roles_responsibilities.md` QMS template; AI Officer role | -| CC1.2 | Independence of governance | Approval gate operator ≠ trainer | +| CC1.2 | Independence of governance | The approval gate records the approver identity, so trainer ≠ approver is auditable; ForgeLM does not enforce it | | CC1.3 | Establishes structures, reporting lines | `roles_responsibilities.md` defines AI Officer / ML Lead / DPO | | CC1.4 | Demonstrates commitment to competence | Annual EU AI Act / GDPR training (deployer policy) | | CC1.5 | Enforces accountability | `FORGELM_OPERATOR` attribution + audit chain | diff --git a/docs/usermanuals/en/operations/iso-soc2-deployer.md b/docs/usermanuals/en/operations/iso-soc2-deployer.md index 862c2748..15237c6c 100644 --- a/docs/usermanuals/en/operations/iso-soc2-deployer.md +++ b/docs/usermanuals/en/operations/iso-soc2-deployer.md @@ -21,7 +21,7 @@ Four pillars an ISO / SOC 2 auditor cares about most have direct ForgeLM evidenc The deep guide answers each with the exact `jq` / CLI command + the artefact it returns: 1. "Show me the audit trail for every model promotion in the past 90 days" → `forgelm verify-audit` + `jq 'select(.event == "human_approval.granted")'`. -2. "Show me the change-control evidence — who approved this model?" → cross-reference `training.started` + `human_approval.granted` events; two distinct operator IDs prove segregation of duties (ISO A.5.3, SOC 2 CC1.5). +2. "Show me the change-control evidence — who approved this model?" → cross-reference `training.started` + `human_approval.granted` events; compare the two identities; they are self-asserted (`FORGELM_OPERATOR`, else the OS user), so segregation of duties (ISO A.5.3, SOC 2 CC1.5) holds only if your identity provider makes them different people. 3. "Show me the data lineage" → `data_provenance.json`; `sha256` + `hf_revision` pin the corpus — but only when `hf_revision_source` reads `loaded`. `unverified` means the SHA is a Hub lookup made when the bundle was written, with no coupling to the load; `unresolved` means no SHA was obtained and none is claimed. 4. "Show me the supply chain" → `gh release download "$(gh release view --json tagName -q .tagName)" --pattern 'sbom-*'`; CycloneDX 1.5 JSON. 5. "Show me the access controls" → IdP audit log + `FORGELM_OPERATOR` cross-reference. diff --git a/docs/usermanuals/tr/operations/iso-soc2-deployer.md b/docs/usermanuals/tr/operations/iso-soc2-deployer.md index d96a3898..cea9adf4 100644 --- a/docs/usermanuals/tr/operations/iso-soc2-deployer.md +++ b/docs/usermanuals/tr/operations/iso-soc2-deployer.md @@ -21,7 +21,7 @@ ISO / SOC 2 denetçisinin en çok önem verdiği dört sütun, doğrudan ForgeLM Derin rehber her birini tam `jq` / CLI komutu + döndürdüğü artefakt ile yanıtlar: 1. "Son 90 gündeki her model promotion için audit trail'i göster" → `forgelm verify-audit` + `jq 'select(.event == "human_approval.granted")'`. -2. "Bana change-control kanıtını göster — bu modeli kim onayladı?" → `training.started` + `human_approval.granted` olaylarını çapraz referans alın; iki farklı operator ID, görev ayrılığını (segregation of duties) kanıtlar (ISO A.5.3, SOC 2 CC1.5). +2. "Bana change-control kanıtını göster — bu modeli kim onayladı?" → `training.started` + `human_approval.granted` olaylarını çapraz referans alın; iki kimliği karşılaştırın; ikisi de kendi beyanıdır (`FORGELM_OPERATOR`, yoksa OS kullanıcısı), dolayısıyla görev ayrılığı (segregation of duties; ISO A.5.3, SOC 2 CC1.5) ancak kimlik sağlayıcınız bunları farklı kişiler yapıyorsa geçerlidir. 3. "Veri lineage'ını göster" → `data_provenance.json`; `sha256` + `hf_revision` corpus'u pinler — ancak yalnızca `hf_revision_source` `loaded` olduğunda. `unverified`, SHA'nın paket yazılırken yapılan ve yüklemeyle hiçbir bağı olmayan bir Hub sorgusu olduğu anlamına gelir; `unresolved` ise hiçbir SHA alınmadığı ve hiçbir iddiada bulunulmadığı anlamına gelir. 4. "Tedarik zincirini göster" → `gh release download "$(gh release view --json tagName -q .tagName)" --pattern 'sbom-*'`; CycloneDX 1.5 JSON. 5. "Erişim kontrollerini göster" → IdP audit log + `FORGELM_OPERATOR` çapraz referansı.