Ders videosunu izle: Kriptografik Makbuzlarla AI Ajanlarını Güvenceye Alma
(Ders videosu ve küçük resim, Microsoft içerik ekibi tarafından birleştirme sonrası, ders 14 / 15 düzenine uygun şekilde eklenecektir.)
Bu derste şunları inceleyeceğiz:
Bu dersi tamamladıktan sonra şunları bileceksiniz:
Contoso Travel için bir AI ajanı dağıttığınızı hayal edin. Ajan müşteri isteklerini okur, uçuşlar API’sini çağırarak seçeneklere bakar ve müşterinin adına koltukları ayırır. Geçen çeyrekte ajan 50.000 rezervasyon işledi.
Bugün bir denetçi gelir. Basit bir soru sorar: “Ajanınızın ne yaptığını gösterin.”
Günlük dosyalarınızı veririrsiniz. Denetçi bunlara bakar ve daha zor bir soru sorar: “Bu günlüklerin düzenlenmediğini nasıl bilebilirim?”
İşte denetim izi problemi budur. Bugün çoğu ajan dağıtımı şunlara dayanır:
Bunların hiçbiri, denetçinin birine (sizin, bulut sağlayıcınızın veya veritabanı satıcınızın) güvenmesini gerektirmeden soruyu yanıtlayamaz. İç kullanımda bu güven kabul edilebilir. Düzenlenen iş yükleri (finans, sağlık, AB AI Yasasına tabi işler) için kabul edilmez.
Kriptografik makbuzlar, her ajan eylemini bağımsız olarak doğrulanabilir hale getirerek bunu çözer. Denetçinin size güvenmesine gerek yoktur. Sadece sizin açık anahtarınıza ve makbuza ihtiyacı vardır.
Bir makbuz, bir ajanın ne yaptığını kaydeden, dijital imzayla imzalanmış bir JSON nesnesidir.
flowchart LR
A[Ajan bir araç çağırır] --> B[Fiş yükünü oluştur]
B --> C[JSON RFC 8785'i kanonikleştir]
C --> D[SHA-256 hash]
D --> E[Ed25519 imzala]
E --> F[İmzalı fiş]
F --> G[Denetçi çevrimdışı doğrular]
G --> H{İmza geçerli mi?}
H -- evet --> I[Tamper-kanıtı delil]
H -- hayır --> J[Fiş 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..."
}
}
İş yapan üç özellik vardır:
İmza. Makbuz, ajanın ağ geçidi tarafından Ed25519 özel anahtarı ile imzalanır. Karşılık gelen açık anahtara sahip herkes imzayı çevrimdışı doğrulayabilir. Herhangi bir alanın değiştirilmesi imzayı geçersiz kılar.
Kanonik kodlama. İmzalamadan önce makbuz JSON Kanonizasyon Şeması (JCS, RFC 8785) kullanılarak serileştirilir. Bu, aynı mantıksal makbuzu üreten iki uygulamanın bayt olarak özdeş çıktılar üretmesini sağlar. Kanonizasyon olmadan farklı JSON serileştiriciler aynı içerik için farklı imzalar üretirdi.
Hash zincirleme. previous_receipt_hash alanı her makbuzu ondan önceki makbuza bağlar. Bir makbuzu kaldırmak veya yeniden sıralamak, ardından gelen her makbuzu bozar. Bireysel imzalar atlatılsa bile tahrifat zincir seviyesinde görünür olur.
Bu özellikler birlikte üç garanti verir:
Makbuz üretmek için özel bir kütüphane gerekmez. Kriptografik primitifler yaygın olarak bulunmaktadır ve mantık birkaç düzine Python satırıdır.
code_samples/18-signed-receipts.ipynb içindeki uygulamalı egzersizler tüm akışı adım adım gösterir. Özet:
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 (prodüksiyonda, bir anahtar kasasında saklayın)
signing_key = signing.SigningKey.generate()
verify_key = signing_key.verify_key
# Makbuz yükünü oluşturun (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)),
},
}
Bu tüm imzalama hattıdır. Defterdeki egzersizler her adımı açıklar.
Doğrulama tam 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ı yok, servis bağımlılığı yok, üçüncü tarafa güvenmek gerekmez.
Tahrifat tespitini görmek için defterde:
tool_args_hash alanında bir bayt değiştirilir.Bu, makbuzların tahrifat belirtili olduğunun pratik göstergesidir: en küçük değişiklik bile imzayı bozar.
Tek bir imzalı makbuz bir eylemi korur. Makbuz zinciri bir diziyi korur.
flowchart LR
R0[Fiş 0<br/>genesis] --> R1[Fiş 1]
R1 --> R2[Fiş 2]
R2 --> R3[Fiş 3]
R1 -. previous_receipt_hash .-> R0
R2 -. previous_receipt_hash .-> R1
R3 -. previous_receipt_hash .-> R2
Her makbuz, ondan önceki makbuzun hash’ini kaydeder. Zincirin ortasından 2 numaralı makbuzu sessizce kaldırmak için:
previous_receipt_hash alanını değiştirmek gerekir (bu makbuz 3’ün imzasını bozar), YA DAÖzel anahtar bir donanım anahtar kasasında ve her makbuzla açık anahtar yayımlanıyorsa, bu saldırılardan hiçbiri tespitsiz mümkün değildir.
Defterde:
previous_receipt_hash alanının bir önceki makbuzun gerçek hash’i ile uyumlu olduğu doğrulanır.Bu, dış denetçinin size güvenmeden doğrulayabileceği bir denetim izi üretmenin yoludur.
Dersin en önemli bölümü budur. Makbuzlar güçlüdür ancak güçleri sınırlıdır.
Makbuzlar üç şeyi kanıtlar:
Makbuzlar KANITLAMAZ:
policy_id ile belirtilen politikanın gerçekten değerlendirildiği ya da kontrol edilseydi bu eyleme izin vereceği. Makbuz kaydeder ne iddia edildiğini, ne uygulandı.Bu sınır önemlidir çünkü:
Yaygın hata “makbuzlarımız var”ın “yönetiliyoruz” anlamına geldiğini varsaymaktır. Değil. Makbuzlar bir temeldir. Yönetim onun üstünde kurulan sistemdir.
Bu dersteki Python kodu kasıtlı olarak minimaldir ki her satırı okuyup tam olarak ne olduğunu anlayabilesiniz. Üretimde iki seçeneğiniz var:
Kriptografik primitifler üzerinde doğrudan inşa edin. Yukarıdaki 50 satır birçok kullanım için yeterlidir. PyNaCl (Ed25519) ve jcs paketi (kanonik JSON) iyi bakımlı ve denetlenmiş kütüphanelerdir.
Üretim seviyesi bir makbuz kütüphanesi kullanın. Birkaç açık kaynak proje aynı deseni ek özelliklerle (anahtar döndürme, toplu doğrulama, JWK Set dağıtımı, politika motorları entegrasyonu) uygular:
draft-farley-acta-signed-receipts) izlemektedir.protect-mcp (npm) ve @veritasacta/verify (npm) paketleri, herhangi bir MCP sunucusunu tahrifat belirtile denetim izi ile sarmak için Node tabanlı imzalama ve çevrimdışı doğrulama sağlar.pip install nobulex), Python’da LangChain ve CrewAI entegrasyonlarıyla aynı Ed25519 + JCS imzalama modelini sağlar; yayımlanmış çapraz doğrulama test vektörleri ve OWASP PR #2210 ile katkı sağlanmış uyumluluk haritası dahil.Kendi imzalama kütüphanenizi yazmak ile denenmiş bir JWT kütüphanesi kullanmak kararı gibidir: her ikisi de makuldür; kütüphane zaman kazandırır ve denetim yüzeyini azaltır; en baştan yazmak her primitifin anlaşılmasını zorunlu kılar. Bu ders en baştan yazma yolunu öğreterek her iki seçim için de temel sağlar.
Uygulama egzersizine geçmeden önce anlayışınızı test edin.
1. Bir makbuz ajanının özel Ed25519 anahtarı ile imzalanır. Denetçinin yalnızca açık anahtarı vardır. Denetçi makbuzu çevrimdışı doğrulayabilir mi?
2. Bir saldırgan makbuzun policy_id alanını daha izin verici bir politika iddiasıyla değiştirir. İmza orijinal yük üzerinde yapılmıştır. Doğrulama sırasında ne olur?
3. Makbuz neden ham argümanlar ve sonuç yerine tool_args_hash ve result_hash içerir?
4. previous_receipt_hash alanı her makbuzu öncekiyle bağlar. Zincirin ortasından bir makbuz sessizce silinirse ne geçersiz olur?
5. Bir makbuz temiz doğrulanırsa bu ajanın eyleminin doğru, sağlam veya politika ile uyumlu olduğunu kanıtlar mı?
code_samples/18-signed-receipts.ipynb dosyasını açın ve dört bölümü tamamlayın:
Esneme meydan okuması 2: iki makbuzunuzu SHA-256 ile birlikte hashleyin (kanonik baytlarını deterministik bir sırayla birleştirin) ve oluşan özeti üçüncü bir makbuza yeni bir alan olarak yerleştirin, ardından imzalayın. Üç makbuzun da hala iki yönlü olarak geçtiğini doğrulayın. Böylece tek adımlı bir dahil etme kanıtı oluşturmuş olursunuz: üçüncü makbuza sahip herkes, birinci ikisinin imzalandığı anda var olduğunu, içeriklerini açığa çıkarmadan kanıtlayabilir. Bu, seçmeli açıklama makbuzlarının büyük ölçekte kullandığı desendir (Merkle taahhütleri, RFC 6962).
Kriptografik makbuzlar, AI ajanlarına şu özelliklere sahip bir denetim izi sağlar:
Bunlar, girdi doğrulama, politika uygulama veya kimlik altyapısının yerine geçmez. O katmanların temeli olarak hizmet ederler. Düzenlemeye tabi iş yüklerine, çoklu kuruluş iş akışlarına veya gelecekteki bir denetçinin size güvenmediği herhangi bir ortama ajanlar dağıtırken, makbuzlar denetim izini dürüst yapmanın yoludur.
En önemli çıkarım: makbuzlar kim ne dedi, ne zaman dediğini kanıtlar. Söylenenin doğru veya gerçek olduğunu kanıtlamazlar. Bu ayrımı sıkı tutun. Bu, dürüst bir kaynak sistemi ile yanıltıcı bir sistem arasındaki farktır.
Bu dersten gerçek bir ortamda makbuzla imzalanan ajanlar dağıtmaya geçmeye hazır olduğunuzda:
https://your-org.example.com/.well-known/agent-keys.json ‘dir.Microsoft Foundry Discord‘a katılın; diğer öğrenenlerle tanışın, ofis saatlerine katılın ve AI Ajanlarındaki sorularınızı cevaplatın.
Bu ders tek makbuzlu imzalamayı ve hash zinciri dizilerini kapsar. Aynı temel yapıtaşları, yönetişim pozisyonunuz olgunlaştıkça karşılaşabileceğiniz daha gelişmiş birkaç desene dönüşür:
authorization_*) ve sonrası (result_*) olarak bağımsız imzalara sahip iki yarıya bölerler; yetkilendirme kararı ve gözlemlenen sonuç farklı aktörler tarafından veya farklı zamanlarda üretildiğinde faydalıdır. Bu, bu derste öğretilen makbuz formatının üzerine artımsal olarak eklenir.result_hash içine yerleştirdiğiniz baytları mühürler. Gerçek dünya verileri genellikle tek bir araç çağrısı sonucundan daha zengindir: karar öncesi muhakeme (model tahmini, düşünülen seçenekler, kanıt ve bütünlüğü, risk durumu, hesap verebilirlik zinciri, kapı sonucu) yük içinde yaşayabilir, tek bir makbuzla mühürlenir. Bu, makbuz formatını minimal tutarken yük şemalarının alan bazında gelişmesine olanak tanır.signature.alg alanı, göç gerektiğinde ML-DSA-65 (NIST kuantum sonrası imza standardı) taşıyabilir. Makbuzların çift imzalı olduğu bir geçiş dönemi planlayın.Bilgisayar Kullanım Ajanları Oluşturma (CUA)
(Müfredat sorumluları 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.