# tor-mcp

`.onion` / dark web araştırması için bir MCP sunucusu. Yetkili tehdit istihbaratı,
kırmızı takım ve güvenlik araştırması içindir.

Bu sunucu işi sıfırdan yapmaz. [OpenTor skill](https://github.com/)'inin motorunu
**Model Context Protocol üzerinden dışarı açar**. MCP açık bir protokol olduğu için
sunucu model bağımsızdır: Cursor, VS Code, Zed, Cline, Continue, OpenAI Agents SDK,
LangChain gibi MCP konuşan her istemci ve tool-calling yapabilen her model
kullanabilir.

Neden sarmalayıcı, neden kopya değil: motor kodunda reklam filtreleme, diferansiyel
kalibrasyon, ayna birleştirme ve açıklanabilir sıralama gibi kırılgan bilgi birikmiş.
İkinci bir kopya tutmak iki ayrı yerde bakım yapmak demek olurdu.

## Gereksinimler

| Gereksinim | Not |
|---|---|
| Python 3.10+ | |
| OpenTor motoru | Konumu `OPENTOR_SKILL_ROOT` ile belirtilir |
| Tor SOCKS proxy | Çalışıyor olmalı, sunucu Tor'u kendisi başlatmaz |

Sunucu, skill'in `.env` dosyasındaki `TOR_SOCKS_PORT` ayarını kullanır.

- **9050**: bağımsız `tor.exe` veya Tor Expert Bundle
- **9150**: Tor Browser (açık kalmalı)

`OPENTOR_SKILL_ROOT` ortam değişkenini OpenTor motorunun bulunduğu klasöre ayarla.

## Kurulum

```bash
git clone https://github.com/ilkerK01/tor-mcp.git
cd tor-mcp
python -m venv .venv
```

Linux / macOS:

```bash
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python selftest.py
```

Windows:

```powershell
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe selftest.py
```

`ALL CHECKS PASSED` görmelisin. Tor kapalıysa ağ tool'ları atlanır, geri kalan
her şey yine test edilir.

## İstemciye bağlama

Aşağıdaki yollarda `/path/to/tor-mcp` kısmını kendi klasörünle değiştir.

### Elle JSON (Cursor, Zed, Cline, VS Code vb.)

```json
{
  "mcpServers": {
    "tor-mcp": {
      "command": "/path/to/tor-mcp/.venv/bin/python",
      "args": ["/path/to/tor-mcp/server.py"]
    }
  }
}
```

Windows'ta `command` alanı `C:\\path\\to\\tor-mcp\\.venv\\Scripts\\python.exe` olur.

> **Windows yol notu:** Kullanıcı adında ASCII dışı karakter varsa (ör. Türkçe
> `İ`, `ş`, `ğ`) UTF-8 okumayan araçlar yolu bozup süreci dosyayı bulamadan
> öldürebilir. Bu durumda `dir /x` ile 8.3 kısa yolunu öğrenip onu kullan.

## Tool'lar (14)

### Bağlantı

| Tool | İş |
|---|---|
| `tor_status` | Tor bağlı mı, çıkış IP'si ne. Her oturumda önce bunu çağır. |
| `tor_new_identity` | Devreyi yenile, yeni çıkış düğümü al. Kontrol portu 9051 gerekir. |

### Arama

| Tool | İş |
|---|---|
| `onion_search` | 12 motorda ara. Reklam ve sayfa mobilyası ayıklanmış, tekilleştirilmiş, skorlanmış sonuç döner. |
| `list_engines` | Motor ve analiz modu listesi |
| `engine_health` | Tüm motorları pingle, up/down ve gecikme raporla |

### Çekme

| Tool | İş |
|---|---|
| `onion_fetch` | Tek URL'yi Tor üzerinden çek, metne çevir |
| `onion_batch_fetch` | Birden çok URL'yi paralel çek |
| `triage_results` | Hangi sonuçlar gerçekten canlı, ölüleri ele ve canlıları öne al |

### Analiz

| Tool | İş |
|---|---|
| `extract_iocs` | Hash, IP, domain, e-posta, CVE, kripto cüzdanı, ATT&CK tekniği, mesajlaşma handle'ı çıkarır |
| `plan_queries` | Tek hedefi çeşitli bir sorgu setine genişletir |
| `classify_target` | Hedefin türünü belirler (domain, e-posta, onion, aktör adı) |

### Soruşturma

| Tool | İş |
|---|---|
| `investigate` | Çok turlu soruşturma: ara, pivotla, dosya çıkar. Bütçe sınırlı. |
| `crawl_onion` | Bir .onion sitesini öncelik güdümlü tarar, yapısını çıkarır |
| `export_findings` | JSON, CSV, STIX, MISP veya düz metin olarak dışa verir |

## Analiz modları

`onion_search`, `plan_queries` ve `investigate` bir `mode` parametresi alır. Mod,
hangi motorların kullanılacağını ve sorguların nasıl genişletileceğini belirler.

- `threat_intel`: genel tehdit istihbaratı, tüm motorlar
- `ransomware`: fidye yazılımı sızıntı siteleri, bilinen tohum adresler dahil
- `personal_identity`: kimlik ve kimlik bilgisi sızıntısı
- `corporate`: kurumsal maruziyet

## Tipik akış

```
1. tor_status                     bağlantıyı doğrula
2. engine_health                  kaç motor ayakta (az sonuç gelirse sebebi budur)
3. plan_queries(hedef, mode)      sorgu setini gör
4. onion_search(sorgu, mode)      sonuçları topla
5. triage_results(sonuclar)       ölü adresleri ele
6. onion_batch_fetch(canli_urls)  içerikleri çek
7. extract_iocs(metin)            IOC çıkar
8. export_findings(..., "misp")   platforma teslim et
```

Kestirme yol: `investigate(hedef, mode)` 3 ile 7 arasını tek çağrıda yapar.

## Dikkat edilecekler

**Süre.** Tor üzerinden her istek 30 ile 60 saniye sürer. `onion_search` motorları
paralel sorgular ama yine de bir dakikayı bulabilir. `investigate` varsayılan olarak
240 saniyelik sert bir bütçeyle çalışır, çünkü çoğu MCP istemcisinin zaman aşımı
bunun üstündedir. Bütçe dolunca kısmi dosya döner, hiçbir şey kaybolmaz.

**Ölü adresler normaldir.** Sızıntı siteleri sürekli adres değiştirir.
`triage_results` tam olarak bunun için var.

**Sonuç azsa önce motorları kontrol et.** `.onion` arama motorlarının yarısının
aynı anda kapalı olması olağandır. "Bu konuda hiçbir şey yok" demeden önce
`engine_health` çalıştır.

**Tokenizasyon önemli.** Motorlar niyeti değil token'ı indeksler. Bitişik, boşluklu
ve tireli formlar farklı sonuç verir. Bir şeyin indekste olmadığına karar vermeden
önce üçünü de dene.

**Gözlem yorum değildir.** `investigate` bir dosya döner, hüküm vermez. Bir
sızıntının gerçek mi yoksa yeniden satılan eski bir dump mı olduğuna karar vermek
çağıranın işidir.

**Kapsam.** Yetkili tehdit istihbaratı, kırmızı takım ve güvenlik araştırması
içindir. Sunucu yasa dışı içeriği filtreler ama asıl sınırı kullanan çizer.

## Sorun giderme

| Belirti | Sebep ve çözüm |
|---|---|
| `Tor SOCKS proxy is not reachable` | Tor kapalı. 9150 ise Tor Browser'ı aç, 9050 ise `tor` sürecini başlat. |
| `tor_new_identity` hata veriyor | Kontrol portu 9051 `torrc` içinde açık değil |
| Arama boş dönüyor | `engine_health` çalıştır, motorlar düşmüş olabilir |
| `OpenTor skill not found` | `OPENTOR_SKILL_ROOT` değişkenini skill klasörüne ayarla |
| Sunucu hiç açılmıyor | `selftest.py` çalıştır ve hatayı oku |

## Dosyalar

```
tor-mcp/
├── server.py         MCP sunucusu, 14 tool
├── selftest.py       Tor'suz çalışan doğrulama testi
├── requirements.txt
├── LICENSE
└── README.md
```

Veritabanı ve bulgu defteri skill ile ortaktır (`<skill>/database/opentor.db`).
Yani MCP üzerinden yaptığın araştırma, skill üzerinden yaptığınla aynı hafızayı
paylaşır. Bu dosya repoya dahil değildir.

## Lisans

MIT. Ayrıntı için `LICENSE` dosyasına bak.