Référence des outils
Cinq outils. Tous en lecture seule, tous idempotents, aucun capable de modifier quoi que ce soit.
Chaque outil renvoie du texte en anglais et en français, et chacun peut renvoyer un résultat d'erreur plutôt que des données — voir Formes d'échec, la section qui mérite d'être lue deux fois.
bits_recommend
Un objectif en entrée, des agents en sortie.
| Paramètre | Type | Requis |
|---|---|---|
goal | chaîne, 2000 octets maximum | oui |
os | chaîne | non |
arch | chaîne | non |
Renvoie des agents classés avec la raison pour laquelle chacun convient et — lorsque votre objectif implique une plateforme — la vue plateforme de cet agent, de sorte que vous ne soyez jamais orienté vers quelque chose qui livre un binaire mais ne dispose encore d'aucun chemin d'enrôlement.
Chaque réponse porte un bloc de complétude du catalogue :
"catalogue": { "state": "complete", "agents_expected": 4, "agents_read": 4, "as_of": "..." }
« Aucun de ceux-ci ne convient » n'est émis que lorsque state vaut complete.
Si le catalogue n'était lu que partiellement — l'enregistrement d'un agent ne
parvenant pas à se charger — un outil naïf répondrait tranquillement « nous
n'avons rien pour cela » et vous iriez voir ailleurs. Rien n'aurait échoué.
Vérifiez state avant d'agir sur une réponse négative.
bits_explain
| Paramètre | Type | Requis |
|---|---|---|
agent | bitcollector | bitscanner | bitenforcer | bitmapper | oui |
topic | observes | never_touches | privileges | platforms | heartbeat | where_results_land | non |
Renvoie ce que l'agent observe, ce à quoi il ne touche explicitement jamais, ce que le privilège vous apporte, et où atterrissent ses résultats.
Les sujets never_touches et privileges sont les plus utiles. Le privilège ne
change pas seulement ce qu'un agent a le droit de faire — il change ce que sa
sortie signifie. Un bitcollector exécuté sans privilège ne peut pas attribuer
les sockets en écoute à des processus : son inventaire de ports est donc réel,
mais sa correspondance avec les processus est absente, et il le dit plutôt que de
rapporter zéro.
bits_platforms
| Paramètre | Type | Requis |
|---|---|---|
agent | l'un des quatre slugs | oui |
Renvoie trois faits distincts par plateforme, jamais une seule colonne :
| Fait | Signification |
|---|---|
catalogued | un binaire de version signé existe pour cet OS et cette architecture |
enrolable | un chemin d'enrôlement existe aujourd'hui pour cet agent |
observable | cet agent émet un battement de cœur une fois enrôlé |
ainsi qu'un état par plateforme : platform_supported, platform_not_built ou
platform_unknown.
Un agent peut être catalogué sur une plateforme, ne disposer encore d'aucun chemin d'enrôlement, et n'émettre jamais de battement de cœur — le tout en même temps. bitenforcer est exactement dans ce cas aujourd'hui : il livre des binaires Linux signés, n'est pas encore enrôlable, et par conception n'émet jamais de battement de cœur puisqu'il n'a aucun chemin de livraison. Rendre cela par « pris en charge : oui » serait vrai et vous induirait en erreur, à attendre une télémétrie qui ne viendra jamais.
platform_unknown est le troisième état, et il existe pour qu'un échec de
lecture du catalogue ne puisse jamais être rapporté comme « cette plateforme
n'est pas prise en charge ».
bits_plan_config
| Paramètre | Type | Requis |
|---|---|---|
agent | l'un des quatre slugs | oui |
profile | minimal | standard | strict | oui |
destination | control_plane — bitcollector uniquement ; si vous l'omettez, le plan ne configure aucun exportateur | non |
privilege | root | capabilities | unprivileged — la façon dont l'agent s'exécutera réellement | non |
Les deux indices optionnels ne rendent jamais le plan que plus prudent lorsqu'ils
sont absents ou non reconnus : un privilege absent est lu comme
unprivileged, jamais comme root.
Renvoie l'agent et le profile demandés, plus quatre champs :
| Champ | Contenu |
|---|---|
config | un brouillon de configuration à faire relire par un humain ; les valeurs que seul votre tableau de bord peut fournir sont marquées REPLACE_ME, jamais devinées |
will_not_do | ce que cette configuration ne fait délibérément pas, et pourquoi |
notes | les réserves qui s'appliquent au profil et au niveau de privilège que vous avez choisis |
next_step | où aller pour enrôler — jamais une commande, jamais une URL |
Il refuse tout argument qui a la forme d'un jeton d'enrôlement — voir Formes d'échec.
Lisez will_not_do avant de déployer la configuration
Ce n'est pas du remplissage. Cette section nomme les paramètres délibérément laissés de côté, et la raison de chacun. Trois catégories ne sont jamais générées :
Les paramètres qui affirment une chose que vous seul pouvez affirmer. Scanner un autre réseau exige de déclarer que vous y êtes légalement autorisé. L'outil décrira le paramètre ; il n'écrira pas votre déclaration à votre place.
Les paramètres qui disent une chose et en font une autre. Certaines options se lisent comme restrictives sans l'être — un service marqué désactivé dans une politique de pare-feu qui laisse malgré tout un port ouvert, par exemple. Ceux-là sont refusés nommément, avec l'explication de ce qu'il faut faire à la place.
Les paramètres qui ne sont pas implémentés. Une option qui semble activer une protection, ne produit aucune protection et laisse une politique affirmer le contraire est pire que pas d'option du tout.
Le compromis de privilèges est énoncé, jamais supposé
Si vous demandez une configuration fondée sur les capabilities Linux plutôt que sur root là où cela dégrade sensiblement l'agent, le plan le dit avec des chiffres. Pour la capture de flux, les capabilities sans root font chuter l'attribution de processus par flux d'environ 87 % des flux à environ 6 % — et le reste, ce sont les flux de l'agent lui-même. La réponse du moindre privilège est généralement la bonne ; ici, elle supprime silencieusement la fonctionnalité pour laquelle vous avez installé l'agent, on vous le dit donc plutôt que de vous laisser le découvrir.
bits_download
Un agent, une plateforme, un binaire vérifiable.
| Paramètre | Type | Requis |
|---|---|---|
agent | l'un des quatre slugs | oui |
os | linux | darwin | windows | oui |
arch | amd64 | arm64 | oui |
Renvoie, pour le binaire publié :
| Champ | Contenu |
|---|---|
agent, os, arch | ce que vous avez demandé |
version | la version à laquelle appartient le binaire |
file_name | le nom sous lequel enregistrer le fichier |
size_bytes | sa taille en octets |
sha256 | sa somme de contrôle SHA-256, tirée du catalogue des versions |
download_url | l'adresse de téléchargement |
verify_command | une commande qui télécharge le fichier et le contrôle par rapport à sha256 |
note | un rappel de vérifier la somme de contrôle avant d'exécuter le binaire |
Les valeurs proviennent du catalogue des versions ; l'outil ne les calcule ni ne
les devine. Il ne propose jamais un téléchargement dont il ne peut pas fournir la
somme de contrôle : si le catalogue n'a pas de binaire pour cette plateforme, ou
si l'entrée n'a pas de SHA-256, de taille ou de nom de fichier exploitable, la
réponse est une erreur, pas une URL. Appelez d'abord bits_platforms pour voir
sur quelles plateformes un agent est distribué.
Utilisez l'URL de téléchargement que renvoie l'outil, et lancez la vérification avant d'exécuter le binaire. Un outil de téléchargement écrit tout ce qu'il reçoit — y compris une page d'erreur HTML — : seule une somme de contrôle concordante vous garantit que vous avez le vrai fichier.
Comme bits_plan_config, il refuse tout argument qui a la forme d'un jeton
d'enrôlement.
Formes d'échec
Chaque outil peut renvoyer un résultat d'erreur au lieu de données. Traitez-les — ne les prenez pas pour un « aucun résultat ».
| Ce que vous voyez | Ce que cela signifie |
|---|---|
catalogue read failed: … | Le catalogue des versions n'a pas pu être lu ou n'a pas pu être vérifié. Pas « rien trouvé » |
toutes les plateformes en platform_unknown | Même cause, rendue plateforme par plateforme. Ne lisez jamais cela comme « non pris en charge » |
state autre que complete | Le catalogue n'a été lu que partiellement. Toute recommandation négative est retenue |
catalogue read failed (…) — no download is offered | bits_download n'a trouvé aucun binaire dont il puisse répondre — la plateforme n'est pas construite, ou le catalogue n'a pas pu être lu ou vérifié. Aucune URL n'est devinée |
refused: that argument is shaped like a live Cert-IX enrolment token | Vous avez envoyé un jeton d'enrôlement. Retirez-le de la conversation ; sa place est sur la machine de l'agent |
too many requests from your address | Débit limité par adresse. Ralentissez et réessayez un peu plus tard |
HTTP 429 | Débit limité. Respectez Retry-After |
HTTP 405 | Vous avez envoyé autre chose qu'un POST |
Une réponse à laquelle on ne peut pas se fier est rapportée comme un échec, jamais comme un résultat vide ou négatif. Si un outil vous dit qu'un agent ne prend pas en charge votre plateforme, c'est qu'il a cherché et que c'est le cas. S'il n'a pas pu chercher, il vous dit cela à la place.
Cette page vous a-t-elle été utile ?