Befunde und Abdeckung

GET/v1/products/{productId}/findings

Befunde eines Produkts auflisten

Gibt die Befunde der überwachten Uploads des Produkts zurück (jede Produktversion auf dem Markt und der neueste Upload), jeweils mit ihrem Upload und ihrer Produktversion: Eine Schwachstelle, die in zwei überwachten Produktversionen steckt, ergibt zwei Befunde. Befunde zu Schwachstellen, die als ausgenutzt bekannt sind, kommen zuerst, dann nach Schweregrad, dann die neuesten. In dieser Reihenfolge ist zu arbeiten: Eine aktiv ausgenutzte Schwachstelle löst die 24-Stunden-Meldung der Cyberresilienz-Verordnung aus.

Ob eine Schwachstelle ausgenutzt wird, wird bei der Beantwortung der Anfrage ermittelt und nicht am Befund gespeichert, denn eine Schwachstelle wird erst später ausgenutzt, und genau dieser Zeitpunkt zählt.

Erfordert die Berechtigung findings:read.

Scope: findings:read

Parameter

Antworten

{
  "findings": [
    {
      "id": "a1c3e5f7-0b2d-4e6f-8a91-b2c3d4e5f607",
      "component": {
        "name": "golang.org/x/net",
        "version": "0.38.0",
        "purl": "pkg:golang/golang.org/x/net@0.38.0"
      },
      "vulnerability": {
        "id": "GHSA-qppj-fm5r-hxr3",
        "summary": "HTTP/2 rapid reset can cause excessive work in net/http",
        "severity": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:N/I:N/A:H",
        "severity_type": "CVSS_V3",
        "url": "https://osv.dev/vulnerability/GHSA-qppj-fm5r-hxr3"
      },
      "evidence": "range",
      "matched_range": ">=0, <0.38.1",
      "state": "open",
      "exploited": true,
      "exploited_cve": "CVE-2023-44487",
      "exploited_since": "2023-10-10",
      "ransomware": false,
      "first_seen_at": "2026-09-19T05:02:18Z",
      "last_seen_at": "2026-09-21T05:01:47Z",
      "sbom_id": "5d7e9f10-2b4c-4d6e-8f90-a1b2c3d4e5f6",
      "release": "2.4.1"
    }
  ],
  "total": 7,
  "exploited": 1
}

Beispiel

curl --fail-with-body -sS \
  -H "Authorization: Bearer $BITHIVE_TOKEN" \
  "https://app.bithive-it.com/v1/products/$PRODUCTID/findings"

POST/v1/products/{productId}/decisions

Eine VEX-Aussage zu den Befunden eines Produkts festhalten

Hält die eigene Aussage des Kontos zu einer oder mehreren benannten Produktversionen und einer Schwachstelle fest: ob die Produktversion betroffen ist und warum. Je Produktversion wird eine Aussage geschrieben, sodass eine Aussage auf einmal für jede überwachte Produktversion mit derselben Komponentenversion gegeben werden kann. Jede Produktversion muss eine sein, in der ein Befund des Produkts zu der Schwachstelle entstanden ist.

Eine Aussage wird nie geändert. Eine Änderung ist eine neue Aussage, die die ersetzte nennt, und die neueste ist die geltende Entscheidung. Das Token handelt als der Benutzer, der es erstellt hat: Inhaber, Administratoren und Mitglieder halten eine Aussage fest, wo keine gilt; nur Inhaber oder Administratoren ersetzen eine geltende.

Für jeden Status gelten eigene Regeln, angelehnt an das VEX-Profil von CSAF 2.0: not_affected erfordert eine justification oder ein impact_statement oder beides und lässt keine Maßnahme zu; affected erfordert eine action_category und ein action_statement und lässt keine Begründung zu; fixed und under_investigation lassen keins von beidem zu. Ein Feld, das der Status nicht zulässt, wird abgelehnt, nicht verworfen.

Eine Aussage ändert nie einen Fall oder dessen Fristen.

Nimmt einen Idempotency-Key an. Erfordert die Berechtigung findings:decide.

Scope: findings:decide

Parameter

Anfragekörper

• application/json

{
  "releases": [
    "2.4.1",
    "2.5.0"
  ],
  "vulnerability": "GHSA-qppj-fm5r-hxr3",
  "status": "not_affected",
  "justification": "vulnerable_code_not_in_execute_path"
}

Antworten

{
  "decisions": [
    {
      "id": "0d1e2f30-4a5b-4c6d-8e7f-90a1b2c3d4e5",
      "release": "2.4.1",
      "vulnerability": "GHSA-qppj-fm5r-hxr3",
      "status": "not_affected",
      "justification": "vulnerable_code_not_in_execute_path",
      "decided_at": "2026-10-30T09:15:00Z",
      "stale": false
    }
  ]
}

{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "Send the decision as a JSON object with the members the contract names."
}

{
  "type": "about:blank",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "not_affected needs a justification or an impact_statement."
}

Beispiel

curl --fail-with-body -sS -X POST \
  -H "Authorization: Bearer $BITHIVE_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @new-decision.json \
  "https://app.bithive-it.com/v1/products/$PRODUCTID/decisions"

GET/v1/products/{productId}/decisions/history

Die Aussagen zu einer Produktversion und einer Schwachstelle lesen

Gibt jede Aussage zurück, die zu einer Produktversion des Produkts und einer Schwachstelle festgehalten wurde, die neueste zuerst. Die erste ist die geltende Entscheidung.

Erfordert die Berechtigung findings:read.

Scope: findings:read

Parameter

Antworten

Beispiel

curl --fail-with-body -sS \
  -H "Authorization: Bearer $BITHIVE_TOKEN" \
  "https://app.bithive-it.com/v1/products/$PRODUCTID/decisions/history"

GET/v1/products/{productId}/vex

Das VEX-Dokument eines Produkts herunterladen

Gibt die geltenden Aussagen des Produkts als OpenVEX-Dokument (v0.2.0) oder als CycloneDX-VEX (Spezifikation 1.6) zurück. Jede Produktversion wird mit der Paket-URL benannt, die ihre eigene SBOM für ihren Gegenstand angibt, sonst mit urn:bithive:product:<product id>:<release>. Ein Befund ohne Aussage steht nicht im Dokument, und das Dokument nennt keine Person, nur wann jede Aussage getroffen wurde.

Das Token handelt als der Benutzer, der es erstellt hat; er muss Inhaber oder Administrator sein. Ein Konto kann höchstens drei VEX-Dokumente je Stunde exportieren.

Erfordert die Berechtigung findings:read.

Scope: findings:read

Parameter

Antworten

{
  "@context": "https://openvex.dev/ns/v0.2.0",
  "@id": "urn:uuid:11111111-2222-4333-8444-555555555555",
  "author": "ACME GmbH",
  "timestamp": "2026-10-31T12:00:00Z",
  "version": 1,
  "tooling": "BitHive Reporting Desk",
  "statements": [
    {
      "vulnerability": {
        "name": "GHSA-qppj-fm5r-hxr3"
      },
      "timestamp": "2026-10-30T09:15:00Z",
      "products": [
        {
          "@id": "urn:bithive:product:6f1c2a3b-4d5e-4f60-8a71-9b0c1d2e3f40:2.4.1",
          "subcomponents": [
            {
              "@id": "pkg:golang/golang.org/x/net@0.38.0"
            }
          ]
        }
      ],
      "status": "not_affected",
      "justification": "vulnerable_code_not_in_execute_path"
    }
  ]
}

Beispiel

curl --fail-with-body -sS \
  -H "Authorization: Bearer $BITHIVE_TOKEN" \
  "https://app.bithive-it.com/v1/products/$PRODUCTID/vex"

GET/v1/products/{productId}/coverage

Lesen, wie viel von einem Produkt geprüft werden kann

Gibt zurück, wie viele Komponenten des neuesten Uploads des Produkts wir prüfen können, und nennt, was sich nicht prüfen lässt. Die Ergebnisse hängen von der Vollständigkeit der Stückliste ab, deshalb wird der nicht abgedeckte Teil benannt und nicht bloß abgezogen: Ein Client sieht, welche Ökosysteme nicht abgedeckt sind und warum.

Eine Komponente wird nicht überwacht, wenn sie keine Paketkennung trägt (häufig bei Firmware, die mit Yocto oder Buildroot gebaut ist), wenn sie keine Version nennt oder wenn sie zu einem Ökosystem gehört, dessen Abgleich noch nicht nachgewiesen ist.

Erfordert die Berechtigung findings:read.

Scope: findings:read

Parameter

Antworten

{
  "sbom_id": "5d7e9f10-2b4c-4d6e-8f90-a1b2c3d4e5f6",
  "components": 412,
  "monitored": 389,
  "monitored_percent": 94.4,
  "not_monitored": [
    {
      "reason": "no package identifier",
      "components": 14
    },
    {
      "reason": "ecosystem not supported yet",
      "ecosystem": "alpine",
      "components": 9
    }
  ]
}

Beispiel

curl --fail-with-body -sS \
  -H "Authorization: Bearer $BITHIVE_TOKEN" \
  "https://app.bithive-it.com/v1/products/$PRODUCTID/coverage"