Arsitektur

Deep Eye adalah alat pentest yang digerakkan konfigurasi dan berjalan multi-thread. ScannerEngine memegang siklus hidup satu scan, VulnerabilityScanner memegang pemeriksaan per-URL, dan setiap modul adalah paket yang bisa dipasang di bawah modules/ docs/ARCHITECTURE.md:5¹. Lapisan bawahnya sinkron: requests (dengan curl_cffi opsional untuk TLS evasion), ThreadPoolExecutor, ReportLab untuk PDF, dan YAML untuk konfigurasi docs/ARCHITECTURE.md:7².

Pembagian tanggung jawab terlihat langsung pada daftar import scanner_engine.py: engine menarik VulnerabilityScanner, AIPayloadGenerator, PluginManager, PentestStateManager, SubdomainScanner, HTTPClient, ScopeManager, dan ReconEngine core/scanner_engine.py:16-28³. Kelasnya sendiri dideklarasikan sebagai orkestrator proses, bukan pemilik logika serangan core/scanner_engine.py:34-35⁴, sedangkan VulnerabilityScanner dideklarasikan sebagai kumpulan metode serangan core/vulnerability_scanner.py:31-32⁵.

Peta dependensi antar paket

Diagram berikut merangkum arah dependensi: CLI menyusun dua objek tingkat atas, engine menyusun komponen, dan hanya modules/ serta plugins/ yang menempel ke engine atau scanner.

graph TD
  CLI["deep_eye.py main"] --> PM["AIProviderManager"]
  CLI --> ENG["ScannerEngine"]
  CLI --> REP["ReportGenerator"]
  PM --> PROV["ai_providers/*Provider"]
  ENG --> VS["VulnerabilityScanner"]
  ENG --> APG["AIPayloadGenerator"]
  ENG --> PLG["PluginManager"]
  ENG --> SUB["SubdomainScanner"]
  ENG --> HC["HTTPClient"]
  ENG --> SM["ScopeManager"]
  ENG --> ST["PentestStateManager"]
  VS --> MODS["modules/* tester.scan"]
  ENG --> MODS
  APG --> PM
  VS --> HC
  MODS --> HC
  PLG --> PLUG["plugins/* PluginBase"]
  style PM fill:#f59e0b,color:#000
  style HC fill:#336791,color:#fff
  style MODS fill:#8b5cf6,color:#fff
  style REP fill:#2d7d46,color:#fff
%% fig: Dependensi antar paket Deep Eye
%% desc: CLI menyusun AIProviderManager dan ScannerEngine; engine menyusun scanner, payload generator, plugin, dan HTTP client; hanya modules dan plugins yang menyisip ke engine atau scanner.

AIPayloadGenerator menerima ai_manager yang sama dengan engine, jadi seluruh pemakaian AI melewati satu titik core/scanner_engine.py:76-79⁶. PluginManager dimuat dari konfigurasi dan baru memindai bila plugin_manager.enabled bernilai benar core/scanner_engine.py:86-93⁷.

Peran setiap lapisan

Kontrak ai_providers/ dipenuhi oleh satu kelas per vendor. AIProviderManager menginisialisasi provider secara enable-gated, lalu memilih provider aktif dari scanner.ai_provider atau provider pertama yang tersedia ai_providers/provider_manager.py:13-26¹³. generate mencoba provider aktif sampai tiga kali, melempar ulang sebagai RuntimeError("empty AI response") bila hasilnya kosong, lalu berpindah provider dan mengembalikan string kosong bila semuanya gagal ai_providers/provider_manager.py:148-192¹⁰.

Untuk utils/, HTTPClient memegang satu requests.Session bersama (atau curl_cffi.Session saat tls_evasion.enabled) dan membungkus pembatasan laju lewat TokenBucket utils/http_client.py:100-116¹⁴. TokenBucket sendiri menyimpan rate, burst, dan lock, lalu memblokir di acquire() sampai satu token tersedia utils/http_client.py:17-44¹⁵.

Tiga jalur pendaftaran modul

Modul tidak masuk lewat satu pintu. Tester fitur didaftarkan sebagai daftar (check_name, cls(http_client, config)) di _feature_testers, dan tiap entri diimpor dari _specs dengan importlib sehingga satu modul gagal tidak menggagalkan yang lain core/vulnerability_scanner.py:70-107¹⁶. Saat scan, tester hanya dijalankan bila check_name ada di enabled_checks core/vulnerability_scanner.py:325-338¹⁷.

Modul berat punya jalur sendiri lewat _init_extra_module_testers, yang memetakan directory_bruteforce, port_scanner, saml_attacks, subdomain_takeover, dan cache_poisoning ke kelasnya masing-masing, dengan filter yang sama pada enabled_checks core/scanner_engine.py:244-281¹⁸. Hasil _init_extra_module_testers disimpan di _extra_module_testers dan dipanggil per URL core/scanner_engine.py:190¹⁹. Rincian katalog modul ada di Pemindai Kerentanan dan Katalog Modul.

⚠️ Menambah modul baru berarti menyentuh salah satu dari dua daftar di atas. Menaruh logika serangan langsung di vulnerability_scanner.py justru anti-pattern yang dicatat di basis pengetahuan agen AGENTS.md:76-84²⁰.

Kontrak data antar lapisan

Satu temuan adalah dict biasa. Kunci type, severity, url, evidence, dan remediation wajib ada karena dipakai pelaporan dan diff; sisanya opsional, termasuk parameter, payload, fingerprint, cve_references, plugin, ai_evidence_summary, false_positive, dan compliance docs/ARCHITECTURE.md:81-86²¹.

Diagram berikut menunjukkan perjalanan satu dict temuan melewati kontrak-kontrak itu.

graph LR
  A["VulnerabilityScanner.scan<br/>list of dict"] --> B["dedupe_findings + fingerprint"]
  B --> C["FPReplay .replay<br/>EvidenceSummarizer .enrich"]
  C --> D["ReportGenerator"]
  A -.-> E["_identity_no_sev<br/>diff dan retest-new"]
  style B fill:#8b5cf6,color:#fff
  style E fill:#f59e0b,color:#000
  style D fill:#2d7d46,color:#fff
%% fig: Perjalanan satu dict temuan
%% desc: Temuan dari VulnerabilityScanner dilebur berdasarkan fingerprint, disaring ulang oleh FP replay dan evidence summary, lalu dipakai report; identitas tanpa severity menjadi kunci diff.

dedupe_findings mengelompokkan temuan berdasarkan fingerprint (atau menghitungnya lebih dulu) dan menyimpan yang severity-nya tertinggi menurut peringkat critical sampai info utils/finding_fingerprint.py:41-64²⁶. Engine hanya menjalankannya bila reporting.dedupe tidak dimatikan core/scanner_engine.py:851-858²³. Sesudah itu FPReplay dan EvidenceSummarizer dijalankan berurutan tanpa menggagalkan scan bila keduanya tidak aktif core/scanner_engine.py:860-876²⁷. Alur lengkapnya dibahas di Alur Scan, sedangkan bentuk identitas yang dipakai pembandingan ada di Scan Diff dan Retest.

Model threading

Semua worker berbagi satu HTTPClient, dan temuan diagregasi di bawah self.lock core/scanner_engine.py:203-208³¹. Setiap future hasil scan dibaca dengan future.result(timeout=scan_timeout) yang berasal dari scanner.scan_url_timeout dengan nilai default 60 detik, lalu hasilnya diperluas ke self.vulnerabilities di dalam lock yang sama core/scanner_engine.py:646-650³².

⚠️ Pada crawl, hasil worker dibaca dengan future.result(timeout=self.timeout * 3) dan setiap kegagalan hanya dicatat lewat logger.debug("Crawl worker error: ...") core/scanner_engine.py:394-405³³. URL yang gagal tidak pernah muncul sebagai error, jadi jumlah urls_crawled bisa lebih kecil tanpa peringatan.

Titik sambung

CLI hanya menyusun objek tingkat atas: AIProviderManager(config) lalu set_provider(ai_provider), kemudian ScannerEngine dengan konfigurasi dan parameter depth, threads, proxy, headers, dan cookies deep_eye.py:297-314³⁴. Semua knob scan berikutnya dibaca engine dari YAML docs/ARCHITECTURE.md:106-114³⁵. Rincian flag dan cara pakainya ada di Antarmuka CLI, sedangkan isi berkas konfigurasi ada di Instalasi dan Konfigurasi Awal.

Untuk lapisan AI, kontrak dan failover dijelaskan lebih jauh di Lapisan AI Provider; untuk keluaran akhir, lihat Pelaporan dan Ekspor.