> For the complete documentation index, see [llms.txt](https://docs.kangal.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kangal.dev/tr/ai-gateway/security-observability.md). # Güvenlik ve observability AI Gateway; istemci kimliğini, sağlayıcı credential'larını ve sağlayıcı çıkışını ayrı güven sınırları olarak ele alır. İstemcinin gönderdiği tenant, gateway ve consumer değerleri, yapılandırma yüklenmeden önce kayıtlı durumla doğrulanır. ## Çalışma zamanı kimlik doğrulaması ### Consumer API key'i Şu header'ları gönderin: ``` X-Tenant-ID: X-Gateway-ID: X-API-Key: ``` `X-Tenant-ID` yalnızca arama seçicisidir; güvenilir kimlik olarak kabul edilmez. Credential tenant'ı, consumer tenant'ı ve gateway tenant'ı eşleşmelidir. İsteğe bağlı `X-Consumer-ID` veya `X-Consumer-Username` claim'leri doğrulanmış consumer'la eşleşmelidir. ### Consumer bearer JWT'si `Authorization: Bearer ` ile `X-Gateway-ID` gönderin. Token, kayıtlı bir `consumer_id` içeren geçerli bir Kangal token'ı olmalıdır; tenant ve consumer claim'leri veritabanındaki kayıtlarla yeniden doğrulanır. Yaygın hata durumları: | Durum | Anlamı | | ----- | --------------------------------------------------------------------------------- | | `400` | API key için `X-Tenant-ID` veya istek için `X-Gateway-ID` eksik | | `401` | Consumer credential'ı eksik veya geçersiz | | `403` | Tenant/consumer/gateway claim'i doğrulanamadı veya gateway başka bir tenant'a ait | | `404` | Gateway bulunamadı | | `429` | Yapay zekâ politikası veya plan kotası isteği reddetti | ## Sağlayıcı gizli bilgileri Düz metin sağlayıcı `api_key` değerleri ve gizli bilgi içerebilen header değerleri saklanırken şifrelenir; API ve audit yanıtlarında redakte edilir. Tenant kapsamlı bir `vault://...` referansı kullanın: ```json { "api_key_ref": "vault://ai/providers/openai#api_key" } ``` Çözümleyici, istek sırasında doğrulanmış tenant'ı kullanır. Tek bir skaler secret veya tek skaler alan kabul eder; yapılandırılmış bir secret içindeki alanı seçmek için URL fragment'ını kullanın. `env://NAME`, `env:NAME` ve `api_key_env` varsayılan olarak devre dışıdır. Bu referanslar yalnızca `AI_GATEWAY_ALLOW_ENV_SECRET_REFS=true` olduğunda çalışır ve değişken adı güvenli ortam tanımlayıcısı biçimine uymalıdır. Ortam değişkeni referansları dağıtım genelinde geçerli olduğundan paylaşımlı dağıtımlarda tenant kapsamlı Vault referanslarını tercih edin. Doğrudan çalışma zamanı, gelen Kangal authorization header'ını hiçbir zaman sağlayıcıya iletmez. ## Giden istek politikası Credential'lar eklenmeden önce sağlayıcı ve haricî embedding URL'leri şu kurallarla doğrulanır: * HTTPS zorunludur. * URL içinde credential kullanımına izin verilmez. * Loopback, özel, link-local, multicast, rezerve ve bulut metadata hedefleri engellenir. * DNS sonuçları izin verilen genel adres politikası içinde kalmalıdır. * Yönlendirmeler izlenmez ve 3xx yanıtları reddedilir. ## Koruma kuralları İstek koruma kuralları şunları uygular: * `enabled`; * metin içerikli mesajların tamamında `max_prompt_chars`; * `blocked_terms` içindeki büyük/küçük harf duyarsız alt dize eşleşmeleri. Yanıt koruma kuralları, `response_blocked_terms` değerlerinde büyük/küçük harf duyarsız eşleşme ve `response_blocked_patterns` değerlerinde regex uygular. Engellenen normal yanıt `403` döndürür. Korunan bir akış önce tamamen denetlenir; kural eşleşirse sağlayıcıdan gelen byte'lar istemciye gönderilmez. ## PII değiştirme Etkin bir `redaction` kaydı kullanıldığında Kangal, sağlayıcı çağrısından önce string veya text-part mesaj içeriğindeki e-posta, telefon benzeri ve ABD SSN benzeri değerleri şu işaretlerle değiştirir: ``` [REDACTED_EMAIL] [REDACTED_PHONE] [REDACTED_SSN] ``` Redaksiyon sayıları yanıt meta verisine kaydedilir. Redaksiyon etkinleştirildiğinde üç yerleşik algılayıcının tamamı string ve text-part mesaj içeriklerine uygulanır. Algılayıcıları trafiğinizde kullanılan dil ve veri biçimleriyle doğrulayın; araç payload'ları gibi ek hassas alanlar için uygulama düzeyindeki veri işleme kurallarını da uygulayın. ## Telemetri ve audit yönetişimi Yönetilen izleme için payload içermeyen operasyonel telemetriyi ve değişmez audit olaylarını kullanın. Erişimi tenant ve role göre sınırlandırın, saklama süresini tanımlayın ve kayıtları yalnızca onaylı izleme ve audit sistemlerine aktarın. ## Telemetri endpoint'leri Tüm telemetri endpoint'leri yönetici credential'ı gerektirir ve gateway'in istenen tenant'a ait olduğunu doğrular. ``` GET /admin/gateways/{gateway_id}/ai-gateway/telemetry/summary GET /admin/gateways/{gateway_id}/ai-gateway/telemetry/requests GET /admin/gateways/{gateway_id}/ai-gateway/telemetry/live ``` ### Özet Sorgu parametreleri: | Parametre | Varsayılan | Aralık ve kural | | ----------- | -------------------- | ----------------------------- | | `tenant_id` | Yöneticinin tenant'ı | Tenant dışı erişim reddedilir | | `hours` | `24` | 1-720 | Yanıt; istek ve sağlayıcı çağrısı sayılarını, kullanılabilirliği, yedek hedefe geçiş ve önbellek oranlarını, normalize token sayılarını, tahmini maliyet ve tasarrufu, ortalama/p95 gecikmeyi ve gözlemlenen sağlayıcı sağlığını içerir. Sağlık, sentetik probe yerine gözlemlenen sonuçlara göre belirlenir: * `healthy`: gözlemlenen tüm sağlayıcı çağrıları başarılıdır; * `degraded`: en az bir çağrı başarısızdır; * `unavailable`: çağrıların en az yarısı başarısızdır; * `no_data`: zaman aralığında sağlayıcı çağrısı yoktur. Politika ve istemci hataları sağlayıcı kesintisi olarak sayılmaz. Özet en yeni 5.000 olayı tarar; bu sayı aşıldığında yanıtta `truncated: true` bulunur. ### İstek ayrıntıları `hours` 1-720, `limit` 1-100 aralığındadır; varsayılan limit 25'tir. İsteğe bağlı filtreler `provider`, `status_code`, `fallback_used` ve `cache_hit` alanlarıdır. Öğeler; kimlikleri, kapsamı, rota ve consumer referanslarını, durumu, sonucu, gecikmeyi, denemeleri, kullanımı, maliyeti, önbellek/yedek hedef durumunu, hata türünü ve akışın tamamlanma bilgisini içerir. Prompt'lar, yanıtlar ve credential'lar bu telemetri yanıtına eklenmez. ### Canlı akış `limit` 1-100 aralığındadır; varsayılan değer 25'tir. `next_cursor` değerini saklayıp sonraki istekte yeniden gönderin. `has_more: true` olduğunda hemen yeni istek gönderin; aksi durumda `poll_after_ms` süresi kadar bekleyin. Bu süre normalde 2.000 ms'dir. Cursor sürümlüdür, HMAC ile imzalanır, tenant/gateway ve saklama süresine bağlıdır; anahtar yenileme sırasında yapılandırılmış önceki imzalama secret'larını da destekler. Beklenen hata ve durumlar: * Hatalı biçimli, imzasız eski, imzası süresi dolmuş veya değiştirilmiş cursor için `400`; * başka tenant veya gateway'e ait cursor için `403`; * tüketim ya da saklama penceresi aşıldığında `backpressure`, `gap_detected` veya `cursor_expired`. ## Saklama ve hata davranışı `ai_gateway_operations` TTL indeksine sahiptir. Saklama süresi varsayılan olarak 720 saattir ve `AI_GATEWAY_TELEMETRY_RETENTION_HOURS` ile 24-720 aralığında ayarlanır. Çalışma zamanı telemetri yazımları, sağlayıcı yanıt yolunu açık tutmak için fail-open çalışır ve `AI_GATEWAY_TELEMETRY_PERSIST_TIMEOUT_MS` ile sınırlandırılır. Varsayılan değer 100 ms, kabul edilen aralık 1-1.000 ms'dir. Atlanan yazımlar, payload içermeyen şu Prometheus sayacını artırır: `kangal_ai_gateway_telemetry_persistence_dropped_total{store,reason}`. Değişmez audit olayları TTL uygulanan operasyon koleksiyonundan ayrı saklanır. ## Güvenlik kontrol listesi 1. Tenant kapsamlı consumer credential'ları oluşturun ve sahte kapsam değerlerinin reddedildiğini test edin. 2. Sağlayıcı key'lerini Vault'ta saklayın ve giden HTTPS hedeflerini sınırlayın. 3. İstemcinin sağladığı sağlayıcı kimlik doğrulamasını ve ortam referanslarını devre dışı tutun. 4. İstek `blocked_terms` değerlerini ve yanıt terim/desenlerini temsili normal ve akışlı payload'larla test edin. 5. PII algılayıcılarını gerçek diller ve veri biçimleriyle doğrulayın. 6. Telemetri ve audit verilerine tenant kapsamlı erişim ve saklama kontrolleri uygulayın. 7. Sağlayıcı hata sınıfları, telemetri yazım kayıpları, bütçe retleri ve olağan dışı önbellek tasarrufları için alarm oluşturun. 8. Maliyet değerlerini tahmin olarak değerlendirin ve sağlayıcı faturasıyla mutabakat yapın. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.kangal.dev/tr/ai-gateway/security-observability.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.