
NetLogic هي أداة متقدمة لتحليل الشبكات والأمن السيبراني لفحص حركة المرور وتحليل الحزم واكتشاف التهديدات
مخطط سطح الهجوم السحابي الأصلي وموصل الثغرات — الإصدار 3.0
NetLogic هي منصة أمان شبكي تجمع بين مسح المنافذ النشط، وربط الثغرات (واجهة NVD الحية)، وتحليل SSL/TLS، وتدقيق أمان HTTP، وتقييم أمان DNS/البريد الإلكتروني، واكتشاف الاستيلاء على النطاقات الفرعية، واستخبارات المصادر المفتوحة السلبية، والاستقصاء النشط للثغرات، ومحرك استدلال مدعوم بالذكاء الاصطناعي، واكتشاف سلاسل الهجوم عبر المضيفين، وهندسة العوامل الاستقصائية العميقة — مُقدَّمة كـ تطبيق ويب (لوحة تحكم React + FastAPI). محرك المسح الأساسي مكتوب بلغة Python 3.9+ النقية مع مكتبات قياسية بدون أي تبعيات خارجية.
| الوحدة | الوصف |
|---|---|
| ماسح المنافذ | فحص اتصال TCP مع 43/58 منفذاً، 22 استقصاء خدمة، التقاط الشعار |
| موصل الثغرات | واجهة NVD v2.0 الحية + إثراء EPSS عبر FIRST.org |
| محلل TLS | إصدارات البروتوكول، التشفير الضعيف، POODLE/BEAST/CRIME/DROWN، انتهاء الشهادة |
| تدقيق رؤوس HTTP | HSTS، CSP، X-Frame-Options، CORS، علامات الكوكيز؛ درجة 0–100 |
| بصمة التكدس | CMS، الإطار، مزود السحابة، CDN، اكتشاف WAF من الشعار/الرأس/المحتوى |
| أمان DNS | SPF، DKIM، DMARC، DNSSEC، نقل المنطقة، درجة قابلية الانتحال |
| استخبارات المصادر المفتوحة السلبية | سجلات الشفافية للشهادات، DNS عبر DoH، بحث ASN — بدون اتصال مباشر بالهدف |
| ماسح الخدمات | استقصاءات غير مصادقة لـ Redis/Mongo/ES/Docker/K8s/etcd، 33 مسار إداري |
| كاشف الاستيلاء | اكتشاف النطاقات الفرعية عبر سجلات CT + بصمات CNAME لـ 25 مزود سحابي |
| تكامل Nuclei | غلاف لأكثر من 13 ألف قالب مجتمعي (CVE، تقنيات، تعرض، إعدادات خاطئة) — ترخيص MIT |
| خط أنابيب الدمج | بوابة إشارات متعددة الحساسات → اتفاق حتمي → تحكيم بالذكاء الاصطناعي → رسم بياني للهجوم → تقرير من 6 أقسام |
| بصمة الويب | تجزئة الأيقونة المفضلة (mmh3 متوافقة مع Shodan)، أسرار JS، علامات الإصدار، الملفات المكشوفة، كاشف الصفحة الافتراضية |
| التحليل بالذكاء الاصطناعي | OpenAI / Anthropic / OpenRouter / Ollama / Gemini / Groq / Kimi / Qwen — تدفق الرموز عبر SSE |
| محرك الاستدلال | حلقة مراقبة→استدلال→تنفيذ متكيفة مع EvidenceGraph، محرك افتراضات، انحدار الثقة، مصدر البيانات، المجدول، كتب التشغيل، كشف التغيير، التحقق النشط |
| الاستقصاء العميق | هندسة عامل لكل خدمة: ScoutAgent (استطلاع)، ProbeAgent (فحوصات CVE موجهة)، Coordinator، Sandbox |
| عامل التحقيق بالذكاء الاصطناعي | حلقة نمط ReAct: بعد الحساسات الأساسية، يقود الذكاء الاصطناعي سطح أدوات منسق ومحدد النطاق ومراجع (~35 أداة) للتحقق من الخيوط وبناء سلاسل الهجوم — مع أدوات عدوانية اختيارية (استقصاءات تعطل، إثبات حر، استغلال حر) للأهداف المصرح بها |
| محرك التحقق | إعادة تحقق بالذكاء الاصطناعي من CVE: تصميم خطط استقصاء HTTP خام من سياق CVE، التنفيذ عبر مقابس stdlib |
هناك طريقتان بالضبط لتشغيل NetLogic:
| الوضع | الأمر | ماذا يفعل |
|---|---|---|
| تطبيق ويب | netlogic --gui | يبدأ FastAPI + يخدم تطبيق React ذو الصفحة الواحدة + عامل مسح داخلي، ويولد الأسرار تلقائياً، ويفتح لوحة التحكم في متصفحك. هذه هي الطريقة الوحيدة لتشغيل تطبيق الويب. |
| واجهة أوامر | netlogic <target> [flags] |
سطح المنتج هو تطبيق الويب (لوحة تحكم React + FastAPI). محرك المسح تحت src/ يغذي المهام التي تبدأ من واجهة المستخدم.
pip install -r requirements-api.txt pip install -e .
netlogic --gui
netlogic scanme.nmap.org --full
## مرجع CLI```
netlogic [target] [flags]
نقطة الدخول هي api.cli:main (معرفة في pyproject.toml)، والتي تفوض إلى netlogic.py:main(). كل منطق المسح موجود في src/.
netlogic example.com
netlogic example.com --full
netlogic example.com --tls --headers
netlogic example.com --takeover
netlogic example.com --osint
netlogic example.com --stack
netlogic example.com --dns
netlogic 10.0.0.5 --probe
netlogic example.com --full --probe
### اختيار المنفذ```
# Quick — 43 common ports (default)
netlogic example.com --ports quick
# Full — 58 extended ports
netlogic example.com --ports full
# Custom list
netlogic example.com --ports custom=22,80,443,8080,9200
netlogic example.com --ai --ai-key $KEY
netlogic example.com --ai --ai-provider openai --ai-key $KEY --ai-model gpt-4o-mini
netlogic example.com --ai --ai-provider anthropic --ai-key $KEY
netlogic example.com --ai --ai-provider gemini --ai-key $KEY --ai-model gemini-2.0-flash
netlogic example.com --ai --ai-provider ollama
netlogic example.com --ai --ai-provider custom --ai-base-url https://... --ai-model model-name
### مزودو الذكاء الاصطناعي المدعومون
| المزود | النموذج الافتراضي | نمط API |
|---|---|---|
| `openrouter` | `anthropic/claude-sonnet-4` | OpenAI |
| `openai` | `gpt-4o-mini` | OpenAI |
| `anthropic` | `claude-3-5-sonnet-20241022` | Anthropic Messages |
| `kimi` (Moonshot) | `kimi-k2.6` | OpenAI |
| `qwen` (Alibaba) | `qwen-plus` | OpenAI |
| `groq` | `llama-3.3-70b-versatile` | OpenAI |
| `gemini` (Google) | `gemini-2.0-flash` | OpenAI |
| `ollama` | `llama3` | OpenAI |
| `custom` | محدد من قبل المستخدم | OpenAI |
### محرك الاستدلال```
# Adaptive observe→reason→act loop (deterministic by default; AI-augmented with --ai)
netlogic example.com --reason
# Multi-host world modeling — discovers in-scope neighbours, reasons per host
netlogic example.com --reason --multi-host
# Change detection — diffs against prior saved report
netlogic example.com --since-last
# Active validation — confirms hypotheses with safe non-destructive GETs
netlogic example.com --reason --active-validate
# Deep probe — per-service agent architecture with context isolation
netlogic example.com --deep-probe
بعد تشغيل المستشعرات الأساسية، يتيح وكيل اختياري على نمط ReAct للذكاء الاصطناعي قيادة أدواته الخاصة للتحقق من الخيوط وبناء سلاسل الهجوم، بدلاً من ترك إصدارات/لافتات CVE كخيوط غير مؤكدة. يقترح الذكاء الاصطناعي استدعاءات الأدوات؛ ويقوم وقت تشغيل حتمي بتنفيذها — كل أداة مقيدة بالنطاق للهدف، ومُنقّاة، ومُسجّلة كملاحظة. لا يلمس الذكاء الاصطناعي الشبكة مباشرةً أبدًا.```
netlogic example.com --ai --ai-agent
netlogic example.com --ai --agent-depth --agent-max-steps 24 --agent-max-requests 80
الوكيل لديه ~35 أداة للقراءة فقط/آمنة نشطة بشكل افتراضي: HTTP/TLS/DNS probes، و`dir_enum`، و`confirm_tech`،
و`timing_probe`، و`cve_probe` (فحوصات محددة لعلامات الـ CVE المعروفة)، و`sqli_boolean`/`sqli_time`، و`ssrf_canary`،
و`idor_diff`، و`file_disclosure`، و`browser_get` (بدون رأس، يعبر تحديات جافا سكريبت)، بالإضافة إلى مهام HackerOne
(`record_poc`، `severity_suggest`، `submit_readiness`).
**أدوات عدوانية اختيارية** — معطلة افتراضيًا، **فقط للأهداف المأذون لها / المملوكة ضمن النطاق** (لا تُستخدم أبدًا على
مسح عام أو غريب). كل منها يتطلب `--ai-agent`:
| العلم | الأداة | ما يفتحه | القيود المحفوظة |
|---|---|---|---|
| `--allow-crash-probes` | `crash_probe` | فحوصات محددة لـ CVE الانهيار/DoS (http.sys، MS15-034) قد تسبب انهيار المضيف | كتالوج ثابت من 3 CVE — ليس حرًا |
| `--allow-freeform-proof` | `http_proof` | المستوى ج: GET/HEAD/OPTIONS حر (+ POST على مسارات تشبه البحث/تسجيل الدخول/graphql) | الأنماط المدمرة + PUT/PATCH/DELETE محظورة؛ دليل، وليس تغييرًا |
| `--allow-exploit-requests` | `exploit_request` | المستوى هـ: **أي طريقة** (بما في ذلك PUT/PATCH/DELETE) + مسار/رؤوس/جسم عشوائي ضد الهدف | محدد بالنطاق؛ إغلاق فاشل للأنماط الجماعية المدمرة (DROP/TRUNCATE TABLE، `rm -rf`) وحقن رأس CR/LF؛ كل طلب يتم تدقيقه |
تحافظ ActionGate الحتمية على النواة عند `safe_active`؛ هذه الأعلام الثلاثة هي الاشتراكات الصريحة والمدققة
فوق ذلك. مثال (مختبر مملوك + نموذج محلي):```
netlogic YOUR_LAB_HOST --full --ai --ai-agent --agent-depth \
--allow-crash-probes --allow-exploit-requests \
--ai-provider ollama --ai-model gemma4:31b-cloud \
--ai-base-url http://localhost:11434/v1 --ai-key ollama
netlogic example.com --ssh-user admin --ssh-key ~/.ssh/id_rsa
netlogic example.com --ssh-user admin --ssh-pass SECRET
netlogic example.com --ssh-user admin --ssh-key ~/.ssh/id_rsa --ssh-port 2222
### المعيار```
# Fusion pipeline benchmark against recorded cassettes (oracle mode — perfect AI upper bound)
netlogic --benchmark
# With real AI model
netlogic --benchmark --benchmark-ai
# Export report
netlogic --benchmark --benchmark-export report.md
# Verbose per-subject output
netlogic --benchmark --benchmark-verbose
netlogic example.com --report terminal # terminal output (default) netlogic example.com --report json # JSON file netlogic example.com --report html # HTML report netlogic example.com --report all # terminal + JSON + HTML
netlogic example.com --out ./reports
netlogic example.com --min-cvss 7.0
netlogic example.com --no-color
### إدارة ذاكرة التخزين المؤقت لـ NVD```
netlogic --cache-stats
netlogic example.com --nvd-key YOUR_NVD_KEY
netlogic --version # Show version and exit netlogic --gui # Start web dashboard
---
## خط أنابيب الاندماج
خط أنابيب الاندماج هو مسار **المستشعرات → البوابة → التحكيم بالذكاء الاصطناعي → التوليف** يحل محل استدعاءات الذكاء الاصطناعي الأحادية ببوابة دقيقة. يوجد في `src/fusion/` (12 ملفًا).
### مخطط الإشارة (`src/fusion/signals.py`)
عقد بيانات يحمل الأدلة. كل مستشعر يصدر كائنات `Signal`:
- `source`: `probe`/`banner`/`nuclei`/`wappalyzer`/`nvd`/`osv`/`tls`/`dns`
- `kind`: `vuln`/`tech`/`exposure`/`misconfig`/`service`
- `claim`: موضوع موحد (مثل `"CVE-2021-44228"`, `"nginx"`)
- `host`, `port`, `service`, `evidence` (مقتصر على 600 حرف)
- `confidence` (0..1), `reliability` (`high`/`medium`/`low`)
- `kev`, `epss` (0..1), `cvss` (0..10), `exploit_available`, `version_matched`, `probe_confirmed`
- `exposure` dict (قابلية الوصول، WAF، منظور)
- `observed_data` (البيانات الأولية المرسلة إلى الذكاء الاصطناعي — وليست أسماء المستشعرات أو شدة التصنيف لمنع التحيز في التصنيف)
- `ai_view()` يجرد بيانات المستشعر metadata، ويعيد فقط الحقائق المرصودة
### البوابة (`src/fusion/gate.py`)
اتفاق حتمي — مع `list[Signal]`، يتم التجميع حسب الموضوع وإرجاع `list[Verdict]`:
| الشرط | الحكم |
|---|---|
| مُدرج في KEV أو مؤكد بالاستكشاف أو حرج + استغلال / EPSS عالي | **مؤكد** (مثبت — لا يمكن إسقاطه) |
| ≥2 مصدر مستقل متفق عليه، ≥1 موثوقية عالية | **مؤكد** (إلا إذا كان الكل مطابقًا للإصدار → رمادي) |
| موثوقية منخفضة منفردة، تأثير منخفض/متوسط، لا تأكيد | **مهمل** |
| كل شيء آخر | **رمادي** (يكلف رمز ذكاء اصطناعي واحد) |
### التحكيم بالذكاء الاصطناعي (`src/fusion/adjudicator.py`)
يتعامل فقط مع النطاق الرمادي. قيود الأمان مُطبَّقة في الكود (وليس في الموجه):
- العناصر الرمادية ذات الشدة العالية/الحرجة لا يمكن أبدًا إهمالها — في أسوأ الأحوال يتم خفضها إلى `potential`
- التطابقات المعتمدة على الإصدار فقط تُحَدَّد إلى `potential` (التوزيعات تعيد التصحيح دون تغيير الإصدار)
- الذكاء الاصطناعي يكتشف أيضًا نتائج جديدة من سياق المضيف الكامل
- فشل آمن: انقطاع الذكاء الاصطناعي يترك النطاق الرمادي كـ `potential` — لا فقدان صامت للبيانات
### التوليف (`src/fusion/synthesis.py`)
`build_attack_graph(verdicts)` → رسم بياني حتمي لقابلية الوصول من النتائج المؤكدة.
`full_synthesize(...)` → تقرير ذكاء اصطناعي مكون من 6 أقسام:
1. الملخص التنفيذي
2. النتائج الرئيسية (جدول)
3. سلاسل الهجوم (قائمة على الرسم البياني، يروي LLM الحواف الحقيقية)
4. ما وراء CVEs المعروفة
5. النتائج الإيجابية الكاذبة والضوضاء
6. المعالجة
### المستشعرات
| المستشعر | الملف | ما ينتجه |
|---|---|---|
| جسر المحرك | `engine_bridge.py` | يحول نتائج المسح إلى Signals من NVD، والاستكشافات، والمكدس، وNuclei، والمدقق |
| Wappalyzer | `sensors/wappalyzer.py` | بصمة متوافقة مع Wappalyzer بدون تبعيات لاستجابات HTTP |
| Nuclei | `sensors/nuclei.py` | يشغل قوالب YAML ضد الاستجابات (مجموعة فرعية من بناء جملة Nuclei) |
| كاسيت | `cassette.py` | تسجيل/تشغيل من كاسيتات HTTP (بيانات قياسية غير متصلة) |
### عبر المضيف (`src/fusion/cross_host.py`)
تجميع الأحكام بعد التحكيم عبر المضيفين حسب الخدمة المشتركة + الإصدار لسرد سلسلة هجوم متعددة القفزات في التوليف.
### تدفق خط الأنابيب```
Engine artifacts / Cassette data
↓
engine_bridge.py / cassette.py → Signal list
↓
gate.py::adjudicate() → Verdict list (confirmed/discarded/gray)
↓
adjudicator.py::run_adjudication() → AI on gray band only
↓
synthesis.py::full_synthesize() → 6-section report + attack graph
يقع في src/reasoning/ (~58 ملفًا). حلقة متعددة المراحل، محمية بالسلامة، من نوع راقب←استنتج←تصرف. يتم تمكينه باستخدام --reason.
src/reasoning/director.py — ReconDirector.run())StrategyManager يختار الشخصية ← Scheduler يختار الإجراء ← SensorStep ينفذ ← EvidenceGraph يدمج الملاحظات ← ConfidenceEngine يحدّث المعتقداتProposal المقيدة بالنوع ← AICoordinator يطبع/يرتب/يتحقق ← المقترحات المقبولة تُغذي الحالة ← Compiler ← ExecutionPlanner ← ExecutionKernel يشغّل المسابر ← InferenceEngine يحلّCrossHostGraph، يُنتج حالات HostReasoner فرعيةsrc/reasoning/state.py)src/reasoning/ai/)خط الأنابيب: توليد ← تطبيع ← ترتيب ← (MetaReasoner تقليم) ← تحقق ← تخزين
تقع في src/deep/ (7 ملفات). تُستخدم مع --deep-probe. بنية وكيل لكل خدمة لتنفيذ مسبار معزول السياق.
تدفق DeepCoordinator.run():
_build_sensor_plan عبر sensor_director)ScoutAgent للاستطلاع السلبيProbeAgent لكل خدمة (كل منها بسياق CVE/تقنية معزول)يقع في src/verifier/ (3 ملفات). تأكيد CVE مدفوع بالذكاء الاصطناعي بمسابر مستهدفة.
إعادة التحقق من المرحلة 2 (reverify_with_context) توفر سياق المضيف الكامل لتحسين الاختبارات الفاشلة.
يقعون في src/directors/ (4 ملفات). اختيار معاملات المسح المدفوع بـ LLM.
يقع في src/orchestrator.py. يُفعّل بأهداف مفصولة بفواصل. يشغّل run_scan() لكل مضيف، يجمع النتائج، يبني سياقًا عبر المضيفين من الأحكام المدمجة المجمعة. تكتشف مجموعات عبر المضيفين الخدمات/الإصدارات المشتركة عبر المضيفين لسرد سلسلة هجوم متعددة القفزات.
src/nvd_lookup.py)--nvd-key)src/epss.py): واجهة FIRST.org API بدفعات من 100 معرف CVE، ذاكرة تخزين مؤقت على القرص لمدة 24 ساعة في ~/.netlogic/epss_cache.json، فاشل لين 0.0src/external/nuclei_runner.py يغلف ثنائي Nuclei (ترخيص MIT). اختياري — يتدهور بلطف عندما لا يُعثر على الثنائي. تُغذى النتائج في خط أنابيب الدمج كإشارات منقوشة (تُزال تسميات الشدة لمنع انحياز LLM).```
scoop install nuclei # Windows brew install nuclei # macOS go install github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest # Linux
---
## معيار الانصهار (Fusion Benchmark)
`src/fusion/benchmark.py` — قياس دون اتصال مقابل كاسيتات HTTP الموسومة (`benchmark/*.json` و `src/fusion/data/`). المقاييس:
| المقياس | عتبة البوابة |
|---|---|
| FP reduction | ≥ 80% |
| Critical recall | = 100% |
وضعان:
- **Oracle** (`--benchmark`): الحد الأعلى للذكاء الاصطناعي المثالي — يقيس الآلية الحتمية وحدها
- **النموذج الحقيقي** (`--benchmark --benchmark-ai`): يقاس باستخدام LLM المهيأ
---
## البنية (Architecture)```
netlogic/
├── netlogic.py ← Local launcher (`--gui`, optional CLI helpers)
│
├── src/ ← Scan engine (used by the web API)
│ ├── scanner.py ← TCP scanner, 22 service probes, banner grabbing
│ ├── engine.py ← Orchestrator: SensorStep pipeline, all scan modules + fusion
│ ├── orchestrator.py ← Multi-host: per-host scan → cross-host context
│ ├── ai_analyst.py ← LLM integration (9 providers, stdlib-only transport)
│ ├── cve_correlator.py ← CVE matching: NVD
│ ├── nvd_lookup.py ← NVD API v2.0 client, disk cache, CISA KEV
│ ├── epss.py ← EPSS enrichment (FIRST.org, 24h cache)
│ ├── service_prober.py ← Unauthenticated service access, default creds, admin paths
│ ├── vuln_prober.py ← CVE-specific safe active probes
│ ├── osint.py ← DoH, CT logs, ASN lookup
│ ├── tls_analyzer.py ← SSL/TLS deep analysis
│ ├── header_audit.py ← HTTP security header audit
│ ├── stack_fingerprint.py ← CMS, framework, cloud, CDN, WAF detector
│ ├── web_fingerprint.py ← Favicon mmh3, JS secrets, version files, exposed paths, lander detection
│ ├── dns_security.py ← SPF, DKIM, DMARC, DNSSEC, zone transfer
│ ├── takeover.py ← Subdomain takeover (25 provider fingerprints)
│ ├── authenticated.py ← SSH subprocess: dpkg/rpm/apk parsing, 60+ product mappings
│ ├── topology.py ← PTR, IPv6, traceroute, ASN/org/country
│ ├── reachability_prober.py ← Lateral movement matrix from subnet adjacency
│ ├── network_prober.py ← /24 subnet sweep: live-host → full port scan
│ ├── service_enum.py ← Protocol attribute extraction (SSH KEX, SMBv1, RDP NLA, SNMP)
│ ├── ssl_utils.py ← Configurable SSL context management, TLS probe
│ ├── scan_diff.py ← Change-over-time: diffs against prior JSON report
│ ├── json_bridge.py ← Streaming JSON events for agent / REST API
│ ├── reporter.py ← Terminal, JSON, HTML output renderers
│ │
│ ├── fusion/ ← Precision funnel (12 files)
│ │ ├── signals.py ← Signal schema
│ │ ├── gate.py ← Deterministic agreement
│ │ ├── adjudicator.py ← AI adjudication (gray band only)
│ │ ├── synthesis.py ← Attack graph + 6-section report
│ │ ├── ai.py ← CompleteFn/StreamCompleteFn adapter
│ │ ├── engine_bridge.py ← Artifacts → Signals → verdicts
│ │ ├── benchmark.py ← Offline benchmark (oracle + real model)
│ │ ├── cassette.py ← HTTP cassette record/replay
│ │ ├── corpus.py ← Cassette→case conversion + CLI
│ │ ├── cross_host.py ← Cross-host verdict correlation
│ │ ├── sensors/nuclei.py ← Nuclei YAML → Signal conversion
│ │ └── sensors/wappalyzer.py← Wappalyzer fingerprint → Signal
│ │
│ ├── directors/ ← AI sensor directors (4 files)
│ │ ├── sensor_director.py ← LLM selects which sensors to enable
│ │ ├── reprobe.py ← LLM designs re-probe plans
│ │ ├── nuclei_selector.py ← LLM selects Nuclei template tags
│ │ └── subnet_director.py ← LLM directs subnet probing
│ │
│ ├── verifier/ ← AI CVE verification (3 files)
│ │ ├── engine.py ← Verifier orchestration
│ │ ├── planner.py ← Built-in + AI-generated probe plans
│ │ └── runner.py ← Raw TCP/TLS probe execution
│ │
│ ├── deep/ ← Deep probe agents (7 files)
│ │ ├── coordinator.py ← Full deep pipeline orchestrator
│ │ ├── scout_agent.py ← Passive recon agent
│ │ ├── probe_agent.py ← Per-service probe agent
│ │ ├── chain.py ← Exploit chain planning + PoC generation
│ │ ├── sandbox.py ← Restricted PoC execution
│ │ ├── base_agent.py ← Abstract base
│ │ └── models.py ← Mission/AgentReport data models
│ │
│ ├── reasoning/ ← Adaptive reasoning engine (~58 files)
│ │ ├── director.py ← ReconDirector (main loop)
│ │ ├── state.py ← WorldModel/InvestigationState/ExecutionState
│ │ ├── hypothesis.py ← Hypothesis engine (competing candidates)
│ │ ├── evidence_graph.py ← Temporal entity graph (content-addressed obs)
│ │ ├── confidence.py ← Noisy-OR belief computation
│ │ ├── provenance.py ← Observation→Inference→Hypothesis edges
│ │ ├── scheduler.py ← Information-gain action selection
│ │ ├── strategy.py ← Meta-reasoning: personas, explore/exploit
│ │ ├── strategies.py ← Concrete strategy implementations
│ │ ├── action_gate.py ← Risk-tiered probe authorisation
│ │ ├── change_detection.py ← Phase 7: observation-level diff
│ │ ├── active_validation.py ← Phase 8b: SAFE_ACTIVE probes
│ │ ├── cross_host.py ← Cross-host world modeling
│ │ ├── objective.py ← Objective DAG management
│ │ ├── intent.py ← Intent model + EvidenceType enum (29 types)
│ │ ├── candidate.py ← Action candidate with lazy factory
│ │ ├── actions.py ← Action model with RiskTier + Predicate
│ │ ├── compiler.py ← Intent → InvestigationGraph
│ │ ├── execution_planner.py ← InvestigationGraph → ProbePlanGraph
│ │ ├── execution_kernel.py ← Probe execution with validators
│ │ ├── probe_executor.py ← Read-only probe backends
│ │ ├── primitive_registry.py← Probe primitive catalogue
│ │ ├── generators.py ← Deterministic objective/hypothesis population
│ │ ├── playbooks.py ← YAML playbook system
│ │ ├── planning_pass.py ← GoalPlanner integration
│ │ ├── budget.py ← Probe budget management
│ │ ├── inference.py ← Deterministic rule-based inference
│ │ ├── novel_inference.py ← Novel-vuln hypothesis rules
│ │ ├── investigation_planner.py ← Goal-directed investigation planning
│ │ ├── investigation_memory.py ← Strategy attempt memory
│ │ ├── observation_translator.py ← Raw data → structured observations
│ │ ├── observation.py ← Immutable, content-addressed observation
│ │ ├── reflect.py ← PlannerFeedback generation
│ │ ├── reasoning_validator.py ← Continuous integrity audit
│ │ ├── builder.py ← State population from artifacts
│ │ ├── trace.py ← Execution tracing
│ │ ├── explanation.py ← Explanation records
│ │ ├── ai/ ← AI cognitive layer (subsystem)
│ │ ├── packs/ ← Technology pack calibration
│ │ ├── playbooks/ ← YAML playbook templates
│ │ └── rules/ ← JSON inference rules
│ │
│ └── external/nuclei_runner.py ← Nuclei binary wrapper
│
├── api/ ← FastAPI controller
│ ├── main.py ← App factory, lifespan, middleware stack
│ ├── cli.py ← Typer -> netlogic.py bridge
│ ├── db.py ← PostgreSQL connection + migration runner
│ ├── crypto.py ← Fernet seal/unseal (AES-128-CBC + HMAC-SHA256)
│ ├── auth/
│ │ ├── api_keys.py ← Dual-store (memory/PG), SHA-256 hashed
│ │ ├── jwt_handler.py ← Stdlib-only HS256 JWT
│ │ ├── oidc.py ← Clerk/IdP OIDC (RS256 + JWKS)
│ │ ├── license.py ← LicenseManager (stub → real payment API)
│ │ ├── rate_limit.py ← Sliding-window, IP banning
│ │ ├── provisioning.py ← Clerk auto-provisioning
│ │ └── dependencies.py ← require_org FastAPI dependency
│ ├── agents/
│ │ ├── registry.py ← Agent lifecycle (concurrency-aware, JSON persistence)
│ │ └── local_agent.py ← Built-in in-process agent
│ ├── jobs/
│ │ ├── manager.py ← ScanJob lifecycle, capped event deque (10k), SSE, Postgres
│ │ └── executor.py ← Dispatch (capability/selector, least-loaded, reclaimer)
│ ├── middleware/audit.py ← X-Request-ID + structured audit + SIEM shipping
│ ├── models/
│ │ ├── scan_request.py ← Pydantic ScanRequest (ipaddress validation)
│ │ └── agent.py ← AgentRegistration constraints
│ ├── routes/
│ │ ├── auth.py ← /v1/auth/*
│ │ ├── jobs.py ← /v1/jobs/*
│ │ ├── agents.py ← /v1/agents/*
│ │ ├── health.py ← /health + /v1/health
│ │ ├── license.py ← /v1/license/*
│ │ └── settings.py ← /v1/settings/*
│ └── storage/
│ ├── json_store.py ← 10 MB cap, 500 file cap, atomic writes
│ ├── pg_store.py ← Postgres JSONB upsert
│ └── reasoning_store.py ← Dual-store for reasoning state
│
├── dashboard/ ← React SPA (Vite + TypeScript + Tailwind + Clerk)
│ └── src/
│ └── pages/ ← Dashboard, NewScan, ScanDetail, Agents, Targets,
│ TargetTimeline, Settings, License, Login, SignUp, Legal
│
├── docs/ ← Design documentation
│ ├── DEPLOY_SAAS.md, saas-auth.md
│ ├── REASONING_ENGINE_DESIGN.md
│ ├── LEGAL_COMPLIANCE.md
│ ├── ENTERPRISE_READINESS.md
│ └── DESIGN_PARTNER_PACK.md
│
├── db/migrations/ ← PostgreSQL schema migrations
└── benchmark/ ← HTTP cassette recordings for fusion benchmark
جميع المسارات تحت البادئة /v1/. المصادقة:
POST /v1/auth/token → HS256 JWT (تنتهي الصلاحية افتراضيًا بعد ساعة واحدة)require_org التحقق من خلال JWKSPOST /v1/auth/token Exchange API key for JWT [10/min/IP] POST /v1/auth/keys Create API key (X-Admin-Key) [admin] GET /v1/auth/keys List keys (masked) [admin] DELETE /v1/auth/keys Revoke key (body, not URL) [admin]
### وظائف```
POST /v1/jobs Create scan job [30/min/org]
GET /v1/jobs List recent jobs
GET /v1/jobs/history/{target} Scan history for target
GET /v1/jobs/{id} Job detail
GET /v1/jobs/{id}/stream SSE event stream [60/min/org]
GET /v1/jobs/{id}/export Export (format=json|md|raw)
POST /v1/jobs/{id}/explore-beyond AI deep-dive on finding
POST /v1/jobs/{id}/cancel Cancel job
DELETE /v1/jobs/{id} Remove job
POST /v1/agents/register Register agent [5/hr/IP] POST /v1/agents/{id}/heartbeat Keep-alive [3/min] GET /v1/agents/{id}/tasks Poll pending jobs POST /v1/agents/{id}/tasks/{job_id}/events Submit events [60/min, 500/batch] POST /v1/agents/{id}/tasks/{job_id}/complete Mark done/failed GET /v1/agents List agents (org-scoped) GET /v1/agents/{id} Agent detail DELETE /v1/agents/{id} Deregister POST /v1/agents/{id}/activate Enable agent POST /v1/agents/{id}/deactivate Disable agent
### الترخيص / الإعدادات```
GET /v1/license License status
POST /v1/license/activate Activate key [3/hr/IP]
GET /v1/settings/ai Get org AI config (key masked)
POST /v1/settings/ai Update org AI config (encrypted)
POST /v1/settings/ai/test Test AI connection
GET /health Service status + uptime GET /docs OpenAPI docs GET /redoc ReDoc docs
---
## متغيرات البيئة
### المتحكم (Controller)
| المتغير | القيمة الافتراضية | الوصف |
|---|---|---|
| `NETLOGIC_ENV` | _(غير مضبوط)_ | `production`/`prod` = التحقق من السرية عند بدء التشغيل |
| `NETLOGIC_JWT_SECRET` | `changeme-in-production` | سر توقيع HS256، 32 حرفًا على الأقل |
| `NETLOGIC_JWT_EXPIRY` | `3600` | عمر JWT بالثواني |
| `NETLOGIC_ADMIN_KEY` | `admin-changeme` | بيانات اعتماد المشرف، ≥32 حرفًا في الإنتاج |
| `NETLOGIC_API_KEYS` | _(فارغ)_ | مفاتيح البذور: `key1:org1,key2:org2,...` |
| `NETLOGIC_CORS_ORIGINS` | _(فارغ)_ | الأصول المسموح بها (يتم تعطيل CORS إذا كان فارغًا) |
| `NETLOGIC_PORT` | `8000` | منفذ الربط |
| `NETLOGIC_HOST` | `0.0.0.0` | عنوان الربط |
| `NETLOGIC_NO_BROWSER` | _(غير مضبوط)_ | `1` يعطل الفتح التلقائي |
| `NETLOGIC_OIDC_ISSUER` | _(غير مضبوط)_ | رابط API الواجهة الأمامية لـ Clerk → تسجيل الدخول OIDC |
| `NETLOGIC_OIDC_AUDIENCE` | _(غير مضبوط)_ | جمهور OIDC |
| `NETLOGIC_OIDC_DEFAULT_ORG` | _(غير مضبوط)_ | معرف org_id احتياطي لمستخدمي OIDC |
| `NETLOGIC_DATABASE_URL` | _(غير مضبوط)_ | سلسلة اتصال PostgreSQL |
| `NETLOGIC_SECRETS_KEY` | _(غير مضبوط)_ | مفتاح Fernet لبيانات الاعتماد المخزنة |
| `NETLOGIC_AGENT_TOKEN_MAX_AGE` | `604800` | عمر رمز الوكيل (7 أيام) |
| `NETLOGIC_AGENT_PENDING_CAP` | `50` | الحد الأقصى للمهام المجدولة لكل وكيل |
| `NETLOGIC_MAX_AGENTS_PER_ORG` | `100` | الحد الأقصى للوكلاء المسجلين |
| `NETLOGIC_AI_PROVIDER` | `openrouter` | مزود AI الافتراضي |
| `NETLOGIC_AI_API_KEY` | _(فارغ)_ | مفتاح AI الافتراضي |
| `NETLOGIC_AI_MODEL` | الإعداد الافتراضي للمزود | النموذج الافتراضي |
| `NETLOGIC_AI_BASE_URL` | الإعداد الافتراضي للمزود | رابط أساسي مخصص |
| `NETLOGIC_NVD_KEY` | _(فارغ)_ | مفتاح واجهة NVD |
| `NETLOGIC_VALID_LICENSES` | _(فارغ)_ | تجاوزات تراخيص التطوير/الاختبار |
| `NETLOGIC_LICENSE_KEY` | _(فارغ)_ | مفتاح ترخيص المثيل |
| `NETLOGIC_SCANS_DIR` | _(افتراضي)_ | دليل تخزين المسح |
| `NETLOGIC_SIEM_ENDPOINT` | _(فارغ)_ | رابط إرسال سجل التدقيق |
| `NETLOGIC_WAPPALYZER_DATA` | _(مدمج)_ | مسار بصمات Wappalyzer |
### الوكيل (Agent)
| المتغير | القيمة الافتراضية | الوصف |
|---|---|---|
| `NETLOGIC_CONTROLLER` | `http://localhost:8000` | رابط المتحكم الأساسي |
| `NETLOGIC_API_KEY` | _(غير مضبوط)_ | مفتاح API للتسجيل |
---
## بنية الأمان
### مجموعة الوسائط الوسيطة (الترتيب المطبق)
1. **AuditMiddleware** — ربط `X-Request-ID`، سجل تدقيق بتنسيق JSON منظم، إرسال إلى SIEM
2. **RequestSizeLimitMiddleware** — حد حجم النص 10 ميجابايت (حماية من رفض الخدمة)
3. **LicenseMiddleware** — يمنع جميع مسارات `/v1/` عندما لا يكون هناك ترخيص (يرجع 402)
4. **SecurityHeadersMiddleware** — HSTS (سنة واحدة)، CSP (متباين لـ HTML مقابل API)، X-Frame-Options، X-Content-Type-Options، Permissions-Policy، Referrer-Policy
5. **OriginCheckMiddleware** — التحقق من الأصل لـ POST/PUT/DELETE (تعمق دفاعي ضد CSRF)
6. **CORSMiddleware** — مقيد: لا يوجد حرف بدل، أصول محددة فقط
### المصادقة
- **مفاتيح API**: يتم تجزئتها بـ SHA-256 عند التخزين؛ النص الواضح فقط عند `create()` وفي نص الطلب أثناء `verify()`
- **JWT**: HS256 مع المكتبة القياسية (`hashlib`+`hmac`+`base64`)، حقل `alg` مثبت قبل التحقق (يمنع `alg=none`)، احتياطي عشوائي مؤقت للتطوير
- **OIDC**: Clerk/Auth0/WorkOS — RS256 + JWKS، يقوم تلقائيًا بتوفير المستخدمين + المؤسسات عند أول تسجيل دخول
- **رموز الوكيل**: يتم تجزئتها بـ SHA-256 في السجل، مقارنة بزمن ثابت، صلاحية 7 أيام
### تحديد المعدل
نافذة منزلقة في الذاكرة. لكل نقطة نهاية، لكل نطاق (IP، معرف المؤسسة، معرف الوكيل). حظر IP بعد 5 محاولات فاشلة لتبادل الرمز في 10 دقائق (حظر لمدة ساعة واحدة).
### حماية البيانات
- مفاتيح LLM API: مشفرة بـ Fernet عند التخزين (AES-128-CBC + HMAC-SHA256). إغلاق فاشل في الإنتاج: يتطلب `NETLOGIC_SECRETS_KEY`
- تعدد المستأجرين: جميع البيانات محددة النطاق بـ `org_id`؛ البحث عبر المؤسسات يرجع 404 (وليس 403)
- عبور المسار: يتم التحقق من جميع مسارات التخزين، يتم رفض الفواصل و `..`
---
## CI / الاختبار```bash
pip install -r requirements-dev.txt
python -m pytest
خط أنابيب CI (.github/workflows/ci.yml) — 5 وظائف:
pip-auditnpm ci + npm run buildNetLogic مخصص فقط لتقييمات الأمن المصرح بها، واختبارات الاختراق، وإدارة الشبكات. مسح أو اختبار المضيفين دون إذن كتابي صريح غير قانوني في معظم الولايات القضائية. لا يتحمل المؤلف أي مسؤولية عن الاستخدام غير المصرح به.
MIT © 2026 Dmitry Flynn — راجع LICENSE.txt
| تنسيق متعدد المضيفين | خط أنابيب المسح الكامل لكل مضيف → سياق عبر المضيفين ومصفوفة وصول → اكتشاف سلاسل الهجوم |
| مديرو الحساسات بالذكاء الاصطناعي | يقرر LLM أي الحساسات يجب تحديد أولوياتها بناءً على المنافذ المفتوحة، وتكدس التقنيات، وCVE |
| SSH مصادق | عملية ssh فرعية معتمدة تقرأ إصدارات الحزم المثبتة الفعلية (أكثر من 60 تعيين منتج) |
| تعداد الخدمات | استخراج سمات على مستوى البروتوكول (SSH KEX، SMBv1، RDP NLA، مجتمع SNMP، حالة مصادقة HTTP) |
| مخطط الطوبولوجيا | DNS عكسي، IPv6، traceroute، ASN/منظمة/دولة عبر ip-api.com |
| ماسح الوصول | مصفوفة حركة جانبية بعد الاختراق من تقارب الشبكة الفرعية |
| ماسح الشبكة | مسح نشط للشبكة الفرعية (/24 الجيران الخاصين) باكتشاف من مرحلتين (مسح حي → فحص كامل للمنافذ) |
| فرق المسح | التغيير بمرور الوقت: مقارنة المسح الحالي مع أحدث تقرير JSON سابق لكل هدف |
| إدارة الترخيص | نظام تراخيص تجاري مع تفعيل المفتاح (عنصر نائب لـ Stripe/Paddle/Lemon Squeezy) |
| تكوين AI لكل مؤسسة | كل مؤسسة تخزن بيانات اعتماد LLM الخاصة بها مشفرة في حالة السكون عبر Fernet |
| OIDC / Clerk | دخول البشر عبر رموز JWT الصادرة عن Clerk والمتحقق منها مقابل JWKS عام مع توفير تلقائي |
| PostgreSQL | استمرارية متعددة المستأجرين كاملة مع ترحيلات مطبقة تلقائياً (وظائف المسح، إعدادات المؤسسة، حالة الاستدلال، التدقيق) |
| معيار الدمج | معيار غير متصل مقابل تسجيلات HTTP مسجلة؛ مقاييس الدقة/الاستدعاء/الاستدعاء الحرج/تقليل الإيجابيات الخاطئة |
| مسح طرفية لمرة واحدة (بدون خادم)، يطبع/يكتب التقرير. |
| الصيغة | مثال | الوضع |
|---|
| اسم المضيف | example.com | فحص مضيف واحد |
| IPv4 | 10.0.0.5 | فحص مضيف واحد |
| CIDR | 192.168.1.0/24 | مسح CIDR (الماسح فقط، بدون دمج) |
| مفصول بفواصل | target1,target2 | تنسيق متعدد المضيفين (سياق عبر المضيفين) |
GoalPlanner يُنتج خطط التحقيقReasoningValidator تدقيق النزاهة ← ProvenanceBuilder يسجّل الحواف ← الحالة مستمرة| الطبقة | الفئة | ما يتتبعه |
|---|
| WorldModel | WorldModel | EvidenceGraph، الملاحظات، المعتقدات، المضيفين، التقنية، قابلية الوصول |
| InvestigationState | InvestigationState | الأهداف (DAG)، الفرضيات، التناقضات، الطرق المسدودة، الشخصية الحالية |
| ExecutionState | ExecutionState | الميزانية، تاريخ المسابير، المصدر، خطط التحقيق، نص الذكاء الاصطناعي |
| LearnedPatterns | LearnedPatterns | قواعد ارشادية عبر الفحص + كتب اللعب |
| المكون | الملف | الوصف |
|---|
| EvidenceGraph | evidence_graph.py | رسم بياني لكيانات زمنية منزوعة الازدواجية (ملاحظات بعنوان المحتوى عبر SHA-256) |
| محرك الفرضيات | hypothesis.py | مرشحون متنافسون مع احتمالات، إنتروبيا، كسب معلومات، حلول لاحقة |
| ConfidenceEngine | confidence.py | NOISY-OR عبر مصادر متميزة؛ الإصدار فقط يقف عند 0.60؛ KEV/المسبار مثبت عند 0.97 |
| ProvenanceBuilder | provenance.py | حواف الملاحظة→الاستدلال→الفرضية، بعنوان تجزئة المحتوى |
| Scheduler | scheduler.py | اختيار الإجراءات بكسب المعلومات مع احتياطي استكشاف (10%) |
| StrategyManager | strategy.py | ما وراء الاستدلال: اختيار الشخصية، وضع الاستكشاف/الاستغلال، كشف الهضبة |
| ActionGate | action_gate.py | دفاع متعمق: مستويات المخاطرة (READ_ONLY < SAFE_ACTIVE < INTRUSIVE < EXPLOIT)، الحد الأقصى SAFE_ACTIVE |
| InferenceEngine | inference.py | قواعد حتمية من rules/*.json، لا يكتب ثقة أبدًا |
| NovelInferenceEngine | novel_inference.py | قواعد لتسمم ذاكرة التخزين المؤقت، تهريب الطلب، تجاوز المصادقة إلخ. |
| ExecutionKernel | execution_kernel.py | يتحقق + ينفذ + يتتبع المسابير (النطاق → للقراءة فقط → الميزانية → إزالة الازدواج → العمق) |
| نظام كتيب اللعب | playbooks.py | كتب لعب بصيغة YAML مع شروط تفعيل وقوالب نية |
| كشف التغيير | change_detection.py | المرحلة 7: يفرق الملاحظات الثابتة (وليس الحالة)، يُنتج ScanDelta من DeltaEvents |
| التحقق النشط | active_validation.py | المرحلة 8b: مسابر SAFE_ACTIVE غير مدمرة عبر ActionGate |
| الملف | المكون |
|---|
coordinator.py | AICoordinator — تنسيق خط الأنابيب على مراحل |
proposals.py | مغلف Proposal المقيد بالنوع مع حمولة خاصة بالنوع، المصدر، الاقتصاد |
normalize.py | ProposalNormalizer — بوابة التحقق الكلية |
rank.py | ProposalRanker — النتيجة = raw_score × prob_correct × reputation_weight |
meta_reasoner.py | تقليم حتمي (كشف الحلقات، تقليل عدم اليقين) |
verifier.py | 4 مراحل: النحو ← الدلالي ← الدليل ← السلامة |
store.py | ProposalStore — سجل دورة الحياة |
transcript.py | InvestigationTranscript — تسجيل سلسلة السببية |
evaluation.py | حزام تقييم حتمي قائم على الكاسيت |
reputation.py | AgentReputation — يتتبع معدل القبول/الرفض لكل وكيل |
agents/hypothesis_generator.py | C1 — يقترح تفسيرات متنافسة + فرضيات ثغرات جديدة |
agents/counterfactual.py | C11 — يقترح أهداف دحض |
agents/investigation_designer.py | C2 — يصمم خطط جمع الأدلة |
| المكون | الملف | الوصف |
|---|
DeepCoordinator | coordinator.py | ينسق خط الأنابيب العميق بالكامل: خطة حساسات الذكاء ← وكيل الكشافة ← وكيل مسبار لكل خدمة ← تعداد الخدمة ← Nuclei ← مدقق ← استيلاء ← مسبار شبكة فرعية ← طوبولوجيا ← مصادقة ← فرق ← قابلية الوصول |
ScoutAgent | scout_agent.py | استطلاع سلبي: TLS، الرؤوس، المكدس، DNS، OSINT |
ProbeAgent | probe_agent.py | يستهدف خدمة واحدة بسياق CVE/تقنية معزول — يشغّل المسابر + المدقق |
ExploitChain | chain.py | تخطيط مسار هجوم BFS عبر أحكام مدمجة مؤكدة، توليد PoC |
Sandbox | sandbox.py | عملية فرعية مقيدة للتحقق من PoC (دليل مؤقت، مهلة، تنظيف) |
Mission / AgentReport | models.py | نماذج بيانات لتوجيهات الوكيل ونتائجه |
| المكون | الملف | الوصف |
|---|
run_verifier() | engine.py | ينسق: توليد الخطط ← تنفيذ ← بناء إشارات مؤكدة بالمسابير |
generate_plans_for_cves() | planner.py | لكل CVE (CVSS ≥ 7.0): يتحقق من ~20 خطة مدمجة ← الذكاء يولد خطة HTTP أولية (طريقة، مسار، رؤوس، جسم، الحالة/الجسم المتوقع) |
run_test() | runner.py | تنفيذ مأخذ TCP/TLS أولي، تحليل يدوي لـ HTTP/1.0، مطابقة نمط الجسم المتوقع |
| المدير | الملف | ما يقرره |
|---|
SensorDirector | sensor_director.py | أي الحساسات يتم تمكينها/تعطيلها وبأي أولوية، بناءً على المنافذ المفتوحة + مجموعة التقنيات + CVEs |
ReprobeDirector | reprobe.py | هل يمكن حل النتائج المحتملة بمسابر HTTP مستهدفة |
NucleiSelector | nuclei_selector.py | أي علامات قوالب Nuclei يتم تضمينها/استبعادها (يقلل عمليات التشغيل غير ذات الصلة) |
SubnetDirector | subnet_director.py | أي المضيفين المجاورين استطلاع، أي المنافذ، وبأي عمق (تخطي/سريع/قياسي/عميق) |