# 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).