Ders videosunu izleyin: Kriptografik Makbuzlarla AI Ajanlarının Güvenliği
(Ders videosu ve küçük resmi Microsoft içerik ekibi tarafından birleştirme sonrası eklenecektir, ders 14 / 15 örüntüsüne uygun olarak.)
Bu ders aşağıdakileri kapsayacaktır:
Bu dersi tamamladıktan sonra şunları bileceksiniz:
Diyelim ki Contoso Travel için bir AI ajanı dağıttınız. Ajan müşteri taleplerini okuyor, uçuş API’sini çağırıyor ve müşterinin adına koltuk rezervasyonu yapıyor. Geçen çeyrekte ajanın işlettiği rezervasyon sayısı 50.000.
Bugün bir denetçi geliyor. Basit bir soru soruyor: “Ajanınızın yaptığı işleri gösterin.”
Siz de günlük dosyalarınızı veriyorsunuz. Denetçi dosyaları inceliyor ve zor bir soru soruyor: “Bu günlüklerin değiştirilmediğini nasıl bilebilirim?”
Bu denetim izi (audit trail) sorunudur. Bugün birçok ajan dağıtımı şuna dayanır:
Hiçbiri denetçinin sorusunu, denetçinin birine (size, bulut sağlayıcınıza, veritabanı satıcınıza) güvenmesini gerektirmeden yanıtlayamaz. İç kullanım için bu güven genellikle kabul edilebilir. Düzenlemeye tabi iş yükleri (finans, sağlık, EU AI Yasasına tabi her şey) için kabul edilmez.
Kriptografik makbuzlar bunu her ajan eylemini bağımsızca doğrulanabilir kılarak çözer. Denetçinin size güvenmesi gerekmez. Yalnızca genel anahtarınıza ve makbuza ihtiyacı vardır.
Bir makbuz, ajanın ne yaptığını kayıt eden, dijital imza ile imzalanmış bir JSON nesnesidir.
flowchart LR
A[Agent bir araç çağırır] --> B[Fatura yükü oluştur]
B --> C[JSON RFC 8785'i kanonik hale getir]
C --> D[SHA-256 karma]
D --> E[Ed25519 imzala]
E --> F[İmzalı fatura]
F --> G[Denetçi çevrimdışı doğrular]
G --> H{İmza geçerli mi?}
H -- evet --> I[Değiştirilemez kanıt]
H -- hayır --> J[Fatura reddedildi]
Minimal bir makbuz şöyle görünür:
{
"type": "agent.tool_call.v1",
"agent_id": "contoso-travel-bot",
"tool_name": "lookup_flights",
"tool_args_hash": "sha256:a3f9c1...",
"result_hash": "sha256:7b2e1d...",
"policy_id": "contoso-travel-policy-v3",
"timestamp": "2026-04-25T14:30:00Z",
"sequence": 47,
"previous_receipt_hash": "sha256:9d4e6a...",
"signature": {
"alg": "EdDSA",
"sig": "c5af83...",
"public_key": "8f3b2c..."
}
}
Üç özellik işi yapar:
İmza. Makbuz, ajanın geçidi tarafından Ed25519 özel anahtarıyla imzalanır. Karşılık gelen genel anahtara sahip herkes imzayı çevrimdışı doğrulayabilir. Herhangi bir alanı değiştirmek imzayı geçersiz kılar.
Kanonik kodlama. İmzalamadan önce makbuz JSON Kanonizasyon Şeması (JCS, RFC 8785) ile serileştirilir. Bu, aynı mantıksal makbuzu üreten iki farklı uygulamanın bayt bazında aynı çıktıyı üretmesini sağlar. Kanonizasyon olmazsa, farklı JSON serileştiricileri aynı içerik için farklı imzalar üretirdi.
Karma zincirleme. previous_receipt_hash alanı her makbuzu öncekine bağlar. Bir makbuzun silinmesi veya sırasının değiştirilmesi ardından gelen tüm makbuzları bozar. Bireysel imzalar atlatılsa bile tahrifat zincir seviyesinde görünür olur.
Bu özellikler birlikte üç garanti sağlar:
Makbuz üretmek için özel bir kütüphane gerekmez. Kriptografik primitifler yaygın olarak mevcuttur; mantık birkaç düzine satır Python kodudur.
code_samples/18-signed-receipts.ipynb dosyasındaki uygulamalı egzersizler tüm akışı adım adım anlatır. Özet hali:
import json
import hashlib
import base64
from nacl import signing
from jcs import canonicalize # RFC 8785 kanonik JSON
def b64url_nopad(data: bytes) -> str:
return base64.urlsafe_b64encode(data).decode("ascii").rstrip("=")
def sha256_canonical(obj) -> str:
"""SHA-256 of a Python object's JCS-canonical JSON form."""
return f"sha256:{hashlib.sha256(canonicalize(obj)).hexdigest()}"
# Bir imzalama anahtarı oluşturun veya yükleyin (üretimde, bir anahtar kasasında saklayın)
signing_key = signing.SigningKey.generate()
verify_key = signing_key.verify_key
# Makbuz yükünü oluştur (henüz imza yok)
tool_args = {"origin": "SYD", "destination": "LAX"}
tool_result = [{"flight": "QF11", "price": 1850, "stops": 0}]
payload = {
"type": "agent.tool_call.v1",
"agent_id": "contoso-travel-bot",
"tool_name": "lookup_flights",
"tool_args_hash": sha256_canonical(tool_args),
"result_hash": sha256_canonical(tool_result),
"policy_id": "contoso-travel-policy-v3",
"timestamp": "2026-04-25T14:30:00Z",
"sequence": 0,
"previous_receipt_hash": None,
}
# Kanonikleştir, hashle, imzala.
canonical_bytes = canonicalize(payload)
message_hash = hashlib.sha256(canonical_bytes).digest()
signature_bytes = signing_key.sign(message_hash).signature
# Yapılandırılmış bir imza nesnesi ekle.
receipt = {
**payload,
"signature": {
"alg": "EdDSA",
"sig": b64url_nopad(signature_bytes),
"public_key": b64url_nopad(bytes(verify_key)),
},
}
İmzalama hattı tamamen bu kadar. Defterdeki egzersizler her adımı kapsamlıca gösterir.
Doğrulama işlemi tersidir:
import base64
import hashlib
from nacl import signing
from nacl.exceptions import BadSignatureError
from jcs import canonicalize
def b64url_decode(s: str) -> bytes:
padding = "=" * ((4 - len(s) % 4) % 4)
return base64.urlsafe_b64decode(s + padding)
def verify_receipt(receipt: dict) -> bool:
# İmza yapılandırılmış bir nesnedir: {"alg", "sig", "public_key"}.
sig_obj = receipt.get("signature")
if not sig_obj or sig_obj.get("alg") != "EdDSA":
return False
# Aslında imzalanan yükü yeniden oluşturun (imza hariç her şey).
payload = {k: v for k, v in receipt.items() if k != "signature"}
canonical_bytes = canonicalize(payload)
message_hash = hashlib.sha256(canonical_bytes).digest()
try:
verify_key = signing.VerifyKey(b64url_decode(sig_obj["public_key"]))
verify_key.verify(message_hash, b64url_decode(sig_obj["sig"]))
return True
except BadSignatureError:
return False
Bu fonksiyon bir makbuz alır ve imza geçerliyse True, değilse False döner. Ağ çağrısı, servis bağımlılığı veya üçüncü bir tarafa güven gerekmez.
Tahrifat tespitini görmek için defter şunları uygular:
tool_args_hash alanındaki bir baytı değiştirir.Bu, makbuzların tahrifata karşı korumalı olduğunun pratik kanıtıdır: En ufak değişiklik bile imzayı bozar.
Tek bir imzalı makbuz bir eylemi korur. Makbuz zinciri ise bir diziyi korur.
flowchart LR
R0[Makbuz 0<br/>genesis] --> R1[Makbuz 1]
R1 --> R2[Makbuz 2]
R2 --> R3[Makbuz 3]
R1 -. önceki_makbuz_hashi .-> R0
R2 -. önceki_makbuz_hashi .-> R1
R3 -. önceki_makbuz_hashi .-> R2
Her makbuz kendisinden önceki makbuzun karma değerini kaydeder. Bir saldırgan, zincirin ortasındaki 2 numaralı makbuzu sessizce kaldırmak isterse:
previous_receipt_hash alanını değiştirmesi gerekir (bu makbuz 3’ün imzasını bozar), VEYAÖzel anahtar donanımsal anahtar kasasında ise ve siz her makbuzla genel anahtarı yayımlıyorsanız, bu saldırıların hiçbiri fark edilmeden yapılamaz.
Defterde şunlar gösterilir:
previous_receipt_hash değerinin önceki makbuzun gerçek karmasıyla eşleştiğini doğrulamak.Bu, dış denetçinin size güvenmeden doğrulayabileceği bir denetim izi üretme yöntemidir.
Bu, dersin en önemli bölümüdür. Makbuzlar güçlüdür ama güçleri sınırlıdır.
Makbuzlar üç şeyi kanıtlar:
Makbuzlar KANITLAMAZ:
policy_id ile belirtilen politikanın gerçekten değerlendirildiğini veya kontrol edilseydi bu eyleme izin verileceğini. Makbuz kaydeder ne iddia edildiğini, ne uygulandığını değil.Bu sınır iki nedenle önemlidir:
Yaygın hata, “makbuzlarımız var” demenin “yönetiliyoruz/kontrol altındayız” anlamına geldiğini varsaymaktır. Böyle değildir. Makbuzlar temel oluşturur. Yönetim ise üzerine inşa ettiğiniz sistemdir.
Bu derste Python kodu bilinçli olarak minimaldir böylece her satırı okuyup tam olarak ne olduğunu anlayabilirsiniz. Üretimde iki seçeneğiniz vardır:
Kriptografik primitifler üzerine doğrudan inşa edin. Yukarıda gördüğünüz yaklaşık 50 satır birçok kullanım durumu için yeterlidir. PyNaCl (Ed25519) ve jcs paketi (kanonik JSON) iyi bakımı yapılan ve denetlenen kütüphanelerdir.
Üretim makbuz kütüphanesi kullanın. Birkaç açık kaynak proje aynı deseni ek özelliklerle uygular (anahtar dönüşümü, toplu doğrulama, JWK Set dağıtımı, politika motorları ile entegrasyon):
draft-farley-acta-signed-receipts), şu anda standart sürecindedir.protect-mcp (npm) ve @veritasacta/verify (npm) paketleri, her MCP sunucusunu tahrifat geçirmez denetim iziyle sarmak için Node tabanlı makbuz imzalama ve çevrimdışı doğrulama sağlar.Kendi JWT kütüphanenizi yazmakla test edilmiş birini kullanmak arasındaki seçim gibi, kendi makbuz kütüphanenizi yapmak veya hazır kullanmak arasında da tercihtir: Her ikisi de makuldür; kütüphane zaman kazandırır ve denetim yüzeyini küçültür; baştan yazmak her primitifin anlaşılmasını zorunlu kılar. Bu ders baştan yazma yolunu öğretir böylece her iki seçeneğin temeline sahip olabilirsiniz.
Uygulama egzersizine geçmeden önce anlayışınızı test edin.
1. Bir makbuz ajanın özel Ed25519 anahtarıyla imzalanır. Denetçinin yalnızca genel anahtarı vardır. Denetçi makbuzu çevrimdışı doğrulayabilir mi?
2. Bir saldırgan makbuzun policy_id alanını daha izin verici bir politika olduğunu iddia edecek şekilde değiştirir. İmza ise orijinal yük üzerinden hesaplanmıştır. Doğrulamada ne olur?
3. Makbuzda neden ham argümanlar ve sonuçlar yerine tool_args_hash ve result_hash bulunur?
4. previous_receipt_hash alanı her makbuzu öncekine bağlar. Bir saldırgan zincirin ortasından tek bir makbuzu sessizce silerse ne geçersiz olur?
5. Bir makbuz temiz bir şekilde doğrulanıyor. Bu, ajanın eyleminin doğru, mantıklı veya politika uyumlu olduğunu kanıtlar mı?
code_samples/18-signed-receipts.ipynb dosyasını açın ve dört bölümü tamamlayın:
Ek zorluk 1: Makbuz şemasına kendi seçtiğiniz ek bir alan (örneğin, izleme için bir istek kimliği) ekleyin, kanonik imzalama mantığını buna göre güncelleyin ve makbuzun doğrulamadan hala geçtiğini teyit edin. Ardından imzadan sonra alanı değiştirip doğrulamanın başarısız olduğunu doğrulayın. Bu, kanonik kodlamanın her baytının imzaya nasıl katkıda bulunduğunu anlamanızı sağlar. Zorlayıcı görev 2: İki makbuzunuzu birlikte SHA-256 ile hashleyin (kanonik baytlarını belirli bir sıralamada birleştirin) ve ortaya çıkan özet bilgisini üçüncü bir makbuzda yeni bir alan olarak gömün, ardından imzalayın. Üç makbuzun da hala dönüp geri doğrulanabildiğini teyit edin. Böylece tek adımlı bir dahil etme kanıtı oluşturmuş oldunuz: üçüncü makbuzu elinde bulunduran kişi, birinci iki makbuzun imzalanma anında var olduğunu içeriğini açığa çıkarmadan kanıtlayabilir. Bu, seçmeli açıklama makbuzlarının ölçekli olarak kullandığı modeldir (Merkle taahhütleri, RFC 6962).
Kriptografik makbuzlar, Yapay Zeka ajanlarına şu özelliklere sahip bir denetim izi sunar:
Girdi doğrulama, politika uygulama veya kimlik altyapısının yerine geçmezler. Bunlar bu katmanların temelidir. Ajanları düzenlenen işler, çoklu kuruluş iş akışları veya gelecekteki denetçilerin size güvenmeyeceği ortamlara dağıtırken, makbuzlar denetim izini dürüst kılmanın yoludur.
En önemli çıkarım: makbuzlar kimin ne dediğini ve ne zaman söylediğini kanıtlar. Söylenenin doğru veya yerinde olduğunu kanıtlamazlar. Bu farkı dikkatle tutun. Bu, dürüst bir köken sistemi ile yanıltıcı bir sistem arasındaki farktır.
Bu dersten gerçek bir ortamda makbuz-imzalı ajanlar dağıtmaya geçmeye hazır olduğunuzda:
https://your-org.example.com/.well-known/agent-keys.json.Diğer öğrencilerle tanışmak, danışma saatlerine katılmak ve Yapay Zeka Ajanları sorularınızı yanıtlamak için Microsoft Foundry Discord‘a katılın.
Bu ders, tek makbuz imzalama ve hash zincirli dizileri kapsar. Aynı ilkelerm, yönetişim duruşunuz geliştikçe karşılaşabileceğiniz birkaç daha gelişmiş deseni oluşturur:
authorization_*) ve son-uygulama (result_*) yarılara bölünür, yetkilendirme kararı ile elde edilen sonuç farklı aktörler veya zamanlarda üretildiğinde faydalıdır. Bu, bu derste öğretilen makbuz formatının üzerine eklenerek oluşturulur.result_hash alanına koyduğunuz baytları mühürler. Gerçek dünya yükleri genellikle tek bir araç çağrısı sonucundan daha zengindir: ön karar akıl yürütmesi (model tahmini, dikkate alınan seçenekler, kanıt ve bütünlüğü, risk durumu, sorumluluk zinciri, kapı sonucu) yük içerisinde tek bir makbuzla mühürlenmiş halde bulunabilir. Bu, makbuz formatını minimal tutarken alan şemalarının alan-alan evrimleşmesini sağlar.signature.alg alanı ihtiyacınız olduğunda ML-DSA-65 (NIST kuantum sonrası imza standardı) taşıyabilir. Çift imzalı makbuzların olduğu bir geçiş dönemi planlayın.Bilgisayar Kullanım Ajanları Oluşturmak (CUA)
(Müfredat koruyucuları tarafından belirlenecek)
Feragatname: Bu belge, AI çeviri hizmeti Co-op Translator kullanılarak çevrilmiştir. Doğruluk için çaba sarf etsek de, otomatik çevirilerin hata veya yanlışlık içerebileceğini lütfen unutmayınız. Orijinal belge, kendi dilinde yetkili kaynak olarak kabul edilmelidir. Kritik bilgiler için profesyonel insan çevirisi önerilir. Bu çevirinin kullanımı sonucu ortaya çıkabilecek yanlış anlamalardan veya yanlış yorumlamalardan sorumlu değiliz.