PortClue

يشرح PortClue لماذا قد يكون منفذ TCP على جهاز Linux قابلاً للوصول أو غير قابل للوصول. فهو يحوّل حالة المقبس (socket) والعملية وجدار الحماية و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.

ما الذي يقرأه

• مستمعو TCP عبر NETLINK_INET_DIAG، وليس عبر استخراج مخرجات ss
• ملكية العملية والملف التنفيذي وسطر الأوامر وcgroup ومساحة اسم الشبكة عبر /proc
• أوصاف وحدات systemd من ملفات الوحدات المثبّتة ومشغّلات المقابس النشطة عبر systemctl show
• nftables عبر nft --json list ruleset
• iptables عبر iptables-save عندما تكون nftables غير متاحة
• منافذ Docker المنشورة عبر واجهة HTTP المحلية لمحرك Docker، بما في ذلك الصورة والوسوم (labels)

هوية الخدمة

يحدد PortClue ما ينتمي إليه المنفذ قبل شرح التعرّض. تُرتَّب الأدلة بالترتيب التالي:

1. الملف التنفيذي المرصود، ووحدة systemd، ومشغّل المقبس النشط؛
2. صورة Docker، واسم الحاوية، والوسوم؛
3. كتالوج الخدمات المُنتقى المضمّن؛
4. اصطلاح المنفذ المحلي في /etc/services.

المالك الفعلي يتجاوز دائماً اسم المنفذ الاصطلاحي. إذا كان اصطلاح المنفذ فقط معروفاً، تُوسَم الهوية صراحةً بثقة LOW. الكتالوج المضمّن مخزّن في internal/identify/catalog.json ويُشحن داخل الملف التنفيذي الواحد؛ ولا يقوم PortClue بتنزيل بيانات الهوية في وقت التشغيل.

PortClue للقراءة فقط. فهو لا يتصل بالمنفذ المفحوص، ولا يفحص مضيفاً آخر، ولا يغيّر قواعد جدار الحماية، ولا يوقف العمليات أو الحاويات، ولا يرفع البيانات، ولا يشغّل خادماً (daemon).

التثبيت

سكربت التثبيت (موصى به)

يعمل على 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 الأدلة الأكثر اكتمالاً (/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، وتحقق من المجموع الاختباري (checksum)، ثم ثبّت:

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. يُفضَّل استخدام أرشيف الإصدار المُتحقَّق من مجموعها الاختباري أو سكربت التثبيت عندما تريد مخرجات تثبيت قابلة للتكرار.

البناء والتشغيل من المصدر

المتطلبات: 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" وentries مع service_identity وbind_scope. ويستخدم التقرير التفصيلي schema_version: 1 وquery وverdict وpaths مع service_identity وunknowns وwarnings.

ضمن إصدار مخطط واحد، تُعتبر أسماء الحقول الحالية ومعانيها مستقرة. وقد تُضاف حقول اختيارية جديدة. أما الحذف أو إعادة التسمية أو تغيير المعنى بشكل غير متوافق فيتطلب schema_version جديداً. لكلا العقدين اختبارات انحدار.

الأحكام

المدعوم في v0.1

• Linux، TCP، مساحة اسم شبكة المضيف
• تحليل مستمع IPv4 والتصفية المحلية
• تصنيف صحيح لمستمع/ربط IPv6؛ محاكاة جدار حماية IPv6 الكاملة غير مضمونة
• سلاسل أساسية بسيطة لـ nftables/iptables، وقواعد منفذ الوجهة TCP المباشرة، والسياسات الأساسية
• إسناد المنافذ المنشورة عبر جسر Docker
• إسناد خدمة TCP المُنشَّطة عبر مقبس systemd
• مخرجات الطرفية وJSON
• مرشّحات النظرة العامة: --bind-scope و--source و--min-confidence

غير مشمول: UDP، وPodman، وKubernetes، ومجموعات أمان السحابة، واكتشاف الموجّه، والفحص عن بُعد، وeBPF، والمراقبة المستمرة، أو المعالجة.

سلوك متحفظ لجدار الحماية

لا يحاول PortClue عمداً تنفيذ الآلة الافتراضية الكاملة لـ Netfilter. يفهم الإصدار الأول مجموعة صغيرة من القواعد المباشرة. وتتسبب السلاسل الأساسية المتعددة، والقفزات (jumps)، والمجموعات (sets)، والخرائط (maps)، وfib، والتعبيرات الديناميكية، أو أي منطق آخر غير معروف في إنتاج UNKNOWN عندما يمكن أن تؤثر على الاستعلام. وهذا أكثر أماناً من التعامل بصمت مع قاعدة غير محلَّلة كقبول أو إسقاط.

التطوير

راجع 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 للمساهمة.