ss

Documentation

Overview

Package ss implements the ss builtin command.

ss — socket statistics

Usage: ss [OPTION]...

Display information about network sockets. Reads kernel socket state directly without executing any external binary. On Linux the data comes from /proc/net/tcp, /proc/net/tcp6, /proc/net/udp, /proc/net/udp6, and /proc/net/unix via os.Open directly (AllowedPaths sandbox is not used; the paths are derived from ProcPath, a hardcoded kernel pseudo-filesystem root that is never derived from user input). On macOS kernel data is read via syscall.SysctlRaw (no unsafe at the call site). On Windows a narrow unsafe exception is used to call GetExtendedTcpTable via iphlpapi.dll.

Accepted flags:

-t, --tcp
    Display only TCP sockets.

-u, --udp
    Display only UDP sockets.

-x, --unix
    Display only Unix domain sockets.

-l, --listening
    Display only listening (bound) sockets. By default only
    non-listening sockets are shown; -l reverses that.

-a, --all
    Display all sockets regardless of state (listening and
    non-listening). Overrides the default non-listening-only filter.

-n, --numeric
    Do not resolve service names or hostnames; display numeric
    addresses and port numbers.

-4, --ipv4
    Display only IPv4 sockets (TCP and UDP). Has no effect on Unix
    domain sockets.

-6, --ipv6
    Display only IPv6 sockets (TCP and UDP). Has no effect on Unix
    domain sockets.

-s, --summary
    Print a one-page summary of socket statistics and exit. No
    per-socket rows are printed.

-H, --no-header
    Suppress the column header line.

-o, --options
    Show per-socket timer information as a timer:(...) suffix.

-e, --extended
    Show extended socket information: UID and inode number per socket.

-h, --help
    Print usage to stdout and exit 0.

Rejected flags: -F/--filter (GTFOBins file read), -p/--processes (PID disclosure), -K/--kill (writes to kernel), -E/--events (infinite stream), -N/--net (namespace switching), -b/--bpf, -r/--resolve (DNS), -m/--memory, -Z/-z (SELinux), -d/-w/-S/-0 (niche protocols).

Default filter behaviour:

No -t/-u/-x specified    → show all socket types (TCP + UDP + Unix)
No -a, no -l             → show non-listening sockets only
-l                       → show listening sockets only
-a                       → show all sockets (listening + non-listening)
-4 / -6                  → restrict TCP/UDP to the specified IP version

Exit codes:

0  Success (even if no sockets match the filter).
1  An error occurred (unreadable proc file, invalid argument, etc.).

Memory safety:

Linux: /proc/net/ files are finite. Input is read line-by-line via
bufio.Scanner with a MaxLineBytes cap. ctx.Err() is checked at the
top of every scan loop.

macOS: sysctl returns a bounded []byte. Every offset dereference is
bounds-checked against len(data) before reading.

Windows: the DLL grow-loop is capped at MaxWinBufSize (64 MiB).
unsafe.Pointer is used only to pass &buf[0] to the DLL call; the
returned data is parsed entirely with encoding/binary.LittleEndian.

Index

• Constants
• Variables

Constants

const MaxLineBytes = 1 << 20 // 1 MiB

MaxLineBytes is the per-line buffer cap for the Linux /proc/net/ scanner.

const MaxWinBufSize = 64 << 20 // 64 MiB — keep in sync with winnet.MaxBufSize

MaxWinBufSize is the maximum buffer size used by the Windows grow-loop when calling GetExtendedTcpTable / GetExtendedUdpTable. This must match winnet.MaxBufSize; the winnet package owns the authoritative value.

Variables

var Cmd = builtins.Command{
	Name:        "ss",
	Description: "display socket statistics",
	MakeFlags:   registerFlags,
}

Cmd is the ss builtin command descriptor.

var ProcPath = procpath.Default

ProcPath is the proc filesystem root used to locate /proc/net/* files. It is a package-level variable so tests can point it at a synthetic directory instead of the real /proc.

Concurrency contract: this variable is written only in tests and is never mutated by production code after package initialization. Test code that mutates ProcPath must hold a test-package-level mutex for the duration of the test to prevent data races between concurrent test goroutines.