Security and privilege boundary

tcpcc changes host networking. Its privilege model should therefore be understood before production use.

Required authority

The current product model accepts running tcpcc as root inside the target VPS/container.

What matters is whether that root has the effective authority required by the packet path:

  • CAP_NET_ADMIN;
  • readable/writable /dev/net/tun;
  • access to the selected nftables/iptables backend;
  • forwarding enabled for the selected public address family.

Privilege separation is not currently part of the product contract.

Host mutations

tcpcc owns a deliberately narrow set of host resources:

  • one exclusive, nonpersistent TUN queue;
  • point-to-point address/route state associated with that TUN;
  • exact TCP DNAT resources for the configured public address/port mappings.

It does not intentionally install a broad “redirect everything” rule.

For each forward, packet steering is scoped to:

  • exact public destination address;
  • exact TCP destination port.

There is no implicit UDP interception and no implicit masquerade/SNAT policy.

Transactional ownership

Preflight and ownership inspection happen before normal resource acquisition.

After acquisition, resources are tracked and unwound in reverse order. Normal SIGINT/SIGTERM shutdown drains/stops the hosted service, removes owned firewall state, and closes the nonpersistent TUN.

tcpcc does not adopt unrelated firewall state.

Ownership markers contain process identity information so that stale resources can be distinguished from an unrelated rule or simple PID reuse.

Abrupt termination

SIGKILL cannot execute cleanup code.

If the supervisor dies abruptly, marked firewall resources may survive. A later startup reports stale/malformed tcpcc ownership rather than guessing that a rule is safe to delete.

This is an intentional fail-closed behavior.

Public versus backend trust boundary

The public connection terminates inside hosted Linux.

The backend connection is a separate ordinary host TCP connection to:

127.0.0.1:<port>

The current configuration contract deliberately rejects non-loopback backends. This keeps tcpcc's application-facing bridge local to the host/container rather than turning the tool into a generic remote TCP relay.

Application isolation

The backend application does not need:

  • LD_PRELOAD;
  • an LKL syscall-hijack environment;
  • knowledge of tcpcc's internal control ABI;
  • BBR support in the outer host kernel.

It only needs to listen on the configured loopback port.

Read-only validation

Use:

sudo tcpcc --check --config /etc/tcpcc/tcpcc.toml

before normal startup.

The check validates host prerequisites and ownership state without creating the TUN, firewall rules, or hosted process.

What tcpcc does not protect against

tcpcc is not a sandbox for the backend application and is not a security boundary against a hostile root user in the same container.

It also cannot override provider restrictions that remove TUN, deny effective network capabilities, lock forwarding off, or block the relevant public traffic upstream.

For the authoritative ownership/lifecycle model, see ARCHITECTURE.md and docs/runtime-lifecycle.md.