Distinta base e strumenti SBOM
La distinta base del software (SBOM) elenca i componenti che compongono un prodotto. Serve a rispondere in fretta alla domanda che conta durante un incidente: «questo difetto ci riguarda?». CRAnotify non genera SBOM: si collega agli strumenti che già produci in pipeline e ne registra la sincronizzazione.
Strumenti collegabili
Da Area utente › SBOM si attivano gli strumenti in uso e si inseriscono, dove serve, indirizzo e token di accesso:
La configurazione è per organizzazione ed è un’operazione da amministratore; ogni modifica lascia una riga nel registro.
Come funzionano le connessioni
Il collegamento avviene con il modello a token: sul portale dello strumento si genera una chiave API (o Personal Access Token) e la si incolla nel campo corrispondente. Il pulsante Verifica connessioni esegue una chiamata autenticata reale allo strumento e riporta l’esito per ciascuno: ok, token rifiutato o irraggiungibile.
In pratica. Il token generato sullo strumento va conservato come una password: chi lo possiede può leggere i dati della tua distinta base. Ruotalo periodicamente e revocalo se un collaboratore lascia il team.
Ricezione automatica dalle tue pipeline
Uno scanner in CI può inviare direttamente la SBOM a CRAnotify. L’invio autentica con una chiave API che porta lo scope products:write, sull’intestazione X-CRA-API-Key (in alternativa Authorization: Bearer cra_live_…). Il prodotto è identificato dallo SKU nel percorso:
curl -X POST "https://api.cranotify.eu/api/v1/external/products/PRD-4f2a91/sbom?tool=trivy&release=2.4.1" \
-H "X-CRA-API-Key: cra_live_…" \
-H "Content-Type: application/json" \
--data-binary @sbom.json| Aspetto | Valore |
|---|---|
| Formati accettati | CycloneDX (JSON) e SPDX (JSON). |
| Dimensione massima | 25 MB per invio. |
Parametro tool | Facoltativo: se assente, lo strumento viene riconosciuto dai metadati del documento. |
| Prodotto (SKU nel percorso) | Il prodotto è identificato dallo SKU nel percorso (/products/{sku}/sbom): la distinta si aggancia sempre a quel prodotto. Uno SKU inesistente nella tua organizzazione viene rifiutato (vedi sotto). |
Parametro release | Facoltativo: aggancia il documento a una release precisa nello storico del prodotto. Se assente, si usa la release che il prodotto dichiara corrente. |
| Risposta | JSON con strumento, formato, numero di componenti e di vulnerabilità, momento di ricezione. |
Un invio riuscito marca lo strumento come realmente collegato (non basta aver salvato un token), aggiorna il conteggio dei componenti e lascia una riga nel registro.
| Risposta | Significato |
|---|---|
401 invalid_api_key | Chiave assente, errata o revocata. |
403 (scope mancante) | La chiave esiste ma non porta lo scope products:write. |
404 unknown_product | Lo SKU nel percorso indica un prodotto che non esiste nella tua organizzazione. Uno SKU di un’altra organizzazione dà la stessa risposta di uno mai creato. |
422 unrecognised_sbom_format | Il corpo non è né CycloneDX né SPDX in JSON. |
Lo storico: le distinte non si sovrascrivono
Ogni distinta base ricevuta viene conservata come un fatto a sé, con due tempi distinti — quando è stata prodotta e quando l’abbiamo ricevuta. L’identità di una distinta è prodotto + release: un secondo invio per la stessa release diventa una nuova versione, e quella precedente resta leggibile.
La SBOM appartiene dunque a una release precisa ed è versionata per release (mai sovrascritta). Caricamento web, API esterna e CLI convergono tutti sullo stesso modello versionato. Il dettaglio del rilascio (/releases/{id}) mostra le informazioni della release, lo storico delle SBOM e l’inventario dei componenti.
Non è una comodità. Se un’autorità chiede quale versione di un componente fosse distribuita nel giorno in cui la tua organizzazione ha avuto consapevolezza di un problema, la risposta va ricostruita su ciò che il sistema poteva sapere quel giorno — e «non lo sappiamo più» è una risposta che nessuna diligenza successiva recupera.
Caricare una distinta a mano
Dalla scheda di un prodotto si può caricare un file SBOM direttamente, senza pipeline e senza chiave. Serve il primo giorno, quando l’integrazione non c’è ancora ma il prodotto deve già smettere di essere cieco: senza una distinta base, una vulnerabilità pubblicata su un componente non si può agganciare a nessun prodotto.
Il file passa dagli stessi controlli dell’invio automatico — stessi formati, stesso limite di 25 MB, stessi rifiuti — ed entra nello stesso storico. Se non indichi una release viene usata quella che il prodotto dichiara corrente; se il prodotto non ne dichiara nessuna, il caricamento viene rifiutato invece di inventarne una. Resta scritto che a portare dentro quel documento è stata una persona, e quale.
A che cosa serve nel flusso
- Restringere il perimetro. Quando esce una vulnerabilità su una libreria diffusa, la distinta base dice in quali dei tuoi prodotti quella libreria si trova, e in quale versione.
- Alimentare la segnalazione a monte. I componenti censiti sono l’elenco da cui parte la segnalazione al manutentore.
- Documentare la diligenza. Due strumenti attivi coprono uno dei sette passi della lista di attivazione.
CRAnotify non decide al posto tuo se un componente vulnerabile rende il prodotto sfruttabile: la presenza di una libreria non equivale alla presenza del difetto sfruttabile in quel contesto. La valutazione resta il triage.
Formati
Gli standard supportati sono CycloneDX e SPDX. Se produci SBOM in un solo formato, va bene: l’importante è che siano aggiornate a ogni rilascio. Una distinta base ferma a due anni fa è peggio di nessuna, perché induce a conclusioni sbagliate.
Come organizzarsi
- Genera la SBOM nella pipeline di build, non a mano.
- Inviala a CRAnotify a ogni rilascio con la chiave dedicata (scope
products:writesoltanto). - Tieni nell’anagrafica l’elenco dei componenti critici con il rispettivo manutentore.
- Verifica ogni tanto che la data dell’ultima sincronizzazione corrisponda all’ultimo rilascio.