docs: clarify RPC credentials security boundary
What the developer wrote
Authored by crStiv
docs: clarify RPC credentials security boundary
What changed, and why it matters
This commit only updates documentation. It adds a warning to Bitcoin Core's JSON-RPC guide explaining that anyone with valid RPC credentials effectively has significant control over the node and the underlying machine, and that RPC whitelists should not be treated as a strong security boundary. No code behavior was changed.
No code-level action is required. Operators should review the updated guidance and ensure RPC access is limited to trusted parties, with system-level isolation used where appropriate. This commit itself does not fix or introduce a vulnerability.
Security signals we found
Documentation-only change
Warns that RPC credentials grant significant node and filesystem control
Warns that -rpcwhitelist is not a robust security boundary
Recommends system-level isolation for security-sensitive deployments
Evidence from the diff
The diff adds a new ‘RPC Credentials Security Boundary’ section to doc/JSON-RPC-interface.md. It documents that RPC commands can load wallets from arbitrary filesystem paths, specify file paths, and potentially allow broader access than intended. It recommends system-level isolation (containers, virtualization, separate restricted users) instead of relying solely on -rpcwhitelist/-rpcwhitelistdefault. There are no code changes.
Changed components
doc/JSON-RPC-interface.mdInspect captured patch +16 / −0
diff --git a/doc/JSON-RPC-interface.md b/doc/JSON-RPC-interface.md
index e7f085a3..a9ea089d 100644
--- a/doc/JSON-RPC-interface.md
+++ b/doc/JSON-RPC-interface.md
@@ -124,6 +124,22 @@ RPC interface will be abused.
security-sensitive operations on a computer whose other programs you
trust.
+- **RPC Credentials Security Boundary:** Any client with valid RPC credentials
+ should be treated as having significant control over both the Bitcoin Core node
+ and the filesystem resources accessible by the `bitcoind` process. RPC commands
+ can load wallet files from paths that the `bitcoind` process has permission to
+ access, specify file paths for operations, and potentially gain broader access
+ than intended. This means that someone with RPC access can potentially compromise
+ not only the Bitcoin Core node, but also the machine it is running on. Bitcoin Core
+ provides the `-rpcwhitelist` option to restrict which RPC commands specific users
+ can access, and `-rpcwhitelistdefault` to control the default behavior for users
+ without explicit whitelists. However, when using multiple wallets or sharing access
+ with different users, these should not be considered robust security boundaries, as
+ users with access to certain commands may still be able to exploit functionality in
+ unexpected ways. For security-sensitive operations, implement proper system-level
+ isolation (containers, virtualization, separate user accounts with restricted
+ permissions) rather than relying solely on RPC access controls.
+
- **Securing remote network access:** You may optionally allow other
computers to remotely control Bitcoin Core by setting the `rpcallowip`
and `rpcbind` configuration parameters. These settings are only meant
Why this scored 12/100
Community notes
Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.
The AI analysis stands alone for now. Submit a note if you can add evidence or important context.