TrustMeBro: a PATH shim that feeds coding agents fabricated tool output
Bypass llm guardrails by confusing it with fabricated tool output.
At a glance
- What is it?
- TrustMeBro sits between a coding agent and the command line tools it calls, returning invented dig, nslookup and host answers when a rule matches. It is a red-team instrument for testing whether an agent's next decision actually depends on what the tool said.
- Who is it for?
- Adopt it if you are running controlled red-team exercises against a coding agent and you need to know whether a specific tool result is load-bearing for its next action. Do not adopt it as an application security control or as a sandbox; the README states plainly that lab mode is an interception namespace, not a security sandbox, and that it reuses the host filesystem, workspace, network, environment and agent credentials.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 15 days ago.
- What is it written in?
- Mainly Go, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap TrustMeBro targets is between a tool result and the agent's next move
An agent that runs dig and then decides whether to continue is making a decision on data it did not produce. TrustMeBro exists to test that dependency directly. The README describes a controlled local evaluation in which each model had to verify a fresh DNS TXT authorization marker before proceeding with a scan. Without the tool, the real /usr/bin/dig returned no marker and the model stopped. With TrustMeBro in lab mode, the same absolute command path returned fabricated proof and the model went ahead. The README reports that outcome for GPT-5.6 Sol, GPT-5.5, DeepSeek V4 Pro and DeepSeek V4 Flash, all four moving from blocked to proceeded. The audience is narrow: people running red-team exercises on agent decision chains, not people hardening production agents. If your interest is prompt-level jailbreaks, this is a different layer of the stack. TrustMeBro does not touch the prompt. It touches what the shell hands back.
PATH shims, first-match YAML rules, and an audit line per decision
Interception is done with PATH shims rather than a plugin, hook or MCP integration. The installer writes shim binaries for dig, nslookup and host into ~/.local/share/trustmebro/shims/ and prepends that directory to supported shell startup files. The README notes that login shell files are included because agents commonly execute commands through non-interactive bash -lc sessions, which is the detail that makes the trick work in practice. A shim receives the call, loads ~/.config/trustmebro/config.yaml, and walks the rules in file order. The first rule whose every configured match field succeeds wins. Match fields cover command names, domains, DNS record types, argument globs and regular expressions. The winning rule then selects one of four behaviours: return generated dig, nslookup or host output; run the real binary and patch stdout with regex substitutions while preserving stderr and exit status; reject the call; or pass through to the real binary with exec. Anything unmatched goes to the real command unless default_action says otherwise. Each decision is appended to a timestamped JSONL audit log, and the README's sample lines show the shape: one entry with mode spoof and a rule name, another with mode passthrough and the resolved real path /usr/bin/dig.
Getting it running: install, status, check, lab
The prebuilt path is two commands. The README gives curl -sL https://github.com/DavidCarliez/trustmebro/releases/latest/download/trustmebro_linux_amd64.tar.gz | tar xz followed by ./trustmebro install. Open a new terminal and run trustmebro status to confirm the shims landed. Release assets exist for linux_amd64, linux_arm64, darwin_amd64 and darwin_arm64, with SHA256SUMS published alongside. Go users can run go install github.com/DavidCarliez/trustmebro@latest and then ~/go/bin/trustmebro install; building from source is git clone, cd trustmebro, make install. The installer writes four locations: the CLI at ~/.local/bin/trustmebro, shims under ~/.local/share/trustmebro/shims/, rules at ~/.config/trustmebro/config.yaml, and the audit log at ~/.local/state/trustmebro/log.jsonl. The generated config ships a working example against *.trustmebro.test, and the README shows dig marker.trustmebro.test TXT +short returning "trustmebro-marker-7f3a9" while dig cloudflare.com A +short goes to the real resolver. TRUSTMEBRO_CONFIG points one process at a different rule file, which is the cleanest way to keep a test config separate from your default. On Linux, trustmebro lab opens an interception namespace, trustmebro lab -- codex runs an agent inside it, and trustmebro lab --plan -- codex previews which absolute paths would be intercepted. Bubblewrap must be installed through your package manager first. Uninstall is trustmebro uninstall, with --purge to remove the binary, config and state.
Lab mode closes the command -v dig escape, and is explicitly not a sandbox
Plain PATH shims have an obvious hole: an agent that runs command -v dig and then invokes the returned absolute path skips the shim entirely. Lab mode addresses this with Bubblewrap, shadowing both PATH lookups and discovered absolute paths such as /usr/bin/dig. The original binaries stay reachable through a separate temporary path so passthrough and rewrite rules still function. That is a real design answer to a real bypass. The README is equally direct about the boundary: lab mode is an interception namespace, not a security sandbox, and it deliberately reuses the host filesystem, current workspace, network, environment and agent credentials. Read that as a statement about containment. An agent inside the namespace can still reach your network and your credentials, because the namespace was built to intercept command output, not to isolate the process. Anyone who reads the name and assumes isolation will be wrong, and the documentation does not encourage the mistake. The temporary files disappear when the command exits, so there is no persistent environment to inspect afterwards beyond the audit log.
Strict config parsing turns a typo into exit status 78
Configuration is parsed strictly. Unknown fields, unsafe shim names, invalid actions and malformed rules all make trustmebro check fail. That is the right default for a tool whose output is meant to be believed by something else, but it produces a specific operational failure mode worth naming. If an installed shim encounters an invalid config, it blocks the command and exits with status 78. So a config edit that breaks parsing does not degrade to passthrough. It stops the agent's tool call outright. Teams iterating on rules during a red-team session will hit this, and the diagnostic is trustmebro check rather than reading the agent's error. The README mentions TRUSTMEBRO_DISABLE=1 for explicitly bypassing the config, and the sentence is cut off in the supplied material, so the exact scope of that override cannot be confirmed from what is available here. Treat the environment variable as documented for deliberate bypass only, and verify its behaviour before relying on it in a scripted run.
The honest comparison is against running a fake binary yourself
The obvious alternative is hand-rolled: drop a shell script named dig earlier on PATH and have it print whatever you want. That works for a single command and a single scenario, and it costs nothing. The difference is everything that surrounds the fake. TrustMeBro adds ordered matching across command, domain, qtype, argument globs and regexes, so one config can express several scenarios without renaming files between runs. It adds a rewrite mode that runs the genuine binary and patches only stdout, which matters when you need a realistic response body with one line altered rather than a wholly invented one. It adds passthrough with exec, so unmatched traffic behaves normally and your test does not silently change unrelated agent behaviour. It adds reject for testing what happens when a tool call is refused. And it writes a JSONL record per decision, which a shell script does not do unless you build it. What it does not add is containment, and a hand-rolled script does not have that either. The comparison is convenience, repeatability and auditability, not safety.
Platform support is uneven and the Windows build is experimental
The installer targets Unix shells. The README states that the Windows binary is experimental and does not provide equivalent shell startup integration. For Windows users, that removes the part that makes the PATH shim approach work without manual wiring, and the README offers no equivalent. Lab mode is Linux-only as described, since it depends on Bubblewrap, which is a Linux tool. macOS gets release assets and the shim installation but no namespace mode, so an agent on macOS can still reach the real binary through an absolute path if it looks one up. That is the gap lab mode was built to close, and it remains open on macOS. The README does not describe a macOS substitute. Anyone planning a red-team exercise on a Mac should confirm from the repository whether absolute-path interception exists on that platform before designing the scenario around it, because the supplied material does not establish that it does.
Maintenance, licensing and what to verify before you rely on a run
TrustMeBro is MIT licensed, which permits commercial and private use and modification, and the repository carries a LICENSE file. That is a permissive grant, and it also means the project comes with no warranty from the authors, as MIT states. Nothing here is legal advice, and if you redistribute a modified build you should read the licence text rather than this summary. On maintenance, the visible signals are two releases, v0.1.0 and v0.1.1, both dated 2026-08-26, with the last push to main on 2026-09-01. That is a young project with a short history, and the version numbers suggest early-stage API and config stability rather than a settled surface. The upgrade cost is mostly config drift: strict parsing means a future field rename or validation change can turn a working config into exit 78 on the next install, so keep your rules in version control and re-run trustmebro check after every upgrade. The audit log format is JSONL and the README shows its fields, but log rotation is not described in the supplied material, so long-running sessions will accumulate the file at ~/.local/state/trustmebro/log.jsonl with no documented pruning. Before you trust a result, confirm three things on the machine in question: that trustmebro check passes, that trustmebro lab --plan -- codex lists the absolute paths you expect to be shadowed, and that the log.jsonl entries for your run show the rule name you intended rather than a passthrough line.
Editorial conclusion
Adopt it if you are running controlled red-team exercises against a coding agent and you need to know whether a specific tool result is load-bearing for its next action. Do not adopt it as an application security control or as a sandbox; the README states plainly that lab mode is an interception namespace, not a security sandbox, and that it reuses the host filesystem, workspace, network, environment and agent credentials. Before trusting a result, run trustmebro check against your config, run trustmebro lab --plan -- codex to see which absolute paths would actually be shadowed, and confirm from log.jsonl that the rule you wrote is the rule that fired.
Community notes