PortClue

O PortClue explica por que uma porta TCP em uma máquina Linux pode ou não estar acessível. Ele transforma o estado de socket, processo, firewall e Docker em uma curta cadeia de evidências, em vez de fazer você correlacionar ss, /proc, nftables, iptables e docker inspect manualmente.

Execute-o sem uma porta para descobrir quais endpoints TCP locais merecem atenção:

$ 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 e LOOPBACK_ONLY descrevem onde um socket aceita tráfego. Eles deliberadamente não afirmam que um firewall o permite. Inspecione uma porta para obter a análise completa do firewall 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] O PortClue v0.1 é um protótipo Linux inicial e conservador. POTENTIAL significa que o caminho local observado permite tráfego; ele não afirma que uma porta é acessível a partir da internet pública. Expressões de firewall não suportadas produzem UNKNOWN.

Por que não ss ou lsof

• Ele não precisa deles. Os listeners vêm de NETLINK_INET_DIAG, a mesma interface do kernel que o ss usa, e os detalhes do processo vêm de /proc. Nada é extraído da saída de outra ferramenta, então um contêiner que não tem nem ss nem lsof ainda obtém o listener e seu proprietário. A análise de firewall executa nft ou iptables-save e reporta UNKNOWN sem eles.
• Ele responde à próxima pergunta. ss -ltnp fornece o socket e o PID. Se esse bind é apenas loopback, se uma regra de firewall o permite e se a porta é uma publicação do Docker em vez de um listener do host é um trabalho que você, de outra forma, faria manualmente.
• Ele não vai adivinhar. Uma regra de firewall que o PortClue não consegue modelar produz UNKNOWN, nunca uma resposta confiante e errada.

O que ele lê

• Listeners TCP através de NETLINK_INET_DIAG, não por raspagem da saída do ss
• propriedade do processo, executável, linha de comando, cgroup e namespace de rede através de /proc
• descrições de unidades systemd a partir de arquivos de unidade instalados e gatilhos de socket ativos através de systemctl show
• nftables através de nft --json list ruleset
• iptables através de iptables-save quando o nftables não está disponível
• portas publicadas do Docker através da API HTTP local do Docker Engine, incluindo imagem e labels

Identidade do serviço

O PortClue identifica a que uma porta pertence antes de explicar a exposição. As evidências são classificadas nesta ordem:

1. executável observado, unidade systemd e gatilho de socket ativo;
2. imagem Docker, nome do contêiner e labels;
3. o catálogo de serviços curado embutido;
4. a convenção de porta local de /etc/services.

Um proprietário real sempre tem precedência sobre um nome de porta convencional. Se apenas a convenção de porta for conhecida, a identidade é explicitamente marcada com confiança LOW. O catálogo embutido é armazenado em internal/identify/catalog.json e é distribuído dentro do binário único; o PortClue não baixa dados de identidade em tempo de execução.

O PortClue é somente leitura. Ele não se conecta à porta consultada, não escaneia outro host, não altera regras de firewall, não para processos ou contêineres, não envia dados e não executa um daemon.

Instalação

Script de instalação (recomendado)

Executa em Linux (amd64 e arm64). O script baixa o arquivo GitHub Release correspondente, verifica SHA256SUMS e instala um único binário. Ele não modifica a configuração do shell.

Instalação de usuário (padrão, sem root). Instala em ~/.local/bin, de sua propriedade:

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

Uma instalação de usuário é executada sem root e reporta as evidências disponíveis para sua conta, observando o que está faltando. Isso é suficiente para explorar listeners e mapeamentos do Docker. Como o sudo não pesquisa em ~/.local/bin e este binário é gravável pelo seu usuário, não execute esta cópia com sudo.

Instalação de sistema (de propriedade do root, para sudo portclue). O PortClue lê as evidências mais completas (restrito /proc, estado completo do firewall) como root. Para isso, instale um binário de propriedade do root em /usr/local/bin (o script usa sudo apenas para a etapa final de instalação, não para baixar ou extrair):

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

Substituições opcionais: PORTCLUE_VERSION=0.1.2 (sem o v inicial) e PORTCLUE_INSTALL_DIR para qualquer um dos modos.

Desinstalação:

# 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

Arquivo de release

Baixe o portclue-VERSION-linux-ARCH.tar.gz correspondente e o SHA256SUMS de GitHub Releases, verifique o checksum e então instale:

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

Mapeamento de arquitetura:

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

Cada arquivo inclui o binário, o README, a licença Apache-2.0 e os avisos de terceiros.

Instalação via Go

Requer Linux e Go 1.27+: