Ringkasan Proyek Guardian

Guardian adalah platform otomasi penetration testing berbasis AI yang dipakai lewat satu perintah CLI bernama guardian. Blok [project.scripts] memetakan perintah itu ke objek Typer cli.main:app pyproject.toml:53-54¹. README menempatkan Guardian sebagai framework otomasi penetration testing yang menggabungkan beberapa provider AI dengan tool keamanan README.md:13².

Halaman ini hanya memberi peta: tujuan, fitur rilis 4.0, modul tingkat atas, dan prasyarat. Mekanisme tiap bagian dibahas di halaman lain dan ditautkan di sepanjang teks.

Tujuan dan batas pemakaian

Guardian dirancang khusus untuk pengujian keamanan yang berizin dan tujuan edukasi. README memisahkan pemakaian legal (penetration testing berizin, riset keamanan, lingkungan edukasi) dari pemakaian ilegal (akses tanpa izin, aktivitas berbahaya), lalu menegaskan bahwa pengguna bertanggung jawab penuh memastikan izin tertulis sebelum menguji sistem apa pun README.md:21-30³.

⚠️ Mengarahkan guardian workflow run ke target yang tidak Anda miliki adalah pelanggaran hukum, bukan sekadar kesalahan konfigurasi. Pengaman teknisnya — validasi scope berbasis DNS-resolve, safe_mode, dan confirmation gate — dijelaskan di Keamanan, Scope, dan Sanitasi.

Fitur rilis 4.0

Rilis [4.0.0] bertanggal 2026-05-29 dan berisi 14 item dalam 2 track, dengan 296 test lulus CHANGELOG.md:9-12⁴. Track A mengisi sisi AI/agent, sedangkan Track B memperluas cakupan tool CHANGELOG.md:16-50⁵ CHANGELOG.md:52-71⁶.

Track A — AI/Agent R&D

Track B — Perluasan cakupan tool

Angka yang berubah di rilis ini: registry tool tumbuh dari 31 menjadi 50 tool dan registry provider dari 4 menjadi 6 provider CHANGELOG.md:83-85¹³. Suite berisi 296 test lulus CHANGELOG.md:118¹⁴, dan waktu startup guardian --help tetap di bawah 500ms karena kontrak lazy load dipertahankan CHANGELOG.md:95-96¹⁵.

Batasan yang masih terbuka pada rilis 4.0: provider selain OpenAI dan Claude belum mengimplementasikan generate_with_images sehingga visual triage dilewati dengan alasan tercatat; reranker embedding bergantung pada sentence-transformers; dan ranker telemetry abstain saat operator masih di bawah 20 sesi CHANGELOG.md:124-133¹⁶.

Modul tingkat atas

cli adalah permukaan perintah yang mendaftarkan workflow, scan, recon, analyze, report, ai, models, lalu dua grup tambahan kb dan telemetry cli/main.py:63-83¹⁷. core memegang WorkflowEngine yang membangun PentestMemory, ScopeValidator, dan empat agent — PlannerAgent, ToolAgent, AnalystAgent, ReporterAgent core/workflow.py:27-50¹⁸.

graph TD
    CLI["cli.main:app (Typer)"] --> WF["core.workflow.WorkflowEngine"]
    WFY["workflows/*.yaml (DSL v2)"] --> WF
    WF --> AGENT["core agents: planner, tool_agent, analyst_agent, reporter_agent"]
    AGENT --> PROV["ai.providers.get_provider"]
    AGENT --> REG["core.tool_agent.TOOL_REGISTRY"]
    CLI --> REG
    CLI --> EXPORT["guardian report --export sarif|defectdojo|slack"]
    REG --> WRAP["tools/*.py wrapper, diimpor saat dipakai"]
    WF --> MEM["core.memory.PentestMemory"]
    EVAL["evals/ tiga tier"] --> WRAP
    style MEM fill:#336791,color:#fff
    style PROV fill:#f59e0b,color:#000
    style REG fill:#8b5cf6,color:#fff
    style EVAL fill:#2d7d46,color:#fff
%% fig: Peta modul tingkat atas Guardian
%% desc: CLI memanggil WorkflowEngine, yang merangkai agent, provider AI, registry tool, dan memory; workflows/ memasok definisi langkah dan evals/ memutar ulang keluaran tool untuk menguji parser.

Struktur direktori lengkap beserta komentar per folder tercantum di README README.md:547-591²⁴. Ketergantungan antar modul, alur satu run, dan pembagian tanggung jawab antar agent diuraikan di Arsitektur Sistem serta Sistem Multi-Agen.

Permukaan perintah

Selain workflow run, CLI menyediakan scan, recon, report, models, kb, telemetry, dan ai docs/README.md:76-86²⁵. Ekspor laporan dipicu lewat flag berulang pada satu perintah, misalnya guardian report --export sarif --export defectdojo --export slack README.md:90-95²⁶. Daftar opsi, argumen, dan contoh tiap perintah ada di Referensi Perintah CLI.

Prasyarat

Paket menetapkan requires-python = ">=3.11" dan mendaftarkan nama guardian-cli pyproject.toml:5-10²⁷. Runtime intinya adalah typer, rich, langchain beserta konektor provider, pydantic, dan jinja2 pyproject.toml:27-40²⁸. Modul yang dipaketkan lewat [tool.setuptools] adalah cli, core, ai, tools, reports, utils, dan workflows pyproject.toml:56-57²⁹.

Di sisi operator, prasyaratnya adalah Python 3.11 atau lebih baru, satu API key provider AI yang dipilih, dan Git untuk mengkloning repository README.md:123-134³⁰. Tool eksternal seperti nmap atau nuclei bersifat opsional; Guardian tetap berjalan tanpa tool eksternal tetapi kemampuan scanning menjadi terbatas README.md:163³¹. Langkah pemasangan, isi config/guardian.yaml, dan deployment container dibahas di Instalasi, Konfigurasi, dan Deployment.

Versi dan jebakan penomoran

Fungsi _get_version() mengambil versi dari metadata paket dengan version("guardian-cli") dan jatuh ke 0.0.0+local bila paket tidak ditemukan cli/main.py:19-36³². Sementara itu pyproject.toml menetapkan version = "0.1.0" pyproject.toml:5-10²⁷, sedangkan dokumentasi menyebut Guardian sedang merilis v4.0.0 docs/README.md:3-4³³ dan changelog mencatat [4.0.0] — 2026-05-29 CHANGELOG.md:9-12⁴.

⚠️ guardian --version membaca metadata paket, jadi angka yang muncul bisa 0.1.0 walaupun kode yang berjalan adalah jalur v4.0.0. Jangan memakai angka banner sebagai penanda fitur; pakai entri changelog sebagai acuan.

Riwayat rilis

Detail masing-masing mekanisme ada di halaman khusus: provider dan kontrak plugin di Provider AI dan Kontrak Plugin, penjadwalan langkah di Engine Workflow DSL v2, pemilihan tool di Integrasi Tool dan Pemilihan Tool, grounding referensi di Knowledge Base RAG, ekspor laporan di Pelaporan, CVSS, dan Exporter, dan angka pengujian di Pengujian dan Evaluasi.