Skip to content

Security: KeiaiLab/SwarmOps

SECURITY.md

Security policy

How do I report a vulnerability?

Privately, never in a public issue, pull request, discussion or commit: on the repository's Security tab, choose Report a vulnerability. That opens a draft security advisory that only you and the maintainers can see.

What should a report include?

What you found, how to reproduce it (a store, a command line, a crafted file), what it lets an attacker do, and the commit or swarmops --version you tested. A report about a dependency's advisory needs evidence that SwarmOps reaches the affected code.

Which versions get fixes?

Fixes land on stable, the main line, and ship in the next release. No earlier release gets a fix. CHANGELOG.md notes each fix under Security. An install the installer made, of a release after 0.11.0, takes the next release by itself unless that is turned off (so update --status says which); every other install is updated by whoever runs it (Install, How do I update?).

What answer should I expect?

No time is promised. The maintainers work out the fix with you in the draft advisory, and publish the advisory once the fix has landed.

Which problems are in scope?

A flaw that breaks the local trust model below: a crafted store file, request or git repository that makes SwarmOps panic, write outside its bounds or allocate without bound; a credential that leaks; a test hook a release build honours; an update of the program that takes anything but a newer release from the project's releases; a supply-chain weakness. A local user with write access to the store, and lost data after a crash, are not vulnerabilities. The details follow.

What is in scope

The trust model is M1's: SwarmOps runs on one host, as a library linked into each swarmops process, with no daemon and no network service. Three things reach the network, each through a program of the user's run as a child process: SwarmOps opens no connection itself. Since M13, clone, fetch, push and sync reach a git remote, through the user's own git. auth login without --with-token reaches the provider's login addresses, through the user's own curl. And the program's own update reaches github.com's release addresses for this repository, through the user's curl and the installer built into the program. The first two happen when a command that is named for them is run. The third also happens unasked: an install the installer made looks for a newer release after a command, at most once a day, in a detached process that ends when it has looked or installed, and installs a release the maintainers marked for it ("The program's own update", below, says what is trusted and how it is turned off). Every agent and person that runs swarmops against a store is a trusted local user acting for the same owner, and the store directory's filesystem permissions are the access boundary. A login (swarmops auth login) keeps a token in one file of the user's, outside every store, whose own mode is its boundary. Within that model, these are vulnerabilities:

  • Crafted or damaged store files. SwarmOps reads files it did not necessarily write: a store copied or restored from elsewhere, a damaged disk, a file someone placed there. Reading any of them must fail with an error, never panic, abort, hang, read out of bounds, allocate without bound or return wrong data as valid. That covers object files (objects/<2hex>/<62hex>: the header, the zstd frame and the payload, which is checked against its id on every read), the journal (meta/journal.log, journal.off, journal.ckpt), the changeset index (meta/idx/*.col, meta/parents.log, meta/sorted/*), ref files (meta/refs/*), derived values (meta/derived/*, a cache whose files carry a checksum over their slot and value, not a signature), external id entries (meta/external_ids/*, a cache that maps a git commit to its changeset, whose files carry a checksum, not a signature) and the write queue's files (meta/queue/*: requests, answers and batch manifests that writers leave for the lock's holder and that nothing else reads). A queue file is opened as meta/lock is, a regular file only and no symlink followed, and its length is checked against its bound (64 KiB for a request, 1 MiB for an answer, the manifest's for a manifest) before a byte of it is read; each record starts with a magic and a version and ends in a checksum. A request that is torn or past its bound is left unplanned; one of another version, or whose body does not decode, is declined, and its writer runs it again alone. An answer that does not decode is an error to its waiter, never run again. These cases are known and tracked (docs/known-limitations.md, "Hostile input"): an object whose zstd frame really decompresses to a large size (a compression bomb) is decompressed in full before its hash is checked, so reading it takes 512 MiB of payload, the most an object holds, plus the decoder window of up to 128 MiB, and about 1.1 GiB of address space (a header that records more is refused before any allocation, a frame that only records its size as corrupt); crafted journal.off entries that agree with each other, deeper than the two links recovery and readers check, pass as valid, so a read that starts past them numbers its frames by them until verify walks the file and reports them (recovery checks every listed frame before it cuts or lists anything, so no committed frame is lost); the generations a crafted index records (meta/idx/gen.col) are checked only against their parents' where a history walk uses them, so a run of them crafted to agree can still have a land's merge base or log --path answer wrongly, though every changeset they reach is on the first-parent chain the changeset objects name, and verify reports the damage; and a derived value file crafted with a value its derivation does not give, whole and with its trailer right, is refused by a reader only where the reader's checks against the index and the objects tell (a skip list's first entry, length and each jump against the list one level down; a last touch's changeset against the path), and is otherwise read as valid until verify --deep, which checks every value of the built-in derivations against the objects, reports it (removing meta/derived/ has every value derived again). A derived value's zstd frame is decoded whole within the object bound, 512 MiB. FORMAT, REPO (an id and a name of at most 255 bytes), journal.ckpt and the ref files are capped at their sizes, and a store file that is not a regular file is refused before it is opened.

  • Requests. Change lists, revisions and paths that get past their checks: a repository path with a .. component, a leading / or a NUL byte; a request that makes SwarmOps write outside the store; one that corrupts the store; or one that makes it allocate without bound. A request's size is checked before it is read: its text (a --changes file or stdin, or one line of swarmops mcp's input) holds at most 64 MiB. A commit's contents hold at most 1 GiB together and a put's content at most 512 MiB, both measured by the sizes they declare (a client file's length) before a byte of them is read, and again as each content is converted, in list order, for a file that grows meanwhile. One case is known and tracked (docs/known-limitations.md, "A request takes the memory its type holds"): a request type's own fields are built in full before the operation checks them, so a long list of short strings or a map of small entries takes up to about 15 times its text, near 1 GiB for a line at the 64 MiB cap.

  • Test hooks in a release build. The SWARMOPS_TEST_* variables make a process crash or fail at a chosen filesystem call, count its calls, pin its clock, hold the writer lock while it waits for other writers' requests, print another version for its own, or count as a release's build for update. A build without the test-hooks feature, as cargo build --release is, must ignore them; one that honours them is a vulnerability.

  • The git import (M3). Importing a git repository brings in content and paths that an attacker controls. Path traversal and symlink attacks through crafted repositories are a known class in this field: jj's critical GHSA-88h5-6w7m-5w56, "Path traversal via crafted Git repositories", and gitoxide's GHSA-6p9q-f2xg-6pr5, a symlink planted during a forced checkout that sends writes outside the worktree, and GHSA-x862-c2wj-4mwr, an allocation sized by a pack header's object count that aborts the process. An import that writes outside the store, follows a symlink out of a workspace, or exhausts memory on a crafted repository is a vulnerability.

  • The workspaces (M5). swarmops ws writes a changeset's files into a directory on the caller's host, and the Claude Code hook runs the repository's bootstrap command there, as a build would. A write outside the workspace's directory, a write through a symlink, or an update that overwrites an edit the agent made is a vulnerability.

  • The git export (M8). swarmops git export writes git objects and one branch into a git repository at a path that the request names, on the caller's host, so the export is a trust boundary. A request that makes SwarmOps write outside that repository, move a branch other than the one it names, or write through a name that git does not take as a branch is a vulnerability.

  • The git remotes (M13): credentials and the child's environment. No store holds a credential: remotes.toml holds a token's variable name (token_env), never its value, and a URL with a password in it is refused. The variable's token reaches git only through the child's environment, as an HTTP header keyed by the remote's URL, never as an argument or in a file, and is removed, with its base64 forms, from whatever git prints before it enters an error. git keeps that header for its whole run, and would add it to what it sends an address the remote redirected its first request to; a call that carries a token, a variable's or a login's, therefore follows no redirect (http.followRedirects=false) and fails at one. The child runs without a shell, its arguments after --end-of-options, with GIT_TERMINAL_PROMPT=0, GIT_ALLOW_PROTOCOL set to the remote URL's scheme alone (file://, ext:: and local paths are refused as remotes), an empty hooks directory, and the variables that point git at another repository or trace its traffic removed; the user's credential helpers, ssh agent, GIT_SSH_COMMAND and proxy variables pass through, as they do for the user's own git fetch. A token or credential that reaches a file under the store, an argument, an envelope or an error; a git child that runs a hook or a command a remote or a fetched repository chose; or a mirror write outside git/mirror.git, is a vulnerability. What the remote sends is imported as the git import above takes any repository. A SwarmOps- trailer line in a remote commit is trusted as proof that the remote holds a change (the known limitations' "A trailer line is taken as proof"): anyone who can push to the remote is trusted with its content.

  • The login file (auth login). swarmops auth login keeps one token per host in one file of the user's, outside every store: the file SWARMOPS_AUTH_FILE names, else swarmops/auth.toml in the user's state directory. The token is there in plain text, by design and with no keyring: the file is made with mode 0600 in a directory made with mode 0700, and any process that runs as the same user can read it. The token is read from stdin, never from an argument, or granted by the provider's device flow (below); a usage error of auth login quotes nothing of its line but its flags' names, and the refusal of a --scope that is no scope states the rule without the value, so that a token typed as an argument is not repeated in the envelope. A login file that is a symbolic link, or that its group or others can read or write, is refused, and so is a file that is not the one its path named when the path was looked at without following a link (a link put there before the open is not read through). A read never changes a file's mode; a login or a logout replaces the file with one of mode 0600. clone, fetch, push, sync and remote add send the token to a remote over https (or over http to a loopback address) that names no token variable and whose host and port are the login's, exactly; it reaches git as a variable's token does, and is removed the same way from what git prints. One command prints the token: auth git-credential get, the credential helper a user's own git runs, on its stdout alone and only for a request whose protocol, host and port are the login's by the same rule. A token that reaches any other file, an argument, an envelope, an error, stderr, what auth status prints or the stdout of any other command; a token sent to a remote at another host or port, a redirect's target among them, or to one that names a variable; a helper's answer to a request for another host or port; a login file made with a wider mode; or a login file read through a link, is a vulnerability. No store, remote or request can name the login file: only the user's environment does.

  • The device flow (auth login --gh without --with-token). SwarmOps asks GitHub for a device code and then for the token by running the user's curl (SWARMOPS_CURL, else the first on PATH), which is trusted as the user's git is. The child runs without a shell, with the arguments -q --config - alone, the whole request on its stdin, and a cleared environment but for PATH, the proxy variables and the certificate variables. It speaks https only, with TLS 1.2 or later, and follows no redirect. The two addresses are constants at github.com: no flag, variable, store, remote or answer changes them. The client ID, a public value, comes from SWARMOPS_GH_CLIENT_ID. What GitHub answers is checked before it is used: the code and the page shown on stderr can hold no control character, the page is at github.com over https, and an answer with a refresh token is refused. A way for a store, a remote or an answer to send these requests elsewhere; a device code or a token in an argument, an envelope, an error or on stderr; or an answer that reaches the terminal unchecked, is a vulnerability. A proxy the user's environment names, and the certificates it trusts, are the user's.

  • The program's own update (update, and automatic update). so update replaces swarmops and so with the latest release, and an install the installer made does the same unasked, after a command, for a release that is marked for its minor line. This makes the releases page a supply chain at run time: whoever can publish a release of this repository, and upload a mark to it, changes the program on every install that updates itself within a day of its use.

    • What is trusted. HTTPS to github.com, with the certificates the user's curl trusts, and the release's own SHA256SUMS, which comes from the same place as the archive: it shows a damaged or a wrong download, not a release that was replaced at GitHub. No signature is checked, as none is by the installer; the releases carry none (RELEASE.md). The programs run are the user's, trusted as the user's git is: curl (SWARMOPS_CURL, else the first on PATH) for the two requests of the program's own, and for the download /bin/sh with the installer's tools from PATH (curl or wget, tar, sha256sum or shasum, awk and the like). Whoever can write the directory the binaries are in could replace them already; the receipt, the lock and the note beside them give that party nothing more.
    • What is constant. The addresses: https://github.com/KeiaiLab/SwarmOps/releases/latest, and …/releases/download/v<version>/ for the mark and the archive. No flag, variable, store, remote, workspace file, MCP request or answer changes them, and no MCP tool runs an update. The two requests of the program's own are HEAD requests that follow no redirect, over https with TLS 1.2 or later, with a cleared environment but for PATH, the proxy variables and the certificate variables, the header User-Agent: swarmops-update and no token. The installer follows GitHub's redirects to where the files are, as it does when a person runs it, and gets PATH, HOME, TMPDIR, the proxy variables and the certificate variables alone.
    • What is checked. The answer for the latest release must be a redirect to exactly https://github.com/KeiaiLab/SwarmOps/releases/tag/v<X.Y.Z>, three plain numbers. Only a release strictly newer than what is installed is taken, so an older release cannot be put back. The archive is checked against its line in SHA256SUMS, unpacked beside the binaries, and each new binary is run once and must print the release's version before either replaces anything. Unasked, a release is installed only where it holds the mark for the installed minor line; it is announced otherwise.
    • What GitHub learns. The caller's address, this repository's path, the header above and, in the mark's address, the minor line installed (auto-update-from-0.12); from the installer's download, the release and the target, with its downloader's own headers. Nothing goes to a host of the project's own, and nothing is sent that names a store, a user or a login.
    • What is not prevented. A freeze: someone who can answer for GitHub, or keep the request from arriving, can show an install no newer release, and without signed metadata that carries a date the install cannot tell. It then stays as it is, and says nothing. A release published by whoever holds the repository's release permission is installed as the maintainers' own.
    • The switch. so update --auto off (the receipt beside the binaries), the variable SWARMOPS_AUTO_UPDATE=off, and the installer's --no-auto-update or a named --version turn automatic update off; CI, a container, root and a directory of another user's do too. Only the user's environment, the receipt and the installer set it: no store, remote, workspace file or MCP request reads or changes it. A build from a clone and a package's install never update themselves.

    An update from another address or to an older or equal version; an install of a download whose checksum does not match or whose binaries were not run first; a write outside the directory of the binaries and the installer's temporary directory; a check or an install that a store, a remote, a workspace file or an MCP request started, moved or turned on; one that runs after mcp, serve, auth git-credential or ws hook, or that changes what a command prints on stdout or its exit code; a token or a login sent with these requests; or a line of GitHub's answer that reaches the terminal unchecked, is a vulnerability.

  • The SwarmOps supply chain. A dependency or a CI workflow that could change what we build or run. cargo deny check (advisories, licenses, bans, sources) runs over every lockfile the project builds: the workspace's and the fuzz crate's in every just check, and bench/compare's, which just check does not build, wherever it is built (just bench-compare and the weekly scheduled run). The lockfiles are committed and builds use --locked, and the GitHub Actions workflows pin every action by commit, start from permissions: {}, keep no credentials after checkout and are checked with zizmor. A known advisory in a dependency that is already public can go to a normal issue. What a published release then does to the installs that update themselves is the bullet above.

What is not a vulnerability under M1's model

  • One agent acting as another. In M1 an identity (--as, SWARMOPS_AGENT) is a claim that is recorded, not verified: every envelope's meta.auth says "trust". Tokens arrive later. swarmops serve (M14) is the exception: its caller is named by the operator's ssh key line or web server, not claimed, and the store's access.toml decides what that caller may do (E_AUTH, E_POLICY_DENIED).
  • Anything a local user with write access to the store can do directly: delete, rewrite or corrupt its files, hold its lock, fill its disk. Filesystem permissions are the boundary. SwarmOps detecting such damage is in scope (swarmops verify --deep re-hashes every object and checks the derived values against them); preventing it is not.
  • Reading files the caller can read. A change list's {"file": "<path>"} content is read on the client, with the caller's own permissions, as any program the caller runs could read it, and land --resolve reads its {"file"} content on the client the same way; the stdio MCP server runs as its caller and reads it the same way. A server that takes requests from another host, M11's swarmops serve --stdio over ssh first, must refuse such content, and will (operations spec §7).
  • Anything a local user with write access to the binaries' directory can do directly: replace swarmops and so, or write the receipt that turns automatic update on. The directory's permissions are the boundary, as a store's are.
  • Durability failures. Data lost after a crash, a power loss or a disk error is a serious bug, not a vulnerability: report it as an issue. docs/architecture.md describes the durability model and its tests.
  • Builds with the test-hooks feature, which exist for the test suite only.

swarmops serve (M14) takes git's requests from another host, behind the operator's ssh or web server: what a caller may do is the store's access.toml, and no text it sends a client names a host path, except the git lines docs/known-limitations.md lists. A flaw that lets a caller act past its grants, or read a host path, is a vulnerability. When M11's server takes SwarmOps requests from another host, the trust model changes again, and this policy with it.

There aren't any published security advisories