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 sockets, processos, 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 está acessível a partir da internet pública. Expressões de firewall não suportadas produzem UNKNOWN.

O que ele lê

• Listeners TCP através de NETLINK_INET_DIAG, não por meio de scraping da saída de ss
• Propriedade do processo, executável, linha de comando, cgroup e network namespace 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 pertence uma porta 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 em /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 interrompe 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 de Release correspondente do GitHub, verifica o 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, pertencente a você:

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 relata 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 procura 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 (pertencente ao 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 pertencente ao 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:

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.25+:

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

Isso coloca o binário em $(go env GOPATH)/bin. Prefira o arquivo de Release verificado por checksum ou o script de instalação quando quiser artefatos de instalação reproduzíveis.

Compilar e executar a partir do código-fonte

Requisitos: Linux e Go 1.25 ou mais recente.

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

O modo de visão geral aceita filtros opcionais (campos ignorados permanecem sem restrição):

./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 aceita uma lista separada por vírgulas de ALL_INTERFACES, SPECIFIC_INTERFACE e LOOPBACK_ONLY. --source aceita host e/ou docker. --min-confidence mantém entradas iguais ou acima de HIGH, MEDIUM, LOW, ou UNKNOWN. Essas flags se aplicam apenas quando PORT é omitido.

Executar sem root ainda fornece evidências úteis de listener, mapeamento do Docker e endereço de bind. A identidade do processo e as evidências de firewall podem estar incompletas quando /proc ou o estado do firewall está restrito; o PortClue relata isso em Incomplete evidence. Use sudo para o resultado mais completo:

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

JSON versionado

As formas JSON são destinadas a scripts e agentes. O JSON de visão geral usa schema_version: 2, mode: "overview" e entries com service_identity e bind_scope. Um relatório detalhado usa schema_version: 1, query, verdict, paths com service_identity, unknowns e warnings.

Dentro de uma versão de schema, os nomes e significados dos campos existentes são tratados como estáveis. Novos campos opcionais podem ser adicionados. Uma remoção, renomeação ou mudança de significado incompatível requer um novo schema_version. Ambos os contratos têm testes de regressão.

Vereditos

Suportado na v0.1

• Linux, TCP, network namespace do host
• Análise de listener IPv4 e filtragem local
• Classificação correta de listener/bind IPv6; simulação completa de firewall IPv6 não é prometida
• Cadeias base simples de nftables/iptables, regras diretas de porta de destino TCP e políticas base
• Atribuição de porta publicada em bridge do Docker
• Atribuição de serviço TCP ativado por socket systemd
• Saída em terminal e JSON
• Filtros de visão geral: --bind-scope, --source, --min-confidence

Não incluído: UDP, Podman, Kubernetes, grupos de segurança de nuvem, descoberta de roteador, varredura remota, eBPF, monitoramento contínuo ou remediação.

Comportamento conservador do firewall

O PortClue intencionalmente não tenta implementar toda a máquina virtual do Netfilter. A primeira versão entende um pequeno conjunto de regras diretas. Múltiplas cadeias base, jumps, sets, maps, fib, expressões dinâmicas ou outra lógica não reconhecida causam UNKNOWN quando podem afetar a consulta. Isso é mais seguro do que tratar silenciosamente uma regra não analisada como accept ou drop.

Desenvolvimento

Consulte CONTRIBUTING.md para escopo, testes e como relatar resultados de firewall UNKNOWN.

make check
make release VERSION=0.1.2

make release requer uma árvore de trabalho Git limpa e cria arquivos versionados amd64/arm64 mais dist/SHA256SUMS. Enviar uma tag v* para o remoto GitHub configurado executa as mesmas verificações e cria uma release no GitHub. Nenhuma tag é criada pelo Makefile.

O design de longo prazo mantém o analisador, o modelo causal e os renderizadores neutros em relação à plataforma. Linux é o primeiro backend de evidências; Windows é provavelmente o segundo backend se o protótipo Linux conquistar uso real.

Licença

O PortClue é licenciado sob a Apache License 2.0. Consulte LICENSE. Os arquivos binários também incluem THIRD_PARTY_NOTICES.

Consulte CHANGELOG.md para o histórico de releases e notas de compatibilidade do JSON, SECURITY.md para versões suportadas e relato privado de vulnerabilidades, e CONTRIBUTING.md para contribuir.