PortClue

PortClue explica por qué un puerto TCP en una máquina Linux puede o no ser accesible. Convierte el estado de sockets, procesos, cortafuegos y Docker en una breve cadena de evidencia en lugar de obligarte a correlacionar ss, /proc, nftables, iptables y docker inspect a mano.

Ejecútalo sin un puerto para descubrir qué endpoints TCP locales merecen atención:

$ sudo portclue
LOCAL TCP LISTENERS

PORT    SERVICE                   CONFIDENCE BIND            OWNER       SOURCE BIND SCOPE
22      OpenSSH server            HIGH       0.0.0.0,::      ssh.service host   ALL_INTERFACES
8080    NGINX web server          HIGH       0.0.0.0,::      nginx       host   ALL_INTERFACES
8443    api service               MEDIUM     192.0.2.10      demo-api    docker SPECIFIC_INTERFACE
9000    Python HTTP server        MEDIUM     127.0.0.1       python3     host   LOOPBACK_ONLY

BIND SCOPE describes socket binding, not firewall reachability.
Run `portclue PORT` for the complete evidence chain and local exposure verdict.

ALL_INTERFACES, SPECIFIC_INTERFACE y LOOPBACK_ONLY describen dónde un socket acepta tráfico. Deliberadamente no afirman que un cortafuegos lo permita. Inspecciona un puerto para obtener el análisis completo del cortafuegos local:

$ sudo portclue 8080
POTENTIAL EXTERNAL EXPOSURE

TCP port 8080

  0.0.0.0:8080/tcp  [POTENTIAL]
    Service            NGINX web server
    Category           web
    Confidence         HIGH
    Identity evidence  executable basename matched "nginx"
    -> LISTEN             NETLINK_INET_DIAG reports socket inode 123456 bound to 0.0.0.0:8080/tcp
    -> OWNED              PID 4242 (nginx), systemd unit nginx.service
    -> ALL_INTERFACES     0.0.0.0 accepts traffic addressed to any local interface
    -> ACCEPT             nftables: a direct rule matches TCP destination port 8080 and returns accept

Unknown outside this machine:
  - router port forwarding
  - cloud firewall or security group
  - upstream NAT, including carrier-grade NAT

[!IMPORTANT] PortClue v0.1 es un prototipo Linux temprano y conservador. POTENTIAL significa que la ruta local observada permite el tráfico; no afirma que un puerto sea accesible desde la internet pública. Las expresiones de cortafuegos no soportadas producen UNKNOWN.

Por qué no ss o lsof

• No los necesita. Los listeners provienen de NETLINK_INET_DIAG, la misma interfaz del kernel que usa ss, y los detalles del proceso de /proc. Nada se extrae del resultado de otra herramienta, por lo que un contenedor que no tenga ni ss ni lsof igualmente obtiene el listener y su propietario. El análisis del cortafuegos sí ejecuta nft o iptables-save, y reporta UNKNOWN sin ellos.
• Responde la siguiente pregunta. ss -ltnp te da el socket y el PID. Si ese bind es solo loopback, si una regla de cortafuegos lo permite y si el puerto es una publicación de Docker en lugar de un listener del host es trabajo que de otro modo harías a mano.
• No adivinará. Una regla de cortafuegos que PortClue no puede modelar da UNKNOWN, nunca una respuesta incorrecta con confianza.

Qué lee

• Listeners TCP a través de NETLINK_INET_DIAG, no extrayendo la salida de ss
• propiedad del proceso, ejecutable, línea de comandos, cgroup y espacio de nombres de red a través de /proc
• descripciones de unidades systemd desde archivos de unidad instalados y activadores de socket activos a través de systemctl show
• nftables a través de nft --json list ruleset
• iptables a través de iptables-save cuando nftables no está disponible
• puertos publicados de Docker a través de la API HTTP local de Docker Engine, incluida la imagen y las etiquetas

Identidad del servicio

PortClue identifica a qué pertenece un puerto antes de explicar la exposición. La evidencia se clasifica en este orden:

1. ejecutable observado, unidad systemd y activador de socket activo;
2. imagen de Docker, nombre del contenedor y etiquetas;
3. el catálogo de servicios curado integrado;
4. la convención de puertos local de /etc/services.

Un propietario real siempre prevalece sobre un nombre de puerto convencional. Si solo se conoce la convención de puertos, la identidad se marca explícitamente con confianza LOW. El catálogo integrado se almacena en internal/identify/catalog.json y se incluye dentro del único binario; PortClue no descarga datos de identidad en tiempo de ejecución.

PortClue es de solo lectura. No se conecta al puerto consultado, no escanea otro host, no cambia reglas de cortafuegos, no detiene procesos ni contenedores, no sube datos ni ejecuta un daemon.

Instalación

Script de instalación (recomendado)

Se ejecuta en Linux (amd64 y arm64). El script descarga el archivo de GitHub Release correspondiente, verifica SHA256SUMS e instala un único binario. No modifica la configuración del shell.

Instalación de usuario (predeterminada, sin root). Instala en ~/.local/bin, propiedad tuya:

curl -fsSL https://raw.githubusercontent.com/pbxqdown/portclue/v0.1.2/scripts/install.sh | sh
portclue

Una instalación de usuario se ejecuta sin root y reporta la evidencia disponible para tu cuenta, señalando lo que falta. Esto es suficiente para explorar listeners y mapeos de Docker. Como sudo no busca en ~/.local/bin y este binario es escribible por tu usuario, no ejecutes esta copia con sudo.

Instalación del sistema (propiedad de root, para sudo portclue). PortClue lee la evidencia más completa (restricted /proc, estado completo del cortafuegos) como root. Para eso, instala un binario propiedad de root en /usr/local/bin (el script usa sudo solo para el paso final de instalación, no para descargar o extraer):

curl -fsSL https://raw.githubusercontent.com/pbxqdown/portclue/v0.1.2/scripts/install.sh | sh -s -- --system
sudo portclue

Anulaciones opcionales: PORTCLUE_VERSION=0.1.2 (sin la v inicial) y PORTCLUE_INSTALL_DIR para cualquiera de los dos modos.

Desinstalación:

# user install
rm ~/.local/bin/portclue
# system install
sudo rm /usr/local/bin/portclue
# or, matching how you installed:
curl -fsSL https://raw.githubusercontent.com/pbxqdown/portclue/v0.1.2/scripts/install.sh | sh -s -- --uninstall
curl -fsSL https://raw.githubusercontent.com/pbxqdown/portclue/v0.1.2/scripts/install.sh | sh -s -- --system --uninstall

Archivo de release

Descarga el portclue-VERSION-linux-ARCH.tar.gz correspondiente y SHA256SUMS desde GitHub Releases, verifica la suma de comprobación y luego instala:

sha256sum -c SHA256SUMS --ignore-missing
tar -xzf portclue-0.1.2-linux-amd64.tar.gz   # or linux-arm64
sudo install -m 0755 portclue-0.1.2-linux-amd64/portclue /usr/local/bin/portclue
portclue --version

Mapeo de arquitecturas:

uname -m	Archive
x86_64	linux-amd64
aarch64, arm64	linux-arm64

Cada archivo incluye el binario, el README, la licencia Apache-2.0 y los avisos de terceros.

Instalación con Go