Findings und Detections

Die API beschreibt Schwachstellen auf zwei Ebenen.

• Eine Detection ist ein einzelnes Vorkommen einer Schwachstelle in einem Scan, so wie dieser Scan es gemeldet hat: Datei und Zeile, Paket und CVE oder die IaC-Regel. Jeder Scan erzeugt neue Detections mit neuen IDs. Die unter Issues aufgeführten Endpunkte liefern Detections; ein Issue und eine Detection sind dasselbe.
• Ein Finding ist die Schwachstelle selbst, in einem Projekt und über alle Scans hinweg, die sie erkannt haben. Es hat eine ID, die sich von Scan zu Scan nicht ändert, und hier findet die Triage statt: Status, Kommentar, zugewiesene Person, Ablaufdatum der Risikoakzeptanz, Fälligkeitsdatum und SLA.

​

Von einer Ebene zur anderen

Jedes Detection-Element enthält die finding_id seines Findings. Gruppieren Sie Detections danach und nie nach first_detection_date: Das ist eine Eigenschaft des Findings, kein Schlüssel. Das Feld ist nur bei Detections null, die erfasst wurden, bevor es Findings gab. Jedes Finding enthält latest_detection: seine neueste Detection, mit der ID, die die Detection-Endpunkte erwarten, und dem Locator der jeweiligen Familie (file_path und line_number, path, package, version und cve, oder path, rule_id, start_line und end_line). Eine Triage-Änderung auf einer der beiden Ebenen landet beim Finding und damit bei jeder seiner Detections.

​

Welcher Endpunkt ist der richtige?

​

Die Detection-Endpunkte

/detections ist der neue Name der Endpunkte unter Issues, keine separate API. Jeder davon ist unter beiden Pfaden erreichbar: Beide Pfade führen denselben Code aus und liefern dieselbe Response, einschließlich der Schlüssel issues und total_issues. Verwenden Sie in neuen Integrationen /detections; /issues wird weiterhin unterstützt.

​

Die Finding-Endpunkte

GET /api/v1/findings liefert eine Zeile pro Finding, neueste zuerst nach dem Zeitpunkt der ersten Erkennung, paginiert über page und page_size (bis zu 100) und mit der Gesamtzahl total_findings. Filter akzeptieren kommagetrennte Listen, sofern nicht anders angegeben: Einen branch-Filter gibt es nicht: Ein Finding gehört zu einem Projekt, und der Branch ist eine Eigenschaft seiner Detections. Das Token benötigt dieselbe Leseberechtigung wie für die Detection-Liste der jeweiligen Familie; eine Familie anzugeben, die das Token nicht sehen darf, führt zu 403. GET /api/v1/findings/{finding_id} liefert ein einzelnes Finding in derselben Form: seine Triage-Felder, urgency, classification, project, detection_state, first_detection_date, last_detection_date, detections_count und latest_detection.

​

detection_state

Ein Finding ist active, solange es in seinem Projekt eine Detection hat, und retired, sobald seine letzte Detection zusammen mit ihrem Scan oder Projekt gelöscht wurde. Ein Finding, das ein Rescan nicht mehr meldet, wird nicht retired: Es bleibt active, und sein status wechselt zu fixed. Ein retired Finding behält seine Triage, sodass eine Detection, die wieder auftaucht, derselben Finding-ID zugeordnet wird und dieselbe Entscheidung übernimmt.

​

Triage nach Finding

PATCH /api/v1/triage/findings akzeptiert finding_ids: eine Liste von Finding-IDs (aus GET /api/v1/findings oder aus der finding_id der Detection-Elemente) oder von Detection-IDs. Eine Finding-ID steht für die neueste Detection des Findings, und die Entscheidung gilt für jede seiner Detections. IDs, die sich nichts zuordnen lassen, kommen in unresolved_ids zurück und zählen als nicht gefunden; ein Batch mit einer veralteten ID wendet die übrigen also trotzdem an. Die Massen-Triage deckt die Familien SAST, Secret, Logic, Code-Qualität und Dependency ab; eine Container- oder IaC-ID kommt in unresolved_ids zurück, und die Audit-Zeilen geben finding_type als sast oder sca an. Eine rule kann einen statuses-Bereich enthalten. So kann ein einziger Aufruf zum Beispiel jedes Finding, das heute als akzeptiertes Risiko gilt, auf False Positive setzen.

​

Ein Sync-Loop

Verwenden Sie die Finding-ID als Schlüssel des Tickets. Eine Detection-ID ändert sich mit jedem Scan, eine Finding-ID nicht. Jeder Durchlauf liest drei Listen und schreibt einen Batch. Jede Liste ist paginiert: Fragen Sie page=1, 2, … mit page_size=100 ab, bis page den Wert total_pages erreicht. Speichern Sie den Startzeitpunkt des Durchlaufs als vollständigen ISO-8601-Zeitstempel in UTC und übergeben Sie ihn beim nächsten Mal als <last run>.

1. GET /api/v1/findings?created_since=<last run>: Legen Sie für jedes neue Finding ein Ticket an. Ein neues Finding hat noch keine Triage-Änderung, daher liefert Schritt 2 es nicht.
2. GET /api/v1/findings?status_changed_since=<last run>&detection_state=all: Übernehmen Sie Triage-Änderungen, auch die an retired Findings. Ein Finding, dessen status zu fixed wechselte, schließt sein Ticket.
3. GET /api/v1/findings?detection_state=retired: Gleichen Sie retired Findings ab. Beim Retirement wird weder ein Zeitpunkt erfasst noch der Status geändert, daher liefert keiner der beiden Cursor diese Findings. Vergleichen Sie diese vollständige Liste mit Ihren offenen Tickets und schließen oder markieren Sie die enthaltenen. Taucht eine Detection wieder auf, wird das Finding mit derselben ID wieder active.
4. PATCH /api/v1/triage/findings mit finding_ids: Übertragen Sie im Ticketsystem getroffene Entscheidungen zurück an Corgea. Lesen Sie unresolved_ids auch bei einem 200. Diese IDs, darunter jedes Container- und IaC-Finding, wurden nicht aktualisiert, der Rest des Batches dagegen schon.

Ergänzen Sie jeden Listenaufruf um issue_type, wenn Sie Code-Quality-Findings synchronisieren, die der Standard auslässt. Ein 404 von GET /api/v1/findings bedeutet, dass der Finding-Index des Kontos noch nicht vollständig ist, nicht, dass es nichts zu synchronisieren gibt. Versuchen Sie es später erneut und behalten Sie den alten Cursor.