netshoot

packaged by Chainguard

Chainguard Container for netshoot

Minimal image with the netshoot tool set for troubleshooting Docker and Kubernetes networking, including tcpdump, tshark, nmap, dig, iproute2, iperf3 and scapy.

Chainguard Containers are regularly-updated, secure-by-default container images.

Download this Container Image

For those with access, this container image is available on cgr.dev:

docker pull cgr.dev/ORGANIZATION/netshoot:latest

Be sure to replace the ORGANIZATION placeholder with the name used for your organization's private repository within the Chainguard Registry.

Compatibility Notes

Chainguard's netshoot image is meant to serve as a drop-in replacement for the upstream nicolaka/netshoot image. It carries the same troubleshooting tool set, runs as root in /root, and starts zsh with upstream's shell configuration, so the oh-my-zsh framework and the powerlevel10k prompt behave the same way. The image sets LANG to C.UTF-8 because the prompt renders its icons through zsh's multibyte handling.

This image runs as root, unlike most Chainguard Containers. Its tools need CAP_NET_RAW to open raw sockets and CAP_NET_ADMIN to change network state. A non-root process receives neither unless the binary itself carries file capabilities, and scapy cannot carry them at all because Linux ignores file capabilities on scripts. Under the Kubernetes restricted Pod Security Standard, which permits adding back only NET_BIND_SERVICE, packet capture does not work at any uid.

A few upstream tools are absent, either because upstream abandoned them or because Alpine packages them in a way that has no Chainguard equivalent:

Two packages differ in how they are split rather than in what they contain:

• nping and the Nmap Scripting Engine scripts ship inside the nmap package, so there is no separate nmap-nping or nmap-scripts to install.
• The util-linux binaries are packaged individually. The image includes the same set as upstream except su and login, which a troubleshooting container does not need.

python3 is Python 3.13, and pip installs into that interpreter.

Prerequisites

The packet-level tools need extra kernel privileges that Docker and Kubernetes do not grant by default:

• tcpdump, tshark, ngrep, nmap, nping, scapy, and fping open raw sockets, which needs the NET_RAW capability.
• ip, iptables, nftables, ipset, ipvsadm, and conntrack change network state, which needs the NET_ADMIN capability.
• Attaching to another container's or pod's network namespace needs that namespace to be shared explicitly.

Getting Started

Start an interactive shell:

docker run --rm -it cgr.dev/ORGANIZATION/netshoot:latest

The container greets you with the netshoot banner and a powerlevel10k prompt.

Run a single tool instead of a shell by passing it as the command:

docker run --rm cgr.dev/ORGANIZATION/netshoot:latest dig +short chainguard.dev

Capture traffic inside another container's network namespace. This is the most common use of the image, because it lets you watch a container's traffic without adding any tooling to that container:

docker run --rm -it --net "container:my-app" --cap-add NET_RAW --cap-add NET_ADMIN \
  cgr.dev/ORGANIZATION/netshoot:latest tcpdump -i any -n port 80

Measure throughput between two containers. Start the server:

docker run --rm --name iperf-server cgr.dev/ORGANIZATION/netshoot:latest iperf3 -s

Then run the client against it:

docker run --rm --net "container:iperf-server" \
  cgr.dev/ORGANIZATION/netshoot:latest iperf3 -c 127.0.0.1 -t 5

In Kubernetes, attach an ephemeral container to a running pod to inspect its network from the inside:

kubectl debug -it my-pod --image=cgr.dev/ORGANIZATION/netshoot:latest --target=my-container -- zsh

Or run a throwaway pod to test cluster DNS and service reachability:

kubectl run netshoot --rm -it --restart=Never \
  --image=cgr.dev/ORGANIZATION/netshoot:latest \
  -- dig +search kubernetes.default

Configuration

The image reads its shell configuration from /etc/zsh/zshrc and its banner from /etc/motd. Upstream ships the same configuration as ~/.zshrc, which only resolves for root; a global rc loads for any uid. Mounting your own ~/.zshrc replaces the shipped one rather than layering on top of it. The following example switches to the lighter robbyrussell prompt and enables history search, which replaces the zsh-autosuggestions plugin that upstream carries:

cat > zshrc <<'EOF'
export ZSH=/usr/share/oh-my-zsh
ZSH_THEME="robbyrussell"
plugins=(git docker history-substring-search)
source $ZSH/oh-my-zsh.sh
EOF

Start the container with that file in place:

docker run --rm -it -v "$PWD/zshrc:/root/.zshrc:ro" \
  cgr.dev/ORGANIZATION/netshoot:latest

Grant only the capabilities the task needs, and prefer an ephemeral container over a long-lived one.

Documentation and Resources

• netshoot upstream repository, which documents each tool with worked examples
• Debugging with an ephemeral debug container in the Kubernetes documentation
• Chainguard Containers documentation on Chainguard Academy

What are Chainguard Containers?

Chainguard's free tier of Starter container images are built with Wolfi, our minimal Linux undistro.

All other Chainguard Containers are built with Chainguard OS, Chainguard's minimal Linux operating system designed to produce container images that meet the requirements of a more secure software supply chain.

The main features of Chainguard Containers include:

• Minimal design, without unnecessary software bloat
• Daily builds to ensure container images are up-to-date with available security patches
• High quality build-time SBOMs attesting to the provenance of all artifacts within the image
• Verifiable signatures provided by Sigstore
• Reproducible builds with Cosign and apko (read more about reproducibility)

For cases where you need container images with shells and package managers to build or debug, most Chainguard Containers come paired with a development, or -dev, variant.

In all other cases, including Chainguard Containers tagged as :latest or with a specific version number, the container images include only an open-source application and its runtime dependencies. These minimal container images typically do not contain a shell or package manager.

Although the -dev container image variants have similar security features as their more minimal versions, they include additional software that is typically not necessary in production environments. We recommend using multi-stage builds to copy artifacts from the -dev variant into a more minimal production image.

Need additional packages?

To improve security, Chainguard Containers include only essential dependencies. Need more packages? Chainguard customers can use Custom Assembly to add packages, either through the Console, chainctl, or API.

To use Custom Assembly in the Chainguard Console: navigate to the image you'd like to customize in your Organization's list of images, and click on the Customize image button at the top of the page.

Learn More

Refer to our Chainguard Containers documentation on Chainguard Academy. Chainguard also offers VMs and Libraries — contact us for access.

Trademarks

This software listing is packaged by Chainguard. The trademarks set forth in this offering are owned by their respective companies, and use of them does not imply any affiliation, sponsorship, or endorsement by such companies.