Basis CLI

Only the latest release is supported, and there is a documented upgrade path that is a single command: re-running ./download.sh fetches and verifies the newest version this repository knows about, because the version is resolved from checksums/ by version sort rather than pinned. SECURITY.md states the support policy and why — this tracks a development network that may be reset without notice, so pinning an old client to a chain that no longer exists helps nobody — and the roadmap repeats it as a deliberate non-goal rather than an omission. The upgrade is not difficult: there is no state to migrate, no configuration file, and no installed footprint beyond the binary itself. The CHANGELOG records what changed between versions and what it means.

GitHub Issues. https://github.com/basis-network/basis-cli/issues

No vulnerabilities have been reported or resolved in this repository in the last 12 months — the repository has existed since August 2026 and has had no vulnerability reports at all, so there is nobody to credit yet. The policy for when there is one is already written rather than improvised at the time: SECURITY.md states that reporters are credited in the release notes unless they ask not to be, and the documented handling process ends with the advisory published, the CHANGELOG saying what changed and why, and the reporter credited. https://github.com/basis-network/basis-cli/blob/main/SECURITY.md#reporting-a-vulnerability

SECURITY.md documents the process end to end in six steps: acknowledge the reporter and open a GitHub private security advisory (so an emailed report ends up in the same place, visible to the reporter); triage — reproduce, and decide whether it falls inside this repository's security boundary or belongs to basis-core or the network, forwarding it and saying where it went if it does not; record severity, scope and affected versions in the advisory; fix on a branch with a regression test where the defect is testable from here, reviewed before merge; release, with checksums committed before publication and assets verified and signed by the release workflow; disclose, with the advisory published, the CHANGELOG explaining the change and the reporter credited, timing agreed with them. A report that turns out not to be a vulnerability gets told why rather than left waiting. Committed timelines: acknowledgement within 3 working days, first assessment within 10, a fix or a stated plan within 90 days. https://github.com/basis-network/basis-cli/blob/main/SECURITY.md#how-a-report-is-handled

The primary language is bash, and CONTRIBUTING.md names the Google Shell Style Guide as the standard contributions follow, with two deliberate differences stated rather than left to be discovered: comments explain why and not what, and indentation is two spaces to match the existing scripts. It also states the conventions for the other file types here — YAML workflows two-space indented with every action pinned to a commit SHA, Markdown wrapped at 80 columns — and requires that a silenced lint rule carries a # shellcheck disable= directive at the line it applies to with a reason, never file-wide. https://github.com/basis-network/basis-cli/blob/main/CONTRIBUTING.md#coding-style

shellcheck is the FLOSS tool for this language and it runs in CI on every push and every pull request, over download.sh, test/run.sh and test/coverage.sh. It is a required status check on the protected main branch, so a violation blocks the merge rather than producing a warning somebody may or may not read; the same command is available locally as make lint. Exceptions are allowed but must be per-line # shellcheck disable= directives with a reason at the point they apply, so they are reviewable and can be handled automatically later. There are currently none: the tree is clean with no suppressions at all.

No native binaries are generated by this project. There is no compiler and no linker involved anywhere in this repository: the software it produces is bash read by an interpreter as it is, and the Makefile has no build target — only check, coverage and lint. The compiled basis binary is built elsewhere, from basis-core, which is outside this entry's declared scope. There are therefore no CC, CFLAGS, CXX, CXXFLAGS or LDFLAGS for anything here to honour or override.

There is no build or installation system that could strip anything. Nothing is compiled, so no debugging information is generated in the first place, and download.sh copies bytes and verifies a digest rather than installing with install -s or anything like it. The script it produces is its own source and is fully readable at run time.

There is no build system to be recursive. The Makefile is flat, has no build target, no subdirectory makefiles and no cross-directory dependencies: each target is a single command that runs a script in place. Nothing is compiled, so there is no dependency graph that could be got wrong.

No building occurs. This is a scripting-language project: download.sh and test/run.sh are used directly by the interpreter, not compiled into anything, so there is no generated artefact whose bit-for-bit reproduction could be compared. Reproducibility of the compiled binary is a property of basis-core, outside this entry's scope, and is listed as a known gap in the assurance case rather than claimed here.

Installation is ./download.sh, which is the commonly-used convention for this kind of tool — a single verified-download script, the same pattern as rustup or the many curl | sh installers, except that this one refuses to proceed if it cannot verify what it fetched. The README documents it as the first thing after the description, along with the by-hand curl plus sha256sum -c equivalent for readers who want to do it themselves. Uninstallation is equally simple and is a real answer rather than a dodge: everything the script produces lives under bin/<platform>/ inside the clone, nothing is written outside it, no system directory is touched, no service is registered and no configuration file is created anywhere. Deleting the directory removes the tool completely.

There is no installation system that writes outside its own directory, so there is no standard convention to honour. download.sh writes only to bin/<platform>/ relative to the script's own location; it installs nothing into a system prefix, so DESTDIR and PREFIX have nothing to select. Where the binary goes afterwards is the user's choice, made with mv or by adding that directory to PATH.

Clone the repository and run make check. That is the whole development environment: the suite needs nothing that download.sh itself does not need — bash, curl and a SHA-256 tool, all present on a stock Linux or macOS — and it touches no network, because each case fabricates a throwaway release in a temporary directory and reaches it over file://. There is nothing to install, no language runtime to provision, no container to build and no fixture to download. make lint adds shellcheck and reuse, and make coverage adds bashcov (gem install bashcov); both are documented in CONTRIBUTING.md and neither is needed to make and test a change.

This repository ships no code dependencies — no package manifest, no vendored code, nothing from a language registry — and the two classes of external dependency it does have are both listed in a computer-processable way. The GitHub Actions the workflows call are declared in the workflow YAML with every action pinned to a commit SHA and the version in a trailing comment, which is the convention for that ecosystem and is what Dependabot reads; .github/dependabot.yml declares the github-actions ecosystem so those declarations are watched weekly. The run-time dependencies are the operating system's own bash, curl and sha256sum or shasum, which is why there is no manifest to add them to; the README and CONTRIBUTING.md both state them, and the script itself checks for the SHA-256 tool at run time and exits if it is missing. https://github.com/basis-network/basis-cli/blob/main/.github/dependabot.yml

Dependabot runs weekly over the github-actions ecosystem and opens a pull request when a pinned action moves, which is the whole point of the configuration: pinning to a commit SHA makes an action safe but not current, and without something watching, a pin quietly rots. Six such updates have already been merged. Those pull requests run the same required CI as any other change, so an update cannot land broken. GitHub's own vulnerability alerting is enabled on the repository, CodeQL analyses the workflows on every push and weekly, and OpenSSF Scorecard publishes a Vulnerabilities check result publicly on every push. There are no other external components: no language-registry dependencies and no convenience copies of anything.

Everything reused is the standard component provided by the system. The script uses the operating system's bash, curl and sha256sum or shasum, all updated by the system package manager, and there are no convenience copies, no vendored libraries and no forked standard components anywhere in the tree — so a security update to any of them takes effect immediately, with nothing here holding an old copy alive. The only other reused components are the GitHub Actions, which are pinned by commit SHA and therefore trivially identifiable, and Dependabot updates them weekly.

Nothing deprecated or obsolete is used. The script's entire external surface is POSIX-standard utilities and current curl options, with no shell builtin or flag that has been deprecated; shellcheck runs in CI specifically to catch constructs that are obsolete or fragile, and the tree is clean with no suppressions. The CI side is kept current by Dependabot: all GitHub Actions are on their current major versions, and when a whole family had to move together — every codeql-action reference from v3 to v4 — it was done in a single change rather than left half-migrated.

.github/workflows/test.yml runs the full suite on every push to main and every pull request targeting it, via make check. It reports success or failure as a GitHub status check — download.sh test suite — which is required on the protected branch, so a failing suite blocks the merge rather than being noticed later. The suite is nine cases and 28 assertions covering the whole download-and-verify path end to end, including the two failure paths that justify the repository. A second job in the same workflow measures statement coverage and fails below 90%.

No bugs have been fixed in this repository in the last six months, so there is no denominator: the repository was made public in August 2026, has had no bug reports against download.sh and no defect fixes to add regression tests for. The policy for when there is one is already in place rather than to be decided later — CONTRIBUTING.md requires that a change to what download.sh does comes with a test, the review checklist makes a behaviour change without a test a blocking comment, and SECURITY.md's handling process specifies a regression test as part of fixing a reported vulnerability. Two of the nine existing cases are failure paths written for exactly this purpose.

Measured, not estimated: 98.1% statement coverage of download.sh, 52 of 53 statements. make coverage runs the suite under bashcov, the FLOSS coverage tool for bash, and CI runs it as its own job on every push and every pull request, failing the job below a hard floor of 90% — so a regression shows up as a red check on the pull request that caused it. Getting an honest figure needed two things that are documented in test/coverage.sh: the suite deletes each sandbox when its case ends, taking the traced copy of the script with it, so BASIS_TEST_KEEP keeps them; and SimpleCov silently drops any path with a dot-prefixed component, which yields a confident 0% with no error. Each case traces its own copy of the same bytes, so the copies are summed per line. One line is reported uncovered and is not — the done carrying the loop's redirection, which bash attributes to the while — and it is left in the report rather than special-cased, because a coverage tool taught to lie about one line stops being evidence about the others.

CONTRIBUTING.md states it as a rule, not a suggestion: "A change to what download.sh does comes with a test." It goes on to say why, which is what makes it stick — the script exists to refuse a download that does not match the committed checksum, and a refusal that stops working is silent. The same document requires make check to pass and asks contributors to say in the pull request which case covers their change, and the review checklist makes a behaviour change with no covering test a blocking comment. SECURITY.md applies the same rule to vulnerability fixes.

It is written down in CONTRIBUTING.md, in the section a contributor reads before opening a pull request, and repeated as a checklist item in the pull request template. https://github.com/basis-network/basis-cli/blob/main/CONTRIBUTING.md#tests

shellcheck runs at its default severity, which is the lowest one and therefore reports everything from style upwards, over every script in the repository, with no exclusions and no suppressions. Its optional --enable=all checks were reviewed and not adopted: they are formatting preferences (brace every variable reference, prefer [[ ]] to [ ]) rather than defect detection, and adopting them would mean rewriting working code to a house style it does not use.

docs/ASSURANCE-CASE.md works through Saltzer and Schroeder principle by principle with the concrete application in each row. The ones that carry the design: fail-safe defaults — every path denies by default, and no checksum file, no hash tool or a digest mismatch each end in a non-zero exit with the binary never made executable; separation of privilege — subverting a download requires control of both the release and the git history, two mechanisms with different failure modes and different audiences; economy of mechanism — about 110 lines of bash, no dependency manifest, no configuration file and no persistent state, so the whole verification argument fits on a page; complete mediation — every name in the checksum file is verified, not just the first, which the multi-entry test case guards; least privilege — workflows are read-all by default and elevated per job only where genuinely needed. Where principles conflict the choice is stated rather than hidden.

No SHA-1 and no CBC-mode SSH: the only hash is SHA-256 and the only transport is TLS as curl negotiates it. (git names its own objects with SHA-1, which is a property of the version control system rather than of anything this project produces or verifies with — the integrity guarantee this repository makes rests on the SHA-256 in checksums/, not on a commit id.)

The verification format is the standard sha256sum/shasum -c file, which is not tied to a single implementation and already runs through two interchangeable back ends selected at run time: sha256sum where it exists and shasum -a 256 where it does not, which is what macOS ships. The digest algorithm lives in the checksum files under checksums/<tag>/<platform>.sha256 rather than being compiled into logic, so moving to another algorithm is a new file set and a matching shasum -a selection, not a redesign. SHA-256 is a current SHA-2 algorithm with no known weakness relevant here, and there is no cipher suite or key exchange in this project to negotiate: the signatures on release assets are Sigstore's, whose algorithm agility is that project's.

This project never processes authentication credentials or private cryptographic keys. download.sh authenticates to nothing, sends no credential, reads no keystore, prompts for no passphrase, and stores nothing — it fetches a public release asset over HTTPS and hashes it. Release signing is Sigstore keyless: the identity is the release workflow's short-lived OIDC token and there is no private key in the repository, in CI, or anywhere for a person to hold. SECURITY.md states plainly that nothing here, download.sh included, touches key material of any kind.

All network communication is HTTPS. download.sh fetches from https://github.com/<repo>/releases/download by default, and curl verifies the certificate chain by default with no flag anywhere in this project disabling it — there is no --insecure, no -k and no GIT_SSL_NO_VERIFY-style escape hatch. The base URL can be overridden by BASIS_CLI_BASE_URL, which exists so the test suite can point at a local directory over file:// without touching the network; that is an explicit action by the user, which is exactly the condition the criterion allows. Nothing insecure is enabled by default and no plaintext protocol is used at all.

TLS is used through the system's curl and its TLS library, so the project supports whatever they do, which on any currently supported platform is TLS 1.2 and 1.3. The script pins no version, disables nothing and offers no option to downgrade, so a system hardened to 1.2-or-better stays that way. GitHub, the only host contacted by default, requires TLS 1.2 as a minimum on its side.

Certificate verification is on, by default, and cannot be turned off from here. download.sh invokes curl -fSL --retry 3 --retry-delay 2, and curl verifies the certificate chain and hostname by default; this project passes no --insecure, no -k, no --cacert override and sets no environment variable that would weaken it. There are no subresources: one request per asset named in the checksum file, all to the same host. A failed verification makes curl exit non-zero, and with set -euo pipefail the script stops there. Worth noting that the integrity guarantee does not rest on this anyway: even a fully broken TLS connection cannot produce a binary matching a digest committed to git.

The software sends no private information over TLS at all — no HTTP headers carrying credentials, no cookies, no tokens, no authentication of any kind. download.sh issues unauthenticated GET requests for public release assets; there is nothing private that could be sent before or after verification. The CLI's inability to send an Authorization header is documented in the README as one of its known limitations. Certificate verification is nonetheless on by default for every request, as answered in crypto_certificate_verification.

Every release asset is cryptographically signed with Sigstore cosign in keyless mode by .github/workflows/release.yml, which fires on release: published — deliberately not on a tag push — so what is signed is exactly what people download rather than a rebuild that resembles it. Before signing, the workflow verifies every published asset against the checksums committed to git, so a mismatch fails loudly instead of being signed. The private key requirement is met in the strongest available form: there is no private key at all. The signing identity is the workflow's short-lived OIDC token and the certificate is recorded in the public Rekor transparency log, so nothing persistent exists on the distribution site or anywhere else to be stolen. SECURITY.md documents verification with a complete cosign verify-blob command including the certificate identity and OIDC issuer to pin against, and the README links to it. Independently of the signatures, every release also has its SHA-256 committed to this repository before publication. https://github.com/basis-network/basis-cli/blob/main/SECURITY.md#signatures

Every input from a potentially untrusted source is checked against an allowlist before it is used, and rejected if it does not match. The platform argument is not interpolated into a URL on trust: it must correspond to an existing checksums/<version>/<platform>.sha256 file, and anything else exits 1 listing the versions and platforms that do exist — a test case covers exactly that. The version is resolved from the directories that exist in checksums/, so it cannot name something arbitrary. The checksum file is the input that matters most, and CI validates its format with an allowlist on both fields: each digest must be exactly 64 lowercase hex characters, and each file name must be basis or basis.exe — nothing else parses, which is also what stops a ../ name reaching the download loop. The downloaded bytes themselves are the untrusted input the whole project exists to check, and they are verified against the committed digest before anything is made executable. Every shell expansion is quoted, enforced by shellcheck in CI.

The hardening available to a shell script is applied. set -euo pipefail is the first executable line: an unset variable, a failing command or a failing pipeline stage aborts rather than continuing with a wrong value — the failure mode that turns a shell defect into a security problem. Every expansion is quoted and shellcheck enforces it in CI as a required check. The script asks for no privilege and writes only under its own bin/ directory, touching no system location. On the CI side, which is the part of this project with credentials: permissions: read-all at workflow level with elevation per job only where genuinely needed, persist-credentials: false on every checkout, and every action pinned to a commit SHA rather than a mutable tag. The project sites are GitHub, which serves Content-Security-Policy, HSTS, X-Content-Type-Options and X-Frame-Options.

docs/ASSURANCE-CASE.md contains all four required parts. Threat model: six adversaries described by capability rather than identity — network attacker, release attacker, repository attacker, compromised CI, hostile user environment, and the tooling supply chain — each with the mechanism that counters it, the test case or workflow that evidences it, and the residual risk that remains. Trust boundaries: four regions, with the one security-relevant crossing identified as untrusted bytes entering a machine checked against a digest that came the other way. Secure design: Saltzer and Schroeder row by row with the concrete application of each. Implementation weaknesses: CWE-494, 347, 829, 78, 22 and 367 answered individually, with the inapplicable half of the OWASP list named as inapplicable rather than silently skipped. It also states the claim it does not make — nothing about the compiled binary's behaviour — and ends with the known gaps, including that single-maintainer review is the dominant residual risk. https://github.com/basis-network/basis-cli/blob/main/docs/ASSURANCE-CASE.md

CodeQL's Actions query pack is written for exactly the vulnerabilities of this environment — expression injection, excessive GITHUB_TOKEN permissions, artifact poisoning, unpinned actions. OpenSSF Scorecard also runs against the repository weekly and on every push to main. https://scorecard.dev/viewer/?uri=github.com/basis-network/basis-cli

Nothing in this repository is written in a memory-unsafe language. It is shell, YAML and Markdown. (The CLI it distributes is Rust, and is outside the scope of this entry.)