ALL_INTERFACES, SPECIFIC_INTERFACE e LOOPBACK_ONLY descrivono dove un socket accetta traffico. Deliberatamente non affermano che un firewall lo permetta. Ispeziona una porta per l'analisi completa del firewall locale:

[!IMPORTANT] PortClue v0.1 è un prototipo Linux precoce e conservativo. POTENTIAL significa che il percorso locale osservato consente il traffico; non afferma che una porta sia raggiungibile da internet pubblico. Le espressioni firewall non supportate producono UNKNOWN.

Cosa legge

• Listener TCP tramite NETLINK_INET_DIAG, non estraendo l'output di ss
• Proprietà del processo, eseguibile, riga di comando, cgroup e network namespace tramite /proc
• Descrizioni delle unit systemd dai file unit installati e trigger socket attivi tramite systemctl show
• nftables tramite nft --json list ruleset
• iptables tramite iptables-save quando nftables non è disponibile
• Porte pubblicate da Docker tramite l'API HTTP locale di Docker Engine, inclusi immagine ed etichette

Identità del servizio

PortClue identifica a cosa appartiene una porta prima di spiegare l'esposizione. Le prove sono ordinate in questo modo:

1. eseguibile osservato, unit systemd e trigger socket attivo;
2. immagine Docker, nome del container ed etichette;
3. il catalogo di servizi curato integrato;
4. la convenzione di porta locale /etc/services.

Un proprietario effettivo prevale sempre su un nome di porta convenzionale. Se è nota solo la convenzione di porta, l'identità è esplicitamente contrassegnata con confidenza LOW. Il catalogo integrato è memorizzato in internal/identify/catalog.json e viene distribuito all'interno del singolo binario; PortClue non scarica dati di identità a runtime.

PortClue è in sola lettura. Non si connette alla porta interrogata, non scansiona un altro host, non modifica regole del firewall, non arresta processi o container, non carica dati e non esegue un daemon.

Installazione

Script di installazione (consigliato)

Funziona su Linux (amd64 e arm64). Lo script scarica l'archivio GitHub Release corrispondente, verifica SHA256SUMS e installa un singolo binario. Non modifica la configurazione della shell.

Installazione utente (predefinita, senza root). Installa in ~/.local/bin, di tua proprietà:

Un'installazione utente viene eseguita senza root e riporta le prove disponibili per il tuo account, indicando ciò che manca. Questo è sufficiente per esplorare i listener e le mappature Docker. Poiché sudo non cerca in ~/.local/bin e questo binario è scrivibile dal tuo utente, non eseguire questa copia con sudo.

Installazione di sistema (di proprietà di root, per sudo portclue). PortClue legge le prove più complete (restricted /proc, stato completo del firewall) come root. Per questo, installa un binario di proprietà di root in /usr/local/bin (lo script usa sudo solo per il passaggio finale di installazione, non per il download o l'estrazione):

Override opzionali: PORTCLUE_VERSION=0.1.2 (senza v iniziale) e PORTCLUE_INSTALL_DIR per entrambe le modalità.

Disinstallazione:

Archivio Release

Scarica il file portclue-VERSION-linux-ARCH.tar.gz corrispondente e SHA256SUMS da GitHub Releases, verifica il checksum, quindi installa:

Mappatura delle architetture:

Ogni archivio include il binario, il README, la licenza Apache-2.0 e le note di terze parti.

Installazione con Go

Richiede Linux e Go 1.25+:

Questo mette il binario in $(go env GOPATH)/bin. Preferisci l'archivio release verificato tramite checksum o lo script di installazione quando desideri artefatti di installazione riproducibili.

Compilazione ed esecuzione dal sorgente

Requisiti: Linux e Go 1.25 o superiore.

La modalità panoramica accetta filtri opzionali (i campi ignorati rimangono non vincolati):

--bind-scope accetta un elenco separato da virgole di ALL_INTERFACES, SPECIFIC_INTERFACE e LOOPBACK_ONLY. --source accetta host e/o docker. --min-confidence mantiene le voci pari o superiori a HIGH, MEDIUM, LOW, o UNKNOWN. Questi flag si applicano solo quando PORT è omesso.

L'esecuzione senza root fornisce comunque prove utili su listener, mappature Docker e indirizzi di bind. L'identità del processo e le prove del firewall possono essere incomplete quando /proc o lo stato del firewall sono limitati; PortClue lo segnala sotto Incomplete evidence. Usa sudo per il risultato più completo:

JSON con versione

Le forme JSON sono destinate a script e agenti. Il JSON panoramico usa schema_version: 2, mode: "overview" e entries con service_identity e bind_scope. Un report dettagliato usa schema_version: 1, query, verdict, paths con service_identity, unknowns e warnings.

All'interno di una versione dello schema, i nomi e i significati dei campi esistenti sono considerati stabili. Nuovi campi opzionali possono essere aggiunti. Una rimozione, una rinomina o una modifica incompatibile del significato richiede un nuovo schema_version. Entrambi i contratti hanno test di regressione.

Verdetti

Supportato in v0.1

• Linux, TCP, network namespace dell'host
• Analisi dei listener IPv4 e del filtraggio locale
• Corretta classificazione di listener/bind IPv6; la simulazione completa del firewall IPv6 non è garantita
• Catene base nftables/iptables semplici, regole dirette sulla porta di destinazione TCP e policy di base
• Attribuzione delle porte pubblicate su bridge Docker
• Attribuzione dei servizi TCP attivati da socket systemd
• Output su terminale e JSON
• Filtri panoramica: --bind-scope, --source, --min-confidence

Non incluso: UDP, Podman, Kubernetes, security group cloud, discovery del router, scansione remota, eBPF, monitoraggio continuo o remediation.

Comportamento conservativo del firewall

PortClue intenzionalmente non tenta di implementare l'intera macchina virtuale Netfilter. La prima versione comprende un piccolo insieme di regole dirette. Catene base multiple, jump, set, map, fib, espressioni dinamiche o altra logica non riconosciuta causano UNKNOWN quando possono influenzare la query. Questo è più sicuro che trattare silenziosamente una regola non analizzata come accept o drop.

Sviluppo

Vedi CONTRIBUTING.md per ambito, test e come segnalare risultati firewall UNKNOWN.

make release richiede un worktree Git pulito e crea archivi versionati amd64/arm64 più dist/SHA256SUMS. Il push di un tag v* verso il remoto GitHub configurato esegue gli stessi controlli e crea una release GitHub. Nessun tag viene creato dal Makefile.

Il design a lungo termine mantiene l'analizzatore, il modello causale e i renderer indipendenti dalla piattaforma. Linux è il primo backend di prove; Windows è il probabile secondo backend se il prototipo Linux otterrà un utilizzo reale.

Licenza

PortClue è distribuito sotto la Apache License 2.0. Vedi LICENSE. Gli archivi binari includono anche THIRD_PARTY_NOTICES.

Vedi CHANGELOG.md per la cronologia delle release e le note di compatibilità JSON, SECURITY.md per le versioni supportate e la segnalazione privata di vulnerabilità, e CONTRIBUTING.md per contribuire.