L'API REVIEWIT

01In una frase #sec_decf73bd

L'API REVIEWIT espone le campagne, le decisioni, le prove e la pista di audit ai tuoi strumenti personali — in lettura, sotto un'identità di macchina autenticata tramite certificato, e senza mai permettere di prendere una decisione di revisione.

02Il problema #sec_148ec0fa

Una campagna di ricertificazione non vive da sola. I suoi risultati interessano altri sistemi: lo strumento di governance dei rischi che consolida i controlli, il SIEM che correla gli eventi di sicurezza, lo strumento decisionale che segue gli indicatori, la gestione dei servizi che attiva le rettifiche.

Senza un'interfaccia programmatica, questi scambi avvengono tramite esportazioni manuali: qualcuno scarica un file, lo deposita da qualche parte e lo rifarà il mese successivo. Ne derivano tre difetti, tutti noti :

La freschezza. Un cruscotto alimentato a mano è falso la maggior parte delle volte.

La tracciabilità. Un file che transita per una casella di posta non ha più un'origine certa, né una garanzia di completezza.

Il costo umano. Il tempo trascorso a trasportare dati è tempo che non è stato trascorso a esaminare gli accessi.

03Il principio #sec_63100d97

Si legge tutto. Non si decide nulla.

Questa è la regola fondamentale dell'API ed è l'esatto pendant del principio che governa le superfici di amministrazione: l'amministratore non approva nulla.

Nessuna decisione di revisione tramite API

È impossibile certificare, revocare o porre un'eccezione tramite chiamata programmatica. Non si tratta di una funzionalità rimandata a più tardi: è un'esclusione di principio.

Una decisione di ricertificazione trae tutto il suo valore dalla sua imputabilità a una persona che ha guardato, giudicato e che ne risponde. Una decisione prodotta da uno script non ha un autore — al massimo, ha un operatore che ha lanciato lo script, il che non è la stessa cosa. Aprire questa porta equivarrebbe a permettere di certificare un parco intero in una richiesta e a ridurre a zero il valore probante di tutte le altre decisioni del sistema.

L'API serve quindi a sfruttare i risultati del controllo, mai a fabbricarli.

La sottoscrizione proviene dal token, mai dalla chiamata

Nessuna chiamata contiene un parametro che designa il cliente, la sottoscrizione o il perimetro da interrogare. Il perimetro è derivato dall'identità del token presentato.

La conseguenza è che non esiste alcuna richiesta, anche malformata, anche malevola, che possa restituire i dati di un altro cliente. Non ci si protegge da un errore di parametro: si elimina il parametro.

L'autenticazione tramite certificato è obbligatoria

I sistemi chiamanti non si autenticano con un segreto condiviso, ma con un certificato: firmano la loro richiesta di token con la loro chiave privata, che REVIEWIT verifica con la chiave pubblica dichiarata.

La differenza è concreta. Un segreto condiviso è una stringa di caratteri: circola, viene copiato in un file di configurazione, si ritrova in un repository di codice e, una volta divulgato, è utilizzabile da chiunque. Una chiave privata non lascia mai il sistema chiamante — non c'è nulla da intercettare.

04Come funziona #sec_ad3e5605

I clienti API

Ogni sistema autorizzato a chiamare l'API è dichiarato come cliente, collegato a una sottoscrizione, con le proprie autorizzazioni. La gestione viene effettuata dal Subscription Manager e la capacità di aprire l'API dipende dall'edizione sottoscritta.

Questi clienti sono distinti dalle connessioni che REVIEWIT utilizza per andare a raccogliere i dati presso il cliente. Sono due nozioni opposte — una entra, l'altra esce — e confonderle equivarrebbe a far sì che un accesso in lettura sull'API ereditasse le autorizzazioni di raccolta.

Le autorizzazioni

Un cliente non riceve « l'API »: riceve un insieme di autorizzazioni corrispondenti ai domini di cui ha bisogno. Un connettore SIEM che consuma solo la pista di audit non ottiene l'accesso alle prove firmate.

La paginazione è obbligatoria

Tutte le collezioni si percorrono tramite cursore: ogni risposta indica dove riprendere. Non è un dettaglio di comfort.

Una paginazione per numero di pagina diventa falsa non appena i dati si spostano durante il percorso — alcuni elementi vengono visti due volte, altri mai. Su un'esportazione di conformità, ciò significa una prova incompleta senza che nessuno se ne accorga. Il cursore elimina questa classe di errore.

Il contratto è fisso e verificato

La specifica dell'interfaccia è bloccata da un test automatizzato. Qualsiasi modifica non intenzionale del contratto — un campo rinominato, un tipo modificato, una risposta la cui forma evolve — fa fallire la catena di integrazione prima della pubblicazione.

Questo è ciò che permette di impegnarsi sulla stabilità dell'interfaccia: non è garantita da una buona intenzione, ma da un meccanismo che rifiuta il cambiamento accidentale. Le evoluzioni di rottura passano attraverso una nuova versione.

05Ciò che l'API espone #sec_0de57e12

Tre punti meritano di essere dettagliati.

Le decisioni sono normalizzate. Gli stati interni del prodotto sono tradotti in un vocabolario pubblico stabile e documentato. Un'evoluzione del funzionamento interno non rompe le integrazioni dei clienti.

Le prove non sono memorizzate. Il certificato che attesta una revisione viene prodotto al momento in cui viene richiesto, a partire dai dati della pista, e poi firmato elettronicamente. Nulla viene conservato in anticipo. La conseguenza è importante: una prova scaricata oggi riflette lo stato verificabile oggi e non è un documento fisso di cui si ignorerebbe la freschezza. Una revisione non decisa non produce una prova — produce un rifiuto esplicito.

L'esportazione di audit è progettata per il flusso continuo. Funziona avanzando su un cursore e adotta una semantica protettiva: finché gli eventi escono, viene fornita la posizione successiva; quando non c'è nulla di nuovo, non viene restituita alcuna posizione e il consumatore conserva la propria. Un sistema di raccolta che interroga ogni minuto non perde quindi mai la sua posizione, anche se si riavvia.

06Ciò che viene dopo #sec_45c04ae7

Le notifiche in uscita si baseranno sullo stesso meccanismo di uscita delle e-mail del prodotto. Non è una scelta di implementazione banale: garantisce che un webhook e una notifica descrivano lo stesso evento, nello stesso momento, con le stesse garanzie di consegna — piuttosto che due percorsi concorrenti che finirebbero per divergere.

Le scritture amministrative permetteranno di controllare le campagne da uno strumento terzo: creare, avviare, chiudere. Rimarranno strettamente amministrative.

La decisione di revisione, invece, non sarà mai esposta — in nessuna versione.

07Un punto aperto, dichiarato #sec_10c3ba42

I quoti di consumo sono parzialmente trattati. Una limitazione della portata istantanea protegge oggi il servizio, ma i quoti per periodo e per edizione non sono ancora arbitrati: è una decisione commerciale tanto quanto tecnica, ed è identificata come tale.

Questo dossier lo menziona piuttosto che far credere a una copertura completa.

08Da ricordare #sec_9a930c7a

L'API risponde a una richiesta semplice — i nostri dati di conformità devono vivere nei nostri strumenti — senza cedere su ciò che costituisce il valore del prodotto.

È aperta in lettura su tutto ciò che il dispositivo produce, chiusa su ciò che deve rimanere un atto umano. Autentica i suoi chiamanti tramite certificato, deriva il loro perimetro dalla loro identità piuttosto che chiederglielo, pagina tramite cursore per non mentire mai sulla completezza e garantisce il suo contratto tramite un test piuttosto che tramite una promessa.

Un'integrazione non deve mai diventare un mezzo per fare più velocemente ciò che il controllo richiede di fare attentamente.