docs(config): add network exposure considerations (#10856)
this adds Security section in effort to clarify how each port should be evaluated from the security perspective
Marcin Rataj committed
Jul 11, 2025 at 18:33 UTC
b4e6769a567da2008f44c024a37f03ba2c6ec6eb
1 file changed
+44
docs/config.md
+44
@@ -235,6 +235,9 @@ config file at runtime.
235
- [`legacy-cid-v0` profile](#legacy-cid-v0-profile)
236
- [`test-cid-v1` profile](#test-cid-v1-profile)
237
- [`test-cid-v1-wide` profile](#test-cid-v1-wide-profile)
238
+ - [Security](#security)
239
+ - [Port and Network Exposure](#port-and-network-exposure)
240
+ - [Security Best Practices](#security-best-practices)
241
- [Types](#types)
242
- [`flag`](#flag)
243
- [`priority`](#priority)
@@ -271,6 +274,7 @@ Supported Transports:
274
>
275
> - If you need secure access to a subset of RPC, secure it with [`API.Authorizations`](#apiauthorizations) or custom auth middleware running in front of the localhost-only RPC port defined here.
276
> - If you are looking for an interface designed for browsers and public internet, use [`Addresses.Gateway`](#addressesgateway) port instead.
277
+> - See [Security section](#security) for network exposure considerations.
278
279
Default: `/ip4/127.0.0.1/tcp/5001`
280
@@ -286,6 +290,16 @@ Supported Transports:
290
* tcp/ip{4,6} - `/ipN/.../tcp/...`
291
* unix - `/unix/path/to/socket`
292
293
+> [!CAUTION]
294
+> **SECURITY CONSIDERATIONS FOR GATEWAY EXPOSURE**
295
+>
296
+> By default, the gateway is bound to localhost for security. If you bind to `0.0.0.0`
297
+> or a public IP, anyone with access can trigger retrieval of arbitrary CIDs, causing
298
+> bandwidth usage and potential exposure to malicious content. Limit with
299
+> [`Gateway.NoFetch`](#gatewaynofetch). Consider firewall rules, authentication,
300
+> and [`Gateway.PublicGateways`](#gatewaypublicgateways) for public exposure.
301
+> See [Security section](#security) for network exposure considerations.
302
+
303
Default: `/ip4/127.0.0.1/tcp/8080`
304
305
Type: `strings` ([multiaddrs][multiaddr])
@@ -304,6 +318,7 @@ Supported Transports:
318
319
> [!IMPORTANT]
320
> Make sure your firewall rules allow incoming connections on both TCP and UDP ports defined here.
321
+> See [Security section](#security) for network exposure considerations.
322
323
Note that quic (Draft-29) used to be supported with the format `/ipN/.../udp/.../quic`, but has since been [removed](https://github.com/libp2p/go-libp2p/releases/tag/v0.30.0).
324
@@ -2485,6 +2500,14 @@ transports, multiaddrs for these transports must be added to `Addresses.Swarm`.
2500
2501
Supported transports are: QUIC, TCP, WS, Relay, WebTransport and WebRTCDirect.
2502
2503
+> [!CAUTION]
2504
+> **SECURITY CONSIDERATIONS FOR NETWORK TRANSPORTS**
2505
+>
2506
+> Enabling network transports allows your node to accept connections from the internet.
2507
+> Ensure your firewall rules and [`Addresses.Swarm`](#addressesswarm) configuration
2508
+> align with your security requirements.
2509
+> See [Security section](#security) for network exposure considerations.
2510
+
2511
Each field in this section is a `flag`.
2512
2513
#### `Swarm.Transports.Network.TCP`
@@ -3202,6 +3225,27 @@ See <https://github.com/ipfs/kubo/blob/master/config/profile.go> for exact [`Imp
3225
> Follow [kubo#4143](https://github.com/ipfs/kubo/issues/4143) for more details,
3226
> and provide feedback in [discuss.ipfs.tech/t/should-we-profile-cids](https://discuss.ipfs.tech/t/should-we-profile-cids/18507) or [ipfs/specs#499](https://github.com/ipfs/specs/pull/499).
3227
3228
+## Security
3229
+
3230
+This section provides an overview of security considerations for configurations that expose network services.
3231
+
3232
+### Port and Network Exposure
3233
+
3234
+Several configuration options expose TCP or UDP ports that can make your Kubo node accessible from the network:
3235
+
3236
+- **[`Addresses.API`](#addressesapi)** - Exposes the admin RPC API (default: localhost:5001)
3237
+- **[`Addresses.Gateway`](#addressesgateway)** - Exposes the HTTP gateway (default: localhost:8080)
3238
+- **[`Addresses.Swarm`](#addressesswarm)** - Exposes P2P connectivity (default: 0.0.0.0:4001, both UDP and TCP)
3239
+- **[`Swarm.Transports.Network`](#swarmtransportsnetwork)** - Controls which P2P transport protocols are enabled over TCP and UDP
3240
+
3241
+### Security Best Practices
3242
+
3243
+- Keep admin services ([`Addresses.API`](#addressesapi)) bound to localhost unless authentication ([`API.Authorizations`](#apiauthorizations)) is configured
3244
+- Use [`Gateway.NoFetch`](#gatewaynofetch) to prevent arbitrary CID retrieval if Kubo is acting as a public gateway available to anyone
3245
+- Configure firewall rules to restrict access to exposed ports. Note that [`Addresses.Swarm`](#addressesswarm) is special - all incoming traffic to swarm ports should be allowed to ensure proper P2P connectivity
3246
+- Control which public-facing addresses are announced to other peers using [`Addresses.NoAnnounce`](#addressesnoannounce), [`Addresses.Announce`](#addressesannounce), and [`Addresses.AppendAnnounce`](#addressesappendannounce)
3247
+- Consider using the [`server` profile](#server-profile) for production deployments
3248
+
3249
## Types
3250
3251
This document refers to the standard JSON types (e.g., `null`, `string`,