API di convalida

L'API di convalida OSCAL Secani convalida i documenti JSON OSCAL 1.2.2 su HTTP. PUBBLICA il documento stesso come organismo della richiesta – senza busta, senza account – e ricevi un rapporto leggibile dalla macchina dallo stesso motore che alimenta il validatore del browser. È progettato per macchine in volo: lavori CI, script di integrazione e altri strumenti che producono o trasformano documenti OSCAL.

Contratto sulla privacy. Il tuo documento viene elaborato temporaneamente in memoria sui server dell'UE (Francoforte) e scartato quando viene inviata la risposta. Niente viene persistente, registrato o utilizzato per altro oltre a produrre la risposta; la telemetria è solo aggregata (tipo di modello, intervallo di dimensioni, risultato, durata). IL validatore del browser rimane completamente locale nel browser: il tuo documento non lascia mai il browser lì.

Avvio rapido

curl -sS -X POST https://secani.com/api/oscal/v1/validate \
  -H "content-type: application/json" \
  --data-binary @system-security-plan.json

Gli artefatti di grandi dimensioni (i cataloghi completi possono superare il limite di 4 MB del corpo grezzo) si comprimono molto bene: inviali compressi:

gzip -c catalog.json | curl -sS -X POST https://secani.com/api/oscal/v1/validate \
  -H "content-type: application/json" \
  -H "content-encoding: gzip" \
  --data-binary @-

Risposta

Una convalida completata restituisce sempre HTTP 200 – "valid": false è una convalida riuscita di un documento non valido. Ramo sul valid campo, non il codice di stato.

{
  "valid": false,
  "model": "system-security-plan",
  "oscalVersion": "1.2.2",
  "level": "schema",
  "complete": true,
  "issues": [
    {
      "ruleId": "nist-schema:1.2.2:system-security-plan:required:system-security-plan/metadata/version:required",
      "path": "/system-security-plan/metadata/version",
      "message": "must have required property 'version'",
      "keyword": "required",
      "severity": "error"
    }
  ],
  "issueCount": 37,
  "truncated": false,
  "meta": {
    "engine": "@secani/oscal",
    "validator": "1.2.2",
    "schemaSource": "NIST OSCAL v1.2.2 release JSON schemas",
    "patches": ["profile-combine-method"],
    "durationMs": 84
  }
}

Errori

Gli errori utilizzano i dettagli del problema RFC 9457 (application/problem+json) con un formato leggibile dalla macchina stabile code:

Ogni problema include anche un'azione utilizzabile resolution e un documentation URL. Vedi il completo riferimento per il ripristino degli errori.

Livelli di validazione

IL level il parametro di query controlla la profondità di convalida. Senza nessuno dato, level=schema viene eseguito: semplice convalida dello schema JSON, invariato. level=full coinvolge inoltre il livello semantico: controlli di vincoli e riferimenti che vanno oltre ciò che il solo JSON Schema può esprimere.

curl -sS -X POST "https://secani.com/api/oscal/v1/validate?level=full" \
  -H "content-type: application/json" \
  --data-binary @catalog.json

UN full run che raggiunge effettivamente il livello semantico può restituire risultati con severity: "warning". warning i risultati sono consultivi e non rendono un documento non valido: segnalano modelli discutibili ma che non violano lo schema (come un collegamento interno che non punta a nulla) e valid soggiorni true. Continua a ramificarsi valid; severity quindi separa gli errori dai suggerimenti.

{
  "valid": true,
  "model": "catalog",
  "oscalVersion": "1.2.2",
  "level": "full",
  "complete": true,
  "issues": [
    {
      "ruleId": "CAT-002.a",
      "path": "/catalog/controls/0/links/0/href",
      "message": "local catalog link '#missing-part' does not resolve to a control, part, or resource",
      "keyword": "resolved-catalog-link",
      "severity": "warning"
    }
  ],
  "issueCount": 1,
  "truncated": false,
  "meta": {
    "engine": "@secani/oscal",
    "validator": "1.2.2",
    "schemaSource": "NIST OSCAL v1.2.2 release JSON schemas",
    "patches": ["profile-combine-method"],
    "durationMs": 112,
    "semanticRules": {
      "count": 30,
      "sha256": "d5e9ef745394fed06db58bcd5999c505cbccc83e460db024b6f3061cb710d213"
    }
  }
}

Le regole predefinite vengono attivate individualmente tramite rules= – un elenco di ID regola separati da virgole, valido solo insieme level=full. Ritorna un ID sconosciuto 400 ERR_UNSUPPORTED_PARAMETER nominare l'ID incriminato, senza scaricare il catalogo delle regole:

curl -sS -X POST "https://secani.com/api/oscal/v1/validate?level=full&rules=PROF-002.a" \
  -H "content-type: application/json" \
  --data-binary @profile.json

Ogni full run che raggiunge i report del livello semantico meta.semanticRules: il numero di regole semantiche attive (count) e un SHA-256 stabile sull'insieme ordinato dei loro ID (sha256). UN full run rifiutato a livello di schema non raggiunge mai la semantica, quindi porta no meta.semanticRules. L'hash identifica esattamente quale set di regole è stato applicato, quindi è possibile inserire una regola rules= lo cambia. Una risposta archiviata diventa quindi una registrazione riproducibile di ciò che è stato effettivamente controllato, anche se il catalogo delle regole cresce con le versioni future.

Limiti

• Corpo della richiesta: 4 MB grezzi, 24 MB decompressi (Content-Encoding: gzip è supportato e consigliato per documenti di grandi dimensioni).
• Un documento per richiesta.
• Limiti di velocità anonimi: 10 richieste al minuto e 300 al giorno per cliente, emerse RateLimit-Limit, RateLimit-Remaining, E RateLimit-Reset intestazioni di risposta, con Retry-After su 429 risposte. Hai bisogno di più? Crea una chiave API (vedi sotto) o contatta ciao@secani.com.

Chiavi API

Limiti più elevati e durevoli vengono forniti con una chiave API. Crei le chiavi nelle impostazioni dell'organizzazione; ogni chiave viene mostrata esattamente una volta: al momento della creazione. Invialo come Authorization: Bearer sk_oscal_…:

curl -sS -X POST https://secani.com/api/oscal/v1/validate \
  -H "authorization: Bearer sk_oscal_..." \
  -H "content-type: application/json" \
  --data-binary @system-security-plan.json

Con una chiave, i limiti salgono a 120 richieste al minuto e 10.000 al giorno per chiave, applicati centralmente e indipendentemente da ogni singola istanza del server, mentre i limiti anonimi sono ottimali per istanza. Resta il livello anonimo: richieste senza an Authorization l'intestazione si comporta invariata. Ritorna una chiave sconosciuta o revocata 401 ERR_INVALID_API_KEY e non ritorna mai al livello anonimo.

Parametri riservati

level E rules non sono più prenotati: sono attivi; vedere Livelli di convalida sopra. Un parametro mantiene un intervallo di valori riservato:

• oscal-version – blocca la versione specifica e accetta solo 1.2.2 Oggi. Qualsiasi altro valore è riservato per futuri rilasci e resi OSCAL ERR_UNSUPPORTED_PARAMETER con una spiegazione.

OpenAPI

Viene notificato il contratto canonico leggibile dalla macchina /openapi.json. La versione /api/oscal/v1/openapi.json L'URL rimane disponibile per la compatibilità. CORS è aperto (*), in modo che l'API possa essere richiamata direttamente dagli strumenti basati su browser.

Vedi anche: il validatore del browser per uso interattivo e il Kit di strumenti TypeScript dietro entrambi.