childflow

childflow is a per-command-tree network sandbox for Linux. Run one command and its child processes in an isolated network context, control DNS / hosts / proxy behavior, block sensitive destinations, and capture only that tree's traffic.

About

childflow runs one command tree in an isolated network context and applies DNS, hosts, proxy, sandbox, and capture controls only to that tree.

This is useful for tools that do not honor proxy environment variables consistently. childflow forces the proxy at the command tree's network path instead of relying on HTTP_PROXY, HTTPS_PROXY, or LD_PRELOAD-style interception.

It has two Linux backends: rootless-internal for the default day-to-day path, and rootful via --root when you need host-integrated behavior such as --iface or transparent interception.

• affects only the target command tree, not the whole host session
• can force DNS, /etc/hosts, proxying, baseline sandbox controls, and packet capture per command tree
• can force proxying without depending on HTTP_PROXY, HTTPS_PROXY, or LD_PRELOAD tricks
• defaults to rootless-internal
• uses --root only for features like --iface and transparent interception

Install

cargo

cargo install childflow

Requirements

Host requirements:

• Linux only
• ip
• iptables
• ip6tables

Additional rootless-internal requirements:

• user, network, and mount namespace support
• /dev/net/tun
• user namespaces enabled on the host
• uidmap is recommended on Debian / Ubuntu style systems for newuidmap / newgidmap fallback

Additional rootful requirements:

• root privileges
• writable /proc/sys/net/ipv4/ip_forward
• writable /proc/sys/net/ipv6/conf/all/forwarding
• Linux features required for TPROXY when proxy interception is used

If you are evaluating from macOS or another non-Linux environment, use the Docker workflows instead of trying to run the binary directly.

Usage

$ childflow --help
Run one command tree inside a controlled network sandbox

Usage: childflow [OPTIONS] [COMMAND]...

Arguments:
  [COMMAND]...  Command to execute

Options:
  -c, --capture <OUTPUT>
          Write only the target command tree's traffic as pcapng
  -C, --capture-point <OUTPUT_VIEW>
          Select which capture point or view `--capture` should write. `child` is the current stable view [default: child] [possible values: child, egress, wire-egress, both]
      --root
          Use the rootful backend. Without this flag, childflow uses the default rootless backend
      --doctor
          Diagnose whether the current host is ready for the selected backend
  -d, --dns <DNS>
          Force DNS traffic for the child tree to this IPv4 or IPv6 resolver
      --hosts-file <HOSTS_FILE>
          Bind-mount an `/etc/hosts`-format file over the child's `/etc/hosts` so those entries are consulted first during name resolution
  -p, --proxy <PROXY>
          Configure an upstream proxy URI, for example http://127.0.0.1:8080, https://proxy.example.com:443, or socks5://host.docker.internal:10080. `--root` uses transparent interception, while the default rootless backend relays outbound TCP through the selected proxy from the parent-side engine
  -U, --proxy-user <PROXY_USER>
          Username for upstream proxy authentication
  -P, --proxy-password <PROXY_PASSWORD>
          Password for upstream proxy authentication
      --proxy-insecure
          Ignore certificate trust errors for https:// upstream proxies while still validating the hostname
      --summary
          Print a post-run summary to stderr
      --offline
          Block all outbound networking for the child tree, including DNS forwarding
      --block-private
          Block child-tree traffic to private, loopback, link-local, and ULA-style destinations
      --block-metadata
          Block common cloud metadata endpoints such as 169.254.169.254
  -i, --iface <IFACE>
          Force the host-side egress interface for the child's direct traffic
  -h, --help
          Print help
  -V, --version
          Print version

example

childflow -- curl https://example.com

childflow -c rootless.pcapng -- curl https://example.com

childflow -d 1.1.1.1 -- curl https://example.com

childflow --hosts-file ./hosts.override -- curl http://demo.internal

childflow --offline -- cargo test

childflow --block-metadata -- ./my-client

childflow --block-private -- curl https://example.com

childflow -p http://127.0.0.1:8080 -- curl https://example.com

childflow -p http://127.0.0.1:8080 -- gobuster dir -u http://target.local/ -w ./wordlist.txt

childflow \
  -p https://proxy.example.com:443 \
  -U alice \
  -P secret \
  -- curl https://example.com

sudo childflow --root -c capture.pcapng -- curl https://example.com

childflow -- ping -c 1 8.8.8.8
childflow -- ping -6 -c 1 2606:4700:4700::1111

childflow -- traceroute -n -q 1 -w 2 8.8.8.8
childflow -- traceroute -I -n -q 1 -w 2 8.8.8.8

Description

Backend Summary

Use rootless-internal by default. It is the main path for isolated execution, DNS control, proxying, packet capture, ping, and traceroute without host-wide rootful setup.

Use --root when you specifically need host-integrated behavior that the rootless path does not expose yet, including:

• transparent proxying
• interface-forced direct egress with --iface
• broader raw-ICMP behavior than the current rootless relay engine implements

Capture Modes

childflow is intended to capture only the target command tree's traffic, not unrelated host traffic.

The default child mode keeps the isolated child-side view.

• egress synthetic egress-oriented view on both backends
• wire-egress real host egress capture on both backends
• both writes sibling .child.pcapng and .egress.pcapng files

Generated pcapng files also embed metadata describing the capture view, backend, kind, and interface.

For the fuller comparison of current capture points and the planned child / egress / wire-egress / both capture-point direction, see docs/technical-details.md.

License

MIT. See LICENSE.