Security

Security

What bothy verifies, what it deliberately does not, and where each boundary ends. To report a vulnerability, use SECURITY.md — privately, through GitHub's security advisories, not a public issue.

What bothy downloads, and what checks it

bothy fetches eight tools. Every one is pinned to a version and a sha256 in bothy.lock, and the checksum is verified before the file is kept. A tool already on your PATH at a good version is used as-is and nothing is downloaded.

Where a project publishes a checksum of its own, bothy lock compares the two before recording the pin, and refuses outright if they disagree. Several projects publish nothing. bothy tools says which is which, per tool: pin: upstream was compared, pin: download is the hash of what the maintainer downloaded on the day they ran bothy lock.

What that comparison is worth, precisely. The published file sits in the same release as the asset, so whoever can replace one can replace the other. It rules out a substitution after publication, and a download corrupted or intercepted on the way. It does not rule out a compromised release pipeline, and no checksum can.

The limit: these are other projects' releases. A checksum proves the bytes are the ones bothy expected; it does not prove those bytes are safe. bothy does not sign what it did not build.

What bothy itself is signed with

Nothing you have to trust a key for. Release artifacts are signed by the GitHub Actions workflow that built them, keyless, and recorded in a public transparency log — so the binary can be traced to a specific run of a specific workflow on a specific commit (ADR-030).

There is deliberately no private key, so there is none to store, rotate or leak.

What that does not do: it does not make a compromise impossible. It makes one visible and permanent. If this repository's Actions were compromised, the attestation would record the attacker's build, and that record could not be withdrawn quietly.

It is also not what Gatekeeper asks for. Apple requires an identifiable paid developer account; the attestation answers a different question, and neither substitutes for the other. See Installing.

curl | sh

The install script is fetched over HTTPS and run, unsigned, before bothy exists to verify anything. This is a real gap and it is not solved — no signature on an artifact fixes verifying the verifier.

What you can do instead: download it, read it, then run it. It is one file and deliberately small.

curl -fsSL -o install.sh https://raw.githubusercontent.com/lampseen/bothy/main/bootstrap/install.sh
less install.sh
sh install.sh

Or avoid it: go install, the .deb and dnf do not have this step.

Confining the agent

bothy confine runs the agent in a rootless podman container with your project directory and the agent's own credentials mounted, and nothing else from $HOME. It is opt-in and there is no setting that turns it on.

What it stops: every other project, ~/.ssh, ~/.aws, your shell history. Verified rather than assumed — a test fails if the invocation ever mounts $HOME.

What it does not stop, on purpose:

the network	the agent calls its API; that is the job. This is a filesystem wall, not a network one
the agent's own credentials	mounted, or it cannot log in and the wall protects nothing you wanted
the project directory	mounted writable, because editing it is the point

Without confine, there is no wall at all — and bothy says so rather than implying otherwise. The agent runs as you, with your access, exactly as it would if you had started it yourself. bothy is not making that worse; it owns the launch, which is a position to make it better if you ask.

What bothy does not do

• No telemetry, no auto-updater, no background service. A test fails if any shipping file names a host that is not GitHub.
• It does not touch your dotfiles. Not ~/.vimrc, not ~/.config/yazi, not your git config. It writes into its own tree and points tools there for one process (ADR-009).
• It never asks for root.

Scope for a report

In scope: the release pipeline, the confinement wall, bootstrap/install.sh, the Homebrew cask's quarantine removal, and the configs bothy generates for other tools. Out of scope: what the agent does, and holes in the tools bothy fetches — although a flaw in how bothy pins or verifies them is in scope. The full statement is SECURITY.md.