Zum Inhalt springen
RedcheckStartseite
REST-API / Befunde

Befunde

Die Befunde eines fertigen Laufs kommen als JSON über die API, in derselben Form wie in findings.json. Den Status eines Befunds setzen Sie an zwei Stellen: fixed am Lauf, angenommene oder nicht zutreffende Befunde über eine Quittierung an der Domain.

Befunde lesen

GEThttps://api.red-check.de/v1/scans/{id}/findings

severity
enum[]
–critical · high · medium · low · info
category
string
–
status
enum
–open · fixed · accepted · not_applicable
confirmed_cve_only
boolean
Entspricht dem Schalter „Nur bestätigte CVEs“.
confidence
enum[]
Kommaliste; gefiltert wird auf dem Server. Drei Codes, zwei Wörter: Die Oberfläche nennt `likely` und `candidate` beide „möglich“ und sendet für diese Schaltfläche deshalb beide Werte. Wer hier nur einen der beiden schickt, blendet Befunde aus, die das Etikett „möglich“ scheinbar einschließt.confirmed · likely · candidate
effort_level
string[]
Kommaliste von Aufwandsstufen, z. B. `gering,mittel`. Die Stufen sind absichtlich keine Aufzählung: Sie stammen aus dem Befundkatalog und sollen sich ohne Migration erweitern lassen. Welche Stufen in diesem Lauf vorkommen, steht in `effort_levels` der Antwort; daraus baut sich die Filterleiste, statt aus einer zweiten, fest verdrahteten Liste.

Listenfilter wie severity und confidence nehmen mehrere Werte als Kommaliste ohne Leerzeichen:

Nur kritische und hohe, bestätigt
GET /v1/scans/{id}/findings?severity=critical,high&confidence=confirmed

Die Antwort ist ein Objekt ohne Seiten. Neben items trägt sie die Zähler und die Werte für Filter:

items
object[]Pflicht
–
counts
objectPflicht
–
positives_count
integerPflicht
–
categories
object[]Pflicht
Kategorien mit Anzahl, für die Filter-Pillen in A06.
effort_levels
object[]Pflicht
Aufwandsstufen mit Anzahl, gebaut wie `categories` und aus demselben Grund: `effort_level` ist keine Aufzählung und kommt aus dem Befundkatalog. Eine feste Liste in der Oberfläche zeigte mit der Zeit Stufen, die es nicht mehr gibt, und ließe neue weg.
positives
object[]
–

Die Felder eines einzelnen Befunds stehen unter findings.json-Schema.

200
Befunde samt Zählern und Positives.
400
Eingabe ungültig (`validation_failed`).
404
Nicht gefunden (`not_found`).

Als behoben markieren

PATCHhttps://api.red-check.de/v1/scans/{id}/findings/{finding_id}

status
enumPflicht
Absichtlich enger als `FindingStatus`. Die beiden anderen Werte des Enums stehen weiterhin an `Finding.status`, aber gesetzt werden sie über die Quittierung.open · fixed
note
string
–

Erlaubt sind open und fixed. Der Status gilt für diesen Lauf und wirkt auf die Zähler offener kritischer und hoher Befunde. Der Bericht bleibt unverändert. accepted und not_applicable weist die API mit 400 use_acknowledgment ab. Dafür gibt es die Quittierung.

200
Geändert.
400
Eingabe ungültig (`validation_failed`).
403
In der Kundensicht deaktiviert (`read_only_session`).

Quittierungen

Eine Quittierung hängt am Sachverhalt und an der Domain. Deshalb gilt sie auch für künftige Läufe derselben Domain.

kindBedeutung
acceptedDas Risiko ist bekannt und bewusst angenommen.
not_applicableDer Befund trifft auf diese Anlage nicht zu.

Beide nehmen die Risikopunkte des Befunds aus dem Score. Das wirkt sofort auf den jüngsten abgeschlossenen Lauf der Domain und auf alle späteren. Ältere Läufe behalten ihren Score.

Quittieren

POSThttps://api.red-check.de/v1/domains/{id}/acknowledgments

scan_id
uuidPflicht
–
finding_id
uuidPflicht
–
kind
enumPflicht
Warum ein Befund quittiert ist. * `accepted`: Das Risiko ist bekannt und bewusst angenommen. * `not_applicable`: Der Befund trifft auf diese Anlage nicht zu. Beide nehmen die Risikopunkte des Befunds aus dem Score. Sie bleiben getrennt, weil sie für den Kunden zwei verschiedene Aussagen sind und in einer Prüfung verschieden wiegen. Eine dritte Art „nur zur Kenntnis genommen“ gibt es bewusst nicht. Sie wirkte nicht auf den Score, und drei Arten, von denen zwei etwas tun, sind in der Oberfläche schwerer zu erklären als eine Notiz am Befund, die es ohnehin gibt.accepted · not_applicable
reason
stringPflicht
–
expires_at
string | null
Optional. Ohne Angabe gilt die Quittierung unbefristet.
Anfrage
curl -X POST https://api.red-check.de/v1/domains/{id}/acknowledgments \
  -H "Authorization: Bearer rc_live_••••••••" \
  -H "Content-Type: application/json" \
  -d '{
  "scan_id": "3f9a1c20-5e4b-4d8a-9a11-0c21e7b4c21e",
  "finding_id": "3f9a1c20-5e4b-4d8a-9a11-0c21e7b4c21e",
  "kind": "accepted",
  "reason": "",
  "expires_at": "2026-09-03T09:14:22Z"
}'

Den Sachverhaltsschlüssel bildet der Server aus scan_id und finding_id. reason ist Pflicht, zwischen 10 und 500 Zeichen. Ohne expires_at gilt die Quittierung unbefristet. Gilt für denselben Sachverhalt schon eine, antwortet die API mit 409.

201
Angelegt.
400
Eingabe ungültig (`validation_failed`).
403
Kein Zugriff (`forbidden`, `insufficient_role`).
404
Nicht gefunden (`not_found`).
409
Zustand passt nicht (`conflict`, `already_exists`).

Auflisten

GEThttps://api.red-check.de/v1/domains/{id}/acknowledgments

include_revoked
boolean
Nimmt widerrufene Quittierungen mit auf; ohne den Schalter kommen nur die geltenden. Widerrufene werden nicht gelöscht, weil auch das Aufheben einer Entscheidung eine Entscheidung ist.

Die Antwort ist ein Array, jüngste zuerst. active sagt, ob eine Quittierung jetzt gilt, effective_in_last_scan, ob sie im jüngsten Lauf einen Befund getroffen hat.

id
uuidPflicht
–
domain_id
uuidPflicht
–
catalog_id
stringPflicht
Die Katalogkennung des quittierten Sachverhalts.
title
string
Der Titel, wie er beim Quittieren im Lauf stand. Zur Anzeige.
location
string
Der Fundort im Klartext, leer bei ortlosen Befunden. Er steht zusätzlich zum Schlüssel und nicht nur in ihm. Ändert der Scanner eine Normalisierung, treffen die Schlüssel ins Leere, und dann zeigt nur noch dieses Feld, was der Kunde gemeint hat.
kind
enumPflicht
Warum ein Befund quittiert ist. * `accepted`: Das Risiko ist bekannt und bewusst angenommen. * `not_applicable`: Der Befund trifft auf diese Anlage nicht zu. Beide nehmen die Risikopunkte des Befunds aus dem Score. Sie bleiben getrennt, weil sie für den Kunden zwei verschiedene Aussagen sind und in einer Prüfung verschieden wiegen. Eine dritte Art „nur zur Kenntnis genommen“ gibt es bewusst nicht. Sie wirkte nicht auf den Score, und drei Arten, von denen zwei etwas tun, sind in der Oberfläche schwerer zu erklären als eine Notiz am Befund, die es ohnehin gibt.accepted · not_applicable
reason
stringPflicht
Pflicht. Eine Quittierung nimmt Punkte aus dem Score. Wer das tut, nennt den Grund, sonst steht in einem halben Jahr eine Zahl da, die niemand mehr erklären kann.
expires_at
string | null
Optionales Ende. `null` heißt unbefristet.
active
booleanPflicht
Ob sie jetzt gilt, also weder widerrufen noch abgelaufen ist. Der Wert wird abgeleitet und nicht gespeichert, weil ein gespeicherter Wahrheitswert ohne Schreibvorgang falsch würde.
effective_in_last_scan
boolean
Ob sie im jüngsten abgeschlossenen Lauf tatsächlich einen Befund getroffen hat. Daran lässt sich ablesen, ob eine Quittierung nach einer Schlüsseldrift noch wirkt.
created_at
string (date-time)Pflicht
–
created_by_name
string
Wer quittiert hat. Leer, wenn das Konto entfernt wurde.
revoked_at
string | null
–
revoked_by_name
string
–
revoke_reason
string
–

Aufheben

POSThttps://api.red-check.de/v1/domains/{id}/acknowledgments/{ack_id}/revoke

reason
stringPflicht
Pflicht, aus demselben Grund wie beim Anlegen: Der Score ändert sich.

Auch das Aufheben braucht einen Grund. Die Quittierung bleibt als widerrufen stehen und erscheint mit include_revoked=true.

200
Aufgehoben.
400
Eingabe ungültig (`validation_failed`).
403
Kein Zugriff (`forbidden`, `insufficient_role`).
404
Nicht gefunden (`not_found`).

Rechte

Aufrufread_onlystart_scansfull
Befunde und Quittierungen lesenjajaja
PATCH am Befundneinneinja
quittieren, Quittierung aufhebenneinneinja