Referensi Perintah CLI

Guardian memasang satu entry point konsol bernama guardian yang menunjuk ke cli.main:app (pyproject.toml:53-54¹). Objek Typer dibuat dengan name="guardian", add_completion=False, dan rich_markup_mode="rich" (cli/main.py:64-69²). Sembilan perintah didaftarkan lewat app.command(...) dan dua grup lewat app.add_typer(...) pada objek yang sama (cli/main.py:74-83³). Perintah version menyusul lewat dekorator @app.command() (cli/main.py:103-115⁴).

Hampir semua perintah menerima typer.Option bernama. Pengecualiannya workflow, yang mengambil action sebagai typer.Argument, dan kb query, yang mengambil text sebagai argumen (cli/commands/workflow.py:18-52⁵, cli/commands/kb.py:295-313⁶). Kegagalan validasi selalu berakhir dengan raise typer.Exit(1) sebelum pekerjaan dimulai.

Pohon perintah

graph TD
  app["app — cli.main:app"] --> init["init"]
  app --> scan["scan"]
  app --> recon["recon"]
  app --> analyze["analyze"]
  app --> report["report"]
  app --> workflow["workflow"]
  app --> ai["ai"]
  app --> models["models"]
  app --> version["version"]
  app --> kb["kb — Typer sub-app"]
  app --> telemetry["telemetry — Typer sub-app"]
  kb --> kb_status["kb status"]
  kb --> kb_seed["kb seed"]
  kb --> kb_update["kb update"]
  kb --> kb_query["kb query"]
  telemetry --> tel_export["telemetry export"]
  telemetry --> tel_train["telemetry train"]
  telemetry --> tel_status["telemetry status"]
  style app fill:#f59e0b,color:#000
  style kb fill:#336791,color:#fff
  style telemetry fill:#8b5cf6,color:#fff
  style version fill:#2d7d46,color:#fff
%% fig: Pohon perintah Typer Guardian
%% desc: Objek app di cli/main.py mendaftarkan sembilan perintah tunggal dan dua sub-app, lalu sub-app kb dan telemetry memecah diri menjadi subcommand masing-masing.

Nama kolom pertama di tabel itu sama dengan nama yang dipakai pada app.command(name=...), dan tiga baris terakhir memakai nama yang diteruskan ke app.add_typer (cli/main.py:74-83³).

init

Signature dua opsi itu ada di cli/commands/init.py:14-27⁷. Perintah menyalin template config/guardian.yaml ke <config_dir>/guardian.yaml, meminta kunci Gemini lewat prompt berpassword, lalu menulis <config_dir>/.env berisi GOOGLE_API_KEY=<kunci> (cli/commands/init.py:38-58⁸). Dua direktori kerja ikut dibuat di akhir: ./reports dan ./logs (cli/commands/init.py:38-58⁸). Bila guardian.yaml sudah ada dan --force tidak diberikan, perintah meminta konfirmasi Overwrite? sebelum menimpa (cli/commands/init.py:38-58⁸).

scan

Kelima opsi itu dideklarasikan di cli/commands/scan.py:16-36⁹. scan hanyalah pembungkus NmapTool: konfigurasi dimuat, override diterapkan, lalu nmap.execute(target, ports=ports) dijalankan lewat asyncio.run (cli/commands/scan.py:16-36⁹). Nilai --provider divalidasi terhadap daftar gemini, openai, claude, openrouter, requesty; nilai di luar daftar mencetak Invalid provider '{provider}'. Must be one of: ... lalu keluar dengan kode 1 (cli/commands/scan.py:47-52¹⁰).

recon

Seluruh opsi tercantum di cli/commands/recon.py:18-60¹¹. Bila hanya --domain yang diberikan, nilainya dipakai sebagai target dan sebuah pesan deprecation dicetak; bila keduanya kosong, perintah mencetak --target is required lalu keluar (cli/commands/recon.py:70-91¹²). Target divalidasi dengan is_valid_domain atau is_valid_url, dan --dry-run mencetak rencana lalu return sebelum konfigurasi dimuat (cli/commands/recon.py:70-91). Rencana dry-run terdiri dari empat langkah: Subfinder, Nmap, httpx, dan AI Analysis (cli/commands/recon.py:147-159). Override provider memakai daftar lima nilai yang sama seperti scan (cli/commands/recon.py:96-112).

ℹ️ Opsi --save/--no-save dideklarasikan dengan default True, tetapi save_results hanya muncul di blok signature dan tidak dibaca lagi di jalur eksekusi (cli/commands/recon.py:38-42¹⁵).

analyze

Dua opsi itu ada di cli/commands/analyze.py:13-16¹⁶. Badan perintah memeriksa keberadaan berkas, memuat JSON, lalu mencetak AI analysis feature coming soon! beserta jumlah findings yang ditemukan (cli/commands/analyze.py:28-37¹⁷). Perintah ini belum menjalankan analisis apa pun.

report

Himpunan ekspor yang sah dibatasi konstanta _VALID_EXPORTS = {"sarif", "defectdojo", "slack"} dan keenam opsi dideklarasikan sesudahnya (cli/commands/report.py:13-38¹⁸). Setiap nilai --export diperiksa lebih dulu agar kegagalan terjadi cepat; nilai asing mencetak Unknown export format '{fmt}'. Valid: ... lalu keluar (cli/commands/report.py:59-67¹⁹). Session dibaca dari ./reports/session_{session_id}.json, dan berkas yang tidak ada menghasilkan Session not found: ... (cli/commands/report.py:68-72²⁰). Laporan ditulis lewat ReporterAgent.execute, dengan ekstensi keluaran dipilih dari {"markdown": "md", "html": "html", "json": "json"} (cli/commands/report.py:74-96²¹).

Ekspor tambahan berjalan sesudah berkas utama ditulis: sarif menghasilkan report_<id>.sarif, defectdojo menghasilkan report_<id>.defectdojo.json, dan slack memanggil slack_exporter.post lalu mencetak status HTTP (cli/commands/report.py:99-119²²).

⚠️ --export slack tanpa --slack-webhook atau env GUARDIAN_SLACK_WEBHOOK langsung berhenti dengan pesan --export slack requires --slack-webhook or GUARDIAN_SLACK_WEBHOOK env var sebelum payload dibangun (cli/commands/report.py:99-119²²).

sequenceDiagram
  participant U as operator
  participant C as report_command
  participant M as PentestMemory
  participant R as ReporterAgent
  participant X as core.exporters
  U->>C: report --session id --export sarif
  C->>C: validasi _VALID_EXPORTS
  C->>C: cek ./reports/session_id.json
  C->>M: load_state session file
  C->>R: execute format
  R-->>C: report content
  C->>C: tulis berkas output
  C->>X: export sarif / defectdojo / slack
  X-->>C: dokumen atau HTTP status
%% fig: Urutan eksekusi guardian report
%% desc: Perintah memvalidasi pemilih ekspor dan berkas session lebih dulu, baru membangkitkan laporan dan menjalankan ekspor tambahan.

workflow

Kedelapan parameter itu ada di cli/commands/workflow.py:18-52⁵. action == "list" memanggil _list_workflows lalu kembali (cli/commands/workflow.py:62-81²³). action == "run" mewajibkan --name; --target juga wajib kecuali --resume diberikan, dengan pesan --name is required for 'run' action dan --target is required for 'run' action (unless --resume is used). Aksi lain berakhir dengan Unknown action: {action} (cli/commands/workflow.py:62-81²³).

list membaca setiap *.yaml di direktori workflows/, memakai nama berkas tanpa ekstensi sebagai nama workflow, dan menampilkan kolom Name, Description, Steps (cli/commands/workflow.py:84-121²⁴). Pada run, provider divalidasi terhadap lima nilai yang sama lalu WorkflowEngine dibangun dan resume_session dipanggil bila --resume diisi; kegagalan menghasilkan Cannot resume session '{resume}' (cli/commands/workflow.py:125-158²⁵). Nama autonomous dirutekan ke run_autonomous, nama lain ke run_workflow (cli/commands/workflow.py:125-158²⁵). Override provider dan model diterapkan pada config["ai"] sebelum engine dibuat (cli/commands/workflow.py:131-147²⁶).

ai

Opsi itu dideklarasikan di cli/commands/ai_explain.py:17-34²⁷. Tanpa --session maupun --last, perintah mencetak Please specify --session <id> or use --last lalu keluar (cli/commands/ai_explain.py:17-34²⁷). Keputusan dibaca dari kunci ai_decisions pada berkas session (cli/commands/ai_explain.py:17-34²⁷).

models

models tidak menerima parameter apa pun (cli/commands/models.py:11-23²⁸). Perintah mencetak satu tabel berisi lima kelompok provider beserta capability tiap model: GEMINI, OPENAI, CLAUDE, OPENROUTER, dan REQUESTY (cli/commands/models.py:11-23²⁸). Baris penutup mengingatkan lima variabel lingkungan kunci: GOOGLE_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, OPENROUTER_API_KEY, REQUESTY_API_KEY (cli/commands/models.py:11-23²⁸).

kb

kb status mencetak jumlah baris per kind; bila index kosong ia mencetak KB is empty lalu keluar dengan kode 0 (cli/commands/kb.py:39-54²⁹). kb seed memanggil KnowledgeBase().upsert(_seed_entries()) dan melaporkan jumlah entri yang ditulis (cli/commands/kb.py:163-168³⁰).

kb update menerima --kind dengan nilai cve, cwe, attck, atau template, ditambah --accept-network dan --file (cli/commands/kb.py:174-199³¹).

⚠️ Tanpa --file, kb update menolak melakukan fetch bila --accept-network tidak diberikan, dengan pesan Refusing to fetch without --accept-network dan exit code 1 (cli/commands/kb.py:174-199³¹). Bila --accept-network diberikan tetapi tidak ada berkas, perintah mencetak Network corpus fetch is not bundled. lalu keluar dengan exit code 2 (cli/commands/kb.py:174-199³¹).

kb query menerima text posisional, --top dengan default 5, penyaring --kind, dan --prompt untuk merender hasil sebagai prompt-block (cli/commands/kb.py:295-313⁶).

telemetry

export menerima berkas session_<id>.json atau direktori reports/ dan menulis ke ./telemetry.jsonl bila --out tidak diisi (cli/commands/telemetry.py:30-42³²). train memakai --min-confidence dengan default 0.7 sebagai ambang abstain ranker; bila train_from_jsonl mengembalikan 0, perintah mencetak No usable rows in JSONL. lalu keluar (cli/commands/telemetry.py:45-59³³). status memuat ~/.guardian/ranker.pkl; bila berkas tidak ada ia mencetak No ranker trained yet. lalu keluar dengan kode 0 (cli/commands/telemetry.py:62-75³⁴).

version

version mencetak guardian-cli <versi> (cli/main.py:103-115⁴). Versi berasal dari _get_version(), yang membaca metadata paket guardian-cli dan jatuh ke 0.0.0+local bila paket tidak terpasang (cli/main.py:103-115⁴).