Referencia de herramientas

Cinco herramientas. Todas de solo lectura, todas idempotentes, ninguna capaz de cambiar nada.

Todas las herramientas devuelven texto en inglés y francés, y todas pueden devolver un resultado de error en lugar de datos — véase Formas de fallo, que es la sección que conviene leer dos veces.

---

bits_recommend

Entra un objetivo, salen agentes.

Parámetro	Tipo	Obligatorio
goal	cadena, máximo 2000 bytes	sí
os	cadena	no
arch	cadena	no

Devuelve agentes ordenados por pertinencia con el motivo por el que cada uno encaja y —cuando su objetivo implica una plataforma— la vista de plataforma de ese agente, de modo que nunca se le dirige a algo que distribuye un binario pero que todavía no tiene vía de enrolamiento.

Cada respuesta lleva un bloque de completitud del catálogo:

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

Por qué existe ese bloque

«Ninguno de estos encaja» solo se emite cuando state vale complete. Si el catálogo se leyera parcialmente —porque el registro de un agente no llegue a cargarse— una herramienta ingenua respondería sin ruido «no tenemos nada para eso» y usted se iría a otra parte. Nada habría dado error. Compruebe state antes de actuar sobre una respuesta negativa.

---

bits_explain

Parámetro	Tipo	Obligatorio
agent	bitcollector | bitscanner | bitenforcer | bitmapper	sí
topic	observes | never_touches | privileges | platforms | heartbeat | where_results_land	no

Devuelve qué observa el agente, qué no toca nunca de forma explícita, qué le aporta el privilegio y dónde acaban sus resultados.

Los temas never_touches y privileges son los útiles. El privilegio no solo cambia lo que a un agente se le permite hacer: cambia lo que su salida significa. Un bitcollector que se ejecuta sin privilegios no puede atribuir a procesos los sockets en escucha, así que su inventario de puertos es real pero su correspondencia con los procesos está ausente, y lo dice en lugar de informar de cero.

---

bits_platforms

Parámetro	Tipo	Obligatorio
agent	uno de los cuatro slugs	sí

Devuelve tres hechos separados por plataforma, nunca una sola columna:

Hecho	Significado
catalogued	existe un binario de versión firmado para este sistema operativo y esta arquitectura
enrolable	existe hoy una vía de enrolamiento para este agente
observable	este agente reporta un latido una vez enrolado

y un estado por plataforma: platform_supported, platform_not_built o platform_unknown.

Por qué tres hechos y no uno

Un agente puede estar catalogado en una plataforma, no tener todavía vía de enrolamiento y no reportar nunca un latido, todo a la vez. bitenforcer es exactamente eso hoy: distribuye binarios de Linux firmados, todavía no es enrolable y, por diseño, nunca emite un latido porque no tiene vía de entrega. Presentar eso como «compatible: sí» sería cierto y le induciría a esperar una telemetría que no va a llegar nunca.

platform_unknown es el tercer estado, y existe para que una lectura fallida del catálogo no pueda comunicarse nunca como «esta plataforma no es compatible».

---

bits_plan_config

Parámetro	Tipo	Obligatorio
agent	uno de los cuatro slugs	sí
profile	minimal | standard | strict	sí
destination	control_plane — solo bitcollector; si se omite, el plan no configura ningún exportador	no
privilege	root | capabilities | unprivileged — cómo se ejecutará realmente el agente	no

Las dos indicaciones opcionales, cuando faltan o no se reconocen, solo pueden hacer el plan más conservador: un privilege ausente se interpreta como unprivileged, nunca como root.

Devuelve el agent y el profile que usted pidió, más cuatro campos:

Campo	Contenido
config	un borrador de configuración para que lo revise una persona; los valores que solo su panel puede aportar se marcan como REPLACE_ME, nunca se adivinan
will_not_do	lo que esta configuración deliberadamente no hace, y por qué
notes	salvedades que se aplican al perfil y al nivel de privilegio que usted haya elegido
next_step	adónde ir para enrolar — nunca un comando, nunca una URL

Rechaza cualquier argumento con forma de token de enrolamiento — véase Formas de fallo.

Lea will_not_do antes de desplegar la configuración

No es texto de relleno. Nombra los ajustes que se dejaron fuera deliberadamente, y el motivo de cada uno. Hay tres categorías que nunca se generan:

Ajustes que afirman algo que solo usted puede afirmar. Escanear otra red exige declarar que está legalmente autorizado a hacerlo. La herramienta describirá el ajuste; no escribirá su declaración por usted.

Ajustes que dicen una cosa y hacen otra. Algunas opciones se leen como restrictivas y no lo son: un servicio marcado como deshabilitado en una política de cortafuegos que aun así acaba dejando un puerto abierto, por ejemplo. Esas se rechazan por su nombre, con una explicación de qué hacer en su lugar.

Ajustes que no están implementados. Una opción que aparenta establecer una protección, no produce protección alguna y deja una política afirmando lo contrario es peor que no tener ninguna opción.

La contrapartida del privilegio se declara, no se da por supuesta

Si pide una configuración basada en capabilities en lugar de root allí donde eso degrada materialmente al agente, el plan lo dice con números. En la captura de flujos, las capabilities sin root hunden la atribución de procesos por flujo desde alrededor del 87 % de los flujos hasta cerca del 6 % — y los restantes son los del propio agente. La respuesta de mínimo privilegio suele ser la correcta; aquí elimina sin hacer ruido la funcionalidad para la que usted instaló el agente, así que se le dice en lugar de dejar que lo descubra.

---

bits_download

Un agente, una plataforma, un binario verificable.

Parámetro	Tipo	Obligatorio
agent	uno de los cuatro slugs	sí
os	linux | darwin | windows	sí
arch	amd64 | arm64	sí

Devuelve, para el binario publicado:

Campo	Contenido
agent, os, arch	lo que usted pidió
version	la versión a la que pertenece el binario
file_name	el nombre de archivo con el que guardarlo
size_bytes	su tamaño en bytes
sha256	su suma de verificación SHA-256, tomada del catálogo de versiones
download_url	dónde descargarlo
verify_command	un comando que descarga el archivo y lo comprueba con sha256
note	un recordatorio de verificar la suma de verificación antes de ejecutar el binario

Las cifras proceden del catálogo de versiones; la herramienta no las calcula ni las adivina. Nunca ofrece una descarga para la que no pueda dar una suma de verificación: si el catálogo no tiene ningún binario para esa plataforma, o la entrada carece de un SHA-256, un tamaño o un nombre de archivo utilizables, la respuesta es un error, no una URL. Llame primero a bits_platforms para ver en qué plataformas se distribuye un agente.

Verifique antes de ejecutar

Use la URL de descarga que devuelve la herramienta y ejecute la verificación antes de ejecutar el binario. Una herramienta de descarga escribe lo que reciba —incluida una página de error HTML—, así que solo una suma de verificación coincidente le indica que tiene el archivo auténtico.

Al igual que bits_plan_config, rechaza cualquier argumento con forma de token de enrolamiento.

---

Formas de fallo

Cualquier herramienta puede devolver un resultado de error en lugar de datos. Trátelos como tales: no los interprete como «sin resultados».

Lo que ve	Qué significa
catalogue read failed: …	No se pudo leer el catálogo de versiones o no se pudo verificar. No es «no se encontró nada»
todas las plataformas en platform_unknown	La misma causa, expresada por plataforma. No lea esto nunca como «no compatible»
state distinto de complete	El catálogo se leyó parcialmente. Se retiene toda recomendación negativa
catalogue read failed (…) — no download is offered	bits_download no encontró ningún binario que pueda respaldar: no hay compilación para esa plataforma, o el catálogo no se pudo leer o verificar. No se adivina ninguna URL
refused: that argument is shaped like a live Cert-IX enrolment token	Envió un token de enrolamiento. Retírelo de la conversación; debe estar en la máquina del agente
too many requests from your address	Límite de tasa alcanzado por dirección. Reduzca el ritmo y vuelva a intentarlo en breve
HTTP 429	Límite de tasa alcanzado. Respete Retry-After
HTTP 405	Envió algo que no es POST

La regla que hay detrás de todas ellas

Una respuesta en la que no se puede confiar se comunica como un fallo, nunca como un resultado vacío o negativo. Si una herramienta le dice que un agente no admite su plataforma, significa que lo comprobó y no la admite. Si no pudo comprobarlo, dice eso en su lugar.