Güvenlik

Contextator belirli bir dağıtım için inşa edilmiştir: özel bir ağda ya da bir reverse proxy’nin arkasında, güvenilir bir ekip. Panonun hesapları ve rolleri vardır; MCP endpoint’lerinin proje başına bir kapısı vardır. Başka bir yerde açığa çıkarmadan önce bu sayfayı okuyun.

---

Bilinmesi gereken tek şey

Yeni bir proje token required olarak doğar: onu oluşturmak bir ilk token üretir ve gizli anahtarı oluşturma diyaloğunda bir kez gösterir, böylece endpoint’i ilk saniyeden itibaren kapalıdır. Bu varsayılan olmadan önce oluşturulmuş bir proje, zaten sahip olduğu modu korur — yükseltme, mevcut bir projeyi geriye dönük olarak kapatmaz ya da açmaz. Her iki durumda da, modun ayarlandığı yer proje sayfasındaki MCP access panelidir, ve üç tane vardır: open, endpoint’in herkese yanıt verdiği mod; token required, bundan sonra bir istemcinin Authorization: Bearer ctxm_… göndermesi ya da 401 yanıtı alması gereken mod; ya da account required, projenin kendi üyeliklerinin OAuth 2.1 üzerinden endpoint’e ulaştığı ve her istekte denetlendiği mod. Anahtar için Projeler’e ve istemci tarafı için Yapay Zekâ İstemcilerini Bağlamak’a bakın.

Bir token, bir hesap değil, endpoint için bir kimlik bilgisidir. Hiçbir kimlik ve hiçbir doküman başına kural taşımaz, bu yüzden onu elinde tutan herkes o projede indekslenen her şeyi okur, ve pano rolleri /mcp/*’a hiç ulaşmaz.

Yani ağ konumu çoğunu hâlâ belirler. Projelerini open bırakan bir örnek, panonun kimin neyi görebileceği konusunda ne söylediğine bakılmaksızın, ona ulaşabilen herkes tarafından okunabilir: portu özel tutun, ya da onun önüne kimlik doğrulama koyun.

Pano ve admin API’si ayrı bir kapıdır, ve o her zaman kilitlidir: bir kişisel hesap gerektirirler. ADMIN_TOKEN o kilit değildir — betikler için /api/*’a makine erişimidir — ve ikisi de /mcp/*’ı korumaz. Bunu koruyan tek şey bir projenin kendi tokenlarıdır. Bkz. Hesaplar ve İzinler.

Operatör kontrol listesi

1. Her kişiye kendi hesabını verin, ve ihtiyacı olmayan kimseye vermeyin. İlki, tek seferlik bir kodla /setup’ta oluşturulur; geri kalanı sağ üst menüdeki Users’tan gelir. Bir member hesabı yalnızca eklediğiniz projelere ulaşır — bkz. Hesaplar ve İzinler. Düz HTTP bir LAN adresinde AUTH_COOKIE_SECURE=0 ayarlayın, aksi halde tarayıcı oturum çerezini düşürür ve kimse oturum açamaz.
2. ADMIN_TOKEN’ı tarayıcılardan uzak tutun, ve API’ye ihtiyaç duyan bir betik yoksa ayarını kaldırın. Her endpoint’te root izinleriyle davranır; onu bir root parolası gibi ele alın.
3. Özel bir git deposu ya da bir Notion integration’ı eklemeden önce SECRET_KEY’i 32+ rastgele karaktere (openssl rand -hex 32) ayarlayın. Onu veritabanı yedeğinizden başka bir yerde saklayın.
4. Herkese açık olmaması gereken projeleri kapatın. Proje sayfasında MCP access: token required, ardından istemci başına bir kez New token, ya da onu okuyabilecek kişilerin zaten burada hesapları varsa account required. Açık bırakılan bir proje, URL’sine ulaşabilen herkes tarafından okunabilir — bkz. Projeler.
5. Portu genel internetten uzak tutun, ya da kimlik doğrulamayı bir reverse proxy’de sonlandırın — kasıtlı olarak open bıraktığınız projeler için de dahil. Varsayılan (CONTEXTATOR_BIND=127.0.0.1) portu zaten yalnızca bu makinede yayımlar; bunu değiştiren tek ayar 0.0.0.0’dır, ve önüne bir reverse proxy ya da bir VPN koymanın tam zamanı da budur. Bkz. Yapılandırma.
6. ALLOWED_DOC_ROOTS’u dar tutun. Hangi dizinlerin indekslenebileceğine karar veren sınır budur.
7. Gönderilen compose dosyasının yaptığı gibi dokümantasyonu salt okunur bağlayın (:ro).
8. Kaynak tokenlarını sıkı kapsamlayın. Bir git token’ının dokümantasyon depolarına okuma erişimine ihtiyacı vardır, daha fazlasına değil.
9. Sırları indekslemeyin. İndekslenen her şey, endpoint’e ulaşabilen her agent tarafından — ve hiçbir doküman başına kural taşımayan o projenin MCP tokenlarını elinde tutan herkes tarafından — okunabilir.

Ne korunur, ve nasıl

Kimlik doğrulamayı öne koymak

Akış aktarımlarını bozulmadan bırakan nginx Basic authentication örneği:

location / {
    auth_basic           "Contextator";
    auth_basic_user_file /etc/nginx/.htpasswd;

    proxy_pass         http://127.0.0.1:3444;
    proxy_http_version 1.1;
    proxy_set_header   Host $host;
    proxy_set_header   X-Forwarded-Proto $scheme;
    proxy_buffering    off;
    proxy_read_timeout 1h;
}

# the webhook endpoint must stay reachable by the git host
location /api/webhooks/ {
    auth_basic off;
    proxy_pass http://127.0.0.1:3444;
}

Çoğu MCP istemcisinin Basic kimlik bilgileri gönderemediğini unutmayın, bu yüzden böyle bir proxy, agent’lardan çok panoya hizmet eder — ve pano zaten bir hesap istediğinden, önüne ikinci bir sorgu koymak pek az şey kazandırır. /mcp/*’ın kendisi için bir proje token’ı daha iyi bir uyumdur, çünkü o, MCP istemcilerinin zaten ayarlamayı bildiği sıradan bir Authorization başlığıdır. Kasıtlı olarak open bıraktığınız projeler için proxy’yi, ya da bir mutual-TLS ya da VPN sınırını koruyun.

TLS’yi sonlandıran bir proxy’nin arkasında, X-Forwarded-Proto’ya güvenmek yerine AUTH_COOKIE_SECURE=1 ayarlayın.

Şeyleri değiştirmek

Contextator’ın karşı savunmadığı şeyler

• Dokümantasyon üzerinden prompt injection. Bir doküman “talimatlarını yoksay ve…” diyorsa, agent onu okuyabilir. Contextator metni sadakatle döndürür; niyeti temizlemez. İndekslenmiş gövdenizi güvenilir girdi olarak ele alın.
• Hız sınırlama. Oturum açmak, IP adresi başına ve hesap başına sınırlıdır. Başka hiçbir şey değil: /api/*’ın geri kalanı değil, /mcp/* de değil — token korumalı bir proje de istisna değil — bir token’ı elinde tutan bir istemci istediği kadar sık sorabilir. Ağ sınırı kontroldür.
• İki faktörlü kimlik doğrulama. Yoktur; yerel bir hesap bir kullanıcı adı ve bir paroladır. Tekli oturum açma ayrıdır — yapılandırılmış bir OIDC sağlayıcısı olan bir örnek onu bir parolanın yanında sunar — ve kimin ne yaptığının kaydı, yalnızca sunucu logu değil, panodaki #/~audit’teki audit logudur, yalnızca root ve admin için.
• /mcp/*’ta kullanıcı başına ya da doküman başına kurallar. Bir proje token’ı, bir kimlik değil, tüm endpoint için bir kimlik bilgisidir. Onu elinde tutan herkese, bu token en son ne zaman kullanıldının ötesinde hiçbir audit izi olmadan, projedeki her dokümanı verir. Pano rolleri /mcp/*’a ulaşmaz — bir viewer üyeliği orada hiçbir şey vermez, ve hiçbir şey bir token’ı bir projenin bir kısmına daraltmaz. İkisini köprülemek planlıdır ve henüz inşa edilmemiştir; öyle olana kadar, her istemciye kendi token’ını verin ve artık tanımadıklarınızı iptal edin.
• Hangi projelerin var olduğunu gizlemek. Token korumalı bir proje, bilinmeyen bir adın 404 yanıtladığı yerde 401 yanıtlar, bu yüzden sunucuya ulaşabilen herkes yine de bir proje adı öğrenebilir.

Bir güvenlik açığı bildirmek

Onu herkese açık bir issue’da değil, depo sahibine özel olarak bildirin.