Walidacja API

Interfejs API walidacji Secani OSCAL sprawdza poprawność dokumentów OSCAL 1.2.2 JSON za pośrednictwem protokołu HTTP. WYŚLIJ sam dokument jako treść żądania – bez koperty, bez konta – i otrzymaj raport do odczytu maszynowego z tego samego silnika, który obsługuje Walidator przeglądarki. Jest przeznaczony dla maszyn w locie: zadań CI, skryptów integracyjnych i innych narzędzi, które tworzą lub przekształcają dokumenty OSCAL.

Gwarancja prywatności. Dokument jest tymczasowo przetwarzany w pamięci na serwerach w UE (Frankfurt) i usuwany po wysłaniu odpowiedzi. Nie jest utrwalany, rejestrowany ani używany w żadnym innym celu; telemetria obejmuje wyłącznie dane zbiorcze (typ modelu, przedział rozmiaru, wynik i czas trwania). Walidator działający w przeglądarce pozostaje całkowicie lokalny — dokument nigdy nie opuszcza przeglądarki.

Szybki start

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

Duże artefakty (pełne katalogi mogą przekraczać limit 4 MB nieprzetworzonej treści) kompresują się wyjątkowo dobrze – wyślij je spakowane w formacie 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 @-

Odpowiedź

Zakończona walidacja zawsze zwraca HTTP 200 – "valid": false oznacza pomyślną walidację nieważnego dokumentu. Oddział na valid pole, a nie kod stanu.

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

Błędy

Błędy wykorzystują szczegóły problemu RFC 9457 (application/problem+json) ze stabilnym odczytem maszynowym code:

Każdy problem zawiera również rozwiązanie, które można podjąć resolution i a documentation Adres URL. Zobacz całość odniesienie do odzyskiwania po błędzie.

Poziomy walidacji

Parametr zapytania level określa głębokość walidacji. Domyślna wartość level=schema uruchamia standardową walidację schematu JSON. Wartość level=full włącza dodatkowo warstwę semantyczną: sprawdzanie ograniczeń i odwołań, których nie da się wyrazić wyłącznie za pomocą schematu JSON.

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

Przebieg full, który dociera do warstwy semantycznej, może zwrócić wyniki z severity: "warning". Ostrzeżenia mają charakter informacyjny i nie unieważniają dokumentu: sygnalizują wątpliwe wzorce, które nie naruszają schematu, na przykład odsyłacz wewnętrzny bez celu, a pole valid pozostaje ustawione na true. Logika klienta powinna nadal opierać się na valid; pole severity pozwala następnie odróżnić błędy od ostrzeżeń.

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

Reguły dotyczące domyślnego wyłączenia wyrażają zgodę indywidualnie za pośrednictwem rules= – rozdzielona przecinkami lista identyfikatorów reguł, obowiązująca tylko obok level=full. Zwraca nieznany identyfikator 400 ERR_UNSUPPORTED_PARAMETER nazewnictwo naruszającego identyfikatora, bez zrzucania katalogu reguł:

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

Każdy full run, który dociera do raportów warstwy semantycznej meta.semanticRules: liczba aktywnych reguł semantycznych (count) i stabilny SHA-256 na posortowanym zestawie ich identyfikatorów (sha256). A full run odrzucony w warstwie schematu nigdy nie osiąga semantyki, więc nie przenosi meta.semanticRules. Hash dokładnie identyfikuje, który zestaw reguł został zastosowany, więc włączenie reguły jest kontynuowane rules= zmienia to. Przechowywana odpowiedź staje się zatem powtarzalnym zapisem tego, co faktycznie zostało sprawdzone, nawet w miarę powiększania się katalogu reguł w przyszłych wersjach.

Granice

• Treść żądania: 4 MB nieprzetworzonego, 24 MB zdekompresowanego (Content-Encoding: gzip jest obsługiwany i zalecany w przypadku dużych dokumentów).
• Jeden dokument na żądanie.
• Pojawiły się anonimowe limity szybkości: 10 żądań na minutę i 300 dziennie na klienta RateLimit-Limit, RateLimit-Remaining, I RateLimit-Reset nagłówki odpowiedzi, z Retry-After na 429 odpowiedzi. Potrzebujesz więcej? Utwórz klucz API (patrz poniżej) lub skontaktuj się hello@secani.com.

Klucze API

Wyższe, trwałe limity są dostarczane z kluczem API. Klucze tworzysz w ustawieniach organizacji; każdy klawisz jest pokazany dokładnie raz – podczas tworzenia. Wyślij jako 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

W przypadku klucza limity wzrastają do 120 żądań na minutę i 10 000 dziennie na klucz – egzekwowane centralnie i niezależnie od jakiejkolwiek instancji pojedynczego serwera, natomiast limity anonimowe są ustalane w trybie best-efut na instancję. Poziom anonimowy pozostaje: żądania bez Authorization nagłówek zachowuje się bez zmian. Zwraca nieznany lub unieważniony klucz 401 ERR_INVALID_API_KEY i nigdy nie wraca do poziomu anonimowego.

Zarezerwowane parametry

level I rules nie są już zarezerwowane – są żywe; zobacz Poziomy walidacji powyżej. Jeden parametr zachowuje zarezerwowany zakres wartości:

• oscal-version – przypina wersję specyfikacji i akceptuje tylko 1.2.2 Dzisiaj. Każda inna wartość jest zarezerwowana dla przyszłych wydań i zwrotów OSCAL ERR_UNSUPPORTED_PARAMETER z wyjaśnieniem.

OpenAPI

Umowa kanoniczna do odczytu maszynowego doręczana jest pod adresem /openapi.json. Wersjonowany /api/oscal/v1/openapi.json Adres URL pozostaje dostępny w celu zapewnienia zgodności. CORS jest otwarty (*), dzięki czemu interfejs API można wywołać bezpośrednio z narzędzi opartych na przeglądarce.

Zobacz także: Walidator przeglądarki do użytku interaktywnego i Zestaw narzędzi TypeScript za obydwoma.