
Ogni validatore OSCAL dichiara di «validare OSCAL». Quasi nessuno sa dirvi che cosa significhi questa frase.
I modelli OSCAL del NIST sono scritti in Metaschema: otto moduli radice più import condivisi, migliaia di righe di XML che definiscono non solo la forma dei documenti ma anche la loro semantica: vocabolari di valori ammessi, regole di unicità, indici di riferimenti incrociati, requisiti di cardinalità. Uno JSON Schema intercetta la forma. È nella semantica che i documenti di compliance sbagliano davvero, ed è lì che «validiamo OSCAL» diventa silenziosamente «validiamo una parte di OSCAL, non sappiamo bene quale».
Noi volevamo sapere esattamente quale parte. Così abbiamo costruito il nostro validatore come si sottopone a audit un sistema: partire dai sorgenti, enumerare tutto e rendere conto di ogni singolo elemento.
La prima decisione è stata quella decisiva: l’autorità sono i sorgenti NIST, non l’implementazione di riferimento. Abbiamo fissato usnistgov/OSCAL al commit 21403b4a… (v1.2.2), messo in cache ogni Metaschema in modo identico al byte con hash SHA-256 e trattato la veterana OSCAL CLI in Java per ciò che è davvero: un termine di confronto da sottoporre a controinterrogatorio, non una verità da copiare. (Tra l’altro incorpora i binding di OSCAL 1.2.1: può elaborare documenti 1.2.2, ma non parla 1.2.2.)
Poi abbiamo inventariato lessicalmente ogni occorrenza di vincolo nei sorgenti fissati. Non i tipi di vincolo, ma le occorrenze, identificate per file e riga, così che due vincoli che condividono per caso un ID non collassino mai in uno solo. Il conteggio è arrivato a 348.
Per ogni occorrenza, la nostra build deve sostenere esattamente uno di tre verdetti, imposti da un generatore che ricalcola il registro a ogni esecuzione:
Occorrenze senza verdetto: zero.
È proprio l’ultima categoria, quella delle esclusioni, che si è rivelata interessante.
Quando si verificano 348 vincoli uno per uno, si trovano delle cose. Tre delle nostre esclusioni sono difetti dei sorgenti NIST stessi:
oscal_mapping-common_metaschema.xml, riga 657, vincola un flag definito cinque righe prima, che poi non viene mai referenziato da nulla. Nessun documento possibile contiene questo flag. Il vincolo è insoddisfacibile.inventory-item si applica solo quando @type è software, hardware o service, ma inventory-item non dichiara alcun flag type. (Il suo vicino, asset-id, è a sua volta commentato nel sorgente.) Il predicato non può mai corrispondere.with-child-controls dei profile. Chi legge il sorgente li vede; lo schema compilato non li applica mai. Tutti e tre i rilievi sono stati segnalati upstream: usnistgov/OSCAL#2254, #2255, #2256.E l’audit ha colpito in entrambe le direzioni: il nostro stesso valutatore aveva un bug per cui i vincoli rivolti ai flag (come i valori ammessi di action/@type) venivano compilati nell’inventario ma non scattavano mai, in silenzio. Non l’abbiamo trovato per fortuna: il gate di chiusura si è rifiutato di accettare evidenze per quelle due occorrenze, ed è esattamente la modalità di guasto che l’intero sistema è progettato per far emergere.
Affermare che «l’implementazione di riferimento si lascia sfuggire qualcosa» sulla sola base dell’ispezione dei sorgenti è esattamente il tipo di asserzione non dimostrata che questo progetto vuole eliminare. Abbiamo quindi scaricato la Java OSCAL CLI 3.2.0 da Maven Central, ne abbiamo verificato l’hash ed eseguito entrambi i validatori su una famiglia di fixture i cui documenti di base superano la validazione senza errori su entrambi i lati, così che ogni disaccordo sia attribuibile a un’unica modifica introdotta.
OSCAL 1.2.2 ha modificato esattamente due vincoli oltre agli aggiornamenti di versione (entrambi nel modello SSP). La CLI Java, che incorpora i binding 1.2.1, sta dalla parte sbagliata in ogni conseguenza osservabile:
rel="validation" pendente viola la 1.2.2. Java: valido, exit 0.rel="validated-by" pendente è corretto secondo la 1.2.2 (il vincolo è stato eliminato). Java: non valido.responsible-role senza il party-uuid facoltativo è corretto secondo la 1.2.2: il NIST ha aggiunto il predicato proprio per risolvere questo problema. Java va in errore con, testualmente, Key reference [null] not found.Poi un caso che non ha nulla a che vedere con lo sfasamento di versione: un catalog la cui action nei metadati dichiara "type": "invented-type", vietato alla riga 877 del Metaschema dei metadati sia nella 1.2.2 sia nei sorgenti 1.2.1 incorporati da Java. Java lo dichiara valido, in JSON e in XML. Il vincolo è rivolto a un flag; i vincoli sui flag che non scattano in silenzio sono esattamente la classe di bug che il nostro gate di completezza ha intercettato nel nostro valutatore. L’implementazione di riferimento ha la stessa classe di bug, e nessun gate di chiusura che la intercetti. L’abbiamo segnalato upstream come metaschema-framework/oscal-cli#279. (Abbiamo mappato la classe in modo meccanico: esattamente 2 delle 200 occorrenze di allowed-values riguardano flag, e l’unico membro di livello error è quello che abbiamo testato dal vivo. Nessun residuo non testato.)
E ora il momento dell’onestà, perché l’esecuzione ha colpito in entrambe le direzioni: il nostro validatore ha respinto il catalog SP 800-53 rev5 dello stesso NIST. Venti errori, tutti dovuti a un unico difetto: il nostro valutatore degli indici trattava come violazione un campo chiave facoltativo mancante, mentre la specifica Metaschema lo definisce una chiave nulla. Java ha accettato il file; avevamo torto noi; l’abbiamo corretto il giorno stesso e ora l’800-53 si valida senza errori. In seguito l’esecuzione ne ha intercettato un secondo: continuavamo ad applicare il vocabolario OSCAL dei tipi di action anche quando action/@system dichiarava un URI personalizzato, cioè esattamente la segmentazione per organizzazione richiesta dalle osservazioni dello stesso NIST. Corretto anche questo. Un banco di prova differenziale che trova sempre e solo i bug dell’altra parte non è un banco di prova, è marketing.
(Da archiviare sempre sotto «entrambi i lati»: nessuno dei due resolver validava semanticamente il proprio output. Il resolve-profile di Java scrive tranquillamente un catalog che lo stesso validate di Java respinge poi, e il nostro faceva lo stesso, con un gate sullo schema ma non sulla semantica. Il nostro ora si rifiuta di scrivere risoluzioni semanticamente non valide; Java ancora non può, perché chiudere questa falla richiede un livello semantico di cui ci si possa fidare.)
La seconda cosa che manca agli strumenti esistenti: i documenti OSCAL non vivono isolati. Un assessment result importa un assessment plan, che importa un SSP, che importa un profile, che si risolve rispetto ai catalog. La documentazione del modello è piena di relazioni che nessun validatore di singoli file può verificare: «il target di questo finding deve risolversi in uno statement della baseline», «questo POA&M deve identificare il proprio sistema».
Abbiamo quindi costruito una validazione tra documenti che risolve davvero questi collegamenti. Chiedetegli di verificare un SSP: risolve la baseline importata attraverso l’intera pipeline di risoluzione dei profile (secondo la bozza di specifica) fino ai catalog, calcola l’insieme di controlli selezionati e vi dice:
{
"ruleId": "SSP-003.b",
"severity": "warning",
"path": "/…/implemented-requirements/1/control-id",
"message": "implemented control 'ac-99' is not supplied by the resolved import-profile 'file:///…/baseline.json'"
}
Con una regola di progettazione cruciale: queste verifiche delle relazioni sono interpretazioni di testo documentato, e le trattiamo come tali: disattivate per impostazione predefinita, avvisi e non errori, con l’ambito di risoluzione di ogni campo fissato alla relativa riga del sorgente e con tutto ciò che è soltanto deducibile escluso esplicitamente per nome. Dove la norma è cauta, un validatore non dovrebbe bluffare. (Il nostro esempio preferito: la specifica del POA&M dice che è richiesto un import di SSP oppure un system-id: «Both may be present.» Avvisiamo quindi solo quando non è presente nessuno dei due. Nessun or esclusivo inventato.)
Perché i documenti vivono in browser, funzioni serverless, CLI e database, e volevamo un unico validatore in tutti questi contesti, non un sidecar JVM accanto a ciascuno. I validatori sono moduli standalone Ajv precompilati: semplice JavaScript generato, nessuna compilazione di schemi a runtime, output stabile al byte. Lo stesso codice che alimenta le nostre funzionalità di validazione gira senza modifiche nella scheda del vostro browser e nella nostra CLI. E il determinismo non è solo una comodità operativa: è ciò che rende possibili, in primo luogo, evidenze fissate tramite hash.
import { createDiagnosticsOscalProcessor } from "@secani/oscal/diagnostics";
const result = createDiagnosticsOscalProcessor({ maxIssues: 50 }).validate(doc);
validate --resolve-imports --interpretive all)Il report tecnico completo (modello di autorità, chiusura di completezza, tabella delle prove del confronto differenziale e ciò che deliberatamente non affermiamo) si trova nella documentazione del validatore. Il validatore è in staging privato in vista di un rilascio open source; l’API di validazione in hosting espone oggi il livello dello schema, mentre il livello semantico seguirà.

OSCAL · 26 luglio 2026 · 20 Min.
OLIR fornisce contenuti di mappatura e governance. OSCAL fornisce la struttura leggibile dalle macchine per usare quelle mappature nella gap analysis, nel riutilizzo delle evidenze e nei flussi di analisi dell’impatto delle modifiche.

OSCAL · 14 luglio 2026 · 7 Min.
OSCAL trasforma i documenti di compliance in dati strutturati: otto modelli documentali, tre formati e un ecosistema che sta diventando lo standard per la regolamentazione.

OSCAL · 16 luglio 2026 · 6 Min.
Con la RFC-0024 e le Consolidated Rules 2026, FedRAMP rende obbligatori i dati di autorizzazione strutturati. Le scadenze sono scaglionate, la direzione è inequivocabile.
Secani collega gli ambiti, le prove, i compiti e gli agenti AI in uno spazio di lavoro condiviso.