Ringkasan Proyek

Deep Eye versi 1.4.0 dengan code name Hanzou adalah pemindai penetrasi berbasis AI yang dijalankan dari satu titik masuk CLI, deep_eye.py. Metadata paket mendeskripsikannya sebagai "Advanced AI-Driven Penetration Testing Tool" dengan lisensi MIT, dan menyatakan python_requires=">=3.8" (setup.py:23-31¹, setup.py:33-47²). Badge di README menegaskan angka yang sama: versi 1.4.0, Python 3.8+, dan code name Hanzou (README.md:13-18³).

Paket memasang satu perintah, deep-eye, lewat console_scripts yang menunjuk ke deep_eye:main (setup.py:49-53⁴). Saat config/config.yaml belum ada, main() menjalankan wizard run_onboard, lalu memuat konfigurasi lewat ConfigLoader.load (deep_eye.py:238-264⁵).

Alur tingkat tinggi

graph TD
  cli["deep_eye.py: main()"] --> cfg["ConfigLoader.load / run_onboard"]
  cli --> aim["AIProviderManager"]
  aim --> prov["Adapter provider: openai, claude, grok, ollama, ..."]
  cli --> engine["ScannerEngine.scan()"]
  engine --> recon["run_reconnaissance()"]
  engine --> crawl["crawl_recursive()"]
  engine --> vscan["VulnerabilityScanner.scan()"]
  vscan --> feat["_feature_testers: 27 entri"]
  engine --> post["Pipeline pasca-scan"]
  post --> dedupe["dedupe_findings()"]
  post --> rag["CVERagIndex.search()"]
  post --> comp["enrich_vulnerabilities()"]
  post --> triage["AITriage / BountyWriter"]
  engine --> rep["ReportGenerator.generate()"]
  rep --> out["html, pdf, json, sarif, junit, csv, xlsx"]
  style aim fill:#f59e0b,color:#000
  style prov fill:#f59e0b,color:#000
  style feat fill:#f59e0b,color:#000
  style post fill:#8b5cf6,color:#fff
  style rag fill:#8b5cf6,color:#fff
  style comp fill:#8b5cf6,color:#fff
  style rep fill:#2d7d46,color:#fff
  style out fill:#336791,color:#fff
%% fig: Alur tingkat tinggi Deep Eye
%% desc: CLI menyiapkan provider AI dan ScannerEngine, menjalankan fase scan, lalu mengalirkan temuan ke pipeline pasca-scan dan pembuatan laporan.

main() merakit AIProviderManager dari konfigurasi, memanggil set_provider untuk provider yang dipilih, lalu menyerahkan ScannerEngine dengan depth, threads, proxy, custom_headers, dan cookies (deep_eye.py:297-314⁶). Pemanggilan scanner.scan() membawa empat sakelar fase: enable_recon, full_scan, quick_scan, dan scan_subdomains (deep_eye.py:342-347⁷). Signature scan() itu mengembalikan satu Dict, dan pada akhirnya mengisi pentest_state, end_time, duration, serta mengirim notifikasi penyelesaian sebelum berpindah ke PentestPhase.COMPLETED (core/scanner_engine.py:682-700⁸, core/scanner_engine.py:943-961⁹).

Lapisan AI provider

AIProviderManager._initialize_providers membuat instance adapter hanya untuk kunci ai_providers yang enabled: true. Setiap kegagalan impor dicatat sebagai warning dan tidak menghentikan proses (ai_providers/provider_manager.py:28-137¹⁰). README mengiklankan failover lintas 11 provider (README.md:22¹¹), sedangkan _initialize_providers memuat blok untuk 12 kunci, termasuk nvidia_nim (ai_providers/provider_manager.py:130-137¹²).

Setiap baris berasal dari blok inisialisasi yang sama (ai_providers/provider_manager.py:28-137¹⁰). generate() menetapkan max_retries = 3 dan berpindah provider ketika percobaan aktif gagal (ai_providers/provider_manager.py:148-160¹³). SDK yang menjadi bahan lapisan ini tercantum di requirements.txt: openai, anthropic, ollama, mistralai, google-genai, litellm, dan google-generativeai (requirements.txt:7-14¹⁴). Rincian pemilihan model dan failover ada di Lapisan AI Provider.

Pemindai kerentanan

VulnerabilityScanner membaca daftar enabled_checks dari bagian vulnerability_scanner di konfigurasi (core/vulnerability_scanner.py:31-39¹⁵). scan() hanya menjalankan pemeriksaan yang namanya muncul di daftar itu; contohnya sql_injection dan xss dipanggil berurutan berikut pencatatan start_attack/end_attack ke state manager (core/vulnerability_scanner.py:125-139¹⁶). Di luar pemeriksaan inti, konstruktor merakit 27 pasangan check_name/kelas ke _feature_testers, dan entri yang gagal diimpor dilewati tanpa error (core/vulnerability_scanner.py:71-99¹⁷).

README mengiklankan 50+ pemeriksaan kerentanan (README.md:22¹¹), sementara docstring kelas menyebut "45+ attack methods" (core/vulnerability_scanner.py:31-32¹⁸). Tiap temuan berbentuk dict dengan kunci type, severity, url, parameter, payload, evidence, dan remediation (docs/MODULES.md:17-19¹⁹).

Katalog lengkap ada di Pemindai Kerentanan dan Katalog Modul.

Pipeline pasca-scan

Sebelum pemindaian URL, ScannerEngine.scan mengambil hasil crawl_recursive, menambahkan endpoint dari openapi_ingest bila openapi.enabled, lalu meminta AIAttackPlanner.plan menentukan urutan pemeriksaan bila ai_planner.enabled (core/scanner_engine.py:796-845²⁰). Sesudah itu temuan melewati beberapa tahap pengayaan berurutan:

1. dedupe_findings dan FPReplay.replay merapikan daftar temuan (core/scanner_engine.py:851-867²¹).
2. CVERagIndex.search mencari CVE mirip dengan top_k dari konfigurasi rag dan mengisi cve_references (core/scanner_engine.py:878-910²²).
3. enrich_vulnerabilities menambahkan kontrol dari framework yang diminta (core/scanner_engine.py:912-923²³).
4. AITriage.triage_vulnerabilities membuang false positive, lalu BountyWriter.generate_reports menulis laporan per temuan (core/scanner_engine.py:925-941²⁴).

Urutan itu disengaja: komentar di kode menegaskan triage berjalan setelah RAG dan compliance, tetapi sebelum bounty writer (core/scanner_engine.py:925-941²⁴). Rincian tiap tahap dibahas di CVE Intelligence dan RAG dan Alur Scan.

Laporan dan keluaran

graph LR
  cli["--formats"] --> resolve{"Resolusi format"}
  cfg["reporting.formats"] --> resolve
  dflt["reporting.default_format"] --> resolve
  resolve --> loop["geser formats satu per satu"]
  loop --> ext["ext_map: junit -> junit.xml"]
  ext --> gen["ReportGenerator.generate()"]
  gen --> files["deep_eye_{domain}_{timestamp}.{ext}"]
  style resolve fill:#f59e0b,color:#000
  style loop fill:#8b5cf6,color:#fff
  style gen fill:#2d7d46,color:#fff
  style files fill:#336791,color:#fff
%% fig: Resolusi format laporan
%% desc: Format dipilih dari CLI, lalu konfigurasi, lalu default; setiap format memakai satu stem berkas yang sama.

Prioritas pemilihan format berurutan: --formats dari CLI, lalu reporting.formats, lalu reporting.default_format yang defaultnya html (deep_eye.py:381-387²⁵). Setiap format dipetakan ke ekstensi lewat ext_map, dan semua berkas memakai satu stem deep_eye_<domain>_<timestamp> (deep_eye.py:403-428²⁶). ReportGenerator.generate() meneruskan junit ke utils.exports lewat build_junit_xml (core/report_generator.py:42-55²⁷).

Pemetaan ini diambil apa adanya dari ext_map (deep_eye.py:403-428²⁶). Rilis 1.4 menambahkan ekspor JUnit XML, CSV, dan XLSX beserta flag --formats; bagian yang sama mencatat pemetaan PCI-DSS v4.0, SOC 2, dan ISO 27001:2022 (CHANGELOG.md:8-16²⁸, CHANGELOG.md:18-23²⁹). Daftar format, opsi ekspor, dan isi tiap berkas dibahas di Pelaporan dan Ekspor.

Mode diff dan struktur repository

Flag --diff BASELINE CURRENT melewati fase scan sepenuhnya. Mode ini memuat dua JSON, memanggil diff_scans, merender hasil sesuai --diff-format, lalu mencetak New, Fixed, Severity Changed, Unchanged, dan Net Delta (deep_eye.py:207-235³⁰). Fitur yang sama menormalkan URL agar pencocokan antar-scan akurat (CHANGELOG.md:35-39³¹). Alur retest dan interpretasi delta ada di Scan Diff dan Retest.

Direktori tingkat atas memisahkan CLI (deep_eye.py), mesin dan pelaporan (core/), adapter provider (ai_providers/), modul serangan dan pipeline (modules/), utilitas termasuk ekspor (utils/), template YAML (templates/), plugin kustom (plugins/), dan suite pytest (tests/) (README.md:204-222³²).

⚠️ Deep Eye hanya untuk pengujian keamanan yang berizin. README menegaskan pemakaian terbatas pada sistem yang dimiliki atau memiliki izin tertulis, bahwa akses tanpa izin melanggar hukum, dan bahwa penulis tidak menanggung tanggung jawab atas penyalahgunaan (README.md:252-259³³).

Sisanya dijelaskan pada halaman Arsitektur, Instalasi dan Konfigurasi Awal, Antarmuka CLI, Template YAML dan Plugin Kustom, dan Skills Agen dan Pengujian.