From 4e02e72e026e4c43166be0c9eac51d823e76bff6 Mon Sep 17 00:00:00 2001 From: Ben Westgate Date: Mon, 21 Sep 2026 03:41:08 -0500 Subject: [PATCH 1/2] docs: Define supported threat model Describe only the trust boundaries introduced by the CipherStick installer and handoff guidance, then distinguish them from risks that remain the responsibility of Tails, Bitcoin Core, hardware, and the operator.\n\nFixes #212. --- README.md | 2 ++ docs/THREAT_MODEL.md | 17 +++++++++++++++++ 2 files changed, 19 insertions(+) create mode 100644 docs/THREAT_MODEL.md diff --git a/README.md b/README.md index 95631a7b..ee3d3961 100644 --- a/README.md +++ b/README.md @@ -92,6 +92,8 @@ For a discussion on the pros and cons of using CipherStick, refer to the [detail On this branch, CipherStick installs and configures Bitcoin Core, guides Persistent Storage setup, provides passphrase practice, and installs the pinned `python-codex32` application for codex32 backup and recovery. Clone/Backup actions and the removed legacy `bails-wallet` implementation are not supported recovery interfaces. +See the [CipherStick threat model](docs/THREAT_MODEL.md) for the installer-specific trust boundaries and non-goals. + ## Source Code Headers Every file containing source code must include copyright and license diff --git a/docs/THREAT_MODEL.md b/docs/THREAT_MODEL.md new file mode 100644 index 00000000..dea98bfd --- /dev/null +++ b/docs/THREAT_MODEL.md @@ -0,0 +1,17 @@ +# CipherStick Threat Model + +CipherStick's supported runtime is a Tails installer for Bitcoin Core, Persistent Storage setup guidance, passphrase practice, and the pinned `python-codex32` application for codex32 backup and recovery. CipherStick itself does not manage wallet keys or make wallet-security decisions; `python-codex32` and Bitcoin Core do. + +## Boundaries CipherStick owns + +- **Installer delivery:** downloaded CipherStick code can modify Persistent Storage. Releases and updates must identify and authenticate the exact code before it runs. +- **Bitcoin Core installation:** CipherStick chooses download locations, accepted signers, and release metadata. Its verification must reject an artifact, signer set, or metadata value that does not meet the local policy. +- **Persistent Storage changes:** CipherStick writes software and configuration beneath the unlocked persistence mount. It must use intended paths and permissions and must not silently copy wallet, recovery, log, or identifying data. +- **Pinned codex32 checkout:** CipherStick fetches an exact `python-codex32` revision and repairs a checkout whose files differ from it. This check catches corruption and accidental changes. It does not protect against an attacker who can already write Persistent Storage, since that attacker can also change CipherStick's own scripts. +- **Handoff guidance:** a recipient should start with their own Tails installation and Persistent Storage. Any transferred data must be selected explicitly by the person performing the handoff. + +## Assumptions and non-goals + +CipherStick relies on Tails for operating-system isolation, encryption, and Tor routing, and on Bitcoin Core for consensus validation and wallet behavior. It does not claim to protect against compromised hardware or firmware, an attacker controlling an unlocked Tails session, loss of required secrets, coercion, transaction-graph analysis, malicious counterparties, or all traffic correlation. + +The installer can reduce the risk introduced by its own automation; it cannot remove risks inherited from Tails, Bitcoin Core, the user's hardware, or the user's operational choices. Planned features are outside this threat model until they are implemented, tested, and reviewed. From c8b005a88644bcbe903ac3ee5e13ec72f8287647 Mon Sep 17 00:00:00 2001 From: Ben Westgate Date: Tue, 6 Oct 2026 04:03:40 -0500 Subject: [PATCH 2/2] docs: Note unsigned delivery gap --- docs/THREAT_MODEL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/THREAT_MODEL.md b/docs/THREAT_MODEL.md index dea98bfd..7f89ff35 100644 --- a/docs/THREAT_MODEL.md +++ b/docs/THREAT_MODEL.md @@ -4,7 +4,7 @@ CipherStick's supported runtime is a Tails installer for Bitcoin Core, Persisten ## Boundaries CipherStick owns -- **Installer delivery:** downloaded CipherStick code can modify Persistent Storage. Releases and updates must identify and authenticate the exact code before it runs. +- **Installer delivery:** downloaded CipherStick code can modify Persistent Storage. Releases and updates must identify and authenticate the exact code before it runs. Current repository clones do not yet satisfy this boundary; signed-release work is tracked by #206. - **Bitcoin Core installation:** CipherStick chooses download locations, accepted signers, and release metadata. Its verification must reject an artifact, signer set, or metadata value that does not meet the local policy. - **Persistent Storage changes:** CipherStick writes software and configuration beneath the unlocked persistence mount. It must use intended paths and permissions and must not silently copy wallet, recovery, log, or identifying data. - **Pinned codex32 checkout:** CipherStick fetches an exact `python-codex32` revision and repairs a checkout whose files differ from it. This check catches corruption and accidental changes. It does not protect against an attacker who can already write Persistent Storage, since that attacker can also change CipherStick's own scripts.