Riferimento degli strumenti

Cinque strumenti. Tutti di sola lettura, tutti idempotenti, nessuno in grado di modificare alcunché.

Ogni strumento restituisce testo in inglese e francese, e ognuno può restituire un risultato di errore invece dei dati — si vedano le Forme dell'errore, che sono la sezione che vale la pena leggere due volte.

---

bits_recommend

Obiettivo in ingresso, agenti in uscita.

Parametro	Tipo	Obbligatorio
goal	stringa, massimo 2000 byte	sì
os	stringa	no
arch	stringa	no

Restituisce gli agenti in ordine di pertinenza con il motivo per cui ciascuno è adatto e — quando il suo obiettivo implica una piattaforma — la vista per piattaforma di quell'agente, così non le viene mai indicato qualcosa che distribuisce un binario ma non ha ancora un percorso di registrazione.

Ogni risposta porta con sé un blocco di completezza del catalogo:

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

Perché quel blocco esiste

«Nessuno di questi fa al caso suo» viene emesso solo quando state è complete. Se il catalogo fosse letto solo in parte — con il record di un agente che non riesce a caricarsi — uno strumento ingenuo risponderebbe in sordina «non abbiamo nulla per questo» e lei andrebbe altrove. Nulla avrebbe segnalato un errore. Controlli state prima di agire su una risposta negativa.

---

bits_explain

Parametro	Tipo	Obbligatorio
agent	bitcollector | bitscanner | bitenforcer | bitmapper	sì
topic	observes | never_touches | privileges | platforms | heartbeat | where_results_land	no

Restituisce che cosa l'agente osserva, che cosa dichiara esplicitamente di non toccare mai, che cosa le porta il privilegio e dove finiscono i suoi risultati.

I topic never_touches e privileges sono quelli utili. Il privilegio non cambia soltanto ciò che a un agente è consentito fare — cambia ciò che il suo output significa. Un bitcollector eseguito senza privilegi non può attribuire ai processi i socket in ascolto: il suo inventario delle porte è quindi reale, ma la mappatura dei processi è assente, e lo dichiara invece di riportare zero.

---

bits_platforms

Parametro	Tipo	Obbligatorio
agent	uno dei quattro slug	sì

Restituisce tre fatti distinti per ogni piattaforma, mai una sola colonna:

Fatto	Significato
catalogued	esiste un binario di release firmato per questo sistema operativo e questa architettura
enrolable	esiste oggi un percorso di registrazione per questo agente
observable	questo agente riporta un heartbeat una volta registrato

e uno stato per piattaforma: platform_supported, platform_not_built oppure platform_unknown.

Perché tre fatti e non uno

Un agente può essere catalogato su una piattaforma, non avere ancora un percorso di registrazione e non riportare mai un heartbeat — tutto nello stesso momento. bitenforcer è esattamente questo oggi: distribuisce binari Linux firmati, non è ancora registrabile e per scelta progettuale non emette mai un heartbeat, perché non ha un percorso di consegna. Renderlo come «supportato: sì» sarebbe vero e la indurrebbe in errore, lasciandola in attesa di una telemetria che non arriverà mai.

platform_unknown è il terzo stato ed esiste affinché una lettura fallita del catalogo non possa mai essere riportata come «questa piattaforma non è supportata».

---

bits_plan_config

Parametro	Tipo	Obbligatorio
agent	uno dei quattro slug	sì
profile	minimal | standard | strict	sì
destination	control_plane — solo bitcollector; se lo omette, il piano non configura alcun exporter	no
privilege	root | capabilities | unprivileged — come verrà effettivamente eseguito l'agente	no

Se mancano o non vengono riconosciute, le due indicazioni facoltative possono solo rendere il piano più prudente: un privilege assente viene letto come unprivileged, mai come root.

Restituisce l'agent e il profile che ha richiesto, più quattro campi:

Campo	Contenuto
config	una bozza di configurazione da far rivedere a una persona; i valori che solo la sua dashboard può fornire sono contrassegnati con REPLACE_ME, senza mai tirare a indovinare
will_not_do	ciò che questa configurazione deliberatamente non fa, e perché
notes	avvertenze che si applicano al profilo scelto e al livello di privilegio
next_step	dove andare per effettuare la registrazione — mai un comando, mai un URL

Rifiuta qualsiasi argomento che abbia l'aspetto di un token di registrazione — si vedano le Forme dell'errore.

Legga will_not_do prima di fare il deploy della configurazione

Non è testo di riempimento. Nomina le impostazioni deliberatamente omesse e la ragione di ciascuna. Tre categorie non vengono mai generate:

Impostazioni che dichiarano qualcosa che solo lei può dichiarare. Scansionare una rete altrui richiede di dichiarare di esservi legalmente autorizzato. Lo strumento descriverà l'impostazione; non scriverà la sua dichiarazione al posto suo.

Impostazioni che dicono una cosa e ne fanno un'altra. Alcune opzioni si leggono come restrittive e non lo sono — per esempio un servizio contrassegnato come disabilitato in una policy di firewall che lascia comunque una porta aperta. Queste vengono rifiutate per nome, con una spiegazione di che cosa fare invece.

Impostazioni non implementate. Un'opzione che sembra impostare una protezione, non produce alcuna protezione e lascia una policy che afferma il contrario è peggio di nessuna opzione.

Il compromesso sui privilegi viene dichiarato, non dato per scontato

Se chiede una configurazione basata sulle capabilities invece di root, laddove questo degradi l'agente in modo sostanziale, il piano lo dice con dei numeri. Per la cattura dei flussi, le capabilities senza root fanno crollare l'attribuzione dei processi per singolo flusso da circa l'87% dei flussi a circa il 6% — e i flussi rimanenti sono quelli dell'agente stesso. La risposta del privilegio minimo è di solito quella giusta; qui rimuove in silenzio la funzionalità per cui ha installato l'agente, perciò glielo si dice invece di lasciare che lo scopra da sé.

---

bits_download

Un agente, una piattaforma, un binario verificabile.

Parametro	Tipo	Obbligatorio
agent	uno dei quattro slug	sì
os	linux | darwin | windows	sì
arch	amd64 | arm64	sì

Restituisce, per il binario pubblicato:

Campo	Contenuto
agent, os, arch	ciò che ha richiesto
version	la release a cui appartiene il binario
file_name	il nome con cui salvare il file
size_bytes	la sua dimensione in byte
sha256	il suo checksum SHA-256, preso dal catalogo delle release
download_url	da dove scaricarlo
verify_command	un comando che scarica il file e lo confronta con sha256
note	un promemoria di verificare il checksum prima di eseguire il binario

I valori provengono dal catalogo delle release; lo strumento non li calcola e non tira a indovinare. Non offre mai un download per cui non sia in grado di fornire un checksum: se il catalogo non ha alcun binario per quella piattaforma, o se la voce non contiene uno SHA-256, una dimensione o un nome di file utilizzabili, la risposta è un errore, non un URL. Richiami prima bits_platforms per vedere su quali piattaforme è distribuito un agente.

Verifichi prima di eseguire

Usi l'URL di download restituito dallo strumento ed effettui la verifica prima di eseguire il binario. Uno strumento di download salva qualunque cosa riceva — compresa una pagina di errore HTML — quindi solo un checksum corrispondente le conferma di avere il file autentico.

Come bits_plan_config, rifiuta qualsiasi argomento che abbia l'aspetto di un token di registrazione.

---

Forme dell'errore

Ogni strumento può restituire un risultato di errore invece dei dati. Li gestisca — non li tratti come «nessun risultato».

Che cosa vede	Che cosa significa
catalogue read failed: …	Il catalogo delle release non ha potuto essere letto oppure non ha potuto essere verificato. Non «nessun risultato»
tutte le piattaforme a platform_unknown	Stessa causa, resa per singola piattaforma. Non lo legga mai come «non supportata»
state diverso da complete	Il catalogo è stato letto solo in parte. Una raccomandazione negativa viene trattenuta
catalogue read failed (…) — no download is offered	bits_download non ha trovato alcun binario di cui possa garantire — per quella piattaforma non esiste una build, oppure il catalogo non ha potuto essere letto o verificato. Lo strumento non tira a indovinare alcun URL
refused: that argument is shaped like a live Cert-IX enrolment token	Ha inviato un token di registrazione. Lo tolga dalla conversazione: va sulla macchina dell'agente
too many requests from your address	Limite di frequenza per indirizzo raggiunto. Rallenti e riprovi a breve
HTTP 429	Limite di frequenza raggiunto. Rispetti Retry-After
HTTP 405	Ha inviato qualcosa di diverso da POST

La regola che sta dietro a tutte

Una risposta di cui non ci si può fidare viene riportata come un errore, mai come un risultato vuoto o negativo. Se uno strumento le dice che un agente non supporta la sua piattaforma, significa che ha guardato e che non la supporta. Se non ha potuto guardare, dice quello.