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.

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, incluyendo imagen y 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 del puerto, 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 demonio.

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 e informa la evidencia disponible para tu cuenta, señalando lo que falta. Esto es suficiente para explorar listeners y mapeos de Docker. Debido a que 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 ( /proc restringido, 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 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, 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:

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

Instalación con Go

Requiere Linux y Go 1.25+:

go install github.com/pbxqdown/portclue/cmd/[email protected]

Esto coloca el binario en $(go env GOPATH)/bin. Prefiere el archivo de release verificado con suma de comprobación o el script de instalación cuando quieras artefactos de instalación reproducibles.

Compilar y ejecutar desde el código fuente

Requisitos: Linux y Go 1.25 o superior.

go build -o portclue ./cmd/portclue
./portclue
./portclue --json
./portclue 8080
./portclue --json 8080

El modo de vista general acepta filtros opcionales (los campos ignorados permanecen sin restricción):

./portclue --bind-scope ALL_INTERFACES,SPECIFIC_INTERFACE
./portclue --source docker
./portclue --min-confidence MEDIUM
./portclue --json --bind-scope ALL_INTERFACES --min-confidence HIGH

--bind-scope acepta una lista separada por comas de ALL_INTERFACES, SPECIFIC_INTERFACE y LOOPBACK_ONLY. --source acepta host y/o docker. --min-confidence mantiene las entradas en o por encima de HIGH, MEDIUM, LOW, o UNKNOWN. Estas banderas se aplican solo cuando se omite PORT.

Ejecutar sin root aún proporciona evidencia útil de listeners, mapeos de Docker y direcciones de bind. La identidad del proceso y la evidencia del cortafuegos pueden estar incompletas cuando /proc o el estado del cortafuegos está restringido; PortClue lo informa bajo Incomplete evidence. Usa sudo para el resultado más completo:

sudo ./portclue
sudo ./portclue --bind-scope ALL_INTERFACES,SPECIFIC_INTERFACE
sudo ./portclue 8080

JSON versionado

Las formas JSON están destinadas a scripts y agentes. El JSON de vista general usa schema_version: 2, mode: "overview" y entries con service_identity y bind_scope. Un informe detallado usa schema_version: 1, query, verdict, paths con service_identity, unknowns y warnings.

Dentro de una versión de esquema, los nombres y significados de los campos existentes se tratan como estables. Se pueden añadir nuevos campos opcionales. Una eliminación, cambio de nombre o cambio de significado incompatible requiere un nuevo schema_version. Ambos contratos tienen pruebas de regresión.

Veredictos

Soportado en v0.1

• Linux, TCP, espacio de nombres de red del host
• Análisis de listeners IPv4 y filtrado local
• Clasificación correcta de listeners/bind IPv6; no se promete simulación completa de cortafuegos IPv6
• Cadenas base simples de nftables/iptables, reglas directas de puerto de destino TCP y políticas base
• Atribución de puertos publicados en el puente de Docker
• Atribución de servicios TCP activados por socket de systemd
• Salida de terminal y JSON
• Filtros de vista general: --bind-scope, --source, --min-confidence

No incluido: UDP, Podman, Kubernetes, grupos de seguridad en la nube, descubrimiento de routers, escaneo remoto, eBPF, monitoreo continuo o remediación.

Comportamiento conservador del cortafuegos

PortClue intencionalmente no intenta implementar toda la máquina virtual de Netfilter. La primera versión entiende un pequeño conjunto de reglas directas. Múltiples cadenas base, saltos, sets, maps, fib, expresiones dinámicas u otra lógica no reconocida causan UNKNOWN cuando pueden afectar la consulta. Esto es más seguro que tratar silenciosamente una regla no analizada como accept o drop.

Desarrollo

Consulta CONTRIBUTING.md para el alcance, las pruebas y cómo reportar resultados de cortafuegos UNKNOWN.

make check
make release VERSION=0.1.2

make release requiere un árbol de trabajo Git limpio y crea archivos versionados amd64/arm64 más dist/SHA256SUMS. Empujar una etiqueta v* al remoto de GitHub configurado ejecuta las mismas comprobaciones y crea un release de GitHub. El Makefile no crea ninguna etiqueta.

El diseño a largo plazo mantiene el analizador, el modelo causal y los renderizadores neutrales respecto a la plataforma. Linux es el primer backend de evidencia; Windows es el probable segundo backend si el prototipo de Linux gana uso real.

Licencia

PortClue está licenciado bajo la Apache License 2.0. Consulta LICENSE. Los archivos binarios también incluyen THIRD_PARTY_NOTICES.

Consulta CHANGELOG.md para el historial de versiones y notas de compatibilidad JSON, SECURITY.md para las versiones soportadas y el reporte privado de vulnerabilidades, y CONTRIBUTING.md para contribuir.