Skip to content

Commit ca2a708

Browse files
committed
feat(express): add default domain-scoped CA trust for BitGo connections
Restrict outbound HTTPS connections to official BitGo domains (*.bitgo.com, *.bitgo-test.com, *.bitgo-staging.com, *.bitgo-dev.com, and their apex domains) to a bundled multi-provider root CA store (Google Trust Services, Amazon Trust Services, DigiCert, Let's Encrypt/ISRG, and Sectigo) while keeping the system trust store for all non-BitGo destinations: - sdk-api: add createBitGoTlsPolicy({ ca, hosts }) and enforce it in BitGoAPI.getAgentRequest (refusing redirects and plain http on covered hosts) - express: enable the bundled 18-root CA policy by default at startup, with a single opt-out flag (--disablepincerts / BITGO_DISABLE_PIN_CERTS) and automatic proxy fallback when BITGO_USE_PROXY is set - scripts/verify-bitgo-policy-data.sh: CI check verifying all bundled roots are self-signed, valid (>30d), and cover all BitGo domains (plus --live handshake verification) TICKET: WCN-3731
1 parent e29ac14 commit ca2a708

19 files changed

Lines changed: 1716 additions & 8 deletions

‎modules/express/.env.example‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,3 +37,4 @@ BITGO_EXTERNAL_SIGNER_WALLET_IDS=
3737

3838
# Examples
3939
# BITGO_EXTERNAL_SIGNER_WALLET_IDS="{"tbtc":[{"walletId":"xxx","walletPassword":"xxx","secret":"xxx"}],"hteth":["walletId":"xxx","walletPassword":"xxx"]}"
40+
BITGO_DISABLE_PIN_CERTS=

‎modules/express/README.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -198,6 +198,26 @@ BitGo Express currently supports the following proxy protocols:
198198
- SOCKSv5
199199
- PAC
200200

201+
### Domain-scoped CA trust for BitGo connections
202+
203+
By default, BitGo Express restricts outbound HTTPS connections to official BitGo domains (`*.bitgo.com`, `*.bitgo-test.com`, `*.bitgo-staging.com`, `*.bitgo-dev.com`, and their apex domains) to a bundled set of root certificate authorities (`modules/express/bitgo-ca.pem`: Google Trust Services, Amazon Trust Services, DigiCert, Let's Encrypt/ISRG, and Sectigo). Every other outbound destination (external signer, block explorers, webhooks, KMS) continues to use the Node.js / system trust store.
204+
205+
This is **enabled by default** to shrink the blast radius of a compromise of any unrelated CA in the global trust store without requiring manual certificate-pin maintenance across routine BitGo certificate renewals or CA migrations.
206+
207+
- To opt out, pass `--disablepincerts` or set `BITGO_DISABLE_PIN_CERTS=true`.
208+
- When `BITGO_USE_PROXY` is set, Express logs a startup warning and skips the bundled CA policy because the proxy agent owns the TLS connection.
209+
- If your network uses a **transparent TLS-inspecting firewall/proxy** (no `BITGO_USE_PROXY`) whose CA you trust via `NODE_EXTRA_CA_CERTS`: note that the policy agent replaces the trust store for BitGo domains, so `NODE_EXTRA_CA_CERTS` is **ignored** for them. Express logs a startup warning in this case; either pass `--disablepincerts` / `BITGO_DISABLE_PIN_CERTS=true`, or the connections fail with `unable to get local issuer certificate` / `SELF_SIGNED_CERT_IN_CHAIN`. This is a behavior change from prior releases (BitGo domains previously trusted `NODE_EXTRA_CA_CERTS`).
210+
- Redirects are validated on each hop for covered BitGo hostnames: redirects to other covered `https://` BitGo hosts are followed, while redirects to uncovered hosts or plain `http://` are refused.
211+
- At startup, Express warns if any root CA in `bitgo-ca.pem` expires within 30 days.
212+
- The bundle is **not** self-updating. Regenerate it from the current Node.js root store (e.g. when BitGo switches CA providers or a root nears expiry) and re-verify against live endpoints:
213+
```bash
214+
bash scripts/verify-bitgo-policy-data.sh --regenerate # rebuilds modules/express/bitgo-ca.pem
215+
cd modules/express && yarn test:data:live # offline checks + live handshakes to all BitGo endpoints
216+
```
217+
If BitGo ever moves `*.bitgo.com` to a CA provider outside the bundled roots, update `bitgo-ca.pem` **before** the cutover (deployed customers run older images).
218+
219+
> The underlying policy helper (`createBitGoTlsPolicy` in `@bitgo/sdk-api`) is Node-only: it relies on the Node `crypto` and `tls` modules and refuses to build in a browser bundle.
220+
201221
### External Signing Mode
202222

203223
BitGo Express can be run in an external signing mode, where the signing of transactions is performed in a separate instance of BitGo Express that has access to the private keys.
@@ -241,6 +261,7 @@ BitGo Express is able to take configuration options from either command line arg
241261
| N/A | --lightningSignerFileSystemPath | `BITGO_LIGHTNING_SIGNER_FILE_SYSTEM_PATH` | N/A | Local path specifying how to contact the lightning signer node. |
242262
| N/A | --keepalivetimeout | `BITGO_KEEP_ALIVE_TIMEOUT` | N/A | BitGo Express server KeepAliveTimeout node. |
243263
| N/A | --headerstimeout | `BITGO_HEADERS_TIMEOUT` | N/A | BitGo Express server HeadersTimeout node. |
264+
| N/A | --disablepincerts | `BITGO_DISABLE_PIN_CERTS` | false | Disable the default domain-scoped CA bundle restriction for BitGo hostnames. See [Domain-scoped CA trust for BitGo connections](#domain-scoped-ca-trust-for-bitgo-connections). |
244265

245266
\[0]: BitGo will also check the additional environment variables for some options for backwards compatibility, but these environment variables should be considered deprecated:
246267

0 commit comments

Comments
 (0)