Ana içeriğe geç

Bölüm 17: Path Filtreleri

Genel Bakış

Path Filtreleri, yapay zekâ araçlarının (kodlama ajanları, editör yerleşik araçları, MCP sunucuları) dosya sistemine hangi yollara hangi izinle dokunabileceğine karar veren katmandır. Bir kural seti, yol desenlerinden ve bu desenlerle eşleşen yollara tanınacak izinden (write / read / none) oluşur. "Gizli dizinlere hiçbir işlem yapılamasın", "proje dizini salt okunur olsun", "kurumsal anahtar dosyaları okunup yazılabilsin" gibi politikalar bu sayfada tanımlanır.

Çalışma modeli, Bölüm 18'deki MIME ve dosya meta verisi kurallarıyla aynı kitaplık mantığıdır:

  • Desenler burada tanımlanır — /admin/path-filters sayfası (yönetim panelinde İçerik Filtreleme başlığı altında) yeniden kullanılabilir kural setlerini yazar.
  • Atama Access Management'tan yapılır — bir kural seti kullanıcı, rol, grup veya IP hedefine bağlanmadıkça kimseye uygulanmaz (Bölüm 11). Kural setleri sayfasının başlığındaki Access Management düğmesi sizi doğrudan atama ekranına götürür.

Karar, araç çağrısı modelin elinden geçtiği anda verilir: Claude Code, Codex, Gemini CLI gibi editörlerde her araç çağrısı PreToolUse hook zinciri üzerinden gateway'e sorulur (aşağıda "Nerede Uygulanır"); explicit proxy arkasındaki ajanlarda ise SSE akışına gömülü araç çağrıları aynı kurallarla incelenir (Bölüm 23). Bir kural seti birden çok hedefe atanabilir; desenler tek yerde yazılıp her yerde aynı şekilde uygulanır.

Sayfanın görünmesi sunucudaki path_acl özelliğine bağlıdır.

Kural Setleri Sayfası

Sayfanın gövdesi Yeniden Kullanılabilir Path Filtresi Kural Setleri kartıdır: kural setleri yeniden kullanılabilir; desenleri burada tanımladıktan sonra Erişim Yönetimi'nde hedeflere bağlarsınız.

  • Arama — "Kural adı veya yol deseni ara" kutusu, kuralın adı ve desenleri üzerinde çalışır; bir desene göre arama, "bu deseni hangi kural setleri içeriyor?" sorusunun en hızlı yanıtıdır. Arama değişince sayfalama başa döner.
  • Yenile — listeyi sunucudan tekrar çeker.
  • Sayfalama — tablo sayfa başına 8 kural gösterir; Önceki/Sonraki düğmeleriyle gezilir.
  • Boş durum — hiç kural yoksa "Path Filtresi Kuralı Yok" kartı ve doğrudan kural oluşturma kısayolu görünür.
  • Sunucu salt okunur yönetim modundaysa Kural Ekle düğmesi ve satır eylemleri gizlenir; sayfa yalnız listelemeye yarar.

Kural tablosu sütunları:

Sütun İçerik
Name Kuralın görünen adı.
İzin (Permission) Kuralın tanıdığı izin düzeyi: write, read veya none (rozet olarak).
Desenler (Patterns) İlk iki desen etiket olarak görünür; kalanı "+N daha" etiketinde toplanır. İmleci etiketlerin üzerinde bekletmek desenin tamamını, "+N daha" üzerinde bekletmek kalan desenlerin listesini gösterir.
Actions Düzenle ve Sil düğmeleri.

Bu sayfada ayrı bir aktiflik (enabled) sütunu ya da anahtarı yoktur: yeni kural etkin olarak oluşturulur; düzenleme, kayıtlı aktiflik durumunu olduğu gibi korur — bir düzenleme kuralı sessizce kapatıp açamaz.

Runtime Anahtarı Kapalıysa

Path Filter'ın genel anahtarı Ayarlar → Runtime'dadır. Anahtar kapalıysa kural setleri sayfasının üstünde bir uyarı bandı belirir:

Path Filter, Ayarlar → Runtime'da kapalı: bu kural setleri ve Access Management atamaları kayıtlı ama hiçbir yerde uygulanmıyor. Anahtar açıldığı anda, yeniden başlatma olmadan uygulanırlar.

Pratikte bunun anlamı (v1.3.0'dan itibaren iki yönde de anında etkili):

  • Anahtar kapalıyken bile kural oluşturabilir, düzenleyebilir ve Access Management'tan atayabilirsiniz — hepsi kaydedilir, hiçbiri uygulanmaz.
  • Anahtar açıldığı anda, gateway'i yeniden başlatmadan tüm kural setleri ve atamalar devreye girer. (Eski sürümlerde anahtarı açmak yeniden başlatma gerektiriyordu; kapatmak ise explicit proxy ve tarayıcı tarafında uygulamayı sürdürüyordu.)
  • Kalıcı veri katmanı etkin olmayan bir kurulumda sayfa, gerekli altyapının eksik olduğunu belirten bir iletiyle yanıt verir — Arceris destek ekibiyle iletişime geçin.

Kural Oluşturma ve Düzenleme

Kural Ekle düğmesi (veya bir satırdaki Düzenle) modalı açar: "Path Filtresi Kuralı Oluştur" / "Path Filtresi Kuralını Düzenle".

Name — kuralın görünen adı (en fazla 128 karakter; ör. "Gizli bilgileri engelle").

İzin (Permission) — desen eşleştiğinde tanınacak izin düzeyi. Form varsayılanı write'tır:

İzin Anlamı
write Okuma ve yazma erişimi tanır. En yetkili düzeydir.
read Yalnızca okuma erişimi tanır. Dosya/dizin içeriği görülebilir ama değiştirilemez.
none Erişimi tamamen engeller. Eşleşen yola hiçbir işlem yapılamaz.

Desenler (Patterns) — her satıra bir yol deseni, satır satır girilir (en fazla 4096 karakter; en az bir desen zorunlu). Yer tutucunun önerdiği biçim: /etc/**, secret/**, config/**. Joker karakterler desteklenir.

Normalize Önizlemesi

Modalda Windows biçiminde desen girdiğinizde (ters bölü, sürücü harfi, baştaki bölü), Arceris deseni normalize edilmiş hâliyle eşleştirir: ters bölüler düz bölüye dönüşür, sürücü harfi küçük harfe iner, baştaki bölüler kırpılır. Modal, yazdığınız anda bu dönüşümü gösterir:

C:\Users\...\gizli\**   →   c:/Users/.../gizli/**

Amaç, sessizce eşleşmeyen bir kural yazmayı imkânsız kılmaktır: "Windows biçimindeki desenler normalize edilmiş hâliyle eşleştirilecek" notu ve desen başına yazdığınız → eşleşecek satırı görünür. Önizleme yalnızca yol gösterir; eşleştirme anında otoriter normalizasyon sunucu tarafında yapılır.

Düzenleme ve Silme

  • Düzenleme atamalara dokunmaz. Bu sayfa yalnızca kuralı yazar; kimin hangi kurala tabi olduğu Access Management'ta belirlenir ve oradaki atamalar bir düzenlemeden etkilenmez (v1.2.1 öncesinde bir kuralı düzenlemek atamalarını siliyordu).
  • Silme onay ister: "Bu işlem seçili kuralı kalıcı olarak silecek ve yeniden kullanılabilir yol politikasını kaldıracaktır. Bu işlem geri alınamaz."

Desen Eşleştirme Kuralları

Windows Yolları ve Yazım Varyantları

Path filter, bir Windows istemcisinin gerçekten kullanacağı yazımları tanır (v1.3.0'da köklü düzeltme):

  • Sürücü harfleri, UNC paylaşımları (\\sunucu\paylaşım\…), boşluklu tırnak içi yollar, Unicode klasör adları.
  • POSIX öykünme biçimleri: /c/…, /mnt/c/…, /cygdrive/c/… — Git Bash, WSL ve Cygwin yazımları aynı Windows yolu sayılır.
  • PowerShell yazma komutları yazma sayılır. Windows'ta yazma komutları eskiden okuma sanılıyordu; bir read kuralı yazmaları engelleyemiyordu.
  • Büyük/küçük harf: Windows biçimli yollarda ve Windows ya da macOS dosya sistemi bildiren ajanlarda eşleştirme büyük/küçük harf duyarsızıdır — GIZLI\rapor.txt, C:\Users\…\gizli\** kuralını atlatamaz; prod.KEY, **/*.key kuralını atlatamaz. Linux'ta eşleştirme harf duyarlı kalır. (macOS uç noktalarında sürücü harfsiz yollar için de harf duyarsızlığı, arceris-dev güncellemesiyle gelir.)
  • Windows'un yok saydığı yazımlar kuralı atlatamaz: sondaki nokta veya boşluk, ::$DATA akış eki, \??\ öneki. Uzun yol önekleri (\\?\C:\…, \\.\…) normalize edilir.

Henüz kapsanmayanlar: \\?\GLOBALROOT yolları, yönetimsel paylaşımlar (\\makine\C$) ve 8.3 kısa adlar (C:\PROGRA~1\…).

Göreli Yollar ve ~

  • Hook zinciri, göreli yolları (ve .. atlamalarını) oturumun çalışma dizinine göre çözer: type gizli\x.txt ve göreli bir Read, mutlak kurallı bir kuralı atlatamaz.
  • Korumalı klasöre girmek de erişim sayılır: cd gizli && type x.txt gibi bir komut zinciri, gizli dizinine erişim olarak yargılanır.
  • ~ ana dizine açılır: ajanın bildirdiği ana dizin (C:\Users\…) ~ ile yazılan yolu mutlak yola çevirir, böylece mutlak yola yazdığınız kural eşleşir. Ajan eskiyse ve ana dizin bilinmiyorsa ~ yazıldığı gibi kalır — gateway asla bir profil dizini uydurmaz; kural yazarken mutlak yolu tercih edin.

Komut İçindeki Her Dosya Operandı

Path filter bir komutun yalnızca ilk yol benzeri argümanına değil, her dosya operandına bakar:

  • grep -in "redis" .env — .env dosyası cat .env gibi okuma olarak yakalanır (eskiden yalnız ilk argüman incelendiği için bu komut dosyayı okuyordu).
  • cp / mv — yazılan operand son argümandır; bir write kuralı bu yolları da görür, son argümana yazılan dosya kuralı atlatamaz.

Nerede Uygulanır: Hook Zinciri

Karar zinciri editörlerin PreToolUse hook'u ile çalışır: editör eşleştiricisi → arceris-dev hook → broker → daemon → gateway'deki değerlendirme uç noktası. Kritik nokta, zincirin yalnızca editörün eşleştiricisinin seçtiği araç adları için çalışmasıdır: eşleştirici dışındaki bir araç adı sıfır kontrol, sıfır kayıt, sıfır hata alır — paneldeki kural hâlâ "Aktif" görünür.

Editör Araç çağrıları hook'tan geçer
Claude Code MCP araçları (mcp__.*), yerleşik dosya araçları, Windows PowerShell kabuk aracı, web araçları (WebFetch/WebSearch/Fetch), MCP kaynak araçları
Gemini CLI MCP araçları, yerleşik dosya araçları, web araçları
Codex Yalnız Bash ve apply_patch
Cursor / Windsurf Yalnız MCP araçları
  • Windows'ta PowerShell aracı eskiden hiçbir hook listesinde değildi; Claude Desktop "Code" sekmesindeki okumalar için path filter bile devreye girmiyordu. Artık kapsam içinde; eski kurulumlar arceris-dev doctor'da STALE görünür — geçerli agent sürümü kurulup entegrasyonun yeniden çalıştırılması gerekir.
  • Yerelde okunan dosyalar: yeni arceris-dev ile bir kodlama ajanının diskten okuduğu dosya, okuma başlamadan önce MIME ve dosya meta verisi kurallarıyla da yargılanır — dosyayı çalıştırmak/kopyalamak/silmek/listelemek okuma sayılmaz, kaynak kod ve metin dosyaları tür yargılamasına girmez (ayrıntı Bölüm 18).
  • Kapsam kuralları: web araçları için "taranıyor mu?" cevabı bilinemediğinde (coverage_unknown) çağrı asla engellenmez; yaptırım her çağrıda hesaplanır, yalnızca denetim izi ayrı bir pencere içinde tekilleştirilir.
  • Yerleşik hafıza örneği: Claude Code'un yerleşik hafızası herhangi bir MCP politika dışında, yerleşik Write/Edit araçlarıyla ~/.claude/projects/<proje>/memory/MEMORY.md dosyasına yazar. Gerçek çözüm path filter'dır: ~/.claude/projects/**/memory/** desenine none izinli bir kural — hook yerleşik Write/Edit çağrılarını gördüğü için yazmaları gerçekten durdurur.

Politika Uygulanmayan Kullanıcı: Bayt-Birebir Geçiş

Bir kullanıcının üzerine hiçbir (aktif ve atanmış) path filter kuralı düşmüyorsa, explicit proxy'nin SSE araç-çağrısı yakalayıcısı hiçbir şey reddetmez: akış bayt-birebir geçirilir (v1.1.0'dan önce yakalayıcı, kuralsız da olsa yapısal durdurmalarla istemci dökümünde reddeler üretiyordu). Fail-closed yalnızca bir politika gerçekten geçerliyken geçerlidir: kural seti atanmış ve aktif olan bir kullanıcı için aşırı dolu bir araç çağrısı ya da kesik akış, önceki gibi reddedilir.

Red Cevabının Görünümü ve Yan Taramalar

  • Engellenen çağrı kalıcı okunur: red mesajı artık engellenen yolu yankılamaz ve modele başka bir yoldan yeniden denememesi söylenir — yolun kendisi modele ipucu olarak geri gitmez.
  • Path Filter açıkken yanıt PII taraması çalışır: explicit proxy arkasındaki kodlama ajanlarında yanıt taraması artık path filter çıktısının üzerinde çalışır; bir path filter red mesajinin içindeki metin dahil taranır ve maskelenir (ayrıntı Bölüm 23).

Operasyonel Bağlam

  • Kural setlerinin hedeflere bağlanması (kullanıcı, rol, grup, IP) ve bir kullanıcının hangi kurallara tabi olduğu: Bölüm 11 (Access Management).
  • Yerel dosya okumalarında MIME ve dosya meta verisi yargılaması: Bölüm 18.
  • Explicit proxy'de SSE araç-çağrısı yakalama ve yanıt PII taraması: Bölüm 23; her hook red'i denetim izinde aynı şekilde iz bırakır: Bölüm 25.
  • Bu sayfanın görünür olması sunucudaki path_acl özelliğine bağlıdır; lisans paketine bağlı değildir.