Netshoot: Network Troubleshooting Swiss Army Knife

Netshoot is a comprehensive Docker image packed with 70+ networking and system tools for troubleshooting, analysis, and debugging. Built on Debian 13 Trixie with an enhanced Zsh shell, it's your go-to toolkit for network diagnostics in containerized environments.

Origin

This project is heavily inspired by nicolaka/netshoot, a brilliant Alpine-based network troubleshooting container. I love the concept, but I kept running into cases where I needed tools it didn't ship: a Debian base for broader package compatibility, termshark for interactive packet inspection, btop, grpcurl, speedtest, and container runtime variants (Docker, Podman, nerdctl, containerd) for working across different environments. So I built my own.

Architecture

The image uses a multi-stage Dockerfile where all variants extend from a common base stage:

flowchart TB
    A["debian:trixie"] --> B["base"]
    B --> C["docker"]
    B --> D["podman"]
    B --> E["nerdctl"]
    B --> F["containerd"]

    style A fill:#e1f5fe
    style B fill:#c8e6c9
    style C fill:#fff3e0
    style D fill:#fff3e0
    style E fill:#fff3e0
    style F fill:#fff3e0

A separate Dockerfile.slim provides a minimal variant with a reduced toolset.

Features

Feature	Description
70+ Tools	Networking, system diagnostics, container management
Enhanced Shell	Zsh with Oh My Zsh, Powerlevel10k, auto-suggestions, syntax highlighting
Multiple Variants	Base, Docker, Podman, nerdctl, containerd, slim
Python Ready	Python 3, pip, and uv for scripting and automation
Multi-Platform	AMD64 and ARM64 architectures
Secure Base	Debian 13 Trixie stable with regular updates

Quick Start

Pull and run the base image:

docker pull obeoneorg/netshoot:latest
docker run -it --rm obeoneorg/netshoot

Use with host networking for full network access:

docker run -it --rm --network=host obeoneorg/netshoot

Debug a specific container's network namespace:

# Get container PID
docker inspect -f '{{.State.Pid}}' <container-name>

# Enter the network namespace
docker run -it --rm \
  --network=container:<container-name> \
  obeoneorg/netshoot

Common Use Cases

Kubernetes Pod Debugging

# Run as a sidecar for debugging
kubectl run netshoot --rm -it \
  --image=obeoneorg/netshoot

# Debug a specific pod's network
kubectl run netshoot --rm -it \
  --image=obeoneorg/netshoot \
  --overrides='{
    "spec": {
      "hostNetwork": true,
      "containers": [{
        "name": "netshoot",
        "image": "obeoneorg/netshoot",
        "stdin": true,
        "tty": true
      }]
    }
  }'

Network Performance Testing

# Start iperf3 server
docker run -it --rm -p 5201:5201 \
  obeoneorg/netshoot iperf3 -s

# Run client test from another container
docker run -it --rm \
  obeoneorg/netshoot iperf3 -c <server-ip>

Traffic Analysis

# Capture packets on specific interface
docker run -it --rm --network=host \
  obeoneorg/netshoot \
  tcpdump -i eth0 -w /tmp/capture.pcap

# Analyze HTTP traffic
docker run -it --rm --network=host \
  obeoneorg/netshoot \
  ngrep -q -W byline "GET|POST" tcp port 80

# Stream live traffic to local Wireshark
docker run -i --rm --network=host \
  obeoneorg/netshoot \
  tcpdump -i eth0 -U -w - | wireshark -k -i -

DNS Troubleshooting

# Comprehensive DNS query
docker run -it --rm \
  obeoneorg/netshoot dig +trace example.com

# Check DNS propagation
docker run -it --rm \
  obeoneorg/netshoot dig @8.8.8.8 example.com

Image Variants

Choose the variant that matches your container runtime needs:

Variant	Tags	Use Case
Base	`latest`	Network troubleshooting without container runtime
Docker	`docker`	Docker-in-Docker scenarios, CI/CD pipelines
Podman	`podman`	Rootless container management and testing
nerdctl	`nerdctl`	nerdctl client for existing container runtimes
containerd	`containerd`	Full containerd stack with nerdctl
Slim	`slim`	Minimal toolset for constrained environments

Pulling Specific Variants

# Base image (recommended for most use cases)
docker pull obeoneorg/netshoot:latest

# Docker variant for CI/CD
docker pull obeoneorg/netshoot:docker

# Slim variant for minimal footprint
docker pull obeoneorg/netshoot:slim

Included Tools

Netshoot includes 70+ carefully selected tools organized by category:

Network Analysis and Diagnostics

Category	Tools
Protocol Analysis	tcpdump, tshark, termshark, ngrep
Traffic Testing	iperf, iperf3, netperf, mtr, fping
Bandwidth Monitoring	bmon, nload, iftop
DNS	dig, host, nslookup (bind9-utils), dnsutils
Network Scanning	nmap, masscan, arp-scan, netcat-openbsd
Packet Crafting	hping3, arping
Routing / Firewalls	iptables, nftables, ipset, ipvsadm
Interface Management	iproute2 (ip, ss), net-tools (ifconfig, netstat), ethtool, bridge-utils
Connection Tracking	conntrack

Network Utilities

Category	Tools
HTTP/HTTPS	curl, wget, httpie, apache2-utils (ab)
Remote Access	openssh-client, telnet
Data Transfer	socat, rsync, magic-wormhole
VPN	wireguard-tools
SMTP Testing	swaks
Performance Testing	speedtest (Ookla official CLI)
Other	traceroute, tcptraceroute, whois

System and Monitoring Tools

Category	Tools
Process Monitoring	htop, btop, top (procps)
Resource Analysis	iotop, dstat, sysstat (sar, iostat), strace
Disk	ncdu, lsof
File Operations	rsync, unzip, zip, file
Text Processing	jq, vim
Command Correction	thefuck

Development and Scripting

Category	Tools
Python	python3, pip, uv (fast package manager)
Version Control	git
API Testing	grpcurl (gRPC)
Utilities	fzf (fuzzy finder), coreutils, util-linux

Enhanced Shell Experience

Category	Tools
Zsh Framework	oh-my-zsh with custom configuration
Theme	powerlevel10k (modern, informative prompt)
Plugins	zsh-autosuggestions, zsh-completions, fast-syntax-highlighting
Multiplexer	tmux

Security and Authentication

Category	Tools
TLS/SSL	openssl, ca-certificates, check-tls
Access Control	sudo
Storage	NFS support (nfs-common)

View complete package list

Networking: apache2-utils, arping, arp-scan, bind9-utils, bmon, bridge-utils, conntrack, curl, dnsutils, ethtool, fping, hping3, httpie, iftop, iperf, iperf3, iproute2, ipset, iptables, iputils-ping, ipvsadm, masscan, mtr, netcat-openbsd, net-tools, netperf, nftables, ngrep, nload, nmap, openssh-client, socat, speedtest, swaks, tcpdump, tcptraceroute, telnet, termshark, tshark, traceroute, wget, whois, wireguard-tools

System: bash, btop, ca-certificates, check-tls, coreutils, dstat, file, fzf, git, grpcurl, htop, iotop, jq, kitty-terminfo, lsof, magic-wormhole, ncdu, nfs-common, openssl, procps, python3-pip, rsync, strace, sudo, sysstat, thefuck, tmux, unzip, util-linux, uv, vim, zip, zsh

Shell: oh-my-zsh, powerlevel10k, zsh-autosuggestions, zsh-completions, fast-syntax-highlighting

Advanced Usage

Custom Shell Configuration

Mount your own configuration files to customize the environment:

# Custom Zsh configuration
docker run -it --rm \
  -v ~/.zshrc:/root/.zshrc \
  -v ~/.p10k.zsh:/root/.p10k.zsh \
  obeoneorg/netshoot

# Custom aliases and scripts
docker run -it --rm \
  -v ~/my-scripts:/scripts \
  obeoneorg/netshoot

Kubernetes Deployment as DaemonSet

Deploy netshoot on all nodes for cluster-wide troubleshooting:

apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: netshoot
spec:
  selector:
    matchLabels:
      app: netshoot
  template:
    metadata:
      labels:
        app: netshoot
    spec:
      hostNetwork: true
      containers:
      - name: netshoot
        image: obeoneorg/netshoot:latest
        command: ["/bin/sleep", "infinity"]
        securityContext:
          privileged: true

File Transfer with transfer.sh

The included transfer.sh script makes sharing files easy:

# Upload a file
docker run -it --rm \
  -v /path/to/file:/data/file \
  obeoneorg/netshoot transfer.sh /data/file

# Download with expiration
docker run -it --rm obeoneorg/netshoot \
  transfer.sh --max-days 7 myfile.txt

Running as Non-Root

For production environments, run with reduced privileges:

docker run -it --rm \
  --user 1000:1000 \
  --cap-drop=ALL \
  --cap-add=NET_RAW \
  --cap-add=NET_ADMIN \
  obeoneorg/netshoot

Persistent Shell History

Keep your command history between sessions:

docker run -it --rm \
  -v netshoot-history:/root/.zsh_history \
  obeoneorg/netshoot

Building from Source

Quick Build

git clone https://github.com/obeone/netshoot.git
cd netshoot
docker build -t my-netshoot .

Build Specific Variant

# Build with Docker runtime
docker build --target docker \
  -t my-netshoot:docker .

# Build with Podman runtime
docker build --target podman \
  -t my-netshoot:podman .

# Build slim variant
docker build -f Dockerfile.slim \
  -t my-netshoot:slim .

Multi-Platform Build

Use the provided build script for official multi-platform builds:

# Build all variants for AMD64 and ARM64
./build.sh

# Build specific type
./build.sh --type=debian --target=base

# Build without registry cache
./build.sh --no-cache

See CLAUDE.md for detailed build system documentation.

Contributing

Contributions are welcome! Here's how you can help:

Report bugs: Open an issue with details about the problem
Suggest tools: Propose new utilities that would benefit network troubleshooting
Improve documentation: Fix typos, add examples, or clarify instructions
Submit pull requests: Follow conventional commit format for your changes

Check out CLAUDE.md for development guidelines and architecture details.

CI/CD

Docker images are published via GitHub Actions to:

GHCR: ghcr.io/obeone/netshoot
Docker Hub: obeoneorg/netshoot

Pushes to main publish floating tags. Semantic version tags (v*.*.*) publish versioned tags per variant. Pull requests trigger build-only validation (no push).

License

This project is licensed under the MIT License. See the LICENSE file for details.

Credits

Built by Gregoire Compagnon (obeone)

Special thanks to:

Nicolas Kabar (nicolaka) for the original netshoot that started it all
The Debian Project for the solid foundation
Oh My Zsh and Powerlevel10k communities
All the maintainers of the included open-source tools

Related Projects

nicolaka/netshoot - The original Alpine-based network troubleshooting container
docker/cli - Docker CLI
containers/podman - Podman container engine
containerd/nerdctl - Docker-compatible CLI for containerd

Name		Name	Last commit message	Last commit date
Latest commit History 53 Commits
.github		.github
configs		configs
scripts		scripts
tools		tools
.gitignore		.gitignore
.markdownlint.json		.markdownlint.json
.release-please-manifest.json		.release-please-manifest.json
CLAUDE.md		CLAUDE.md
Dockerfile		Dockerfile
Dockerfile.slim		Dockerfile.slim
LICENSE		LICENSE
README.md		README.md
build.sh		build.sh
entrypoint-containerd.sh		entrypoint-containerd.sh
release-please-config.json		release-please-config.json

Folders and files

Latest commit

History

Repository files navigation

Netshoot: Network Troubleshooting Swiss Army Knife

Table of Contents

Origin

Architecture

Features

Quick Start

Common Use Cases

Kubernetes Pod Debugging

Network Performance Testing

Traffic Analysis

DNS Troubleshooting

Image Variants

Pulling Specific Variants

Included Tools

Network Analysis and Diagnostics

Network Utilities

System and Monitoring Tools

Development and Scripting

Enhanced Shell Experience

Security and Authentication

Advanced Usage

Custom Shell Configuration

Kubernetes Deployment as DaemonSet

File Transfer with transfer.sh

Running as Non-Root

Persistent Shell History

Building from Source

Quick Build

Build Specific Variant

Multi-Platform Build

Contributing

CI/CD

License

Credits

Related Projects

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages