From 4adc3d8bdfe8e4de256ee50d3cc78345d33dccd7 Mon Sep 17 00:00:00 2001 From: User Date: Thu, 20 Aug 2026 15:35:52 +0200 Subject: [PATCH] docs: add PSD survey remediation checklist --- ...psd-server-survey-remediation-checklist.md | 311 ++++++++++++++++++ 1 file changed, 311 insertions(+) create mode 100644 docs/operations/psd-server-survey-remediation-checklist.md diff --git a/docs/operations/psd-server-survey-remediation-checklist.md b/docs/operations/psd-server-survey-remediation-checklist.md new file mode 100644 index 00000000..e2b447bb --- /dev/null +++ b/docs/operations/psd-server-survey-remediation-checklist.md @@ -0,0 +1,311 @@ +# PSD Server Survey — Remediation Checklist + +## Purpose and authority + +Questo documento permette al proprietario e a Sol di discutere, decidere e chiudere uno alla volta +i blocker emersi dal survey read-only del server PSD. È il punto di ripresa operativo tra sessioni: +registra soltanto fatti sanitizzati, decisioni, responsabili e riferimenti a evidenze protette. + +Fonti normative: + +- `docs/operations/psd-server-sol-orchestration-prompt.md` +- `docs/plans/2026-08-20-psd-server-deployment-program.md` +- `docs/plans/2026-08-20-psd-server-survey.md` +- `docs/superpowers/specs/2026-08-20-psd-survey-remediation-checklist-design.md` + +Questo documento non autorizza modifiche a server, servizi, database, Nginx, load balancer, +Authentik, Aritmolab o repository esterni. + +## Program gate + +- Program result: `SURVEY_NO_GO` +- Survey report: `/var/tmp/thothii-psd-survey.fJh7DS/survey-report.md` +- Survey report SHA-256: `36461b6c7d1e44d055f24d6919e892b7017352ac9eb99ac67b9ae62f0614f8e7` +- Legacy stack: deve restare acceso e invariato durante la discussione di questa lista +- Project A remains forbidden fino a un nuovo `SURVEY_GO` e all'approvazione esplicita del proprietario +- Project B remains forbidden fino ai PASS automatico, umano e del proprietario per Project A + +## Current activity and resume point + +- Current activity: `1` +- Title: Rotate or revoke the exposed DWH credential safely +- Resume from: Activity 1, identify the accountable credential owner and the credential type without revealing its value +- Discussion rule: una sola attività può essere `IN_DISCUSSION` +- Allowed states: `PENDING`, `IN_DISCUSSION`, `BLOCKED`, `PASS` + +## How to use this checklist + +1. Leggere `Current activity` e `Resume from`. +2. Discutere soltanto l'attività corrente. +3. Non inserire password, token, cookie, chiavi private, stringhe di connessione, claim grezzi o + valori di secret. +4. Registrare solo percorsi protetti, owner, mode, timestamp, nomi o ID di oggetti, checksum ed + esiti sanitizzati. +5. Alla fine della discussione aggiornare stato, note, decisione, evidenze, blocker e prossimo + passo. +6. Spostare `Current activity` solo quando il gate dell'attività corrente è soddisfatto oppure il + proprietario decide esplicitamente di parcheggiarla come `BLOCKED`. +7. Non riaprire un'attività `PASS` salvo nuova evidenza che ne invalidi la decisione. + +## Activity summary + +| ID | Attività | Stato | Responsabile | Prossimo gate | +|---|---|---|---|---| +| 1 | Rotazione controllata della credenziale DWH esposta | `IN_DISCUSSION` | Unassigned | Identificare owner e tipo di credenziale | +| 2 | Assegnazione dei responsabili dei componenti condivisi | `PENDING` | Unassigned | Elenco owner confermato | +| 3 | Risoluzione del dominio pubblico `.it` oppure `.com` | `PENDING` | Unassigned | Origine autorevole documentata | +| 4 | Topologia e responsabilità del load balancer | `PENDING` | Unassigned | Route, health, TLS, rollback e allowlist verificati | +| 5 | Accesso read-only protetto ad Authentik | `PENDING` | Unassigned | Inventario API autorizzato e redatto | +| 6 | Accesso catalog-only protetto a PostgreSQL | `PENDING` | Unassigned | Catalogo, grant e PostgREST verificati | +| 7 | Backup e rollback del vecchio ThothII | `PENDING` | Unassigned | Backup verificabile e restart recipe completa | +| 8 | Accesso Git read-only al workspace PSD | `PENDING` | Unassigned | SHA, descriptor e deploy key verificati | +| 9 | Metadati Pi e LLM verificabili | `PENDING` | Unassigned | Versione, policy e reachability redatte | +| 10 | Conservazione evidenze e nuovo survey bounded | `PENDING` | Unassigned | Nuovo report e decisione proprietario | + +## Activity 1: Rotate or revoke the exposed DWH credential safely + +- Status: `IN_DISCUSSION` +- Accountable owner: Unassigned +- Objective: sostituire o revocare in modo controllato la credenziale DWH comparsa nell'output + interno del survey, senza interrompere consumer legittimi e senza esporne nuovamente il valore. +- Why this is required: la credenziale deve essere considerata compromessa; non può essere usata + come base affidabile per completare il survey o iniziare Project A. +- Ordered actions: + 1. identificare il team che gestisce la route DWH, il suo meccanismo di autenticazione e la + custodia del secret; + 2. determinare il tipo di credenziale senza leggerla o copiarla in questa checklist; + 3. inventariare i consumer tramite riferimenti di configurazione e secret object; + 4. scegliere una transizione a doppia credenziale oppure una finestra atomica con rollback; + 5. generare e distribuire il nuovo secret attraverso il meccanismo protetto approvato; + 6. verificare i consumer autorizzati, l'assenza del nuovo valore nei log e la continuità del + vecchio stack; + 7. revocare la vecchia credenziale e provare che non venga più accettata; + 8. registrare soltanto evidenze redatte. +- Required redacted evidence: + - owner e autorizzazione della rotazione; + - tipo e identificatore non sensibile della credenziale; + - percorso protetto o secret object, senza contenuto; + - elenco dei consumer aggiornati; + - timestamp e risultati dei test positivi e negativi; + - conferma di revoca della credenziale precedente; + - procedura di rollback e relativo esito. +- Discussion notes: il survey ha osservato la credenziale durante l'analisi della configurazione + Nginx relativa al DWH. Non è ancora provato se sia una chiave API, un header condiviso o un altro + tipo di secret; non va confusa automaticamente con una password PostgreSQL. +- Decision: No decision recorded +- Blockers: owner non identificato; tipo di credenziale non verificato; consumer e supporto alla + doppia credenziale non inventariati. +- Next step: il proprietario identifica il responsabile della credenziale della route DWH e indica + se appartiene al team Nginx, Supabase/PostgreSQL o a un altro team. + +## Activity 2: Identify accountable owners for shared components + +- Status: `PENDING` +- Accountable owner: Unassigned +- Objective: associare ogni componente condiviso a una persona o a un team con autorità di lettura, + modifica, approvazione e rollback. +- Why this is required: la leggibilità di una configurazione non implica autorità a modificarla. +- Ordered actions: + 1. identificare gli owner di DNS/load balancer, Nginx/certificati, Authentik, + Supabase/PostgreSQL, Aritmolab, workspace Git e backup legacy; + 2. registrare il canale di approvazione e la procedura di escalation; + 3. confermare separatamente chi può autorizzare Project A e Project B. +- Required redacted evidence: nomi dei team, ruoli, canali operativi e conferme di responsabilità; + nessun contatto personale sensibile. +- Discussion notes: Not discussed +- Decision: No decision recorded +- Blockers: nessun owner condiviso è stato ancora formalmente confermato. +- Next step: compilare la matrice owner/componente dopo la chiusura dell'Activity 1. + +## Activity 3: Resolve the authoritative public origin + +- Status: `PENDING` +- Accountable owner: Unassigned +- Objective: scegliere sulla base di evidenze l'unica origine pubblica finale tra il dominio `.it` + osservato e il dominio `.com` riportato nel piano. +- Why this is required: callback OIDC, certificato, cookie, Nginx, load balancer e sidebar devono + concordare sulla stessa origine HTTPS. +- Ordered actions: + 1. ottenere la dichiarazione autorevole dell'owner DNS/load balancer; + 2. verificare record DNS, route, backend, certificato e redirect; + 3. confrontare l'origine con la configurazione e la sidebar di Aritmolab; + 4. registrare l'origine approvata e le discrepanze da correggere in Project B. +- Required redacted evidence: hostname finale, record/route sanitizzati, SAN del certificato, + destinazione sidebar e approvazione dell'owner. +- Discussion notes: il survey ha osservato `.it`; il piano cita `.com`. La discrepanza è aperta. +- Decision: No decision recorded +- Blockers: owner DNS/load balancer non identificato e origine browser-visible non provata. +- Next step: ottenere la dichiarazione autorevole dopo l'assegnazione degli owner. + +## Activity 4: Establish the load-balancer contract + +- Status: `PENDING` +- Accountable owner: Unassigned +- Objective: documentare il confine effettivo del load balancer e la procedura reversibile per le + route temporanea e finale. +- Why this is required: il survey locale non ha potuto provare owner, backend, health check, TLS, + source range o allowlist. +- Ordered actions: + 1. identificare superficie di configurazione e owner; + 2. registrare backend, porta, health check, punto TLS e source range verso Nginx; + 3. documentare deploy, validazione e rollback; + 4. stabilire se una route temporanea può essere limitata agli operatori; + 5. definire una prova positiva e una negativa dell'allowlist senza creare ancora la route. +- Required redacted evidence: nomi/ID delle route, backend e health check sanitizzati, ownership, + capacità di allowlist e procedura di rollback. +- Discussion notes: Not discussed +- Decision: No decision recorded +- Blockers: il load balancer non è ispezionabile dalla superficie locale autorizzata. +- Next step: coinvolgere l'owner identificato nell'Activity 2. + +## Activity 5: Provide protected read-only Authentik survey access + +- Status: `PENDING` +- Accountable owner: Unassigned +- Objective: permettere un inventario Authentik bounded e read-only della versione installata. +- Why this is required: applicazioni, provider, flow, mapping, gruppi, service account, permessi API + e procedura di export non sono stati verificati. +- Ordered actions: + 1. identificare l'owner Authentik e la procedura di backup/export; + 2. predisporre una credenziale read-only o un'esecuzione assistita dall'owner; + 3. comunicare solo percorso, owner, mode e usabilità del secret; + 4. inventariare nomi/ID e convenzioni senza recuperare secret write-only; + 5. confrontare il comportamento con OpenAPI e documentazione della release installata. +- Required redacted evidence: versione, nomi/ID degli oggetti, permission set della credenziale, + riferimento all'export e risultati sanitizzati. +- Discussion notes: Not discussed +- Decision: No decision recorded +- Blockers: nessuna credenziale amministrativa/API utilizzabile è stata stabilita. +- Next step: ottenere dall'owner un meccanismo protetto post-rotazione. + +## Activity 6: Provide protected catalog-only PostgreSQL survey access + +- Status: `PENDING` +- Accountable owner: Unassigned +- Objective: verificare database, schemi, ruoli, grant, migrazioni e PostgREST con sole query di + catalogo. +- Why this is required: il runtime DWH read-only, lo stato di `thoth_sessions` e i confini Supabase + non sono provati. +- Ordered actions: + 1. identificare DBA e procedura protetta di connessione; + 2. verificare database, utente corrente, schemi e owner; + 3. verificare i grant sullo schema `datawarehouse` senza write probe clinici; + 4. verificare stato di `thoth_sessions` e migration records; + 5. verificare gli schemi esposti da PostgREST; + 6. registrare TLS/CA, backup e convenzioni per ruoli migrator/runtime. +- Required redacted evidence: risultati catalogici bounded, nomi dei ruoli, attributi e grant, + schemi PostgREST, riferimento a backup e TLS; nessuna stringa di connessione. +- Discussion notes: Not discussed +- Decision: No decision recorded +- Blockers: non esiste ancora un meccanismo psql approvato post-rotazione. +- Next step: far predisporre dal DBA l'accesso catalog-only. + +## Activity 7: Prove legacy backup and rollback + +- Status: `PENDING` +- Accountable owner: Unassigned +- Objective: dimostrare che il vecchio ThothII possa essere preservato e ripristinato prima di + qualsiasi stop. +- Why this is required: source, container, bind e network sono inventariati, ma backup verificato, + controller e restart recipe non sono disponibili. +- Ordered actions: + 1. identificare owner e meccanismo lifecycle compatibile; + 2. confermare assenza di lavoro utente da preservare; + 3. definire contenuti, destinazione e protezione del backup; + 4. definire checksum e verifica di leggibilità; + 5. scrivere comandi esatti di stop/start e ordine di chiusura/ripristino route; + 6. eseguire il backup soltanto nella successiva fase autorizzata, prima dello stop. +- Required redacted evidence: inventario, percorso backup, checksum, owner, restart recipe e + rollback route; nessun contenuto di secret. +- Discussion notes: il legacy stack è ancora attivo e invariato. +- Decision: No decision recorded +- Blockers: lifecycle supportato, backup owner e comandi esatti non stabiliti. +- Next step: approvare la procedura senza eseguirla durante la discussione. + +## Activity 8: Provide read-only PSD workspace Git access + +- Status: `PENDING` +- Accountable owner: Unassigned +- Objective: verificare il repository remoto condiviso e il suo stato corrente dal server senza + capacità di push. +- Why this is required: SHA, descriptor, trasporti, Evidence, annotazioni e scope della deploy key + non sono stati osservati dal server. +- Ordered actions: + 1. identificare curator e owner della deploy key; + 2. fornire un riferimento protetto alla chiave server read-only; + 3. verificare remote, branch e SHA con modalità non interattiva; + 4. verificare catalogo, schema v3, trasporti, Evidence e annotazioni; + 5. provare che la credenziale server non possa effettuare push. +- Required redacted evidence: remote, branch, SHA, descriptor blob, stato Evidence/annotations e + attestazione read-only della deploy key. +- Discussion notes: Not discussed +- Decision: No decision recorded +- Blockers: nessun checkout workspace o deploy credential utilizzabile è stato localizzato. +- Next step: coinvolgere il curator e predisporre l'accesso server read-only. + +## Activity 9: Make Pi and LLM metadata verifiable + +- Status: `PENDING` +- Accountable owner: Unassigned +- Objective: verificare versione Pi, provider, modello, thinking level, riferimento credenziale e + reachability LLM senza esporre il secret. +- Why this is required: la root Pi legacy non è attraversabile dall'operatore del survey e i + default del nuovo source non provano la configurazione in esecuzione. +- Ordered actions: + 1. identificare owner della configurazione Pi/LLM; + 2. scegliere tra esecuzione assistita dall'owner e accesso read-only allowlisted; + 3. estrarre esclusivamente metadati non sensibili; + 4. eseguire un controllo bounded di reachability senza stampare credenziali; + 5. registrare anche il mismatch NVML/GPU come rischio separato, non come blocker CPU. +- Required redacted evidence: versione, provider, model ID, thinking level, endpoint sanitizzato, + percorso/mode della credenziale e risultato di reachability. +- Discussion notes: host `x86_64`; due GPU NVIDIA osservate, ma `nvidia-smi` non è utilizzabile per + mismatch driver/libreria NVML. Il deployment CPU resta da valutare con le immagini pinned. +- Decision: No decision recorded +- Blockers: configurazione Pi protetta non leggibile e nessun endpoint LLM credential-free noto. +- Next step: ottenere un controllo assistito o permessi read-only mirati. + +## Activity 10: Retain evidence and run the missing bounded survey checks + +- Status: `PENDING` +- Accountable owner: Unassigned +- Objective: conservare le evidenze protette, ripetere soltanto i controlli mancanti e produrre una + nuova decisione verificabile. +- Why this is required: il report corrente è `SURVEY_NO_GO` e non può essere promosso per inferenza. +- Ordered actions: + 1. scegliere il protected evidence root definitivo; + 2. trasferire la directory del survey senza modificarne i contenuti e verificare il digest; + 3. confermare che le Activity 1–9 siano `PASS` oppure abbiano una risoluzione proprietario + esplicitamente accettata; + 4. eseguire solo i controlli bounded mancanti del piano survey; + 5. aggiornare il report e verificarne checksum e secret hygiene; + 6. chiedere la decisione esplicita del proprietario. +- Required redacted evidence: percorso finale, digest, matrice Activity 1–9, nuovi risultati + bounded, report aggiornato e decisione firmata. +- Discussion notes: Not discussed +- Decision: No decision recorded +- Blockers: dipende dalla chiusura delle Activity 1–9 e dall'approvazione del retention root. +- Next step: avviare soltanto dopo la chiusura dei blocker precedenti. + +## Fresh survey and owner gate + +Un nuovo `SURVEY_GO` richiede contemporaneamente: + +- credenziale DWH precedente revocata e rotazione verificata; +- owner e autorità di modifica/rollback identificati; +- origine pubblica unica e load-balancer contract provati; +- accessi read-only Authentik, PostgreSQL, workspace Git e Pi/LLM verificati; +- identità DWH dimostrata read-only; +- backup e restart recipe legacy verificabili; +- risorse e percorsi della nuova installazione approvati; +- report redatto, secret-scan valido e checksum verificato; +- approvazione esplicita del proprietario. + +Il PASS tecnico del survey non autorizza automaticamente Project A. L'autorizzazione deve essere +registrata separatamente. + +## Change log + +| Data | Attività | Modifica | Autore | +|---|---|---|---| +| 2026-08-20 | Initial | Creata checklist; Activity 1 aperta, Activity 2–10 pending | Sol |