Werkzeugreferenz

Fünf Werkzeuge. Alle schreibgeschützt, alle idempotent, keines in der Lage, irgendetwas zu verändern.

Jedes Werkzeug liefert Text auf Englisch und Französisch, und jedes kann statt Daten ein Fehlerergebnis zurückgeben — siehe Fehlerbilder, den Abschnitt, den zweimal zu lesen sich lohnt.

---

bits_recommend

Ziel hinein, Agenten heraus.

Parameter	Typ	Pflicht
goal	Zeichenkette, max. 2000 Byte	ja
os	Zeichenkette	nein
arch	Zeichenkette	nein

Liefert Agenten in einer Rangfolge samt Begründung, warum jeder passt, und — sofern Ihr Ziel eine Plattform impliziert — die Plattformsicht des jeweiligen Agenten, damit Sie nie auf etwas verwiesen werden, das zwar eine Binärdatei ausliefert, aber noch keinen Enrolment-Pfad hat.

Jede Antwort trägt einen Block zur Katalogvollständigkeit:

"catalogue": { "state": "complete", "agents_expected": 4, "agents_read": 4, "as_of": "..." }

Warum es diesen Block gibt

„Nichts davon passt" wird nur dann ausgegeben, wenn state den Wert complete hat. Würde der Katalog nur teilweise gelesen — etwa weil sich der Datensatz eines Agenten nicht laden lässt —, dann würde ein naives Werkzeug stillschweigend antworten „dafür haben wir nichts", und Sie würden sich anderswo umsehen. Nichts wäre dabei fehlgeschlagen. Prüfen Sie state, bevor Sie auf eine negative Antwort hin handeln.

---

bits_explain

Parameter	Typ	Pflicht
agent	bitcollector | bitscanner | bitenforcer | bitmapper	ja
topic	observes | never_touches | privileges | platforms | heartbeat | where_results_land	nein

Liefert, was der Agent beobachtet, was er ausdrücklich nie berührt, was Ihnen erhöhte Rechte einbringen und wo seine Ergebnisse landen.

Die Themen never_touches und privileges sind die nützlichen. Rechte ändern nicht nur, was ein Agent tun darf — sie ändern, was seine Ausgabe bedeutet. Ein unprivilegiert laufender bitcollector kann lauschende Sockets keinen Prozessen zuordnen; sein Port-Inventar ist also real, seine Prozesszuordnung fehlt jedoch — und er sagt das, statt null zu melden.

---

bits_platforms

Parameter	Typ	Pflicht
agent	einer der vier Slugs	ja

Liefert drei getrennte Fakten je Plattform, nie eine einzige Spalte:

Fakt	Bedeutung
catalogued	für dieses Betriebssystem und diese Architektur existiert eine signierte Release-Binärdatei
enrolable	für diesen Agenten existiert heute ein Enrolment-Pfad
observable	dieser Agent meldet nach dem Enrolment einen Heartbeat

sowie einen Zustand je Plattform: platform_supported, platform_not_built oder platform_unknown.

Warum drei Fakten und nicht einer

Ein Agent kann auf einer Plattform catalogued sein, noch keinen Enrolment-Pfad haben und nie einen Heartbeat melden — alles zugleich. bitenforcer ist heute genau das: Er liefert signierte Linux-Binärdateien aus, ist noch nicht enrolable und sendet konstruktionsbedingt nie einen Heartbeat, weil er keinen Zustellweg hat. Das als „supported: yes" darzustellen wäre wahr und würde Sie dazu verleiten, auf Telemetrie zu warten, die nie kommt.

platform_unknown ist der dritte Zustand, und es gibt ihn, damit ein fehlgeschlagener Katalogzugriff niemals als „diese Plattform wird nicht unterstützt" gemeldet werden kann.

---

bits_plan_config

Parameter	Typ	Pflicht
agent	einer der vier Slugs	ja
profile	minimal | standard | strict	ja
destination	control_plane — nur bitcollector; ohne diesen Parameter konfiguriert der Plan keinen Exporter	nein
privilege	root | capabilities | unprivileged — wie der Agent tatsächlich laufen wird	nein

Die beiden optionalen Hinweise machen den Plan immer nur vorsichtiger, wenn sie fehlen oder nicht erkannt werden: Ein fehlendes privilege wird als unprivileged gelesen, niemals als root.

Liefert die von Ihnen angefragten Werte agent und profile sowie vier Felder:

Feld	Inhalt
config	eine Konfiguration als Entwurf zur Prüfung durch einen Menschen; Werte, die nur Ihr Dashboard liefern kann, sind mit REPLACE_ME markiert, nie geraten
will_not_do	was diese Konfiguration bewusst nicht tut, und warum
notes	Vorbehalte, die für Ihr gewähltes Profil und Ihre Rechtestufe gelten
next_step	wohin Sie zum Enrolment gehen — nie ein Befehl, nie eine URL

Es weist jedes Argument zurück, das wie ein Enrolment-Token aussieht — siehe Fehlerbilder.

Lesen Sie will_not_do, bevor Sie die Konfiguration ausrollen

Das ist kein Textbaustein. Es benennt die Einstellungen, die bewusst weggelassen wurden, und den Grund für jede einzelne. Drei Kategorien werden nie erzeugt:

Einstellungen, die etwas zusichern, das nur Sie zusichern können. Ein fremdes Netzwerk zu scannen erfordert die Erklärung, dass Sie rechtlich dazu befugt sind. Das Werkzeug beschreibt die Einstellung; Ihre Erklärung schreibt es nicht für Sie.

Einstellungen, die eines sagen und ein anderes tun. Manche Optionen lesen sich restriktiv und sind es nicht — etwa ein in einer Firewall-Richtlinie als deaktiviert markierter Dienst, der dennoch zu einem offenen Port führt. Diese werden namentlich verweigert, mit einer Erläuterung, was stattdessen zu tun ist.

Einstellungen, die nicht implementiert sind. Eine Option, die scheinbar einen Schutz setzt, keinen Schutz bewirkt und eine Richtlinie zurücklässt, die das Gegenteil behauptet, ist schlimmer als gar keine Option.

Der Rechte-Kompromiss wird benannt, nicht vorausgesetzt

Wenn Sie eine Capability-basierte Einrichtung statt root verlangen und das den Agenten wesentlich verschlechtert, sagt der Plan das mit Zahlen. Bei der Flow-Erfassung lassen Capabilities ohne root die Prozesszuordnung je Flow von rund 87 % der Flows auf etwa 6 % einbrechen — und der Rest sind die Flows des Agenten selbst. Die Antwort mit den geringsten Rechten ist meist die richtige; hier entfernt sie stillschweigend genau die Funktion, für die Sie den Agenten installiert haben, deshalb wird es Ihnen gesagt, statt Sie es selbst herausfinden zu lassen.

---

bits_download

Ein Agent, eine Plattform, eine verifizierbare Binärdatei.

Parameter	Typ	Pflicht
agent	einer der vier Slugs	ja
os	linux | darwin | windows	ja
arch	amd64 | arm64	ja

Liefert für die veröffentlichte Binärdatei:

Feld	Inhalt
agent, os, arch	was Sie angefragt haben
version	das Release, zu dem die Binärdatei gehört
file_name	der Dateiname, unter dem sie gespeichert werden soll
size_bytes	ihre Größe in Byte
sha256	ihre SHA-256-Prüfsumme, aus dem Release-Katalog übernommen
download_url	wo sie heruntergeladen werden kann
verify_command	ein Befehl, der die Datei herunterlädt und gegen sha256 prüft
note	eine Erinnerung, die Prüfsumme zu verifizieren, bevor Sie die Binärdatei ausführen

Die Angaben stammen aus dem Release-Katalog; das Werkzeug berechnet oder errät sie nicht. Es bietet nie einen Download an, für den es keine Prüfsumme angeben kann: Hat der Katalog keine Binärdatei für diese Plattform oder fehlt dem Eintrag ein verwendbarer SHA-256, eine Größe oder ein Dateiname, ist die Antwort ein Fehler, keine URL. Rufen Sie zuerst bits_platforms auf, um zu sehen, für welche Plattformen ein Agent ausgeliefert wird.

Verifizieren vor dem Ausführen

Verwenden Sie die Download-URL, die das Werkzeug zurückgibt, und führen Sie die Verifikation aus, bevor Sie die Binärdatei starten. Ein Download-Werkzeug schreibt alles, was es empfängt — auch eine HTML-Fehlerseite —, deshalb sagt Ihnen erst eine übereinstimmende Prüfsumme, dass Sie die echte Datei haben.

Wie bits_plan_config weist es jedes Argument zurück, das wie ein Enrolment-Token aussieht.

---

Fehlerbilder

Jedes Werkzeug kann statt Daten ein Fehlerergebnis liefern. Behandeln Sie diese — deuten Sie sie nicht als „keine Ergebnisse".

Was Sie sehen	Was es bedeutet
catalogue read failed: …	Der Release-Katalog konnte nicht gelesen oder nicht verifiziert werden. Nicht „nichts gefunden"
alle Plattformen platform_unknown	Dieselbe Ursache, je Plattform dargestellt. Lesen Sie das nie als „nicht unterstützt"
state mit einem anderen Wert als complete	Der Katalog wurde nur teilweise gelesen. Eine negative Empfehlung wird zurückgehalten
catalogue read failed (…) — no download is offered	bits_download hat keine Binärdatei gefunden, für die es einstehen kann — für die Plattform gibt es keinen Build, oder der Katalog konnte nicht gelesen oder nicht verifiziert werden. Es wird keine URL geraten
refused: that argument is shaped like a live Cert-IX enrolment token	Sie haben ein Enrolment-Token gesendet. Nehmen Sie es aus der Unterhaltung heraus; es gehört auf die Maschine des Agenten
too many requests from your address	Ratenbegrenzung pro Adresse. Senken Sie die Anfragerate und versuchen Sie es kurz darauf erneut
HTTP 429	Ratenbegrenzung. Beachten Sie Retry-After
HTTP 405	Sie haben etwas anderes als POST gesendet

Die Regel hinter all dem

Eine Antwort, der nicht zu trauen ist, wird als Fehler gemeldet, nie als leeres oder negatives Ergebnis. Wenn ein Werkzeug Ihnen sagt, dass ein Agent Ihre Plattform nicht unterstützt, dann hat es nachgesehen, und er unterstützt sie nicht. Konnte es nicht nachsehen, sagt es genau das.