Dokumentation – BitHive

Diese Anleitung führt Sie von der ersten Anmeldung bis zum überwachten Produkt, mit Alarmen, die die richtigen Personen erreichen, und einer Build-Pipeline, die die Stückliste aktuell hält. Sie dauert etwa eine Stunde, das meiste davon in Ihrer Pipeline.

Was der Reporting Desk tut – und was nicht

Nach Artikel 14 der Cyberresilienz-Verordnung muss ein Hersteller eine aktiv ausgenutzte Schwachstelle in seinem Produkt innerhalb von 24 Stunden melden, nachdem er davon erfahren hat (Frühwarnung), innerhalb von 72 Stunden (Meldung) und 14 Tage nach Verfügbarkeit einer Abhilfe (Abschlussbericht). Ein schwerwiegender Sicherheitsvorfall hat dieselben ersten beiden Stufen; sein Abschlussbericht ist einen Monat nach der Meldung fällig.

Der Reporting Desk:

verwahrt die Software-Stückliste (SBOM) jedes Ihrer Produkte;
prüft jede Komponente gegen öffentliche Schwachstellendaten (OSV) und gegen die beiden öffentlichen Listen aktiv ausgenutzter Schwachstellen: den Katalog der CISA (Known Exploited Vulnerabilities) und die EU-Schwachstellendatenbank der ENISA;
eröffnet einen Fall, sobald eine Komponente eines Ihrer Produkte eine Schwachstelle hat, die eine der beiden Listen als ausgenutzt führt, lässt die drei Fristen laufen und alarmiert Ihre Kontakte – mit Eskalation, wenn niemand reagiert;
entwirft jede Meldung aus dem, was er weiß, als Text zum Einfügen in die Single Reporting Platform der ENISA, und hält fest, wann Sie eingereicht haben.

Er reicht nicht für Sie ein: Die Single Reporting Platform nimmt Meldungen von Hand entgegen, von Ihnen. Er sieht weder Ihren Quellcode noch Ihre Firmware, nur die Komponentenliste, die Sie ihm geben. Und er kann nur überwachen, was er identifizieren kann: Komponenten der Ökosysteme npm, PyPI, Maven, Go und NuGet mit einer Paket-URL. Alles andere gilt als nicht überwacht, nie als sicher; die Abdeckung des Produkts sagt, welche Komponenten das sind.

1. Anmelden und die Dokumente annehmen

Melden Sie sich mit Ihrer geschäftlichen E-Mail-Adresse an. Es gibt kein Passwort: Sie erhalten einen Anmeldelink per E-Mail, der einmal funktioniert, zehn Minuten lang.

Die erste Person Ihres Unternehmens, die sich anmeldet, nimmt die AGB und den Auftragsverarbeitungsvertrag für das Unternehmen an und muss dazu berechtigt sein. Jede Person bestätigt einmalig, die Datenschutzhinweise gelesen zu haben. Die Nachweise nennen Version, Veröffentlichungsadresse, Zeitpunkt und Person und sind unveränderlich. Ändert sich ein Dokument, wird die neue Fassung bei der nächsten Anmeldung gezeigt; Ihre API-Token funktionieren währenddessen weiter.

2. Die Personen benennen, die Alarme erhalten

Öffnen Sie Alarme und Kontakte. Tragen Sie mindestens zwei Personen ein; die Überwachung eines Produkts braucht zwei:

einen Hauptkontakt, der den ersten Alarm erhält, wenn ein Fall eröffnet wird;
eine Vertretung, die hinzugezogen wird, wenn zwei Stunden nach Fristbeginn niemand den Fall bestätigt hat.

Verwenden Sie Adressen, die kurzfristig gelesen werden, kein Sammelpostfach ohne Zuständige. Alarme kommen von alerts@bithive-it.com; nehmen Sie die Adresse in die erlaubten Absender Ihres Mailfilters auf.

Bestätigen sagt dem Reporting Desk, dass sich jemand des Falls annimmt, und stoppt die Eskalation. Öffnen Sie dazu den Fall in der Anwendung oder drücken Sie den Knopf hinter dem Link im Alarm. Der Link funktioniert einmal, sieben Tage lang; das bloße Öffnen ändert nichts, denn Mailfilter öffnen jeden Link zur Prüfung – nur der Knopf bestätigt. Eine Bestätigung stoppt keine Frist.

Webhooks gibt es in jedem Tarif, optional. Auf derselben Seite können Sie einen HTTPS-Webhook hinterlegen, der jeden Alarm als JSON erhält: der Weg zu PagerDuty, Opsgenie oder einem Ticketsystem. Zustellungen sind nach Standard Webhooks signiert; das Secret wird beim Anlegen einmal angezeigt (es beginnt mit whsec_). Prüfen Sie die Signatur, bevor Sie auf eine Zustellung reagieren.

3. Produkte anlegen

Öffnen Sie Produkte und legen Sie jedes Produkt an, das Sie auf dem EU-Markt bereitstellen, unter dem Namen, den Sie in einer Meldung verwenden würden. Ihr Tarif enthält eine Anzahl Produkte (3, 10 oder 25 oder die Zahl aus Ihrem Vertrag); die Seite zeigt, wie viele Sie haben.

Schalten Sie dann für jedes Produkt Alarme ein. Dafür braucht es die beiden Kontakte aus Schritt 2. Solange die Alarme aus sind, erfährt niemand von den Fällen des Produkts.

4. Eine Stückliste hochladen

Eine Stückliste in CycloneDX oder SPDX, als JSON, bis 10 MiB. Erzeugen Sie sie im Build mit einem etablierten Open-Source-Werkzeug, zum Beispiel:

syft dir:. -o cyclonedx-json > sbom.json      # Syft
cdxgen -o sbom.json .                         # cdxgen

Erzeugen Sie sie aus dem, was Sie ausliefern: dem gebauten Artefakt oder seinen Lockfiles, nicht aus dem Arbeitsstand einer Entwicklerin samt Testabhängigkeiten. Je besser das Werkzeug Paket-URLs erkennt, desto mehr des Produkts wird überwacht.

Beim ersten Mal laden Sie sie auf der Seite Stücklisten des Produkts hoch. Die Seite Befunde zeigt innerhalb von Sekunden, welche Komponenten bekannte Schwachstellen haben, welche davon ausgenutzt werden, und die Abdeckung: wie viele Komponenten überwacht werden und welche nicht, und warum.

5. Aus der Pipeline aktuell halten

Jede Auslieferung ändert die Komponentenliste, laden Sie die Stückliste also aus der Pipeline hoch, die die Auslieferung baut. Es ist nichts zu installieren: Die Pipeline ruft die HTTPS-API mit curl auf.

Öffnen Sie API-Token und erstellen Sie ein Token mit dem Scope sboms:write, begrenzt auf das Produkt, für das es hochlädt, mit Ablaufdatum (höchstens ein Jahr). Das Token wird einmal angezeigt; hinterlegen Sie es als Secret in Ihrem CI-System, zum Beispiel als BITHIVE_TOKEN.
Die Kennung des Produkts steht in der Adresse seiner Seiten (/products/KENNUNG/findings). Hinterlegen Sie sie als BITHIVE_PRODUCT.
Erzeugen Sie nach dem Build die Stückliste und laden Sie sie hoch:

curl --fail-with-body -sS -X POST \
  -H "Authorization: Bearer $BITHIVE_TOKEN" \
  -H "Content-Type: application/vnd.cyclonedx+json" \
  --data-binary @sbom.json \
  "https://app.bithive-it.com/v1/products/$BITHIVE_PRODUCT/sboms"

Für ein SPDX-Dokument verwenden Sie Content-Type: application/spdx+json. Die Antwort ist 201 für einen neuen Upload und 200, wenn dasselbe Dokument schon einmal hochgeladen wurde – dann passiert nichts, eine doppelt laufende Pipeline schadet also nicht. Ein Fehler antwortet mit einer Problembeschreibung (RFC 9457), die im CI-Log lesbar sagt, was nicht stimmt.

In einem GitHub-Actions-Workflow als Schritt nach dem Build:

- name: Stückliste hochladen
  env:
    BITHIVE_TOKEN: ${{ secrets.BITHIVE_TOKEN }}
    BITHIVE_PRODUCT: ${{ vars.BITHIVE_PRODUCT }}
  run: |
    curl --fail-with-body -sS -X POST \
      -H "Authorization: Bearer $BITHIVE_TOKEN" \
      -H "Content-Type: application/vnd.cyclonedx+json" \
      --data-binary @sbom.json \
      "https://app.bithive-it.com/v1/products/$BITHIVE_PRODUCT/sboms"

In GitLab CI und Jenkins führen Sie denselben curl-Aufruf als Job-Schritt aus, mit dem Token aus einer maskierten CI-Variablen oder einem Credential.

6. Wenn ein Fall eröffnet wird

Ein Fall wird eröffnet, sobald eine Komponente eines Ihrer Produkte eine Schwachstelle hat, die CISA oder ENISA als aktiv ausgenutzt führt. Das passiert, wenn eine Liste eine Schwachstelle nennt, die Ihre Komponenten bereits haben – innerhalb einer Stunde –, oder wenn Sie eine Komponente hochladen, die eine hat, beim nächsten Lesen der Liste, ebenfalls innerhalb einer Stunde. Ihr Hauptkontakt erhält einen Alarm mit einem Link zum Fall.

Auf der Fallseite:

Die Fristen. Die 24- und 72-Stunden-Fristen laufen ab dem Zeitpunkt, zu dem Sie Kenntnis erlangt haben; dieser beginnt mit dem Moment, in dem der Reporting Desk den Fall erfasst hat. Wussten Sie es früher, setzen Sie ihn früher und sagen Sie warum; später kann er nie gesetzt werden. Die Frist des Abschlussberichts beginnt, wenn Sie eine verfügbare Abhilfe erfassen.
Meldungen. Jede Stufe hat ein Formular mit den Feldern, die Artikel 14 verlangt, vorbereitet aus dem, was der Reporting Desk weiß, und von Ihnen vervollständigt. Es liefert den Text zum Einfügen in die Single Reporting Platform. Nach dem Einreichen dort erfassen Sie hier die Uhrzeit; der Nachweis ist unveränderlich.
Wer informiert wurde. Jeder Alarm, an wen, und ob er zugestellt wurde – damit eine fehlgeschlagene Zustellung sichtbar ist und nicht stillschweigend bleibt.
Verwerfen. Trifft ein Befund nicht zu, etwa weil der verwundbare Code nicht in dem steckt, was Sie ausliefern, verwerfen Sie den Fall mit Begründung. Er bleibt im Nachweis.

Einen schwerwiegenden Sicherheitsvorfall, den keine Technik für Sie erkennen kann, erfassen Sie unter Fälle mit Sicherheitsvorfall erfassen. Es gelten dieselben Fristen und Meldungen.

7. Ihre Daten – und wie Sie sie mitnehmen

Ihre Daten werden in Deutschland gespeichert und verarbeitet. Alarme versendet ein E-Mail-Anbieter in der EU. Der Reporting Desk verwahrt die Stücklisten, die Sie hochladen, die Befunde, Fälle, Meldungen und das Protokoll Ihres Kontos, das jede Änderung mit Person und Zeit festhält.

Sie können alles jederzeit mitnehmen: Einstellungen → Ihre Daten → Alles herunterladen gibt Ihnen ein Archiv mit dem Konto, jedem Dokument so, wie es ankam, den Befunden, den Fällen mit ihren Fristen und Meldungen und dem vollständigen Protokoll. § 6.3 der AGB gibt Ihnen das in jedem Tarif, und der Download ändert nichts im Dienst.

Hilfe

Schreiben Sie an contact@bithive-it.com. Wenn ein Alarm Sie nicht erreicht hat oder ein Fall zu fehlen scheint, sagen Sie es uns sofort: Wir behandeln das als Vorfall.