## Problema Rilevamento e correzione delle vulnerabilità esistono già (`snyk-io`, `semgrep-sast`, e le fix-PR di Snyk), ma **manca il processo che li governa**: i finding restano in report che nessuno guarda — `semgrep-sast` in particolare è **sempre verde anche quando trova vulnerabilità** — e nessuno viene avvisato. Con oltre 100 repository, molti poco attivi, alcuni restano con vulnerabilità note non gestite per mesi perché sfuggiti a un controllo manuale. Impattati: chi ha in carico i servizi (rischio operativo non presidiato) e, a valle, l'azienda (ogni vulnerabilità non gestita è una finestra di esposizione). ## Soluzione Due meccanismi distinti per due problemi distinti, senza ricostruire la logica di CI in un job unico (si riusa la pipeline già esistente di ogni repo): 1. **Flusso — gate SAST in MR.** Il job `semgrep-gate` fallisce la pipeline di una MR **solo sui finding introdotti dalla MR** (confronto con il commit base, diff-aware), mai sul debito legacy. Così chi introduce una vulnerabilità è costretto a sistemarla per mergiare, senza essere bloccato dal pregresso. È la protezione dei repo attivi. 2. **Stock e repo dormienti — triggeratore + job che crea issue.** Un triggeratore schedulato (repo product, weekend dopo il planning) individua i repo la cui CI non gira da ≥90 giorni e ne lancia la pipeline. In coda ai job di security, il job `create-security-issue` legge gli artifact già prodotti, li triagea con Claude e apre **una issue per repo nello sprint successivo**, assegnata e pesata. I repo attivi non vengono triggerati (li copre il gate). Il debito accumulato negli anni ("stock") viene drenato con un **bootstrap una-tantum**: il triggeratore lanciato con soglia 0 processa tutti i repo; il cap di peso per persona spalma il lavoro su più sprint. L'agente **non applica fix e non apre MR**: apre solo issue. ## Come funziona - **Triggeratore** (componente A, repo product): elenca i repo non archiviati con `devops.yml`, calcola l'età dell'ultima pipeline sul default branch, e per quelli ≥ `SCAN_STALE_DAYS` (default 90; 0 = bootstrap) lancia la pipeline via API passando `SECURITY_CREATE_ISSUE=true`. Batch limitato (default 50), sequenziale, adatto al weekend. - **Job `create-security-issue`** (componente B, `devops.yml` di ogni repo): gira in coda ai job security **solo se `SECURITY_CREATE_ISSUE=true`** (mai in MR né su push). Legge gli **artifact locali** (`gl-sast-report.json`, `snyk-report-*.json`) — nessun clone, nessuno scan. Poi: soppressione falsi positivi noti (`fp-rules.yaml`, deterministica), triage con Claude (sola lettura, multi-voto sugli incerti), peso proporzionale (critical 3, high 2, medium 1, low 0.5; cap 8, spezzatura per priorità), assegnazione, apertura issue. - **Gate `semgrep-gate`** (componente C, `devops.yml`, in MR): `semgrep ci --baseline-commit`, fallisce solo sui finding introdotti. Opt-in per repo. - **Assegnazione**: top-3 autori di MR mergiate (6→12 mesi) ∩ `teams.yaml` limitato ai team Platform, Integrazioni, Innovation, EVO, esclusi i bot; il meno carico di `technical-debt` nello sprint di destinazione; cap 8/persona. - **Idempotenza**: marker nella descrizione; issue nello sprint attivo non toccata; retest tramite cadenza (un finding non risolto ricompare al trigger successivo). ## Criteri di accettazione - Il triggeratore, schedulato nel weekend, triggera solo i repo con ultima pipeline ≥ soglia; con soglia 0 li processa tutti (bootstrap). - Su una pipeline triggerata, il job apre una issue nello sprint successivo con label, peso, assegnatario e marker corretti, leggendo gli artifact locali. - Il job `create-security-issue` non gira in MR né su push normale. - In MR, introdurre una vulnerabilità SAST fa fallire la pipeline; un finding legacy preesistente non la fa fallire. - I probabili falsi positivi compaiono nella issue in sezione separata, non pesati e non tra le attività da correggere. - Una persona non riceve più di 8 punti di debito tecnico di sicurezza per sprint; se tutti i candidati sono al cap, la issue non si apre. - Con `DRY_RUN` attivo nulla viene creato/modificato su GitLab. ## Test - [x] Il triggeratore seleziona solo i repo dormienti - Eseguire `trigger_scans.py` con `DRY_RUN=true` e `SCAN_STALE_DAYS=90` - Verificare nel report che i repo con pipeline recente siano "saltati-attivi" e solo quelli ≥90gg siano "triggerati" - [x] Bootstrap processa tutti i repo - Eseguire con `SCAN_STALE_DAYS=0` (DRY_RUN) - Verificare che tutti i repo del perimetro risultino triggerati (entro il limite di batch) - [x] Pipeline triggerata apre una issue nello sprint successivo - Triggerare la pipeline di un repo con finding noti (`SECURITY_CREATE_ISSUE=true`) - Verificare una issue nell'iterazione successiva con label `attività::bug, technical-debt, security, automatica`, peso, assegnatario - [x] Il job non gira in MR - Aprire una MR sul repo - Verificare che `create-security-issue` non venga eseguito - [x] Gate diff-aware blocca solo i finding nuovi - Su un repo con `SEMGREP_GATE_ENABLED=true`, aprire una MR che introduce una vulnerabilità SAST → la pipeline fallisce - Aprire una MR che non tocca i file con finding legacy → la pipeline passa - [x] Falso positivo non diventa lavoro - Con una regola in `fp-rules.yaml` per un finding noto (es. MD5 imposto da API) - Verificare che sia soppresso (nel report) e non compaia tra le attività da fixare - [x] Nessun doppione e cap di peso - Triggerare due volte lo stesso repo nello stesso sprint → nessuna seconda issue - Con candidati già a peso 8 → issue non aperta, esito nel report ## Verifica ed evidenze I criteri di test qui sopra non sono eseguibili a mano da un utente non tecnico (riguardano logica di CI, triage, assegnazione): sono coperti da **test automatici** che girano in pipeline, affiancati dalle esecuzioni reali del pilota. - **Suite di test automatici** — uno per criterio, mapping 1:1 con la sezione Test: [`test_acceptance.py`](https://gitlab.com/opencity-labs/product/-/blob/main/.gitlab/ci/security_sprint_agent/tests/test_acceptance.py). Job CI `test:security-sprint-agent`; run verde di riferimento: [job #15312363180](https://gitlab.com/opencity-labs/product/-/jobs/15312363180) — **17 passed**. - **Esecuzione reale — issue di esempio** (16/07): [application-registry#129](https://gitlab.com/opencity-labs/area-personale/stanzadelcittadino-application-registry/-/work_items/129), creata automaticamente su pipeline triggerata, con label, peso, assegnatario e iterazione dello sprint successivo. È il campione di riferimento perché include anche le **vulnerabilità delle dipendenze** (lxml XXE → 6.1.0, urllib3 → 2.7.0), con triage e approccio che citano l'uso reale nel codice — copertura che prima sfuggiva (vedi il fix del parser `applications` e la convenzione Dockerfile in #553). Idempotenza e cap di peso verificati sul campo durante il pilota (un secondo trigger sullo stesso repo non crea una seconda issue). - **Gate diff-aware — verifica dal vivo (13/07)** su [application-registry MR !360](https://gitlab.com/opencity-labs/area-personale/stanzadelcittadino-application-registry/-/merge_requests/360), con `SEMGREP_GATE_ENABLED=true`: - codice pulito (il fix vero della #125) → il gate **passa**: [job 15313337853](https://gitlab.com/opencity-labs/area-personale/stanzadelcittadino-application-registry/-/jobs/15313337853) — _"nessun finding nuovo ≥ High introdotto dalla MR. OK."_ - finding High introdotto dalla MR (command injection di prova) → il gate **blocca** la MR (job fallito, non mergiabile): [job 15313593534](https://gitlab.com/opencity-labs/area-personale/stanzadelcittadino-application-registry/-/jobs/15313593534) — _"la MR introduce 1 finding ≥ High … [HIGH] OS Command Injection … Correggi i finding introdotti"_. - ha bloccato **solo** il finding introdotto, non il debito legacy già presente nel repo (conferma della diff-awareness). - **Ambiente di test**: essendo infrastruttura di CI **senza interfaccia utente**, l'evidenza verificabile è la pipeline (job sopra) e le issue reali create, non uno staging applicativo — che qui non esiste. ## Rischi di sicurezza Rispetto al progetto iniziale (auto-fix + MR), l'agente **non modifica codice e non apre MR**: apre solo issue. Superficie di scrittura minima. - **Prompt injection dai dati degli scanner e dal codice**: finding ed estratti sono trattati come dati non fidati, sanitizzati e incapsulati in blocchi con ID casuale. In triage Claude ha **solo lettura** sul checkout e un ambiente ridotto (`HOME`, `PATH`, `ANTHROPIC_API_KEY`): non vede i token GitLab/Snyk, quindi un'injection non può esfiltrare credenziali né agire su GitLab. - **Token di gruppo / raggio d'azione**: operazioni GitLab (trigger pipeline, apertura issue) col bot token `GITLAB_OC_API_TOKEN`. Mitigazioni: perimetro esplicito, tetto di peso per persona, idempotenza a marker, `DRY_RUN`, throttling del triggeratore, nessuna operazione distruttiva. Da verificare: permessi minimi del token (`api`) ed esclusività al bot. - **Trigger di pipeline su repo altrui**: il triggeratore lancia pipeline sul default branch di altri repo; usa `POST /projects/:id/pipeline` (nessuna modifica al codice), su repo del solo gruppo, con limite di batch. ## Perimetro e pilota Pilota: gate diff-aware su 1-2 repo attivi + trigger reale su 5 repo dormienti (allowlist temporanea), review delle issue col team; poi bootstrap dello stock e rollout. La progettazione completa è in `spec/security-sprint-agent/` nel repo product. Il vecchio job `security-auto-fix` (auto-fix v3) resta opt-in finché il nuovo agente non è validato, poi viene rimosso. ## Label prodotto Assente intenzionalmente: attività infrastrutturale di sicurezza trasversale a tutti i prodotti, non associabile a un singolo `product::`. ## Documentazione Nessuna PR Gitbook, per scelta motivata: Gitbook (Manuali Opencity) è documentazione **rivolta agli utenti finali del prodotto**. Questo è un **agente interno di CI**, senza interfaccia utente, non utilizzato da cittadini né da operatori comunali — quindi **fuori dal perimetro dei manuali cliente**, e non esistono schermate da mostrare (screenshot non applicabili). La documentazione operativa — per i team di sviluppo che ricevono le issue e per chi opera l'agente — è [`SECURITY_SPRINT_AGENT.md`](https://gitlab.com/opencity-labs/product/-/blob/main/.gitlab/ci/security_sprint_agent/SECURITY_SPRINT_AGENT.md) nel repo product, versionata insieme al codice come per gli altri job di `devops.yml`. Questa è la sede corretta della documentazione per un'attività infrastrutturale interna, non Gitbook. <!-- issue riscritta (08/07): architettura a due componenti (triggeratore + job devops.yml) + gate diff-aware in MR, Modello A. -->