If you have found a security vulnerability, please do not open a GitHub issue: an issue is public from the moment it is filed, and so is the window between filing it and a fix being released.
Report it privately instead, by opening a security advisory. Only the maintainers can see it, the discussion stays private until an advisory is published, and a CVE can be requested from it if the vulnerability warrants one.
If you have no GitHub account, or would rather not use it for this, responsible disclosure by email to security at btclib dot org is equally welcome.
A report is acknowledged within 7 days, and a fix or a published advisory follows within 90 days.
A report triaged as easy to rediscover is fixed as soon as possible, since anyone can find it in the meantime, and its advisory is published with the fix.
This is a whole node: src/btclib_node/interpreter.py validates a block
against consensus rules itself, src/btclib_node/chainstate/ carries the
block index and the UTXO set those rules are checked against, and
src/btclib_node/p2p/ and src/btclib_node/rpc/ are what an untrusted
peer and a local caller each reach this process through. A defect in any
of those — a block this node accepts that Bitcoin Core would reject or
the reverse, a p2p message that can wedge a connection or exhaust memory
before its own length is even read, a UTXO index a reorg leaves
inconsistent, an RPC handler that trusts a parameter it should bound — is
this repository's to fix.
What belongs to btclib is the primitives and the wire serialization this node calls rather than reimplements: elliptic-curve arithmetic, script and transaction parsing, the message and address encodings. Report it wherever you found it, though: routing a report is the maintainers' job, not the reporter's, and a doubt about which project owns a flaw is not a reason to keep it to yourself.
The latest security review is dated 2026-09-30. pmazzocchi did it against the assurance case, and issue 1559 records it.
The review's scope is the tree at commit 02b2ed6effd2, and release v2026.9.24
where its RPC code differs.
What changed since
is that commit's comparison with main.
Only the latest release is supported: a fix is published as a new release, and nothing is backported.
Wheels and sdist are published to PyPI with PEP 740 attestations, through a workflow that no long-lived token can authenticate for (PyPI Trusted Publishing), so a distribution can be traced back to the workflow run and the commit it was built from.
The same files are attached to the GitHub release, and those copies carry a build provenance attestation of their own, signed in the run that built them:
signer=btclib-org/.github/.github/workflows/reusable-build.yml
id=$(gh api repos/btclib-org/btclib-node --jq .id)
cert='.[].verificationResult.signature.certificate'gh attestation verify <file> --owner btclib-org \
--signer-workflow "${signer:?}" \
--source-ref refs/tags/v<version> --format json \
--jq "${cert:?}.sourceRepositoryIdentifier" | grep -qx "${id:?}"<file> is a distribution file from the release. The exit code is 0
only where a verified attestation names this repository. The repository
is compared by its id, which a rename keeps: --repo compares the
current name and refuses every release signed before a rename.
--signer-workflow names the workflow that signed, and narrows what
passes: under --owner the command passes without it. For a release
built by the organization's reusable-build.yml, which release.yml
calls, that is that workflow: an attestation made inside a called
workflow names the callee as its signer, while the certificate still
names this repository as the source. --source-ref is what keeps a
build of a branch from passing as the release. A release from v2026.9.24
on, made before this repository called reusable-build.yml, was signed
by reusable-attest.yml, named the same way. Through v2026.9.4 the
signer is release.yml itself, so for those releases signer is
btclib-org/btclib-node/.github/workflows/release.yml. All three take
--source-ref refs/tags/v<version>.
No path verifies a release another signed. The signed statement is attached to the
release as well, as <tag>.intoto.jsonl, or as <tag>.attestation.jsonl on a
release that carries that name instead, so --bundle <that file> runs the
same check reading it from disk instead of asking GitHub for it; one
attestation covers the wheel, the sdist and the bill of materials.
This node speaks BIP324's v2 transport to its peers and refuses v1 unless
started with -v1transport=1 (btclib-org#1190). Bitcoin Core
accepts v1, and falls back to it for a peer that does not offer v2.
v1 is plaintext. An observer on the path reads every message. v1's checksum is not a key: a party on the path can rewrite a message and recompute it, and the peer cannot tell. v2 encrypts and authenticates every packet, so reading the traffic takes an active attacker in the middle of the handshake, and a changed packet ends the connection.
BIP324 has a v2 node accept inbound v1 "to minimize risk of network
partitions", and retry with v1 a dial that a false NODE_P2P_V2 in addr
relay sent to a v1-only peer. Core does both. This node does neither,
and the cost is peers:
- an automatic outbound connection, a feeler included, goes only to an
address advertising
NODE_P2P_V2or carrying exactlySEEDS_SERVICE_FLAGS, as every seed does. It chooses from fewer candidates, which makes it easier to surround with peers of one party, and a v1-only seed, or a v1-only peer falsely advertised asNODE_P2P_V2, is dialled and lost; - an inbound v1 peer, a light client among them, is dropped on the first
16 bytes of its
versionmessage, so those peers have fewer nodes to reach; - an
-addnode,-connector-seednodepeer that speaks v1 alone is never reached: it is dialled with v2, drops the connection, and is not retried with v1.addnodeandaddconnectionwithv2transportfalse are refused.
-v1transport=1 restores Bitcoin Core's behaviour. -v2transport=0
turns v1 on by itself, and -v2transport=0 -v1transport=0 is refused at
start.
This node does not make a wallets directory (btclib-org#1523).
Bitcoin Core's InitConfig makes <datadir>/wallets and
<datadir>/<chain>/wallets with each data directory it creates, at
bitcoin/bitcoin@9be056a8a7 (v31.1), so that a wallet enabled later does not
mix with the other files. This node has no wallet. A data directory it made
is opened by Core with its wallets in the top-level directory, since Core
uses wallets only where it exists.
The scantxoutset refusal "Cannot derive script without private keys" does
not quote the descriptor, which may hold a private key. A config line that
fails to parse, and a command-line argument refused as an invalid parameter,
are quoted as ASSURANCE_CASE.md's CWE-209 entry says. So are the key of an
unknown configuration value, which is also given its file and line, and a
section name, in the unrecognized-section warning and in the log of the
configuration, and a settings.json name, in the unknown-name warning, in
the duplicate-key refusal and in the log of the settings. A settings.json
that is not an object is refused by its value's type. Bitcoin Core quotes
each of these whole, at bitcoin/bitcoin@db0bde16b9: the descriptor at
rpc/util.cpp:1370, the line in GetConfigOptions
(src/common/config.cpp), the argument in ParseParameters
(src/common/args.cpp:234), the key in ReadConfigStream
(src/common/config.cpp:110), the section in AppInitParameterInteraction
(src/init.cpp:992) and logArgsPrefix (src/common/args.cpp:988), the
settings.json name in ReadSettingsFile's warning
(src/common/args.cpp:479), in ReadSettings's refusal
(src/common/settings.cpp:110) and in LogArgs
(src/common/args.cpp:1007), and the value that is not an object in
ReadSettings (src/common/settings.cpp:101). A refusal reaches stderr,
logs and the RPC caller.
Core does not read rawpkh(), rawnode() or rawleaf(). At top level
and in tr(), its scantxoutset refusal of one quotes the expression
whole, a private key in it included (ParseScript in
src/script/descriptor.cpp, at bitcoin/bitcoin@f0de87f040, the v32.1
tag). This node's refusal quotes none of its arguments, as in
'rawnode(...)' is not a valid descriptor function.
Core's log of the settings also writes each settings.json value in clear,
a SENSITIVE option's included (ArgsManager::LogArgs,
src/common/args.cpp, at bitcoin/bitcoin@9be056a8a7). This node masks some
of them, as ASSURANCE_CASE.md's CWE-209 entry says.
What a refusal may print about a secret is the organization's rule, section 7's A refusal carries no secret in btclib-org/.github's README.md.
-reindex-chainstate wipes the undo data with the coins
(btclib-org#1415). Bitcoin Core keeps it:
BlockManager::WriteBlockUndo writes no undo data for a block that has
some (src/node/blockstorage.cpp, at bitcoin/bitcoin@9be056a8a7, v31.1).
This node writes it again as it connects each block, and wipes it because
BlockDB.add_rev_block skips a block that already has a patch, so without
the wipe a corrupt record would survive the rebuild. A stop between the
chainstate wipe and the undo wipe keeps the old patches until a start with
the option wipes them.
The log escapes C1 controls, U+0080 to U+009F, as \x and two hex digits,
beside the C0 controls and DEL that Bitcoin Core escapes too
(btclib-org#1952). Core's BCLog::LogEscapeMessage escapes bytes
below 0x20 and 0x7f (src/logging.cpp, at bitcoin/bitcoin@aa76bd266d). A C1
control's UTF-8 is 0xc2 and a byte from 0x80 to 0x9f, so Core writes it as it
is, and a terminal that decodes UTF-8 and honours C1 controls acts on it in a
log it shows, as it would on an ESC. The cost is a log line that differs from
Core's where a message holds such a character.
Where the reader of a named pipe goes during dumptxoutset, this node answers
AutoFile::write's failure (btclib-org#2187). Bitcoin Core
answers that where a write fails, and Error closing's message where the
bytes left fit its FILE buffer and only the close fails
(src/rpc/blockchain.cpp, at bitcoin/bitcoin@f0de87f040, v32.1). The two
cases split on a buffer size in Core's C library, so no client can rely on
which text it gets. The failure and its RPC code, RPC_MISC_ERROR, are the
same. The cost is a message that differs from Core's where the reader goes
near the end of a dump.
The assurance case is the threat model these are written against, and the argument for what this file does promise.
Known and recorded, rather than something to report again.
- Every caller the JSON-RPC listener accepts may call every method
-rpcwhitelistleaves it, over plain HTTP. It accepts Core's cookie,-rpcauthand-rpcuser/-rpcpasswordusers (btclib-org#1055, btclib-org#1070), and with no-rpcwhitelist, Core's default too, whoever holds one of those credentials can callstopandsendrawtransaction. The credential crosses the wire as HTTP Basic, unencrypted: the listener has no TLS, as Core's has none. Core dropped-rpcsslto remove OpenSSL from the daemon, and says its RPC "does not use encryption" and "has not been hardened to withstand arbitrary Internet traffic". The listener binds loopback by default (btclib-org#27), and-rpcbindbinds elsewhere only beside-rpcallowip, which then decides which sources are answered at all, as in Core. Reach it from another machine only through a tunnel (SSH, stunnel or a VPN), and never expose it to the Internet. - BIP324 does not authenticate the peer. A party in the middle of the
handshake reads and relays everything; comparing
getpeerinfo'ssession_idwith the peer's operator over another channel is what detects it. Nor does v2 hide the timing and sizes of the packets. Development Status :: 3 - Alphais the claimpyproject.tomlmakes, and it is the right one to read the limitations above against: this node has downloaded and validated the chain, which is not the same as having been run against somebody trying to make it do otherwise.