API de validación

La API de validación OSCAL de Secani valida documentos JSON OSCAL 1.2.2 a través de HTTP. PUBLICAR el documento en sí como cuerpo de la solicitud (sin sobre, sin cuenta) y recibir un informe legible por máquina desde el mismo motor que impulsa el validador del navegador. Está diseñado para máquinas en funcionamiento: trabajos de CI, scripts de integración y otras herramientas que producen o transforman documentos OSCAL.

Contrato de privacidad. Su documento se procesa transitoriamente en la memoria de los servidores de la UE (Frankfurt) y se descarta cuando se envía la respuesta. Nada se conserva, se registra ni se utiliza para nada más que para producir la respuesta; la telemetría es solo agregada (tipo de modelo, tamaño del grupo, resultado, duración). El validador del navegador permanece completamente local en el navegador: su documento nunca sale del navegador allí.

Inicio rápido

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

Los artefactos grandes (los catálogos completos pueden exceder el límite de 4 MB de cuerpo bruto) se comprimen extremadamente bien; envíelos comprimidos con gzip:

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 @-

Respuesta

Una validación completa siempre devuelve HTTP 200 – "valid": false es una validación exitosa de un documento no válido. Sucursal en el valid campo, no el código de estado.

{
  "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
  }
}

Errores

Los errores utilizan los detalles del problema RFC 9457 (application/problem+json) con un formato estable y legible por máquina code:

Cada problema también incluye una solución procesable. resolution y un documentation URL. Ver el completo referencia de recuperación de errores.

Niveles de validación

El level El parámetro de consulta controla la profundidad de validación. Sin ninguno dado, level=schema ejecuciones: validación simple del esquema JSON, sin cambios. level=full Además, involucra la capa semántica: controles de restricciones y referencias que van más allá de lo que el esquema JSON por sí solo puede expresar.

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

Una ejecución full que llegue a la capa semántica puede devolver resultados con severity: "warning". Los hallazgos de tipo warning son informativos y no invalidan el documento: señalan patrones cuestionables que no infringen el esquema, como un enlace interno sin destino, mientras valid permanece en true. La lógica debe seguir basándose en valid; severity permite después distinguir los errores de las advertencias.

{
  "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"
    }
  }
}

Las reglas predeterminadas optan por participar individualmente a través de rules= – una lista de identificadores de reglas separados por comas, válida sólo junto a level=full. Vuelve una identificación desconocida 400 ERR_UNSUPPORTED_PARAMETER nombrar la identificación infractora, sin deshacerse del catálogo de reglas:

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

Cada full ejecución que llega a los informes de la capa semántica meta.semanticRules: el número de reglas semánticas activas (count) y un SHA-256 estable sobre el conjunto ordenado de sus identificadores (sha256). A full La ejecución rechazada en la capa de esquema nunca llega a la semántica, por lo que no conlleva meta.semanticRules. El hash identifica exactamente qué conjunto de reglas se aplicó, por lo que optar por una regla mediante rules= lo cambia. De este modo, una respuesta almacenada se convierte en un registro reproducible de lo que realmente se verificó, incluso cuando el catálogo de reglas crece en futuras versiones.

Límites

• Cuerpo de la solicitud: 4 MB sin procesar, 24 MB descomprimidos (Content-Encoding: gzip es compatible y recomendado para documentos grandes).
• Un documento por solicitud.
• Límites de tarifas anónimas: 10 solicitudes por minuto y 300 por día por cliente, expuestas a través de RateLimit-Limit, RateLimit-Remaining, y RateLimit-Reset encabezados de respuesta, con Retry-After sobre 429 respuestas. ¿Necesitas más? Cree una clave API (ver más abajo) o comuníquese hola@secani.com.

Claves API

Los límites más altos y duraderos vienen con una clave API. Las claves se crean en la configuración de la organización; Cada clave se muestra exactamente una vez: en el momento de la creación. envíalo como 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 clave, los límites aumentan a 120 solicitudes por minuto y 10 000 por día por clave, lo que se aplica de manera centralizada e independiente de cualquier instancia de servidor, mientras que los límites anónimos son de mejor esfuerzo por instancia. El nivel anónimo permanece: solicitudes sin Authorization El encabezado se comporta sin cambios. Devuelve una clave desconocida o revocada 401 ERR_INVALID_API_KEY y nunca vuelve al nivel anónimo.

Parámetros reservados

level y rules ya no están reservados – están en vivo; consulte los niveles de validación más arriba. Un parámetro mantiene un rango de valores reservado:

• oscal-version – fija la versión de especificación y acepta solo 1.2.2 hoy. Cualquier otro valor está reservado para futuras versiones y devoluciones de OSCAL. ERR_UNSUPPORTED_PARAMETER con una explicación.

OpenAPI

El contrato canónico legible por máquina se entrega en /openapi.json. el versionado /api/oscal/v1/openapi.json La URL permanece disponible por motivos de compatibilidad. CORS está abierto (*), por lo que se puede llamar a la API directamente desde herramientas basadas en navegador.

Ver también: el validador del navegador para uso interactivo y el Kit de herramientas de TypeScript detrás de ambos.