Status & Quality
Container Registries
Security & Platform
Community
Docs: https://debugbox.ibtisam-iq.com
You need to debug a pod. You run kubectl debug my-pod --image=netshoot and wait for 201 MB to download.
On an edge cluster? Mobile network? Restricted bandwidth? Every MB costs time.
Worse still: you just need to check DNS. You don't need tcpdump, tshark, routing tools. But netshoot is all-or-nothing.
DebugBox is a Kubernetes-native debugging container that lets you choose exactly what you need—no more, no less.
Optimized for Kubernetes:
kubectl debugephemeral containers — launch in secondskubectx/kubenscontext switching — built-in cluster awareness- Shell helpers pre-loaded — json() and yaml() functions ready to use
- Pinned tool versions — deterministic, repeatable builds
Three sizes. Pick one:
- LITE (14.36 MB): DNS & connectivity
- BALANCED (46.16 MB): Daily Kubernetes debugging ⭐
- POWER (104.45 MB): Packet analysis & forensics
No bloat. No waiting. Right-sized for your job.
Pick the right size for your task:
Need to analyze packets?
│
┌────┴─────┐
│ │
NO YES ──────► POWER (104.45 MB)
│ (tshark, iptables, bird)
│
Need tcpdump or K8s tools?
│
┌───┴────┐
│ │
NO YES ─────────► BALANCED (46.16 MB) ⭐
│ (tcpdump, kubectx/ns)
│
YES ────────────────► LITE (14.36 MB)
(minimal, fast)
# Debug a running pod (default: balanced variant)
kubectl debug my-pod -it --image=ghcr.io/ibtisam-iq/debugbox
# Use lite variant (minimal, fastest pull)
kubectl debug my-pod -it --image=ghcr.io/ibtisam-iq/debugbox:lite
# Use power variant (full forensics toolkit)
kubectl debug my-pod -it --image=ghcr.io/ibtisam-iq/debugbox:power
# Standalone debugging session
kubectl run debug --rm -it --image=ghcr.io/ibtisam-iq/debugbox --restart=Never# Interactive session (latest balanced variant)
docker run -it ghcr.io/ibtisam-iq/debugbox
# Lite variant
docker run -it ghcr.io/ibtisam-iq/debugbox:lite
# Power variant
docker run -it ghcr.io/ibtisam-iq/debugbox:power| Image | Compressed Size |
|---|---|
| DebugBox lite | 14.36 MB |
| DebugBox balanced | 46.16 MB |
| DebugBox power | 104.45 MB |
| netshoot v0.15 | 201.67 MB |
DebugBox power is 97 MB smaller than netshoot (48% reduction). DebugBox lite is 14× smaller than netshoot.
On resource-constrained clusters (edge, IoT, Kubernetes on laptops), every MB counts. See detailed bandwidth analysis →
- Trivy scans block HIGH/CRITICAL on every release
- Alpine Linux base (minimal attack surface)
- No unnecessary packages
- Multi-architecture support (amd64, arm64)
What tools are included in each variant? → Complete tool list
| Category | Tools | Lite | Balanced | Power |
|---|---|---|---|---|
| Networking Basics | curl, netcat, iproute2, iputils, bind-tools (dig, nslookup) | ✓ | ✓ | ✓ |
| Data Parsing | jq, yq | ✓ | ✓ | ✓ |
| Shell | bash, bash-completion, less | — | ✓ | ✓ |
| Editors | vi / vim / nano | vi | ✓ | ✓ |
| Filesystem | git, file, tar, gzip | — | ✓ | ✓ |
| System | htop, strace, lsof, procps, psmisc | — | ✓ | ✓ |
| System Deep | ltrace | — | — | ✓ |
| Networking | tcpdump, socat, nmap, mtr, iperf3, ethtool, iftop | — | ✓ | ✓ |
| Packet Analysis | tshark, ngrep, tcptraceroute, fping, speedtest-cli, nmap-nping | — | — | ✓ |
| TLS/SSL | openssl | — | — | ✓ |
| Routing | iptables, nftables, conntrack-tools, bird, bridge-utils | — | — | ✓ |
| Kubernetes | kubectx, kubens | — | ✓ | ✓ |
| Scripting | Python 3 + pip3 | — | — | ✓ |
| Helpers | json(), yaml(), ll() | ✓ | ✓ | ✓ |
| Network Helpers | ports, connections, routes, k8s-info | — | ✓ | ✓ |
| Packet Helpers | sniff(), sniff-http(), sniff-dns(), cert-check(), conntrack-watch() | — | — | ✓ |
| Feature | DebugBox | netshoot | busybox | Alpine |
|---|---|---|---|---|
| Smallest variant | 14.36 MB | 201.67 MB | 1.5 MB | 7.6 MB |
| Variants | ✓ 3 sizes | ✗ one size | ✗ one size | ✗ one size |
| Multi-arch | ✓ amd64+arm64 | ✓ amd64+arm64 | ✓ amd64+arm64 | ✓ amd64+arm64 |
| Pinned tools | ✓ deterministic | ✗ floating | ✗ minimal | ✗ minimal |
| Kubernetes helpers | ✓ kubectx/ns | ✗ none | ✗ none | ✗ none |
| Security scanned | ✓ Trivy | ✗ manual | ✗ manual | ✗ manual |
Why DebugBox wins:
- ✅ Smaller when you need it (14.36 MB vs 201.67 MB)
- ✅ Larger when you need it (104.45 MB for SRE workflows)
- ✅ Kubernetes-first design (kubectx/kubens built-in)
- ✅ Predictable (pinned tools, repeatable builds)
Ephemeral debugging with kubectl debug:
- ✅ One-off troubleshooting sessions
- ✅ Resource-constrained environments (edge, IoT, bandwidth-limited)
- ✅ Multi-cluster operations (kubectx/kubens included)
- ✅ Incident response (fast pull, ready to go)
- ✅ Learning Kubernetes networking
- ✅ SRE forensics workflows (power variant)
Not for:
- ❌ Persistent sidecars — use for ephemeral debugging only
- ❌ Production workloads — runs as root, for debugging only
- ❌ Kubernetes control plane access — no kubectl, no kube-proxy config
DebugBox is published to two registries with 20 tags per release:
| Registry | URL |
|---|---|
| GHCR (Recommended) | ghcr.io/ibtisam-iq/debugbox |
| Docker Hub | docker.io/mibtisam/debugbox |
All three variants are in one repository with variant-based tags:
debugbox:lite # Latest lite variant
debugbox:balanced # Latest balanced variant (default)
debugbox:power # Latest power variantdebugbox:lite-latest # Latest lite
debugbox:balanced-latest # Latest balanced
debugbox:power-latest # Latest powerdebugbox:lite-1.0.0 # Lite v1.0.0
debugbox:balanced-1.0.0 # Balanced v1.0.0
debugbox:power-1.0.0 # Power v1.0.0debugbox:latest # Alias to balanced-latest (default)
debugbox:1.0.0 # Alias to balanced-1.0.0 (short form)Production: Always pin specific versions See Image Tags
Full docs: https://debugbox.ibtisam-iq.com
Essential guides:
- Kubernetes Usage — kubectl debug examples
- Docker Usage — Docker run examples
- Variants Overview — detailed tool breakdown
- Image Tags & Registries — tagging strategy
- Common Workflows — real debugging scenarios
- Local Development — build and test locally
- Contributing — how to contribute
Q: Can I use DebugBox in production?
A: No. DebugBox runs as root and is designed for ephemeral debugging containers only. Use kubectl debug or temporary pods.
Q: What if I need a tool not in DebugBox? A: You can extend DebugBox by creating your own Dockerfile or submitting a feature request. See Local Development.
Q: How do I pin a specific version in production?
A: Use the full tag: ghcr.io/ibtisam-iq/debugbox:1.0.0 (balanced) or ghcr.io/ibtisam-iq/debugbox:lite-1.0.0 (lite). See Image Tags for full strategy.
Q: Does DebugBox work on Kubernetes 1.18+?
A: Yes, works on Kubernetes 1.18+. Best experience with 1.20+ (has kubectl debug support).
Q: Can I use DebugBox outside Kubernetes?
A: Absolutely! docker run -it ghcr.io/ibtisam-iq/debugbox works perfectly for local debugging.
More questions? → Full Troubleshooting Guide
git clone https://github.com/ibtisam-iq/debugbox.git
cd debugbox
make build-all # All variants
make test-all # Smoke tests
make scan # Trivy scanSee Local Development for detailed setup.
Found a bug? Have an idea? We welcome contributions!
MIT License — Free to use, modify, and distribute.
v1.0.0 (Feb 2026)
- Public release
- 3 variants: lite, balanced, power
- Multi-arch support (amd64, arm64)
- Kubernetes-optimized with kubectx/kubens
- SRE-grade routing and analysis tools in power variant
- 💬 GitHub Discussions — ask questions, share ideas
- 🐛 GitHub Issues — report bugs or request features
- 📖 Documentation — https://debugbox.ibtisam-iq.com
- 🤝 Code of Conduct — CODE_OF_CONDUCT.md
Built with ❤️ for Kubernetes debugging by @ibtisam-iq
Faster pulls. Faster debugging. Right-sized containers.