Tools Reference

Five tools. All read-only, all idempotent, none capable of changing anything.

Every tool returns text in English and French, and every one can return an error result rather than data — see Failure shapes, which is the section worth reading twice.

---

bits_recommend

Goal in, agents out.

Parameter	Type	Required
goal	string, max 2000 bytes	yes
os	string	no
arch	string	no

Returns ranked agents with the reason each fits, and — where your goal implies a platform — that agent's platform view, so you are never pointed at something that ships a binary but has no enrolment path yet.

Every response carries a catalogue completeness block:

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

Why that block exists

"None of these fit" is only emitted when state is complete. If the catalogue were read partially — one agent's record failing to load — a naive tool would quietly answer "we have nothing for that" and you would go elsewhere. Nothing would have errored. Check state before acting on a negative answer.

---

bits_explain

Parameter	Type	Required
agent	bitcollector | bitscanner | bitenforcer | bitmapper	yes
topic	observes | never_touches | privileges | platforms | heartbeat | where_results_land	no

Returns what the agent observes, what it explicitly never touches, what privilege buys you, and where its results land.

The never_touches and privileges topics are the useful ones. Privilege does not just change what an agent is allowed to do — it changes what its output means. A bitcollector running unprivileged cannot attribute listening sockets to processes, so its port inventory is real but its process mapping is absent, and it says so rather than reporting zero.

---

bits_platforms

Parameter	Type	Required
agent	one of the four slugs	yes

Returns three separate facts per platform, never one column:

Fact	Meaning
catalogued	a signed release binary exists for this OS and architecture
enrolable	an enrolment path exists for this agent today
observable	this agent reports a heartbeat once enrolled

and a state per platform: platform_supported, platform_not_built, or platform_unknown.

Why three facts and not one

An agent can be catalogued on a platform, have no enrolment path yet, and never report a heartbeat — all at once. bitenforcer is exactly that today: it ships signed Linux binaries, is not yet enrolable, and by design never emits a heartbeat because it has no delivery path. Rendering that as "supported: yes" would be true and would mislead you into waiting for telemetry that is never coming.

platform_unknown is the third state, and it exists so that a failed catalogue read can never be reported as "this platform is not supported".

---

bits_plan_config

Parameter	Type	Required
agent	one of the four slugs	yes
profile	minimal | standard | strict	yes
destination	control_plane — bitcollector only; omit it and the plan configures no exporter	no
privilege	root | capabilities | unprivileged — how the agent will actually run	no

The two optional hints only ever make the plan more conservative when they are missing or unrecognised: an absent privilege is read as unprivileged, never as root.

Returns the agent and profile you asked for, plus four fields:

Field	Contents
config	a draft configuration for a human to review; values only your dashboard can supply are marked REPLACE_ME, never guessed
will_not_do	what this config deliberately does not do, and why
notes	caveats that apply to your chosen profile and privilege level
next_step	where to go to enrol — never a command, never a URL

It refuses any argument shaped like an enrolment token — see Failure shapes.

Read will_not_do before you deploy the config

It is not boilerplate. It names the settings that were deliberately left out, and the reason for each. Three categories are never generated:

Settings that assert something only you can assert. Scanning another network requires declaring that you are legally authorised to do so. The tool will describe the setting; it will not write your assertion for you.

Settings that say one thing and do another. Some options read as restrictive and are not — a service marked disabled in a firewall policy that still results in an open port, for instance. Those are refused by name with an explanation of what to do instead.

Settings that are not implemented. An option that appears to set a protection, produces no protection, and leaves a policy asserting otherwise is worse than no option at all.

The privilege trade-off is stated, not assumed

If you ask for a capabilities-based setup instead of root where that materially degrades the agent, the plan says so with numbers. For flow capture, capabilities without root collapse per-flow process attribution from roughly 87% of flows to about 6% — and the remainder are the agent's own. The least-privilege answer is usually right; here it quietly removes the feature you installed the agent for, so you are told rather than left to discover it.

---

bits_download

One agent, one platform, one verifiable binary.

Parameter	Type	Required
agent	one of the four slugs	yes
os	linux | darwin | windows	yes
arch	amd64 | arm64	yes

Returns, for the published binary:

Field	Contents
agent, os, arch	what you asked for
version	the release the binary belongs to
file_name	the file name to save it as
size_bytes	its size in bytes
sha256	its SHA-256 checksum, taken from the release catalogue
download_url	where to download it
verify_command	a command that downloads the file and checks it against sha256
note	a reminder to verify the checksum before running the binary

The figures come from the release catalogue; the tool does not compute or guess them. It never offers a download it cannot give a checksum for: if the catalogue has no binary for that platform, or the entry lacks a usable SHA-256, size or file name, the answer is an error, not a URL. Call bits_platforms first to see which platforms an agent ships on.

Verify before you run

Use the download URL the tool returns, and run the verification before you execute the binary. A download tool writes whatever it receives — an HTML error page included — so only a matching checksum tells you that you have the real file.

Like bits_plan_config, it refuses any argument shaped like an enrolment token.

---

Failure shapes

Every tool can return an error result instead of data. Handle these — do not treat them as "no results".

What you see	What it means
catalogue read failed: …	The release catalogue could not be read or could not be verified. Not "nothing found"
all platforms platform_unknown	Same cause, rendered per platform. Never read this as "unsupported"
state other than complete	The catalogue was read partially. A negative recommendation is withheld
catalogue read failed (…) — no download is offered	bits_download found no binary it can vouch for — the platform is not built, or the catalogue could not be read or verified. No URL is guessed
refused: that argument is shaped like a live Cert-IX enrolment token	You sent an enrolment token. Take it out of the conversation; it belongs on the agent's machine
too many requests from your address	Rate limited per address. Slow down and retry shortly
HTTP 429	Rate limited. Honour Retry-After
HTTP 405	You sent something other than POST

The rule behind all of them

An answer that cannot be trusted is reported as a failure, never as an empty or negative result. If a tool tells you an agent does not support your platform, it means it looked and it does not. If it could not look, it says that instead.