Assurance case¶
SECURITY states what a user can and cannot expect of this client in terms of security. This page argues why those expectations hold: the threat model, the trust boundaries, how secure design principles are applied, and how common implementation weaknesses are countered. Each argument below names the file, the test or the workflow that supports it; where SECURITY.md already states a fact, this page points at it instead of repeating it. The components named here are the ones ARCHITECTURE describes.
What is claimed¶
A reply is read the way the node sent it. JSON-RPC 1.1 and 2.0 are each read by the function that knows that version’s own rule for where an error can be, and a reply is trusted as this call’s answer only once its
idmatches what was sent.Malformed input from the caller is refused before anything is built or sent. A url, a credential, a timeout, a body limit and a parameter structure are each checked at the call that supplies them, raising
BtcRpcTypeErrororBtcRpcValueError.What a node sends is bounded. A reply larger than the caller’s
max_body_size, or slower than itstimeout, is refused rather than held in memory whole or waited out indefinitely.A credential never appears where it can leak. Not in a url, not in a
__repr__, not in an exception raised about a rejected one, not sent to a host a redirect or an environment variable named instead of the one the caller built the client for.A published distribution is what this tree built. SECURITY.md’s Supported versions states how that is verified.
Threat model¶
This is a library in its caller’s process. It opens no file the caller
did not name a path for, but for the cookie file at a path the caller
supplied or from_chain derived, and it starts no process. Every input
it has is one the caller handed it directly, or bytes a node — or
whatever answered instead of one — sent back over the connection this
client opened. The command below lists the top-level name of every
module src/ imports, at any depth and in any spelling of the
statement:
python3 - <<'EOF'
import ast, pathlib
names = set()
for p in pathlib.Path("src").rglob("*.py"):
for n in ast.walk(ast.parse(p.read_text(encoding="utf-8"))):
if isinstance(n, ast.Import):
names.update(a.name.split(".")[0] for a in n.names)
elif isinstance(n, ast.ImportFrom) and n.level == 0:
names.add(n.module.split(".")[0])
print(sorted(names))
EOF
What it lists, beside the package’s own modules, is entirely the
standard library: pyproject.toml declares no dependency, which
tests/census_test.py holds by reading the same imports with ast.
What is defended.
The credential: what it is built from, where it is read from, and every place it could end up instead of on the one request it authenticates.
The caller’s process: against a reply built to make a parser raise an exception this library does not document, or allocate without bound.
The correctness of what a reply is read as: that a
resultis attributed to the call that asked for it, and that a status the node never computed is never read as one of its errors.
The adversaries.
The node this client is pointed at, or anything answering in its place: a proxy, a captive portal, a host a redirect or an environment variable named instead of the one the caller configured.
The caller’s own configuration: a cookie path or a datadir carried over from a different host, a chain name assumed rather than checked.
A party between the caller and a node reached over anything but loopback, for whom Basic authentication over plain HTTP is cleartext on the wire — SECURITY.md’s Limitations, not vulnerabilities states this and what mitigates it.
What is not defended is SECURITY.md’s Limitations, not vulnerabilities section, in full.
Trust boundaries¶
The caller and the public API. Every constructor and every call
validates its own arguments before anything is built from them: a url’s
scheme, its embedded credentials, its query, its port and any
whitespace or control character in it (_checked_url), none of whose
refusals repeats the url; a credential’s type and the colon it must not
contain; a timeout that is a positive, finite number of seconds
(_assert_valid_timeout); header names that are tokens and values free
of CR, LF, NUL and any character latin-1 cannot encode
(_assert_valid_headers); a body limit that is a non-negative integer
(_assert_valid_max_body_size); and a parameter structure walked for
what json cannot carry — a non-finite number, bytes, a container
reached from inside itself, one nested past a stated depth — before the
encoder ever sees it (_assert_json_params). Each is checked
while the caller is still looking at the line that supplied it, not
deferred to the first call.
The node’s reply. _parsed_json_body decodes it through one parser,
json.loads with every floating-point token a Decimal, every integer
token an int, every non-finite constant refused and every number whose
exponent is past sys.get_int_max_str_digits refused (unless that
limit is 0), never eval and
never a decoder that executes anything the reply carries.
_reply_object refuses a body that is not a json object, _id_error
refuses one whose id does not match the request just sent,
and _discriminate refuses a jsonrpc marker that is neither absent
nor "2.0". None of it is trusted as an answer until every one of those
holds. str() of an RpcError writes the non-printable characters of the
node’s message as escapes, so a reply cannot forge a log line or drive a
terminal. A reply is also read as arbitrary bytes by fuzz/fuzz_reply.py
under ClusterFuzzLite (.github/workflows/fuzz.yml) and, mutated at every
position, by tests/fuzz_test.py, which asserts that only FetchError
comes out; tests/fuzz_corpus_test.py checks that every seed of the corpus
is still read.
The network path. Only http and https reach a built request
(_SCHEMES); no proxy is taken from the environment, ProxyHandler({})
being how the one opener this module does its I/O with has that handler
removed rather than merely left empty; and no redirect is followed
(_NoRedirect). The Authorization header is built for one host, and
each of the three is what keeps it from reaching a different one.
The cookie file. Read fresh at every call rather than held —
bitcoind rewrites it at every restart — through chains.cookie_auth:
opened without blocking and refused unless a regular file, read to one
octet past a bound, decoded as ascii, and refused as a FetchError
naming the path for anything that is not one line with a colon in it. A
file that is simply absent is CookieNotFoundError, which says the node
is not running rather than that something is wrong with the file.
The credential in memory. BitcoinCoreRpcClient defines no
__repr__: a generated one prints every field, which would put the
password in any traceback or log line that renders the client. A
rejected user or password is reported by its type, never echoed by
value, and the same holds for a url carrying embedded credentials —
refused without repeating the url that carried them.
The environment. chains.default_datadir reads HOME or APPDATA,
once at import for the module-level DEFAULT_DATADIR, and again at
every from_chain call that derives a cookie path because the caller
supplied neither a credential nor a cookie_path of its own. Nothing
else in the package reads an environment variable itself. The TLS
context is built by _tls_context and not by
ssl.create_default_context, which would open the file SSLKEYLOGFILE
names and write the session keys to it; the system trust store it loads is
OpenSSL’s, which SSL_CERT_FILE and SSL_CERT_DIR choose, and
SECURITY.md lists that as a limitation.
Secure design principles¶
Saltzer and Schroeder’s principles, against the layering ARCHITECTURE describes.
Economy of mechanism. One
HttpTransportprotocol bothurlopen_transportandSessionTransportsatisfy; one_checked_urlserving both clients through itskindargument rather than a second copy of the same checks; one_read_boundedevery transport built here reads a reply through.Fail-safe defaults. A caller giving neither a credential nor a cookie path is refused rather than answered with a client that sends an empty
Authorization;DEFAULT_MAX_BODY_SIZEbounds a reply even where the caller passes nothing; a caller giving both a credential and a cookie path is refused rather than one silently ranked over the other.Complete mediation. Trust boundaries above is this principle applied at every entry point a caller or a node reaches: nothing downstream of the checks it lists is handed an argument that has not passed them.
Open design. Every refusal in the source names what it refused and why, in the comment beside it; SECURITY.md publishes what this client defends and what it does not, rather than leaving either to be inferred.
Least privilege. Threat model above is the census: nothing but the standard library. No proxy is read from the environment and no redirect is followed, and
BitcoinCoreRestClienttakes no credential at all,-restneeding none.Psychological acceptability. One call is one HTTP request and never a silent retry, so a caller is never surprised by a wallet command re-executed on their behalf;
HttpError.statusandRpcError.codeare typed fields a caller reads, rather than a message a caller’s policy has to parse.Layering.
errors < chains < transport < client, one direction, held bytests/census_test.py.
Common implementation weaknesses¶
Weaknesses from MITRE’s CWE list that a network client of this kind is exposed to, and what counters each.
Improper input validation (CWE-20). Trust boundaries’s first paragraph, and the suite’s own coverage floor under Code that is wrong and still passes below, which holds every one of those refusals reached:
tests/client_test.py,tests/chains_test.pyandtests/transport_test.pyare where the client’s, the chain vocabulary’s and the transport’s own are judged.Insufficiently protected credentials (CWE-522) and cleartext transmission (CWE-319). What SECURITY.md’s Limitations, not vulnerabilities states about Basic authentication over plain HTTP is the transmission this client does not change, Core’s rpc speaking nothing else; what this client does hold is where the credential can end up beside the wire, which Trust boundaries’s credential paragraphs above state in full.
Generation of an error message containing sensitive information (CWE-209). The same paragraphs: a rejected credential is reported by type, and no
__repr__renders one that was accepted. A refused rpc parameter is named by type and position, and an unreadable reply or cookie file is refused without chaining the error that holds it. A chain or network name of at most_MAX_NAME_SHOWNcharacters (chains.py) is echoed as passed, on purpose, so that a typo stays visible: a passphrase that short, passed aschain, lands in the message (GHSA-cg87-q4qx-qw8p). A refusal’s path, which locates the refused value, shows the name of each mapping it goes through only where the name has at most_MAX_KEY_SHOWNcharacters (client.py), and...for a longer one. An encode error holds the text it failed on, so one that a credential, a wallet name or a cookie path can raise is refused without being chained. The rule is README section 7’s A refusal carries no secret in btclib-org/.github.tests/secret_free_refusals_test.pyfeeds a secret to each of these refusals and passes the exception toassert_secret_free. It covers a rejected credential, a refused url, rpc parameter, header, timeout or limit, rest path, wallet name, chain or network name and signet challenge, an unreadable reply, an unreadable cookie file and a refusal’s path. It does not cover the node’s own text:RpcError’s message, which issue 644 keeps as Core wrote it, and theid, thejsonrpcmarker and theerrorobject that a refusal repeats from a reply. A refusal also shows the rpc method as passed, which the request sends to the node anyway, the path of a cookie file, which an operator has to find, the chain a node reports when it is not the one the client was built for, and a refused number the caller passed.URL redirection to an untrusted site (CWE-601) and exposure of a resource to the wrong sphere (CWE-668). A credential built for one host reaching a different one through a followed redirect or an environment-derived proxy is what
_NoRedirectandProxyHandler({})refuse, under The network path above.Use of insufficiently random values (CWE-330). Every request
idissecrets.token_hex, never a counter: a counter is shared mutable state, which would be the one thing making a client unsafe to call from two threads at once, and a value predictable across calls is weaker at the one thing anidis for here — telling this call’s reply from a caching proxy’s answer to another one.Uncontrolled resource consumption (CWE-400, CWE-770).
_read_bounded’s bound on what one reply may weigh, checked before a byte past it is read, and its deadline, checked before each chunk rather than reset by one — under The transport layer in ARCHITECTURE.md.Deserialization of untrusted data (CWE-502).
_parsed_json_bodyis the only place a reply’s bytes become Python objects, throughjson.loadsalone: nopickle, nomarshal, noeval, and a customparse_floatandparse_constantrefuse whatjsonwould otherwise hand back as an unusable amount.Type confusion (CWE-843). mypy runs
strict = true(pyproject.toml) over the package and the suite, as a hook of the lint gate in.pre-commit-config.yaml.Code that is wrong and still passes. Line and branch coverage of the package and of the suite is held at 100% by
fail_underinpyproject.toml.Supply chain. SECURITY.md’s Supported versions describes the attestations and the bill of materials this package publishes.
uv.lockpins every dependency of the development environment, and every workflow command run in that environment passes--locked. Resolved outside it are the build backend ofuv build, the--no-projectanduvxhelpers, the install smoke tests, the pre-commit hook environments, anddeps-latest.ymlanddeps-oldest.yml, which re-lock on purpose. Every third-party GitHub Action is pinned to a commit sha;actionlintandzizmorrun as hooks in.pre-commit-config.yaml. What a live node’s own binary is checked against before this client is asked to talk to it is ARCHITECTURE.md’s What proves it, and what a live node adds.