From b4e6769a567da2008f44c024a37f03ba2c6ec6eb Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Fri, 11 Jul 2025 18:33:03 +0200 Subject: [PATCH] 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 --- docs/config.md | 44 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/docs/config.md b/docs/config.md index 64e555984..d02a7e293 100644 --- a/docs/config.md +++ b/docs/config.md @@ -235,6 +235,9 @@ config file at runtime. - [`legacy-cid-v0` profile](#legacy-cid-v0-profile) - [`test-cid-v1` profile](#test-cid-v1-profile) - [`test-cid-v1-wide` profile](#test-cid-v1-wide-profile) + - [Security](#security) + - [Port and Network Exposure](#port-and-network-exposure) + - [Security Best Practices](#security-best-practices) - [Types](#types) - [`flag`](#flag) - [`priority`](#priority) @@ -271,6 +274,7 @@ Supported Transports: > > - 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. > - If you are looking for an interface designed for browsers and public internet, use [`Addresses.Gateway`](#addressesgateway) port instead. +> - See [Security section](#security) for network exposure considerations. Default: `/ip4/127.0.0.1/tcp/5001` @@ -286,6 +290,16 @@ Supported Transports: * tcp/ip{4,6} - `/ipN/.../tcp/...` * unix - `/unix/path/to/socket` +> [!CAUTION] +> **SECURITY CONSIDERATIONS FOR GATEWAY EXPOSURE** +> +> By default, the gateway is bound to localhost for security. If you bind to `0.0.0.0` +> or a public IP, anyone with access can trigger retrieval of arbitrary CIDs, causing +> bandwidth usage and potential exposure to malicious content. Limit with +> [`Gateway.NoFetch`](#gatewaynofetch). Consider firewall rules, authentication, +> and [`Gateway.PublicGateways`](#gatewaypublicgateways) for public exposure. +> See [Security section](#security) for network exposure considerations. + Default: `/ip4/127.0.0.1/tcp/8080` Type: `strings` ([multiaddrs][multiaddr]) @@ -304,6 +318,7 @@ Supported Transports: > [!IMPORTANT] > Make sure your firewall rules allow incoming connections on both TCP and UDP ports defined here. +> See [Security section](#security) for network exposure considerations. 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). @@ -2485,6 +2500,14 @@ transports, multiaddrs for these transports must be added to `Addresses.Swarm`. Supported transports are: QUIC, TCP, WS, Relay, WebTransport and WebRTCDirect. +> [!CAUTION] +> **SECURITY CONSIDERATIONS FOR NETWORK TRANSPORTS** +> +> Enabling network transports allows your node to accept connections from the internet. +> Ensure your firewall rules and [`Addresses.Swarm`](#addressesswarm) configuration +> align with your security requirements. +> See [Security section](#security) for network exposure considerations. + Each field in this section is a `flag`. #### `Swarm.Transports.Network.TCP` @@ -3202,6 +3225,27 @@ See for exact [`Imp > Follow [kubo#4143](https://github.com/ipfs/kubo/issues/4143) for more details, > 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). +## Security + +This section provides an overview of security considerations for configurations that expose network services. + +### Port and Network Exposure + +Several configuration options expose TCP or UDP ports that can make your Kubo node accessible from the network: + +- **[`Addresses.API`](#addressesapi)** - Exposes the admin RPC API (default: localhost:5001) +- **[`Addresses.Gateway`](#addressesgateway)** - Exposes the HTTP gateway (default: localhost:8080) +- **[`Addresses.Swarm`](#addressesswarm)** - Exposes P2P connectivity (default: 0.0.0.0:4001, both UDP and TCP) +- **[`Swarm.Transports.Network`](#swarmtransportsnetwork)** - Controls which P2P transport protocols are enabled over TCP and UDP + +### Security Best Practices + +- Keep admin services ([`Addresses.API`](#addressesapi)) bound to localhost unless authentication ([`API.Authorizations`](#apiauthorizations)) is configured +- Use [`Gateway.NoFetch`](#gatewaynofetch) to prevent arbitrary CID retrieval if Kubo is acting as a public gateway available to anyone +- 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 +- Control which public-facing addresses are announced to other peers using [`Addresses.NoAnnounce`](#addressesnoannounce), [`Addresses.Announce`](#addressesannounce), and [`Addresses.AppendAnnounce`](#addressesappendannounce) +- Consider using the [`server` profile](#server-profile) for production deployments + ## Types This document refers to the standard JSON types (e.g., `null`, `string`,