| # Kali Agent (LocalAI) | |
| Yerel bir LLM (BaronLLM Llama-3.1) ile **Kali Linux** sanal makinesini SSH üzerinden süren otonom bir sızma testi (pentest) ajanı. Beyin Windows'ta, "kollar" Kali'de. Artık sesli komutla da kontrol edilebilir (offline STT, Türkçe). | |
| > Eğitim ve yetkili sızma testi senaryoları içindir. Sadece izin aldığın sistemler üzerinde çalıştır. | |
| --- | |
| ## Mimari Özet | |
| ``` | |
| [Kullanıcı: klavye veya mikrofon] | |
| | | |
| v | |
| +------------------- Windows --------------------+ | |
| | agent.py (REPL + ReAct loop) | | |
| | | | | |
| | +-- voice.py (faster-whisper STT, ops.) | | |
| | +-- ollama.Client -> BaronLLM (Modelfile) | | |
| | +-- tool_call.py (parse + dispatcher) | | |
| | +-- safety.py (komut filtresi) | | |
| | +-- ssh_client.py | | |
| | +-- logger.py (JSONL session logu) | | |
| +-----------------------|------------------------+ | |
| | paramiko / SSH (anahtar) | |
| v | |
| +--------- Kali VM ---------+ | |
| | bash + nmap/sqlmap/... | | |
| +---------------------------+ | |
| ``` | |
| **ReAct döngüsü** her adımda şu akışı izler: | |
| ``` | |
| Thought: <kısa, tek paragraf> | |
| Action: run_cmd | |
| Action Input: <tek satır bash> | |
| ``` | |
| Komut Kali'de çalıştırılır, çıktı `Observation:` olarak modele geri verilir. Görev `Final Answer:` ile veya `--max-steps` limitiyle biter. Manuel modda her adımda Enter ile onay alınır. | |
| --- | |
| ## Klasör Yapısı | |
| ``` | |
| LocalAI/ | |
| agent.py # Ana orkestrator, REPL, ReAct döngüsü | |
| config.py # .env'den dataclass'lara mapping | |
| ssh_client.py # paramiko sarmalayıcısı (Kali SSH) | |
| tool_call.py # ReAct parser + ToolDispatcher | |
| safety.py # Yıkıcı komut filtresi (block/warn) | |
| voice.py # Sesli komut: faster-whisper + sounddevice | |
| logger.py # Oturum başına JSONL log | |
| Modelfile # Ollama: BaronLLM + sistem promptu + parametreler | |
| requirements.txt | |
| .env / .env.example | |
| test_ssh.py # SSH bağlantısı için izole test | |
| logs/ # session-YYYYMMDD-HHMMSS.jsonl | |
| ``` | |
| --- | |
| ## Kurulum | |
| ### 1. Kali VM tarafı | |
| ```bash | |
| sudo apt update && sudo apt install -y openssh-server | |
| sudo systemctl enable --now ssh | |
| ip a # bridged adapter ise LAN IP'sini not al | |
| ``` | |
| Windows'ta üretilmiş public key'i (`~/.ssh/id_ed25519.pub` içeriği) Kali'de: | |
| ```bash | |
| mkdir -p ~/.ssh && chmod 700 ~/.ssh | |
| echo "ssh-ed25519 AAAA... kerem@windows" >> ~/.ssh/authorized_keys | |
| chmod 600 ~/.ssh/authorized_keys | |
| ``` | |
| ### 2. Windows tarafı | |
| ```powershell | |
| cd C:\Users\kerem\Documents\LocalAI | |
| python -m venv .venv | |
| .\.venv\Scripts\Activate.ps1 | |
| pip install -r requirements.txt | |
| ``` | |
| > Python 3.12 / 3.13 / 3.14 destekleniyor. `faster-whisper` arka planda `ctranslate2` derler; wheel mevcut değilse Visual Studio Build Tools gerekebilir. | |
| ### 3. Ollama + model | |
| ```powershell | |
| # Ollama kurulu degilse: https://ollama.com/download | |
| ollama serve # arka planda calissin | |
| # baronllm-llama3.1-v1-q6_k.gguf dosyasini proje koküne koyduktan sonra: | |
| ollama create KaliSupport -f .\Modelfile | |
| ollama list # KaliSupport gorulmeli | |
| ``` | |
| ### 4. `.env` | |
| `.env.example` dosyasını kopyalayıp düzenle: | |
| ```powershell | |
| Copy-Item .env.example .env | |
| notepad .env | |
| ``` | |
| Doldurulması zorunlu alanlar: | |
| - `KALI_HOST` — Kali VM'in LAN IP'si | |
| - `KALI_SSH_KEY` — Windows'taki **private** anahtarın tam yolu | |
| - `OLLAMA_MODEL` — `ollama list`'te gördüğün isim (örn. `KaliSupport`) | |
| ### 5. SSH'i tek başına doğrula | |
| ```powershell | |
| python test_ssh.py | |
| ``` | |
| `pong` görüyorsan bağlantı sağlam. | |
| --- | |
| ## Çalıştırma | |
| ### REPL (varsayılan) | |
| ```powershell | |
| python agent.py | |
| ``` | |
| REPL komutları: | |
| | Giriş | Anlamı | | |
| |------|--------| | |
| | `<metin>` | Görev metni; ajan ReAct'e başlar | | |
| | `:v` veya `voice` | Mikrofonu aç, konuşmayı transkript et, görev olarak gönder | | |
| | `:r` veya `reset` | Mesaj geçmişini temizle (model konteksini sıfırla) | | |
| | `:q` / `quit` / `exit` | Çık | | |
| ### Voice-first mod | |
| Her prompt'ta otomatik mikrofon açılsın (yine de Enter'a basıp metin de yazabilirsin): | |
| ```powershell | |
| python agent.py --voice | |
| ``` | |
| ### Otomatik mod (her adımı sormadan) | |
| ```powershell | |
| python agent.py --auto | |
| python agent.py --auto --voice | |
| ``` | |
| ### Tek seferlik görev | |
| ```powershell | |
| python agent.py "192.168.1.20 portlarini tara ve 80 acıksa dirb yap" | |
| ``` | |
| ### Manuel mod adım onayı | |
| | Tuş | Etki | | |
| |-----|------| | |
| | Enter / `e` | Komutu çalıştır | | |
| | `d` | Komutu düzenle | | |
| | `s` | Bu adımı atla (modele "skipped" döner) | | |
| | `q` | Loop'u durdur | | |
| --- | |
| ## Voice (Sesli Komut) | |
| ### Nasıl çalışıyor | |
| 1. `:v` yazınca mikrofon akışı (`sounddevice`, 16 kHz mono float32) açılır. | |
| 2. Ekrana akan `.` ve `#` karakterleri mini bir VU-meter gibi davranır (`.` sessizlik, `#` ses var). | |
| 3. Konuşmaya başlayınca kayıt başlar; `VOICE_SILENCE_SECONDS` (varsayılan 1.5sn) kesintisiz sessizlikten sonra otomatik kapanır. | |
| 4. Ses parçası `faster-whisper` ile yerelde transkript edilir (varsayılan model: `small`, dil: `tr`). | |
| 5. Transkript ekrana yazılır; onay/düzenleme menüsü gelir: | |
| | Tuş | Etki | | |
| |-----|------| | |
| | Enter / `e` | Aynen görev olarak gönder | | |
| | `d` | Önce düzenle, sonra gönder | | |
| | `r` | Yeniden dinle | | |
| | `q` | İptal | | |
| ### Ortam değişkenleri (`.env`) | |
| | Değişken | Varsayılan | Açıklama | | |
| |----------|------------|----------| | |
| | `VOICE_ENABLED` | `true` | `false` -> `:v` komutu kapalı, kütüphaneler yine de yüklenmeyebilir | | |
| | `VOICE_PREWARM` | `true` | Agent başlangıcında modeli yükle. Açıkken startup ~5-30 sn uzar, ama ilk `:v`'de bekleme olmaz | | |
| | `VOICE_MODEL` | `small` | `tiny` / `base` / `small` / `medium` / `large-v3`. Türkçe için minimum `small` öneririm | | |
| | `VOICE_DEVICE` | `cpu` | `cpu` / `cuda` / `auto`. CUDA seçersen `compute_type`'ı da güncelle | | |
| | `VOICE_COMPUTE_TYPE` | `int8` | CPU: `int8`. GPU: `float16` veya `int8_float16` | | |
| | `VOICE_LANGUAGE` | `tr` | `tr`, `en`, ... `auto` -> dili Whisper tahmin eder | | |
| | `VOICE_SAMPLERATE` | `16000` | 16 kHz Whisper'in beklediği değer; değiştirme | | |
| | `VOICE_SILENCE_THRESHOLD` | `0.012` | RMS eşiği. Klavye/fan yüzünden tetiklenirse yükselt; konuşma duyulmuyorsa düşür | | |
| | `VOICE_SILENCE_SECONDS` | `1.5` | Kayıt durduran kesintisiz sessizlik süresi | | |
| | `VOICE_MAX_SECONDS` | `60` | Sert üst sınır | | |
| | `VOICE_INITIAL_TIMEOUT` | `8` | Konuşma hiç başlamazsa kaç saniye sonra iptal | | |
| | `VOICE_INPUT_DEVICE` | *(boş)* | Boş = sistem default. Sayı ya da isim parçası verilebilir | | |
| | `VOICE_CONFIRM` | `true` | `false` -> transkript görünür ama onay sormadan görev olarak gider | | |
| ### Mikrofon listesi | |
| ```powershell | |
| python -m voice devices | |
| ``` | |
| Çıktıdaki numarayı `VOICE_INPUT_DEVICE`'a yaz, ya da ismin bir parçasını (örn. `Realtek`). | |
| ### Sadece STT'yi test et | |
| ```powershell | |
| python -m voice listen | |
| ``` | |
| Konuş, transkript ekranda. Ajan, SSH, hiçbiri açılmaz; mikrofon + Whisper bütünleşmesini izole etmek için ideal. | |
| ### Voice kapanırsa | |
| `:v`'yi her tuşladığında "voice kapali" diyorsa: | |
| ```powershell | |
| python -c "import voice; print(voice.VoiceInput(__import__('config').VoiceConfig.from_env()).is_available())" | |
| ``` | |
| Çıkan mesaj: | |
| - `sounddevice yuklu degil` → `pip install sounddevice` (PortAudio sürücüsü Windows'ta gömülü gelir) | |
| - `faster-whisper yuklu degil` → `pip install faster-whisper` | |
| - `VOICE_ENABLED=false` → `.env`'de `true` yap | |
| - `Mikrofon akisi acilamadi` → `python -m voice devices` ile başka cihaz dene | |
| ### Performans ipuçları | |
| - **CPU + `small` + `int8`** ortalama bir laptop'ta ~5-10 sn'lik bir görev için 1-3 sn transkript verir. | |
| - **GPU yetmezse** `VOICE_DEVICE=cpu` kalsın; BaronLLM zaten 4-6 GB VRAM kullanıyor, paylaşmaktansa CPU'da Whisper koşturmak daha sağlıklı. | |
| - Daha hızlı istiyorsan: `VOICE_MODEL=base`. Daha doğru: `medium` (CPU'da yavaşlar ~2x). | |
| ### İlk çalıştırma: model indirme | |
| İlk `:v`'de (veya `VOICE_PREWARM=true` ile agent başlangıcında) faster-whisper modeli HuggingFace Hub'dan indirilir. Boyutlar (yaklaşık): | |
| | Model | İndirme | Bellek | | |
| |-------|---------|--------| | |
| | `tiny` | 75 MB | ~150 MB | | |
| | `base` | 150 MB | ~300 MB | | |
| | `small` | 466 MB | ~700 MB | | |
| | `medium` | 1.5 GB | ~2.5 GB | | |
| | `large-v3` | 2.9 GB | ~5 GB | | |
| İndirilen dosyalar `C:\Users\<sen>\.cache\huggingface\hub\` altında saklanır. | |
| **HF rate limit / hız:** anonim indirme yavaş olabilir. Hızlandırmak için bir HuggingFace token üret ([huggingface.co/settings/tokens](https://huggingface.co/settings/tokens)) ve PowerShell'de: | |
| ```powershell | |
| $env:HF_TOKEN = "hf_xxxxxxxxxxxxxxxxxx" | |
| python agent.py | |
| ``` | |
| Ya da `.env` dosyasına `HF_TOKEN=hf_...` ekle (python-dotenv zaten yükler). | |
| ### Mikrofon ayarı: konuşmama tetiklenmiyor / kayıt durmuyor | |
| Recording sonu basılan `[voice] kayit bitti: 9.7s, rms=0.011 (esik=0.012)` satırı en kritik tanı çıktısı: | |
| - **`rms < esik`** ise kayıt boyunca eşiğin altındasın; transkript boş gelebilir. Çözüm: mikrofona daha yakın konuş, ya da `VOICE_SILENCE_THRESHOLD`'u düşür (örn. `0.005`). | |
| - **Kayıt hiç durmuyor** (sürekli `#`): arka plan gürültüsü yüksek; eşiği yükselt (`0.020`+) ya da `VOICE_MAX_SECONDS`'i kısalt. | |
| --- | |
| ## Konfigürasyon Referansı | |
| ### Ollama | |
| | Değişken | Açıklama | | |
| |---------|----------| | |
| | `OLLAMA_HOST` | `http://127.0.0.1:11434` | | |
| | `OLLAMA_MODEL` | `Modelfile`'dan ürettiğin isim | | |
| | `OLLAMA_NUM_GPU` | GPU katmanı sayısı. CUDA OOM alırsan düşür | | |
| | `OLLAMA_NUM_CTX` | Bağlam penceresi (token). 4096 tipik nmap çıktıları için yeterli | | |
| | `OLLAMA_TEMPERATURE` | Pentest komutları için 0.3-0.5 öneririm | | |
| | `OLLAMA_KEEP_ALIVE` | **Birim zorunlu**. `30m`, `1h`, `0` (anında unload), `-1` (sonsuz). Birimsiz sayı yazarsan `config.py` otomatik dakikaya çevirir | | |
| ### SSH | |
| | Değişken | Açıklama | | |
| |----------|----------| | |
| | `KALI_HOST` / `KALI_PORT` / `KALI_USER` | Kali VM bağlantısı | | |
| | `KALI_SSH_KEY` | Private key tam yolu | | |
| | `KALI_SSH_KEY_PASSPHRASE` | Boş bırak ya da parola | | |
| | `KALI_SSH_PASSWORD` | Public key oturana kadar fallback | | |
| | `SSH_COMMAND_TIMEOUT` | Saniye. nmap full scan için 600+ tut | | |
| ### Safety | |
| | Değişken | Açıklama | | |
| |----------|----------| | |
| | `SAFETY_MODE` | `enforce` (varsayılan; `block` kuralları durdurur) / `audit` (her şey geçer, sadece loglanır) | | |
| `safety.py` içinde tanımlı kurallar (özet): | |
| - `rm -rf /`, `rm -rf ~`, kritik `/etc` üzerine yazma | |
| - `mkfs`, `dd of=/dev/sd*`, `wipefs` | |
| - Fork bomb (`:(){ :|:& };:`) | |
| - `shutdown` / `reboot` / `systemctl poweroff` | |
| - `~/.ssh` veya `authorized_keys` silme; `sshd` durdurma | |
| - `userdel root/kali` | |
| - `curl ... | bash` (warn) | |
| Kuralları elle test: | |
| ```powershell | |
| python safety.py "rm -rf /" | |
| python safety.py "nmap -sV 192.168.1.10" | |
| ``` | |
| --- | |
| ## Loglar | |
| Her oturum yeni bir JSONL dosyası: `logs/session-YYYYMMDD-HHMMSS.jsonl`. Olay tipleri: | |
| - `session_start` / `session_end` | |
| - `info` / `warn` / `error` | |
| - `model` — modelden dönen metin (thought/response) | |
| - `tool_call` — ajanın istediği tool ve argümanlar | |
| - `command` — Kali'de çalışan komutun stdout/stderr/exit_code | |
| - `safety_match` — kuralla eşleşen komutlar | |
| - `voice_*` — voice yaşam döngüsü (`voice_record_start`, `voice_transcript`, `voice_cancelled`, ...) | |
| Ham logları görmek için: | |
| ```powershell | |
| Get-Content .\logs\session-*.jsonl -Tail 30 | ConvertFrom-Json | Format-Table ts,type,message | |
| ``` | |
| --- | |
| ## Sorun Giderme | |
| | Belirti | Sebep / Çözüm | | |
| |---------|---------------| | |
| | `time: missing unit in duration "1"` | `OLLAMA_KEEP_ALIVE` birim içermiyor. `30m`, `1h`, `-1` yaz. (`config.py` artık otomatik düzeltir) | | |
| | `Ollama'ya ulasilamadi` | `ollama serve` çalışmıyor veya `OLLAMA_HOST` yanlış | | |
| | `Ollama'da '<model>' modeli yok` | `ollama create <ad> -f Modelfile` çalıştır | | |
| | `Kimlik dogrulama basarisiz: kali@...` | Public key Kali'deki `~/.ssh/authorized_keys`'te değil; ya da KALI_SSH_KEY private değil | | |
| | `Komut zaman asimina ugradi` | `SSH_COMMAND_TIMEOUT`'u artır | | |
| | `[voice kapali] sounddevice yuklu degil` | `pip install sounddevice` | | |
| | `Mikrofon akisi acilamadi` | `python -m voice devices` ile mevcut cihazları gör; uygun olanı `VOICE_INPUT_DEVICE`'a yaz | | |
| | Konuşunca hiçbir şey kaydedilmiyor (`...........`) | `VOICE_SILENCE_THRESHOLD` çok yüksek; `0.005` deneyebilirsin | | |
| | Sürekli `#` çıkıyor, kayıt durmuyor | Mikrofon arka plan gürültüsü yüksek; eşiği yükselt veya VOICE_MAX_SECONDS düşür | | |
| | `:v` sonrası uzun süre tepkisiz | Model indiriyor (ilk seferde 466 MB / `small`). `VOICE_PREWARM=true` ile bunu agent başlangıcına taşı; veya `HF_TOKEN` set et | | |
| | `unauthenticated requests to the HF Hub` uyarısı | Anonim indirme; `HF_TOKEN` set edilirse kaybolur ve indirme hızlanır | | |
| | CUDA OOM | `OLLAMA_NUM_GPU`'yu düşür; voice'u CPU'da bırak (`VOICE_DEVICE=cpu`) | | |
| --- | |
| ## Geliştirici Notları | |
| ### Kod stili | |
| - Python 3.12+ syntax (`X | Y`, `dict[str, Y]`) | |
| - Tüm fonksiyon imzalarında tip ipucu | |
| - Yan etki içeren her modül `if __name__ == "__main__":` self-test'iyle gelir: | |
| ```powershell | |
| python tool_call.py # ReAct parser testi | |
| python safety.py # safety kural testi | |
| python -m voice listen # STT entegrasyon testi | |
| python test_ssh.py # SSH end-to-end | |
| ``` | |
| ### Yeni tool eklemek | |
| `tool_call.py` içinde `ToolDispatcher.register("benim_tool", fn)` ile dinamik kayıt: | |
| ```python | |
| def my_tool(args: dict[str, str]) -> str: | |
| return f"Observation gibi geri dönecek string" | |
| dispatcher.register("my_tool", my_tool) | |
| ``` | |
| Modelin bu tool'u tetiklemesi için `Modelfile`'daki sistem promptuna kullanım örneği eklemen gerekir. | |
| ### Yol haritası | |
| - [ ] TTS (sesli yanıt) — modelin Final Answer'ını sesli okusun | |
| - [ ] Wake-word (her zaman dinle, "Kali" deyince devreye gir) | |
| - [ ] Çoklu tool (`run_python`, `read_file`, `download`) | |
| - [ ] Web dashboard (logs/`*.jsonl` üzerinden canlı izleme) | |
| --- | |
| ## Lisans | |
| Kişisel/eğitim amaçlı. Bağımlı oldukları kütüphanelerin lisansları geçerlidir (paramiko BSD, ollama-python MIT, faster-whisper MIT, sounddevice MIT). | |