pbxqdown/portclueОбъясните, почему TCP-порт Linux может быть доступен или недоступен
PortClue объясняет, почему TCP-порт на машине с Linux может быть или не быть доступен.
Он превращает состояние сокетов, процессов, межсетевого экрана и 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, а не путём разбора вывода ss/procsystemctl shownft --json list rulesetiptables-save, когда nftables недоступенPortClue определяет, чему принадлежит порт, прежде чем объяснять его доступность. Доказательства ранжируются в следующем порядке:
/etc/services.Фактический владелец всегда имеет приоритет над условным именем порта. Если известно только
соглашение о портах, идентификация явно помечается уровнем достоверности LOW. Встроенный каталог
хранится в internal/identify/catalog.json и поставляется
внутри единого бинарного файла; PortClue не загружает данные идентификации во время выполнения.
PortClue работает только на чтение. Он не подключается к запрашиваемому порту, не сканирует другой хост, не изменяет правила межсетевого экрана, не останавливает процессы или контейнеры, не загружает данные и не запускает демон.
Работает на Linux (amd64 и arm64). Скрипт загружает соответствующий архив
GitHub Release, проверяет SHA256SUMS и устанавливает единый бинарный файл. Он
не изменяет конфигурацию оболочки.
Пользовательская установка (по умолчанию, без 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 читает наиболее
полные доказательства (ограниченный /proc, полное состояние межсетевого экрана) от имени root. Для этого
установите принадлежащий 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
Загрузите соответствующий portclue-VERSION-linux-ARCH.tar.gz и SHA256SUMS из
GitHub Releases, проверьте
контрольную сумму, затем установите:
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
Сопоставление архитектур:
uname -m | Архив |
|---|---|
x86_64 | linux-amd64 |
aarch64, arm64 | linux-arm64 |
Каждый архив включает бинарный файл, README, лицензию Apache-2.0 и уведомления третьих сторон.
Требуется Linux и Go 1.25+:
go install github.com/pbxqdown/portclue/cmd/[email protected]
Это помещает бинарный файл в $(go env GOPATH)/bin. Предпочитайте проверенный по контрольной сумме
архив релиза или скрипт установки, когда вам нужны воспроизводимые артефакты установки.
Требования: 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 обзора использует
schema_version: 2, mode: "overview" и entries с
service_identity и bind_scope. Подробный отчёт использует
schema_version: 1, query, verdict, paths с
service_identity, unknowns и warnings.
В пределах версии схемы существующие имена полей и их значения считаются стабильными.
Могут добавляться новые необязательные поля. Удаление, переименование или несовместимое изменение значения
требует новой schema_version. Оба контракта имеют регрессионные тесты.
| Вердикт | Значение |
|---|---|
POTENTIAL | Наблюдается не-loopback локальный путь, и поддерживаемые доказательства межсетевого экрана его допускают. Внешняя маршрутизация неизвестна. |
NOT_EXPOSED_LOCALLY | Слушатель/сопоставление отсутствует, привязка только к loopback, или поддерживаемые доказательства локального межсетевого экрана блокируют путь. |
UNKNOWN | Требуемый факт недоступен или потенциально значимое выражение межсетевого экрана не поддерживается. |
CONFIRMED | Зарезервировано для будущей явной внешней проверки. Текущий CLI, работающий только локально, никогда его не выдаёт. |
--bind-scope, --source, --min-confidenceНе включено: UDP, Podman, Kubernetes, облачные группы безопасности, обнаружение маршрутизаторов, удалённое сканирование, eBPF, непрерывный мониторинг или устранение проблем.
PortClue намеренно не пытается реализовать всю виртуальную машину Netfilter. Первая версия
понимает небольшой набор прямых правил. Несколько базовых цепочек, переходы, наборы, карты, fib,
динамические выражения или другая нераспознанная логика вызывают UNKNOWN, когда они могут повлиять на запрос.
Это безопаснее, чем молча трактовать неразобранное правило как accept или drop.
См. CONTRIBUTING.md для информации об области охвата, тестировании и о том, как сообщать
о результатах UNKNOWN межсетевого экрана.
make check
make release VERSION=0.1.2
make release требует чистого рабочего дерева Git и создаёт версионированные архивы amd64/arm64
плюс dist/SHA256SUMS. Отправка тега v* в настроенный
удалённый репозиторий GitHub запускает те же проверки и создаёт релиз GitHub. Makefile не создаёт
тег.
Долгосрочный дизайн сохраняет анализатор, причинную модель и средства визуализации платформенно-нейтральными. Linux — первый бэкенд доказательств; Windows — вероятный второй бэкенд, если Linux-прототип получит реальное применение.
PortClue лицензирован под Apache License 2.0. См. LICENSE. Бинарные архивы также включают THIRD_PARTY_NOTICES.
См. CHANGELOG.md для истории релизов и заметок о совместимости JSON, SECURITY.md для поддерживаемых версий и приватного сообщения об уязвимостях, и CONTRIBUTING.md для участия в разработке.