Instalasi, Konfigurasi, dan Deployment

Guardian adalah CLI berbasis Python yang dapat dijalankan langsung dari virtualenv atau dari image Docker. Halaman ini memandu tiga jalur penyiapan: instalasi editable dengan pip install -e ., penyetelan config/guardian.yaml beserta berkas .env, dan penyalaan image lewat Dockerfile dan docker-compose.yml. Untuk daftar perintah beserta opsinya, lihat Referensi Perintah CLI. Untuk pemilihan provider dan kontrak plugin, lihat Provider AI dan Kontrak Plugin. Untuk guardrail scope dan sanitasi, lihat Keamanan, Scope, dan Sanitasi.

Bootstrap dari clone sampai workflow pertama

Prasyarat minimum adalah Python 3.11 atau lebih tinggi, satu API key provider AI, dan Git untuk clone repository README.md:123-134¹. Setelah venv aktif, pip install -e . memasang paket dalam mode editable sehingga perubahan kode langsung terpakai tanpa instalasi ulang README.md:167-190².

graph TD
  clone["git clone guardian-cli"] --> venv["python -m venv venv"]
  venv --> install["pip install -e ."]
  install --> init["python -m cli.main init"]
  init --> cfg["~/.guardian/guardian.yaml"]
  init --> envf[".env + GOOGLE_API_KEY"]
  cfg --> verify["python -m cli.main models"]
  envf --> verify
  verify --> run["workflow run --name recon"]
  style install fill:#2d7d46,color:#fff
  style run fill:#2d7d46,color:#fff
  style cfg fill:#f59e0b,color:#000
  style envf fill:#f59e0b,color:#000
  style verify fill:#8b5cf6,color:#fff
%% fig: Urutan bootstrap dari clone sampai workflow pertama
%% desc: Clone diikuti venv dan instalasi editable, lalu init membuat guardian.yaml dan .env sebelum verifikasi provider dan workflow pertama.

Dependensi inti yang ditarik oleh pip install -e . mencakup typer, rich, keluarga langchain, pyyaml, python-dotenv, pydantic, jinja2, aiofiles, dan asyncio pyproject.toml:27-40³. Ada dua extra opsional: dev untuk pytest, black, dan ruff, serta litellm dengan batas versi >=1.80,<1.87; berkas yang sama juga mendaftarkan console script guardian = "cli.main:app" pyproject.toml:42-54⁴. Di Windows, console script itu tidak selalu tersedia, jadi gunakan python -m cli.main atau launcher guardian.bat yang hanya meneruskan argumen ke modul tersebut guardian.bat:1-3⁵ QUICKSTART.md:141-146⁶.

Langkah inisialisasi menjalankan python -m cli.main init atau .\guardian.bat init QUICKSTART.md:16-28⁷. Perintah init menulis konfigurasi ke ~/.guardian secara default, dengan opsi --config-dir dan --force untuk menimpa berkas yang sudah ada cli/commands/init.py:15-26⁸. Perintah itu menyalin template config/guardian.yaml, menanyakan API key Gemini secara tersembunyi lalu menulis GOOGLE_API_KEY ke .env, serta membuat direktori ./reports dan ./logs cli/commands/init.py:33-74⁹. Alternatif tanpa interaksi adalah make setup, yang menyalin .env.example menjadi .env bila belum ada dan membuat reports serta logs Makefile:42-46.

Verifikasi instalasi dilakukan dengan python -m cli.main --help lalu python -m cli.main models README.md:243-251¹⁰. Perintah models mencetak tabel model per provider (Gemini, OpenAI, Claude, OpenRouter, Requesty) dan mengingatkan lima nama variabel API key cli/commands/models.py:11-57¹¹. Workflow pertama yang lazim dipakai adalah python -m cli.main workflow run --name recon --target example.com QUICKSTART.md:56-59¹². Bila satu parameter didefinisikan di beberapa tempat, urutan prioritasnya adalah parameter YAML workflow, lalu blok konfigurasi, lalu default tool README.md:297-301¹³.

Menyetel config/guardian.yaml

Ada dua lokasi konfigurasi yang perlu dibedakan. init menyalin template ke ~/.guardian/guardian.yaml cli/commands/init.py:33-74⁹, sedangkan dokumentasi menganjurkan menyunting config/guardian.yaml di repository atau ~/.guardian/guardian.yaml QUICKSTART.md:124-131¹⁴. Subcommand workflow dan recon memakai config/guardian.yaml relatif terhadap direktori kerja sebagai default opsi --config/-c, jadi berkas di repository yang terbaca kecuali diarahkan lain cli/commands/workflow.py:22-27¹⁵ cli/commands/recon.py:32-37¹⁶.

Blok ai memilih provider aktif dan menyimpan kredensial per provider; nilai api_key: null berarti kunci diambil dari environment variable config/guardian.yaml:5-45¹⁷. Nilai bawaannya adalah provider: openai, temperature: 0.2, max_tokens: 8000, timeout: 60, dan rate_limit: 2 config/guardian.yaml:41-45¹⁸. Kunci konfigurasi yang paling sering disentuh:

Nilai pada tabel diambil dari blok ai config/guardian.yaml:41-45¹⁸, blok pentest config/guardian.yaml:71-87¹⁹, dan blok output config/guardian.yaml:88-100²⁰.

Blok ai.pricing memetakan nama model ke tarif prompt dan completion dalam USD per 1 juta token config/guardian.yaml:47-68²¹. Tabel ini dipakai untuk menghitung biaya per panggilan; model yang tidak terdaftar menghasilkan biaya 0.0 dan satu peringatan bahwa biaya akan dilaporkan sebagai $0.00 ai/providers/base_provider.py:39-50²². Bila provider baru dipakai, tambahkan entri harganya agar pelaporan biaya tidak kosong.

⚠️ Menyunting config/guardian.yaml di repository tidak otomatis mengubah ~/.guardian/guardian.yaml yang dibuat init. Pilih satu lokasi, atau arahkan setiap perintah dengan --config cli/commands/workflow.py:22-27¹⁵.

Variabel lingkungan dan berkas .env

.env.example hanya mengaktifkan satu variabel, yaitu GOOGLE_API_KEY, sementara LANGCHAIN_TRACING_V2, LANGCHAIN_API_KEY, LANGCHAIN_PROJECT, GUARDIAN_CONFIG_PATH, dan GUARDIAN_REPORTS_DIR tersedia sebagai baris komentar yang harus dibuka sendiri .env.example:1-17²³. Provider membaca api_key dari blok konfigurasi lebih dulu, lalu jatuh ke environment variable bila nilainya kosong, misalnya OPENAI_API_KEY untuk provider OpenAI ai/providers/openai_provider.py:26-33²⁴.

Sumber tabel adalah .env.example:1-17²³, daftar variabel kunci pada README.md:228-241²⁵, dan pengingat nama variabel di keluaran models cli/commands/models.py:11-57. README juga menampilkan bentuk blok YAML per provider di config/guardian.yaml sebagai alternatif environment variable README.md:192-226. Untuk provider lokal, OLLAMA_HOST dipakai sebagai penunjuk endpoint Ollama QUICKSTART.md:66-70.

Deployment dengan Docker

Image dibangun bertahap. Stage builder mengompilasi ffuf dari sumber dengan golang:alpine, lalu menarik biner resmi httpx, subfinder, nuclei, gobuster, amass, dan gitleaks dari image masing-masing Dockerfile:8-17. Stage runtime memakai python:3.11-alpine, menetapkan GUARDIAN_HOME=/guardian, dan menjadikannya working directory Dockerfile:22-35. Seluruh biner hasil stage sebelumnya disalin ke /usr/local/bin Dockerfile:78-85, lalu berkas aplikasi (cli/, core/, ai/, tools/, utils/, workflows/, config/, reports/) disalin dan dipasang dengan pip install --no-cache-dir -e . Dockerfile:111-124.

Container berjalan sebagai user non-root guardian dengan UID 1000, dan ENTRYPOINT-nya adalah python -m cli.main dengan CMD ["--help"] Dockerfile:130-143. Konsekuensinya, container tanpa argumen hanya mencetak bantuan lalu keluar, sehingga pola pakainya adalah docker compose run --rm guardian <perintah> bukan up -d docs/DOCKER.md:5-37²⁸ Makefile:84-98.

graph LR
  ctx["build context ."] --> image["guardian-cli:latest"]
  image --> entry["ENTRYPOINT python -m cli.main"]
  entry --> user["USER guardian UID 1000"]
  envf[".env via env_file"] --> entry
  cfgv["./config -> /guardian/config"] --> entry
  rep["./reports -> /guardian/reports"] --> entry
  style image fill:#8b5cf6,color:#fff
  style envf fill:#f59e0b,color:#000
  style cfgv fill:#f59e0b,color:#000
  style rep fill:#336791,color:#fff
  style user fill:#2d7d46,color:#fff
%% fig: Alur dari build context ke container yang berjalan sebagai non-root
%% desc: Build menghasilkan image, lalu env_file dan volume config serta reports disuntikkan ke container sebelum entrypoint dijalankan sebagai user guardian.

docker-compose.yml mendefinisikan satu service guardian yang membaca .env lewat env_file docker-compose.yml:11-13²⁹, lalu memasang empat volume: ./reports, ./logs, ./config, dan ./workflows ke direktori yang sesuai di dalam container docker-compose.yml:14-27³⁰. Service memakai network_mode: bridge, restart: "no", stdin_open: true, dan tty: true sehingga tidak dimaksudkan sebagai daemon yang hidup terus docker-compose.yml:42-47³¹.

Empat mount tersebut berasal dari docker-compose.yml:14-27³⁰ dan diulang sebagai contoh pada docs/DOCKER.md:84-94³². Untuk mengganti konfigurasi tanpa mengubah image, mount satu berkas guardian.yaml langsung ke /guardian/config/guardian.yaml docs/DOCKER.md:129-134³³. Alternatif tanpa compose memakai docker build -t guardian-cli:latest . lalu docker run --rm dengan volume dan -e yang sama docs/DOCKER.md:51-63³⁴.

Target Makefile membungkus perintah yang sama: docker-build menandai image dengan :latest dan versi dari pyproject.toml, docker-run menjalankannya interaktif, sedangkan compose-up dan compose-down mengurus daur hidup service Makefile:84-98. Untuk eksekusi CLI di dalam venv, make run ARGS="scan --target example.com" memanggil python -m cli.main dengan argumen tersebut Makefile:107-109.

⚠️ Berkas .env dikecualikan dari build context .dockerignore, padahal compose mewajibkannya lewat env_file. Salin .env.example menjadi .env lebih dulu, jika tidak docker compose run gagal karena berkas tidak ada .dockerignore:49-52 docker-compose.yml:11-13²⁹.

⚠️ Build image menuntut memori besar; dokumentasi menyarankan minimal 4GB pada Docker Desktop docs/DOCKER.md:222-227³⁵. Perintah perbaikan izin chmod 777 -R ./reports ./logs bersifat destruktif terhadap permission direktori lokal, jadi jalankan hanya bila mount benar-benar gagal docs/DOCKER.md:229-234³⁶.

Untuk rahasia produksi, jangan menaruh kunci di .env yang ikut terbaca banyak pihak; dokumentasi menyarankan Docker secret dan memastikan container tetap berjalan sebagai non-root guardian docs/DOCKER.md:279-297³⁷.