ALL_INTERFACES, SPECIFIC_INTERFACE et LOOPBACK_ONLY décrivent où un socket accepte le trafic. Ils ne prétendent délibérément pas qu'un pare-feu l'autorise. Inspectez un port pour l'analyse complète du pare-feu local :

[!IMPORTANT] PortClue v0.1 est un prototype Linux précoce et conservateur. POTENTIAL signifie que le chemin local observé autorise le trafic ; il ne prétend pas qu'un port est joignable depuis l'internet public. Les expressions de pare-feu non prises en charge produisent UNKNOWN.

Ce qu'il lit

• Les écouteurs TCP via NETLINK_INET_DIAG, et non en analysant la sortie de ss
• La propriété des processus, l'exécutable, la ligne de commande, le cgroup et l'espace de noms réseau via /proc
• Les descriptions d'unités systemd à partir des fichiers d'unités installés et les déclencheurs de socket actifs via systemctl show
• nftables via nft --json list ruleset
• iptables via iptables-save lorsque nftables n'est pas disponible
• Les ports publiés par Docker via l'API HTTP locale du moteur Docker, y compris l'image et les labels

Identité du service

PortClue identifie à quoi appartient un port avant d'expliquer l'exposition. Les preuves sont classées dans cet ordre :

1. l'exécutable observé, l'unité systemd et le déclencheur de socket actif ;
2. l'image Docker, le nom du conteneur et les labels ;
3. le catalogue de services embarqué et sélectionné ;
4. la convention de port locale /etc/services.

Un propriétaire réel prime toujours sur un nom de port conventionnel. Si seule la convention de port est connue, l'identité est explicitement marquée avec une confiance LOW. Le catalogue embarqué est stocké dans internal/identify/catalog.json et est livré à l'intérieur du binaire unique ; PortClue ne télécharge pas de données d'identité à l'exécution.

PortClue est en lecture seule. Il ne se connecte pas au port interrogé, ne scanne pas un autre hôte, ne modifie pas les règles de pare-feu, n'arrête pas de processus ou de conteneurs, ne téléverse pas de données et n'exécute pas de démon.

Installation

Script d'installation (recommandé)

Fonctionne sous Linux (amd64 et arm64). Le script télécharge l'archive GitHub Release correspondante, vérifie SHA256SUMS et installe un binaire unique. Il ne modifie pas la configuration du shell.

Installation utilisateur (par défaut, sans root). Installe dans ~/.local/bin, vous en êtes propriétaire :

Une installation utilisateur s'exécute sans root et rapporte les preuves disponibles pour votre compte, en signalant ce qui manque. Cela suffit pour explorer les écouteurs et les mappages Docker. Comme sudo ne recherche pas ~/.local/bin et que ce binaire est modifiable par votre utilisateur, n'exécutez pas cette copie avec sudo.

Installation système (appartenant à root, pour sudo portclue). PortClue lit les preuves les plus complètes (restreintes /proc, état complet du pare-feu) en tant que root. Pour cela, installez un binaire appartenant à root dans /usr/local/bin (le script utilise sudo uniquement pour l'étape d'installation finale, pas pour le téléchargement ou l'extraction) :

Substitutions facultatives : PORTCLUE_VERSION=0.1.2 (sans v initial) et PORTCLUE_INSTALL_DIR pour l'un ou l'autre mode.

Désinstallation :

Archive de release

Téléchargez le fichier correspondant portclue-VERSION-linux-ARCH.tar.gz et SHA256SUMS depuis GitHub Releases, vérifiez la somme de contrôle, puis installez :

Correspondance des architectures :

Chaque archive inclut le binaire, le README, la licence Apache-2.0 et les mentions tierces.

Installation via Go

Nécessite Linux et Go 1.25+ :

Cela place le binaire dans $(go env GOPATH)/bin. Préférez l'archive de release vérifiée par somme de contrôle ou le script d'installation lorsque vous voulez des artefacts d'installation reproductibles.

Compiler et exécuter depuis les sources

Prérequis : Linux et Go 1.25 ou plus récent.

Le mode aperçu accepte des filtres facultatifs (les champs ignorés restent non contraints) :

--bind-scope accepte une liste séparée par des virgules de ALL_INTERFACES, SPECIFIC_INTERFACE et LOOPBACK_ONLY. --source accepte host et/ou docker. --min-confidence conserve les entrées égales ou supérieures à HIGH, MEDIUM, LOW, ou UNKNOWN. Ces options ne s'appliquent que lorsque PORT est omis.

L'exécution sans root fournit tout de même des preuves utiles sur les écouteurs, les mappages Docker et les adresses de bind. L'identité des processus et les preuves de pare-feu peuvent être incomplètes lorsque /proc ou l'état du pare-feu est restreint ; PortClue le signale sous Incomplete evidence. Utilisez sudo pour le résultat le plus complet :

JSON versionné

Les formes JSON sont destinées aux scripts et aux agents. Le JSON d'aperçu utilise schema_version: 2, mode: "overview" et entries avec service_identity et bind_scope. Un rapport détaillé utilise schema_version: 1, query, verdict, paths avec service_identity, unknowns et warnings.

Au sein d'une version de schéma, les noms et significations des champs existants sont traités comme stables. De nouveaux champs facultatifs peuvent être ajoutés. Une suppression, un renommage ou un changement de signification incompatible nécessite un nouveau schema_version. Les deux contrats disposent de tests de régression.

Verdicts

Pris en charge dans la v0.1

• Linux, TCP, espace de noms réseau de l'hôte
• Analyse des écouteurs IPv4 et du filtrage local
• classification correcte des écouteurs/binds IPv6 ; la simulation complète du pare-feu IPv6 n'est pas garantie
• chaînes de base nftables/iptables simples, règles directes de port de destination TCP et politiques de base
• attribution des ports publiés sur le bridge Docker
• attribution des services TCP activés par socket systemd
• sortie terminal et JSON
• filtres d'aperçu : --bind-scope, --source, --min-confidence

Non inclus : UDP, Podman, Kubernetes, groupes de sécurité cloud, découverte de routeur, scan à distance, eBPF, surveillance continue ou remédiation.

Comportement conservateur du pare-feu

PortClue n'essaie intentionnellement pas d'implémenter l'intégralité de la machine virtuelle Netfilter. La première version comprend un petit ensemble de règles directes. Plusieurs chaînes de base, sauts, ensembles, maps, fib, expressions dynamiques ou toute autre logique non reconnue provoquent UNKNOWN lorsqu'ils peuvent affecter la requête. C'est plus sûr que de traiter silencieusement une règle non analysée comme accept ou drop.

Développement

Voir CONTRIBUTING.md pour le périmètre, les tests et la manière de signaler les résultats de pare-feu UNKNOWN.

make release nécessite un arbre de travail Git propre et crée des archives versionnées amd64/arm64 ainsi que dist/SHA256SUMS. Pousser un tag v* vers le dépôt distant GitHub configuré exécute les mêmes vérifications et crée une release GitHub. Aucun tag n'est créé par le Makefile.

La conception à long terme maintient l'analyseur, le modèle causal et les moteurs de rendu indépendants de la plateforme. Linux est le premier backend de preuves ; Windows est probablement le second backend si le prototype Linux gagne une réelle utilisation.

Licence

PortClue est sous licence Apache License 2.0. Voir LICENSE. Les archives binaires incluent également THIRD_PARTY_NOTICES.

Voir CHANGELOG.md pour l'historique des versions et les notes de compatibilité JSON, SECURITY.md pour les versions prises en charge et le signalement privé de vulnérabilités, et CONTRIBUTING.md pour contribuer.