ariankeshavarz/network-tools repository overview

⁠Network Tools

A ready-to-use network, system, and Python troubleshooting toolbox built on Alpine Linux 3.22.

ariankeshavarz/network-tools brings common diagnostic utilities into one container. Use it to investigate DNS, TCP connections, TLS certificates, HTTP responses, routing, and network throughput—or to run your own Python diagnostic scripts.

It is useful when an application container has few debugging tools and you need a separate troubleshooting environment without rebuilding the application image.

⁠Quick start

docker pull ariankeshavarz/network-tools:latest
docker run --rm -it ariankeshavarz/network-tools:latest

The default command opens /bin/bash. Exit the shell to stop and remove this temporary container.

To run a single command:

docker run --rm ariankeshavarz/network-tools:latest \
  dig example.com

Examples use the latest tag. Select an available version tag or image digest when you need a fixed image reference.

⁠What can you do with it?

• Check DNS records and query specific resolvers.
• Test TCP ports and inspect listening sockets.
• Inspect TLS handshakes, certificate chains, and HTTP headers.
• Investigate redirects, cookies, and API responses.
• Examine network interfaces, routes, and connection statistics.
• Run ping and MTR checks where runtime permissions allow them.
• Measure throughput against an iperf3 server.
• Inspect processes and system statistics visible to the container.
• Write network checks and automation scripts with Python.

The image starts a shell, not a background network service. It does not require published ports for normal client-side diagnostics.

⁠Included tools

⁠Python libraries

Python runs with unbuffered output, and bytecode file generation is disabled. The image sets LANG and LC_ALL to en_US.UTF-8.

⁠Docker usage

⁠Join an existing Docker network

Use this to test connectivity to services attached to a user-defined Docker network. Replace app-network with its actual name:

docker run --rm -it \
  --network app-network \
  ariankeshavarz/network-tools:latest

⁠Use another container's network namespace

To investigate connectivity from an existing container's network context, replace app-container with the running container's name or ID:

docker run --rm -it \
  --network container:app-container \
  ariankeshavarz/network-tools:latest

This shares the target's network namespace, including its interfaces, routes, and localhost. It does not automatically share the target's filesystem, process namespace, application configuration, or credentials.

⁠Save diagnostic output

Mount a local directory to keep results after the container exits:

mkdir -p diagnostics

docker run --rm -it \
  -v "$PWD/diagnostics:/work" \
  -w /work \
  ariankeshavarz/network-tools:latest

Inside the container:

curl -sS --max-time 20 -D response.headers \
  -o response.body https://example.com/

⁠Kubernetes usage

⁠Start a temporary diagnostic Pod

kubectl run network-tools -n default \
  --image=ariankeshavarz/network-tools:latest \
  --restart=Never --rm -it -- /bin/bash

Replace default with your namespace. This creates a separate Pod; its node placement, labels, NetworkPolicy selection, and network path may differ from those of the application Pod.

⁠Debug an existing Pod's network

When you need to run checks inside the affected Pod's network namespace, add an ephemeral debug container:

kubectl debug -n default -it pod/app-pod \
  --image=ariankeshavarz/network-tools:latest \
  -- /bin/bash

Replace app-pod with the affected Pod's name. Containers in the same Pod share its network namespace, so this is useful for checking localhost listeners and connectivity from that Pod.

Access depends on cluster permissions and admission policies. The debug container has its own filesystem and environment; it does not automatically inherit application credentials or process visibility. Exiting it leaves a terminated ephemeral-container entry until the Pod is removed.

⁠Diagnostic examples

Run the following commands inside the toolbox. Replace example domains, addresses, and service names with your targets.

⁠DNS

dig example.com A
dig example.com AAAA
dig @1.1.1.1 example.com A
cat /etc/resolv.conf

For Kubernetes service discovery, replace the service and namespace in this example:

dig my-service.my-namespace.svc.cluster.local

The cluster DNS suffix may differ from cluster.local.

⁠Interfaces, routes, and sockets

ip -br address
ip route
ip -6 route
ip route get 1.1.1.1
ss -lntup
ss -s

Socket process details depend on process visibility and permissions.

⁠TCP connectivity

nc -zv -w 5 example.com 443

⁠Ping and MTR

ping -c 4 1.1.1.1
mtr -n -r -c 10 1.1.1.1
mtr -n -r -c 10 -T -P 443 example.com

⁠HTTP headers and redirects

Inspect a GET response without downloading its body to the terminal:

curl -sS --max-time 20 -D - -o /dev/null https://example.com/

Follow redirects without enabling cookie storage:

curl -q -v -L --max-redirs 10 --max-time 30 \
  -o /dev/null https://example.com/

Follow redirects while accepting and returning HTTP cookies:

curl -q -v -L -b '' --max-redirs 10 --max-time 30 \
  -o /dev/null https://example.com/

The image does not include a browser or JavaScript challenge solver. curl does not execute JavaScript.

⁠Connect to a specific IP with the original hostname

Replace 192.0.2.10 with the server IP. The URL hostname remains available for HTTP Host, TLS SNI, and certificate verification:

curl -v --max-time 20 \
  --resolve example.com:443:192.0.2.10 \
  https://example.com/

⁠TLS handshake and certificate verification

openssl s_client \
  -connect example.com:443 \
  -servername example.com \
  -verify_hostname example.com \
  -verify_return_error \
  -CAfile /etc/ssl/certs/ca-certificates.crt \
  -showcerts </dev/null

⁠Throughput

With an iperf3 server available at the specified address:

iperf3 -c IPERF_SERVER -t 10
iperf3 -c IPERF_SERVER -t 10 -R

⁠Python HTTP check

python3 - <<'PY'
import requests

response = requests.get("https://example.com/", timeout=10)
print("Status:", response.status_code)
print("Final URL:", response.url)
print("Redirects:", len(response.history))
print("Content-Type:", response.headers.get("Content-Type"))
PY

⁠Runtime permissions

The image uses the base image's default root user. Ordinary DNS, HTTP, TLS, and TCP client checks do not require --privileged or NET_ADMIN.

Some probes, such as MTR or raw ICMP operations, may require NET_RAW. If the runtime has removed that capability, and the environment permits it, add it for that diagnostic session:

docker run --rm -it \
  --cap-add=NET_RAW \
  ariankeshavarz/network-tools:latest

NET_ADMIN is not needed simply to read interfaces or routes. Operations that change network configuration require additional permissions. Installing libcap does not grant capabilities by itself.

This image does not install tcpdump or iftop. System tools report what the container can see; their output is not automatically a complete view of the host.

⁠Build locally

From the directory containing the Dockerfile:

docker build -t network-tools:local .
docker run --rm -it network-tools:local

The base image is alpine:3.22. APK packages and Python libraries are not individually version-pinned, so rebuilding at a later date may produce different tool versions.

⁠Related images

• ariankeshavarz/network-tools⁠
• ariankeshavarz/xray⁠
• ariankeshavarz/3x-ui⁠

⁠Reference documentation

• Docker: Running containers⁠
• Kubernetes: Debug running Pods⁠
• curl: HTTP cookies⁠