Kimlik bilgileri proxy'si — teknik

Proxy nasıl çalışır.

Neleri korur. Neleri korumaz.

Bu sayfa güvenlik incelemecileri, sızma testi uzmanları ve proxy'nin tehdit modelini değerlendiren mühendisler içindir. Proxy'nin protokol düzeyinde ne yaptığını, kimlik bilgilerinin bellekte nerede bulunduğunu ve hangi saldırı yüzeylerinin kaldığını açıklar.

Mimari

Proxy, CONNECT tabanlı bir HTTPS MITM proxy'sidir. Bir yapay zeka aracısı HTTPS_PROXY ayarını buna işaret edecek şekilde yapılandırır. Ajan HTTPS isteği yaptığında, proxy TLS bağlantısını keser, kimlik bilgisi başvuruları için istek üstbilgilerini inceler, bunları Clavitor kasa'sı ile çözer ve isteği kimlik bilgileri enjekte edilmiş olarak yukarı akış API'sine iletir.

Proxy varsayılan olarak 127.0.0.1:1983 üzerinde dinler — proxy ve ajan aynı ana bilgisayarı paylaştığı yan hizmet deseni. Paylaşılan dağıtımlar (özel bir ağda birden fazla ajana hizmet veren tek bir proxy, birden fazla iş yüküne konteyner yan hizmeti, özel proxy ana bilgisayarı) için dinleme arayüzü CLAVITOR_PROXY_LISTEN aracılığıyla yapılandırılabilir.

illustration: unknown name=proxy-sequence

Proxy bağımsız bir Go ikili dosyasıdır. CGO yok. Tüm Clavitor protokol şifrelemesi, WebAssembly'ye derlenmiş ve başlangıçta wazero aracılığıyla yüklenen kanonik bir Rust uygulaması üzerinden çalışır.

TLS işleme

Proxy, ilk çalıştırmada kendinden imzalı bir ECDSA P-256 kök CA oluşturur, bu CA ikili dosyasının dizininde 0600 moduyla kalıcı hale getirilir. Her yukarı akış ana bilgisayarı için, bu CA tarafından imzalanan ve sınırlı tahliye ile bellekte önbelleğe alınan (1.000 ana bilgisayar) bir yaprak sertifika isteğe bağlı olarak basılır. Yaprak sertifikalar 24 saat geçerlidir ve oturum ortası süresinin dolmasını önlemek için 23. saatte şeffaf bir şekilde yeniden oluşturulur.

Ajanın proxy'nin CA sertifikasına güvenmesi gerekir. clavitor-proxy ca ile dışa aktarın.

Yukarı akış bağlantıları, HTTP/2 ve HTTP/1.1 için ALPN müzakeresi ile minimum TLS 1.3 kullanır. Sistem sertifika havuzu yukarı akış doğrulaması için kullanılır. Sertifika sabitleme yok — proxy işletim sisteminin güvendiği her şeye güvenir.

Credential lifecycle

Kimlik bilgileri asla önbelleğe alınmaz, diske asla yazılmaz ve bir HTTP isteğinden daha uzun süre tutulmaz.

Aşama	Kimlik bilgisinin bulunduğu yer	Süre
Kasa'da beklemede	Kasa veritabanında AES-GCM şifreli metin	Silinene kadar
Proxy'ye iletim sırasında	Kasa API'sinden TLS şifreli JSON yanıtı	Bir HTTP gidiş-dönüş
Proxy'de şifresi çözülmüş	İşlem belleği (yığın üzerinde Go dizesi)	Bir HTTP isteği
Yukarı akış isteğine enjekte edilmiş	Yukarı akışa giden tel üzerindeki TLS şifreli baytlar	Bir HTTP isteği

Proxy, ajanın kimlik bilgisi şifre çözme anahtarını (16 bayt) tüm çalışma süresi boyunca bellekte tutar. Başlangıçta şifreli yan hizmet yapılandırmasından (CLV1 formatı) yüklenir ve düzgün kapatma sırasında temizlenir. Anahtar işlemden asla çıkmaz.

Yan hizmet yapılandırması, statik bir tohumdan türetilen deterministik anahtarlar kullanılarak AES-128-GCM ve HMAC-SHA256 ile şifrelenir. Bu gizleme, gizlilik değil — güvenlik sınırı dosya izinleridir (0600) ve dosyanın sahipliğidir. CLV1 formatı proxy, CLI ve tarayıcı uzantısı arasında paylaşılır.

Çözümleme modları

Mod 1 — açık yer tutucu

Ajan, istek üstbilgisinde bir clavitor://Entry/field başvurusu içerir. Proxy, kasada girişi ada göre arar, getirir, belirtilen alanı şifresini çözer ve yer tutucuyu gerçek değerle değiştirir.

Arama sıfır veya birden fazla sonuç döndürürse, proxy kararlı bir hata koduyla 502 döndürür. Yer tutucu asla kaldırılmaz ve olduğu gibi iletilir.

Mod 2 — URL eşleşmesi

Yer tutucu olmadığında, proxy kasadan URL alanının yukarı akış ana bilgisayarıyla eşleştiği girişleri ister. Tanınabilir bir alan şekline sahip tam olarak bir eşleşme varsa, proxy kimlik bilgilerini otomatik olarak enjekte eder.

Sıfır eşleşme → geçiş (kimlik bilgisi beklentisi yok). Birden fazla eşleşme → belirsizliği giderme kılavuzuyla 502. Bilinmeyen alan şekli → 502.

Karar ağacı deterministiktir: yer tutucu mevcut → çöz veya başarısız ol. Yer tutucu yok → URL eşleşmesi veya geçiş. Başarısız bir çözümlemenin kimlik bilgileri olmadan yukarı akışa giden bir istekle sonuçlandığı sessiz bir geri dönüş yolu yoktur.

Agent identity

Varsayılan olarak, kasa her istekte proxy'nin kendi ajan kimliğini görür. Hız sınırları, kapsam kontrolleri ve denetim girişleri proxy'ye atfedilir.

Birden fazla ajan tek bir proxy örneğini paylaştığında, yer tutucu bir ajan kimliği içerebilir: clavitor://agentid@Entry/field. Proxy bu ajan kimliğini kasaya gönderir, bu da o ajanın kapsamlarını ve hız sınırlarını uygular ve erişimi buna göre günlüğe kaydeder. Ajan kimliği, kasa kullanıcı arayüzündeki ajan ayrıntıları sayfasında gösterilen 32 karakterli onaltılık değerdir.

# Without agent ID — attributed to the proxy
Authorization: Bearer clavitor://OpenAI/key

# With agent ID — attributed to agent 0102030405060708090a0b0c0d0e0f10
Authorization: Bearer clavitor://0102030405060708090a0b0c0d0e0f10@OpenAI/key

Dağıtım	Kimlik modeli	İzolasyon
Ajan başına bir proxy	Proxy Kimliği = ajan kimliği (varsayılan)	Tam — ayrı ikili dosya, yapılandırma, kapsam, hız sınırları
Paylaşılan proxy, URL'de ajan kimliği yok	Tüm ajanlar proxy'nin kimliğini paylaşır	Paylaşılan kapsam ve hız sınırları
Paylaşılan proxy + URL'de `agentid@`	Ajan başına kimlik	Ajan başına kapsam, hız sınırları ve denetim

URL'deki ajan kimliği bir kimlik doğrulama mekanizması değildir — proxy'nin CVT belirteci bağlantıyı kimlik doğrular. Ajan kimliği, hangi kapsamların geçerli olduğunu, hangi hız sınırlarının sayıldığını, hangi denetim izinin erişimi kaydettiğini belirten atıfı belirler. Kasa, bilinmeyen ajan kimliklerini yüksek sesle bir hatayla reddeder.

Ağ güvenliği

SSRF koruması

Varsayılan olarak proxy, özel ağlara (RFC 1918), bulut örnek meta verilerine (169.254.169.254), döngüye alma, bağlantı yerel ve taşıyıcı sınıfı NAT aralıklarına yapılan yukarı akış bağlantılarını engeller. DNS önce çözülür; TCP bağlantısı yapılmadan önce döndürülen tüm IP'ler doğrulanır, bu da DNS yeniden bağlama TOCTOU penceresini kapatır.

Özel API'lere meşru şekilde erişen ajanlar için CLAVITOR_PROXY_ALLOW_PRIVATE=true ile geçersiz kılın.

Hedef sabitleme

CONNECT hedef ana bilgisayarı, tünel kurulduğunda yakalanır ve tüm tünel ömrü boyunca kullanılır. Tünel içindeki sonraki istekler, Host üstbilgisini manipüle ederek farklı bir ana bilgisayara yönlendirilemez. Bir uyuşmazlık 502 ile sonuçlanır.

Bu, bir ajanın api.openai.com'a bir tünel kurmasını ve ardından internal-service.corp'a istek göndermesini engeller.

Üstbilgi işleme

Hop-by-hop üstbilgileri RFC 7230 §6.1'e göre hem isteklerden hem de yanıtlardan kaldırılır: Connection, Keep-Alive, Proxy-Authenticate, Proxy-Authorization, Proxy-Connection, TE, Trailers, Transfer-Encoding, Upgrade.

Set-Cookie, yukarı akışların ajanın HTTP istemcisine çerez yerleştirmesini önlemek için yukarı akış yanıtlarından kaldırılır.

İstek ve yanıt gövdeleri arabelleğe alınmadan akış yapar. İstek gövdeleri varsayılan olarak 64 MB ile sınırlıdır (CLAVITOR_PROXY_MAX_BODY_MB). Yanıt gövdeleri sabit bir sınır olmadan akış yapar; Content-Length 100 MB'ı aştığında bir günlük uyarısı verilir.

Field-to-header mapping

URL eşleştirme modunda, proxy kasa alan etiketlerini HTTP üstbilgilerine eşler:

Alan etiketi	Enjekte edilen üstbilgi
`key`, `apikey`, `api_key`, `token`, `secret`, `bearer`, `access_token`	`Authorization: Bearer <value>`
`x-api-key`, `api-key`	`X-API-Key: <value>`
`username` + `password` (eşleştirilmiş)	`Authorization: Basic base64(user:pass)`
Diğer her şey	Reddedildi — `ERR-PROXY-052`

Yer tutucu modunda, ajan hangi alanın çözüleceğini ve nereye gideceğini kontrol eder. Yukarıdaki eşleme yalnızca URL eşleştirme modu için geçerlidir.

Error codes

Her hata kararlı bir ERR-PROXY-NNN kodu üretir. Bu kodlar proxy'nin genel arayüzünün bir parçasıdır — ajanlar ve operatörler uyarı ve hata ayıklama için bunlara göre eşleşebilir.

Aralık	Kategori
`001–019`	Kurulum (yapılandırma, başlatma, CA oluşturma, WASM)
`020–029`	Arka plan programı yaşam döngüsü
`030–049`	Yer tutucu çözümü (`clavitor://` URI'leri)
`050–069`	URL eşleştirme enjeksiyonu
`070–089`	Yukarı akış / TLS

Kimlik alanlarına ulaşılamaz

Kasa girişleri üç şifreleme katmanını destekler. Kasa şifreli alanlar düz metin meta verileridir. Kimlik bilgileri şifreli alanlar ajanın anahtarıyla şifresi çözülür. Kimlik şifreli alanlar, sunucunun ve proxy'nin hiç görmediği bir anahtarla şifrelenir. Yalnızca kasa sahibi, donanım anahtarı aracılığıyla bunların şifresini çözebilir.

Bir yer tutucu kimlik şifreli bir alana başvuruyorsa, proxy ERR-PROXY-035 döndürür. Geri dönüş yok, kısmi sonuç yok. Alan mimari olarak proxy'den ulaşılamaz durumdadır.

Proxy'nin korumadığı şeyler

Proxy'nin tehdit modeli, kimliği doğrulanmış bir ajanın kimlik bilgilerini toplamasını sağlayan bozuk bir beceri veya komut enjeksiyonudur. Kasa'nın ajan başına hız sınırları, benzersiz giriş kotaları ve iki vuruşlu kilitleme birincil savunmalardır. Proxy, kimlik bilgilerinin istek başına çözüldüğü ve ajan tarafından asla tutulmadığı bir ağ katmanı uygulama noktası ekler.

Bozuk bir ana bilgisayar

Proxy, ajanla aynı makinede çalışır. Kök erişimi olan bir saldırgan işlem belleğini okuyabilir, bir hata ayıklayıcı ekleyebilir veya döngü trafiğini kesebilir. Proxy, bir kimlik bilgisi enjeksiyon katmanıdır, bir donanım güvenlik sınırı değildir.

API yanıtı aracılığıyla kimlik bilgisi sızması

Yukarı akış API'si kimlik bilgisini yanıtında yankılarsa (örneğin, bir "kim kimdir" uç noktası), ajan bunu görür. Proxy, kimlik bilgilerini isteklere enjekte eder, yanıtlara değil. Geri dönenleri filtrelemez.

Günlük kaydı

Proxy, kabul edilen her CONNECT için bir satır günlüğe kaydeder ve hatalar için hata satırları yayar. Asla şunları günlüğe kaydetmez:

Şifresi çözülmüş kimlik bilgisi değerleri
Tam istek URL'leri (sorgu dizeleri sırları taşıyabilir — yalnızca şema + ana bilgisayar + yol günlüğe kaydedilir)
İstek veya yanıt gövdeleri
Kimlik bilgisi şifre çözme anahtarı veya yan hizmet yapılandırma içerikleri

Proxy, yukarı akıştan gelen 400 yanıtının kimlik doğrulamayla ilgili anahtar kelimeler (unauthorized, invalid token, vb.) içerdiğini algıladığında, enjekte edilen kimlik bilgisinin güncelliğini yitirmiş olabileceğini öne süren bir tanılama ipucu günlüğe kaydeder. Yanıt değişmeden iletilir.

Kriptografi

Tüm Clavitor protokol şifrelemesi — AES-GCM alan şifre çözme, HKDF anahtar türetme, base62 kodlama, CVT belirteci basma, CLV1 yapılandırma paketleme/paketi açma — yalnızca bir WebAssembly modülü (clavis_crypto.wasm) içinde yürütülür ve wazero aracılığıyla yüklenir; saf Go WASM çalışma zamanı. CGO yok. Clavitor temel bileşenlerinin Go yeniden uygulaması yok.

WASM modülü, tarayıcı, CLI ve tarayıcı uzantıları tarafından kullanılan aynı Rust crate'inden (clavis-crypto) derlenmiştir. Tek doğruluk kaynağı, tek ikili dosya, tek denetim yüzeyi.

Proxy, TLS telgrafı için Go'nun crypto/tls ve MITM sertifika oluşturma için crypto/ecdsa kullanır. Bunlar taşıma sorunlarıdır, Clavitor protokol işlemleri değildir.

Configuration

Sırlar (kimlik bilgisi şifre çözme anahtarı, ajan kimliği, cihaz kimliği, kasa URL'si) şifreli CLV1 yan hizmet yapılandırmasında yaşar, clavitor-proxy init sırasında bir kez yazılır. Operasyonel düğmeler ortam değişkenlerinde yaşar:

Değişken	Varsayılan	Amaç
`CLAVITOR_PROXY_LISTEN`	`127.0.0.1`	Dinleme arayüzü. Paylaşılan dağıtımlar için `0.0.0.0` olarak veya belirli bir arayüz IP'sine ayarlanır.
`CLAVITOR_PROXY_PORT`	`1983`	Dinleme portu
`CLAVITOR_PROXY_ALLOW_PRIVATE`	`false`	RFC-1918 / özel ağlara bağlantılara izin ver
`CLAVITOR_PROXY_MAX_BODY_MB`	`64`	İstek gövdesi boyutu sınırı
`CLAVITOR_PROXY_WRITE_TIMEOUT`	`300`	Saniye cinsinden yanıt yazma zaman aşımı
`CLAVITOR_CONFIG`	(exe dizini)	Yan hizmet yapılandırma yolunu geçersiz kıl

Operasyonel düğmeler sır değildir. Şifreli yapılandırmada yer almazlar. Dağıtım araçlarının zaten yönettiği yerlerde bulunurlar — ortamda.

Kendiniz inceleyin.

Kriptografi, tek bir denetlenebilir WASM artefaktıdır. Tehdit modeli belgelenmiştir. Kaçırdığımız bir şey bulursanız, duymak isteriz.

Bir bulgu bildirin ← İşletme genel bakışı