PortClue

PortClue 解释Linux 机器上的某个 TCP 端口为何可能或不可能被访问。 它将套接字、进程、防火墙和 Docker 状态转化为一条简短的证据链， 而不是让你手动关联 ss、/proc、nftables、iptables 和 docker inspect。

不带端口运行它，可以发现哪些本地 TCP 端点值得关注：

$ 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 和 LOOPBACK_ONLY 描述的是套接字在何处接受流量。 它们刻意不声称防火墙允许该流量。 检查某个端口以获取完整的本地防火墙分析：

$ 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 是一个早期、保守的 Linux 原型。POTENTIAL 意味着 观察到的本地路径允许流量；它并不声称该端口可从公网访问。 不支持的防火墙表达式会产生 UNKNOWN。

它读取什么

• 通过 NETLINK_INET_DIAG 获取 TCP 监听器，而非抓取 ss 输出
• 通过 /proc 获取进程归属、可执行文件、命令行、cgroup 和网络命名空间
• 从已安装的单元文件获取 systemd 单元描述，并通过 systemctl show 获取活动套接字触发器
• 通过 nft --json list ruleset 获取 nftables
• 当 nftables 不可用时，通过 iptables-save 获取 iptables
• 通过本地 Docker Engine HTTP API 获取 Docker 发布的端口，包括镜像和标签

服务身份

PortClue 在解释暴露情况之前，先识别端口属于什么。证据按以下顺序排列：

1. 观察到的可执行文件、systemd 单元和活动套接字触发器；
2. Docker 镜像、容器名称和标签；
3. 内嵌的精选服务目录；
4. 本地 /etc/services 端口约定。

实际所有者始终覆盖约定端口名称。如果只知道端口约定， 身份会被明确标记为 LOW 置信度。内嵌目录存储在 internal/identify/catalog.json 中，并随单个二进制文件一起发布； PortClue 不会在运行时下载身份数据。

PortClue 是只读的。它不会连接到所查询的端口、扫描其他主机、 更改防火墙规则、停止进程或容器、上传数据，也不会运行守护进程。

安装

安装脚本（推荐）

在 Linux（amd64 和 arm64）上运行。该脚本下载匹配的 GitHub Release 归档文件，验证 SHA256SUMS，并安装单个二进制文件。它 不会修改 shell 配置。

用户安装（默认，无需 root）。 安装到 ~/.local/bin，归你所有：

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

用户安装无需 root 即可运行，并报告你的账户可用的证据， 同时注明缺失的内容。这足以探索监听器和 Docker 映射。由于 sudo 不会搜索 ~/.local/bin，且此二进制文件 对你的用户可写，请勿使用 sudo 运行此副本。

系统安装（root 所有，用于 sudo portclue）。 PortClue 以 root 身份读取最 完整的证据（受限的 /proc、完整的防火墙状态）。为此， 将 root 所有的二进制文件安装到 /usr/local/bin（该脚本仅在 最终安装步骤使用 sudo，下载或解压时不使用）：

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

可选覆盖：PORTCLUE_VERSION=0.1.2（不带前导 v）和 PORTCLUE_INSTALL_DIR，适用于任一模式。

卸载：

# 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

Release 归档文件

从 GitHub Releases 下载匹配的 portclue-VERSION-linux-ARCH.tar.gz 和 SHA256SUMS，验证 校验和，然后安装：

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

架构映射：

每个归档文件包含二进制文件、README、Apache-2.0 许可证和第三方声明。

Go 安装

需要 Linux 和 Go 1.25+：

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

这会将二进制文件放入 $(go env GOPATH)/bin。当你需要可复现的 安装产物时，优先使用经过校验和验证的 Release 归档文件或安装脚本。

从源码构建和运行

要求：Linux 和 Go 1.25 或更新版本。

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

概览模式接受可选过滤器（被忽略的字段保持不受约束）：

./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 接受以逗号分隔的 ALL_INTERFACES、 SPECIFIC_INTERFACE 和 LOOPBACK_ONLY 列表。--source 接受 host 和/或 docker。--min-confidence 保留等于或高于 HIGH、MEDIUM、LOW 或 UNKNOWN 的条目。这些标志仅在省略 PORT 时适用。

不以 root 身份运行仍可提供有用的监听器、Docker 映射和绑定地址 证据。当 /proc 或防火墙状态受限时，进程身份和防火墙证据可能不完整； PortClue 会在 Incomplete evidence 下报告这一点。 使用 sudo 获得最完整的结果：

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

版本化 JSON

JSON 形式面向脚本和代理。概览 JSON 使用 schema_version: 2、mode: "overview"，以及带有 service_identity 和 bind_scope 的 entries。详细报告使用 schema_version: 1、query、verdict、带有 service_identity、unknowns 和 warnings 的 paths。

在同一 schema 版本内，现有字段名称和含义被视为稳定。 可能会添加新的可选字段。删除、重命名或不兼容的含义变更 需要新的 schema_version。两个契约都有回归测试。

判定

v0.1 支持的内容

• Linux、TCP、主机网络命名空间
• IPv4 监听器和本地过滤分析
• 正确的 IPv6 监听器/绑定分类；不承诺完整的 IPv6 防火墙模拟
• 简单的 nftables/iptables 基础链、直接的 TCP 目标端口规则和基础策略
• Docker 桥接发布端口归属
• systemd 套接字激活的 TCP 服务归属
• 终端和 JSON 输出
• 概览过滤器：--bind-scope、--source、--min-confidence

不包含：UDP、Podman、Kubernetes、云安全组、路由器发现、 远程扫描、eBPF、持续监控或修复。

保守的防火墙行为

PortClue 有意不尝试实现整个 Netfilter 虚拟机。 第一个版本理解一小组直接规则。多个基础 链、跳转、集合、映射、fib、动态表达式或其他无法识别的逻辑 在可能影响查询时会导致 UNKNOWN。这比默默地将 未解析的规则视为接受或丢弃更安全。

开发

有关范围、测试以及如何报告 防火墙 UNKNOWN 结果，请参阅 CONTRIBUTING.md。

make check
make release VERSION=0.1.2

make release 需要干净的 Git 工作树，并创建版本化的 amd64/arm64 归档文件以及 dist/SHA256SUMS。将 v* 标签推送到配置的 GitHub 远程会运行相同的检查并创建 GitHub release。Makefile 不会创建 任何标签。

长期设计保持分析器、因果模型和渲染器平台中立。 Linux 是第一个证据后端；如果 Linux 原型获得实际使用，Windows 可能是第二个后端。

许可证

PortClue 在 Apache License 2.0 下授权。请参阅 LICENSE。 二进制归档文件还包含 THIRD_PARTY_NOTICES。

有关发布历史和 JSON 兼容性说明，请参阅 CHANGELOG.md， 有关支持的版本和私有漏洞报告，请参阅 SECURITY.md， 要贡献，请参阅 CONTRIBUTING.md。