diff --git a/.oss-scanner/README.md b/.oss-scanner/README.md new file mode 100644 index 000000000..64fd90ed0 --- /dev/null +++ b/.oss-scanner/README.md @@ -0,0 +1,97 @@ +# Bitcoin Keeper — OSS Scanner enrolment preparation + +Status: prepared for review, not submitted to Anthropic and not enrolled. +Checked on 9 October 2026. Contact: anant@bithyve.com. + +## Initial scope + +Enrol the public mobile repository, `KeeperCommunity/bitcoin-keeper`, following +`sprint`. Do not enrol private repositories, upload environment files or include +production credentials. Review the scanned revision against the shipped release: +`sprint` is an integration branch, not a statement that every change is released. + +The first environment should build the Android app and run shared TypeScript / +JavaScript tests offline. iOS source remains available for inspection, but a Linux +image does not establish iOS runtime or hardware-signing coverage. Confirm this +scope with Anthropic before treating the environment as sufficient. + +## What is prepared + +- `project.yaml.example`: the public registration fields and approved contact. + This is deliberately an example, not an active registration. It names a + Dockerfile that must be implemented and validated before submission. +- `threat_model.md`: proposed audit boundaries and report expectations, subject to + maintainer review against the actual enrolled source. +- This dependency and build-integration handoff. No app or release behavior changes. + +## The narrow dependency + +Reuse the Linux toolchain and diagnostic build work in +[PR #7043](https://github.com/KeeperCommunity/bitcoin-keeper/pull/7043), rather than +maintaining a second Android toolchain. The reviewed implementation must be on the +branch selected for scanning before the registry configuration points to it. + +At `cc15f593b62689267168a2405b318876c91947e0`, +`reproducibility/android-diagnostic-in-container.sh` reads +`release/version.json`, but that path is absent at that revision. Resolve that +source/manifest mismatch within the build workstream. Also complete the full +image build: the PR records a successful base-toolchain stage, not a completed +SDK/app build on that head. + +The existing Dockerfile installs a toolchain; it is not by itself the scanner's +project build. Add a small adapter around the reviewed build recipe that: + +1. Copies the scanner-provided checkout to `/src`, as Anthropic requires. Accommodate + the current build helper's `/workspace/keeper` path without losing `/src`. +2. Installs all source, package, Gradle and native dependencies and builds the app + during the network-enabled Docker build. Verify that source checks, including + any `.git` requirement, work in Anthropic's actual build context. +3. Uses only the existing synthetic service values and public debug signing key. + Keeps the corresponding synthetic configuration and dependency caches available + for subsequent offline rebuilding. Never call hosted services during tests. +4. Preserves the built APK/AAB, native sources, shared tests and toolchain inside + the image. Does not publish or install the diagnostic app on a user's device. +5. Rebuilds and runs the documented tests in a container with `--network=none`. + A Gradle `--offline` flag alone is not proof that other processes stay offline. + +Do not submit the example configuration as though this adapter already exists. +Do not replace the missing release manifest with guessed values to get a green build. + +## Submission gates + +- [ ] Resolve the source/manifest mismatch and select the reviewed source branch. +- [ ] Add and review `.oss-scanner/Dockerfile`, reusing the build recipe. +- [ ] Validate the full Docker build and actual network-disabled test run; record + the source commit, commands, results and known coverage limits. +- [ ] Review the proposed threat model and mobile/Linux scope with a maintainer. +- [ ] Copy `project.yaml.example` to `projects/bitcoin-keeper/project.yaml` in a fork + of `anthropics/oss-scanner`; set `disabled: false` only when ready. +- [ ] Run Anthropic's `tools/validate.py` and `tools/check bitcoin-keeper` against + the exact submitted configuration and inspect the resulting offline image. +- [ ] Open the upstream enrolment PR as a core maintainer and complete its checklist. +- [ ] Anant personally completes any required contributor-agreement signature. +- [ ] Verify upstream acceptance before describing Keeper as enrolled. + +A Keeper preparation PR, a question sent by email, or a passing schema check is +not an application accepted by the scanner. + +## Work that should not hold this up + +The final WalletScrutiny / source-to-distributed-binary reproducibility result is +not a scanner prerequisite. Only the usable, tested audit build is needed. + +The full R4 release and the separate Recoverable Wallet preview in +[PR #7041](https://github.com/KeeperCommunity/bitcoin-keeper/pull/7041) need not be +finished. If source alignment with the release-baseline work is needed for the +build, track that exact change rather than making all of R4 a prerequisite. +Do not merge unrelated work or bypass review gates to complete this enrolment. + +Claude for Open Source is a separate, individual maintainer application. It can +be submitted now and has no dependency on any of these product milestones. + +## References + +- https://red.anthropic.com/oss-scanner/ +- https://github.com/anthropics/oss-scanner/blob/main/README.md +- https://github.com/anthropics/oss-scanner/blob/main/CONTRIBUTING.md +- https://github.com/KeeperCommunity/bitcoin-keeper/blob/sprint/SECURITY.md diff --git a/.oss-scanner/project.yaml.example b/.oss-scanner/project.yaml.example new file mode 100644 index 000000000..d0aac8cf6 --- /dev/null +++ b/.oss-scanner/project.yaml.example @@ -0,0 +1,8 @@ +# Preparation only. Do not submit until the named Dockerfile exists and its +# complete build and offline tests have passed on the selected source branch. +repo: https://github.com/KeeperCommunity/bitcoin-keeper#sprint +primary_contact: anant@bithyve.com +homepage: https://bitcoinkeeper.app +disabled: true +dockerfile: .oss-scanner/Dockerfile +threat_model: .oss-scanner/threat_model.md diff --git a/.oss-scanner/threat_model.md b/.oss-scanner/threat_model.md new file mode 100644 index 000000000..e311e57e5 --- /dev/null +++ b/.oss-scanner/threat_model.md @@ -0,0 +1,122 @@ +# Bitcoin Keeper — proposed OSS Scanner threat model + +This is audit guidance for maintainer review, not a certification, a new product +promise, or evidence that the build or tests have passed. Read `SECURITY.md` and +assess the actual checked-out revision. Record its commit in every report. + +## Project and scope + +Bitcoin Keeper is an open-source, self-custodial bitcoin wallet for Android and +iOS. It coordinates single-key and multi-key Wallets and external signing devices. +A defect in transaction construction, signing or recovery can cause irreversible +loss; wallet metadata can also be sensitive without granting spending authority. + +Start with the enrolled mobile repository and its reachable dependencies. Review +native Android/iOS sources as well as shared TypeScript/JavaScript. A Linux build +can exercise Android and shared logic; do not describe iOS, physical signers, +biometrics, cloud delivery or production backends as tested unless separately +reproduced. Public backend source, if needed later, requires an explicit scope +extension and its own supported test environment. Do not retrieve private source. + +Unmerged previews and proposed removals are not deployed features. Code on the +enrolled revision remains relevant even when a proposal would replace it. In +particular, do not exclude USDT or other financial paths solely because a later +release proposes to pause or remove them. + +## Security properties to assess + +- Preserve Wallet identity, network, signer identity and configured policy across + import, registration, signing, migration, archive and recovery. A fingerprint + or device label alone must not substitute for validating the required key and + policy information. +- An authorized spend must preserve the intended recipients, amounts, fee and + change. Treat PSBT fields, derivation metadata and change labels as inputs to + validate, not independent evidence of ownership. Multisig does not by itself + prevent several signers from authorizing the same malicious transaction. +- Keep the Recovery Key, private keys, passcodes and signing material confidential. + The Recovery Key is the user's sensitive 12-word primary backup; it is distinct + from Wallet Configuration Files and external signing-device backups. Do not + assume that an app passcode replaces the Recovery Key. +- Enforce the configured threshold and any applicable Server Key authorization, + delay, spending limit and cancellation rules. The Server Key alone is not + intended to grant authority to spend a multi-key Wallet. Separate client-side + observations from claims about backend enforcement that was not tested. +- Treat account/profile isolation, authenticated backup content, rollback and + revision handling, consent and truthful backup status as security-relevant. + Encryption at rest alone is not evidence that tampering, substitution or stale + data are rejected. Wallet Configuration Files are not intended to contain + private keys; public metadata can still expose a user's privacy. +- Preserve access to existing funds and the information needed to recover them + across key/scheme changes, app upgrades, Archived Wallets and partial failures. + Distinguish data loss or a false verified-backup claim from harmless UI errors. + +## Untrusted inputs and trust boundaries + +Examine QR and animated-QR payloads, NFC, deep links, imported files, descriptors, +Wallet Configuration Files, PSBTs, hardware-wallet messages, externally supplied +keys and policies, Electrum/Relay/SigningServer responses, notifications and +backup records. Include malformed, oversized, duplicated, replayed, reordered, +cross-account and wrong-network data where the real entry point accepts them. + +Trace data through parsing, validation, confirmation, persistence and signing; +identify the actual caller and the authority it has. Check native/JavaScript +bridges, local storage, logs, clipboard and sensitive-screen exposure. Review +reachable dependency behavior and build/release trust boundaries, but do not +claim a vulnerable package automatically means an exploitable Keeper flaw. + +## Attacker assumptions + +Prefer realistic models: a malicious link or file sender, remote cosigner, +untrusted service response, network adversary, or attacker with a specifically +stated level of device access. State authentication, user interaction and signer +cooperation prerequisites. Do not silently grant an attacker the user's complete +Recovery Key, a fully compromised OS, or enough authorized signing keys and then +report the resulting access as a new application vulnerability. + +A stronger assumed compromise may still reveal a useful broken boundary. Report +which extra authority or secret is obtained beyond that initial compromise. + +## Proposed triage priorities + +These are impact-based starting points, not automatic severity assignments. + +- Critical: demonstrate unauthorized spending or recoverable spending-key theft + under realistic prerequisites, or a similarly severe release-integrity breach. +- High: demonstrate a material authorization/policy bypass, substantial secret + exposure, cross-account backup compromise, or a recovery defect with a credible + path to loss. Explain any missing step toward an actual spend or loss. +- Medium: demonstrated privacy exposure, bounded persistent denial of service, or + misleading security state without a demonstrated direct-loss path. +- Low/informational: hardening opportunities or limited-impact behavior. A crash, + old dependency version, naming inconsistency or debug fixture alone is not a + high-severity finding. Elevate only with evidence of the relevant impact. + +Separate demonstrated behavior from hypotheses. Do not suppress a finding merely +because current documentation calls a related behavior intentional; identify the +specific security property that could be violated. + +## Proofs of concept and patches + +Use synthetic accounts, fresh disposable test keys and local fixtures only. No +mainnet transaction, real wallet, real Recovery Key, production token, personal +record or hosted-service test is authorized by this enrolment. Test fully offline +where possible. Do not send reports or test payloads to other users. + +Reports should include the affected commit, platform and entry point, attacker +prerequisites, expected versus observed behavior, a minimal local reproducer, +impact and uncertainty, and a focused regression test where possible. Identify +missing native/hardware/backend coverage. Group duplicate symptoms sharing one +root cause and preserve distinct exploitable paths when their fixes differ. + +Propose small, reviewable patches. Never weaken verification, suppress failing +tests, silently change wallet derivation or require regeneration of existing +keys simply to make a test pass. Key/policy changes need explicit compatibility +and recovery analysis. Maintainers must reproduce and review every proposed fix. + +## Reporting + +Send scanner reports privately to `anant@bithyve.com`. Do not post suspected +vulnerabilities, sensitive traces or proofs of concept in public issues or PRs. +The project's general reporting channel remains GitHub Private Vulnerability +Reporting, as described in `SECURITY.md`. No automatic public disclosure or +production remediation is authorized by this preparation.