Ders videosunu izleyin: Kriptografik Makbuzlarla AI Ajanlarını Güvenceye Alma
(Ders videosu ve küçük resim, birleştirme sonrası Microsoft içerik ekibi tarafından eklenecek, ders 14 / 15 kalıbıyla uyumlu olacak.)
Bu ders şunları kapsayacak:
Bu dersi tamamladıktan sonra şunları bileceksiniz:
Contoso Travel için bir AI ajanı dağıttığınızı hayal edin. Ajan müşteri taleplerini okur, uçuş API’sini çağırarak seçeneklere bakar ve müşterinin adına koltuk rezervasyonu yapar. 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ı teslim edersiniz. Denetçi belgeleri inceler ve zor soruyu sorar: “Bu günlüklerin değiştirilmediğini nasıl biliyorum?”
Bu denetim izi sorunudur. Bugün çoğu ajan dağıtımı şunlara güvenir:
Bu hiçbirisi denetçinin sorusunu cevaplayamaz, denetçinin birine (size, bulut sağlayıcınıza, veritabanı satıcınıza) güvenmesini gerektirir. Dahili kullanımda bu güven genellikle kabul edilir. Düzenlenen iş yükleri için (finans, sağlık, AB AI Yasası kapsamındakiler) kabul edilmez.
Kriptografik makbuzlar, her ajan eyleminin bağımsız olarak doğrulanabilmesini sağlayarak bunu çözer. Denetçinin size güvenmesi gerekmez; sadece açık anahtarınız ve makbuz yeterlidir.
Makbuz, bir ajanın ne yaptığını kaydeden ve dijital imzayla imzalanan bir JSON nesnesidir.
flowchart LR
A[Ajan bir araç çağırır] --> B[Makbuz yükü oluştur]
B --> C[JSON RFC 8785'i kanonikleştir]
C --> D[SHA-256 karması]
D --> E[Ed25519 ile imzala]
E --> F[İmzalı makbuz]
F --> G[Denetçi çevrimdışı doğrular]
G --> H{İmza geçerli mi?}
H -- yes --> I[Müdahale kanıtı]
H -- no --> J[Makbuz 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 görev yapmaktadır:
İmza. Makbuz, ajanın geçidi tarafından Ed25519 özel anahtarı kullanılarak imzalanır. İlgili açık anahtara sahip herkes imzayı çevrimdışı doğrulayabilir. Herhangi bir alanın tahrif edilmesi imzayı geçersiz kılar.
Kanonik kodlama. İmzalamadan önce makbuz JSON Kanonikleştirme Şeması (JCS, RFC 8785) kullanılarak serileştirilir. Bu, aynı mantıksal makbuzu üreten iki uygulamanın aynı baytlar dizisini vermesini sağlar. Kanonikleştirme olmadan farklı JSON serileştiriciler aynı içerik için farklı imzalar üretirdi.
Hash zincirleme. previous_receipt_hash alanı her makbuzu bir öncekine bağlar. Bir makbuzun çıkarılması veya sırasının değiştirilmesi sonrasındaki tüm makbuzları geçersiz kılar. Bireysel imzalar atlanmış olsa bile zincir düzeyinde tahrifat görünür hale gelir.
Birlikte bu özellikler üç garanti sağlar:
Makbuz üretmek için özel bir kütüphaneye ihtiyacınız yok. Kriptografik ilkel araçlar yaygın ve mantık birkaç düzine Python satırından oluşur.
code_samples/18-signed-receipts.ipynb elinizdeki pratik uygulamalar tam akışı anlatır. Özet sürümü:
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()}"
# İmzalama anahtarı oluştur veya yükle (üretimde, bir anahtar kasasında sakla)
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,
}
# Kanonik hale getir, 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 alıştırmalar her adımı detaylandırır.
Doğrulama işleminin tersi şeklidir:
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
# Gerçekten imzalanan yükü yeniden oluşturun (imza dışındaki 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ü taraf güveni gerektirmez.
Tahrifat tespitinin çalışmasını görmek için defterde şunlar anlatılır:
tool_args_hash alanından bir bayt değiştirmek.Bu, makbuzların tahrifata karşı korumalı olduğunu pratikte gösterir: her türlü değişiklik, çok küçük olsa bile, imzayı bozar.
Tek bir imzalı makbuz bir eylemi korur. Bir makbuz zinciri bir diziyi korur.
flowchart LR
R0[Makbuz 0<br/>başlangıç] --> R1[Makbuz 1]
R1 --> R2[Makbuz 2]
R2 --> R3[Makbuz 3]
R1 -. previous_receipt_hash .-> R0
R2 -. previous_receipt_hash .-> R1
R3 -. previous_receipt_hash .-> R2
Her makbuz, öncekine ait makbuzun hash’ini kaydeder. Makbuz 2’yi sessizce kaldırmak isteyen bir saldırgan şunlardan birini yapmak zorundadır:
previous_receipt_hash alanını değiştirmek (makbuz 3’ün imzası bozulur) YA DAÖzel anahtar bir donanım anahtar kasasında ise ve her makbuzla açık anahtar yayınlanıyorsa, hiçbir saldırı tespit edilmeden mümkün değildir.
Defterde şunlar anlatılır:
previous_receipt_hash değerinin önceki makbuzun gerçek hash’i olduğunun doğrulanması.Bu, harici bir denetçinin size güvenmeden doğrulayabileceği bir denetim izi nasıl üretilir onu gösterir.
Bu dersin en önemli bölümüdür. Makbuzlar güçlüdür ama gücü sınırlandırılmıştır.
Makbuzlar üç şey kanıtlar:
Makbuzlar şunları kanıtlamaz:
policy_id içindeki politikanın gerçekten değerlendirildiği ya da kontrol edilse eyleme izin verip vermeyeceği. Makbuz, ne iddia edildiğini kaydeder, ne uygulanandan bahsetmez.Bu sınır iki nedenle önemlidir:
Yaygın hata, “makbuzlarımız var” demenin “denetleniyoruz” demek olduğunu varsaymaktır. Değil. Makbuzlar temeldir. Denetim, üzerine inşa ettiğiniz sistemdir.
Üstteki madde 3 kendi bölümünü hak eder: bir eylem makbuzu “bu anahtar bu içeriği imzaladı” der, “bir insan yetkilendirdi” demez. Yüksek riskli eylemler için (iade, silme, havale) yönetişim çerçeveleri giderek bu eksik ifadeyi zorunlu kılmakta ve bunu bu derste zaten kurduğunuz ilkelere dayanarak üretmek mümkün.
Sonraki defter code_samples/human-authorization-receipts.ipynb, ders makbuzlarıyla aynı zarfta ikinci bir makbuz türü human.approval.v1 ekler (typed payload, Ed25519 ile kanonik SHA-256 üzerinde imzalanmış, imza objesi imzalanan baytların dışındadır). İmzacı, tam kanonik eylemi ve onun özeti yürütmeden önce imzalar; ajanın eylem makbuzu aynı eylem özetine ve parent_approval_ref — onay makbuzunun receipt_hashı — sahiptir, bu zincirde oluşturduğunuz previous_receipt_hash ile aynı sözleşme. Bir tane verify_chain, iki farklı anahtar kaydı altında (onaycı anahtarları ve ajan anahtarları) her iki belgeyi de doğrular, böylece kod ortak ama yetkililer hiç ortak değildir.
Bu özellik dikkatli ifade edilirse: insan bu tam eylemi onayladı ve ajan da tam olarak onaylanan eylemi gerçekleştirdi. Defterdeki ret durumları bu özelliği varsayılan değil gerçek yapar:
Her hata farklı bir gerekçe ile reddedilir, böylece bir denetçi bir reddi okuduğunda yetkinin eski mi yoksa yürütülen eylemin mi değiştiğini anlayabilir. Defterde öğretilen kural: imzalı onay tek başına yetki değildir. Yetki ancak her iki makbuz da yürütme zamanında aynı kanonik eylemi bağlıyorsa vardır. Bu dersin takip ettiği aynı Internet Taslağındaki (draft-farley-acta-signed-receipts) ortak imzalama yolu bu desenin standart yoludur.
Bu derste Python kodu kasıtlı olarak minimaldır, böylece her satırı okuyup tam olarak ne olduğunu anlayabilirsiniz. Üretimde iki seçeneğiniz vardır:
Kriptografik ilkelere doğrudan dayanın. Yukarıdaki 50 satır birçok kullanım durumu için yeterlidir. PyNaCl (Ed25519) ve jcs paketi (kanonik JSON) iyi bakılan ve denetlenen kütüphanelerdir.
Üretim makbuz kütüphanesi kullanın. Birkaç açık kaynak proje aynı deseni ek özelliklerle uygular (anahtar rotasyonu, toplu doğrulama, JWK Set dağıtımı, politika motorları ile entegrasyon):
draft-farley-acta-signed-receipts, revizyon 02) ve şu anda standart sürecindedir, bağımsız uygulamaların bayt olarak aynı kanonik çıktıyı doğruladığı ortak bir uyum testi setiyle (agent-governance-testvectors).protect-mcp (npm) ve @veritasacta/verify (npm) paketleri, imzalama ve çevrimdışı doğrulamayı sağlayan Node tabanlı uygulama sunar; MCP sunucusunu tahrifat karşıt denetimle sarmak için, eş imza bekleyen bir akış dahil, masaüstü akışında WebAuthn destekli onay makbuzu verilen durdurulmuş eylemi kapsar; yukarıdaki insan-izin defterinde anlatılan onay-makbuz kalıbı ile aynıdır.pip install nobulex), Python’da LangChain ve CrewAI entegrasyonlarıyla aynı Ed25519 + JCS imzalama kalıbını sağlar, yayınlanmış çapraz doğrulama test vektörleri ve OWASP PR #2210 (OWASP PR #2210) aracılığıyla katkı sağlanmış uygunluk haritası da içerir.Kendi başınıza yazmakla bir kütüphane kullanmak arasındaki karar, kendi JWT kütüphanenizi yazmak ile test edilmiş birini kullanmak arasındaki kararlara benzer: her ikisi de makul; kütüphane zaman kazandırır ve denetim yüzeyini azaltır; sıfırdan yaklaşım her ilkeyi anlamanızı sağlar. Bu ders sıfırdan yolu öğretir ki her iki seçenek için temelinizi oluşturun.
Uygulama alıştırmasına geçmeden önce anlayışınızı test edin.
1. Makbuz, ajanın Ed25519 özel anahtarı ile imzalanmıştır. Denetçinin sadece açık anahtarı vardır. Denetçi makbuzu çevrimdışı doğrulayabilir mi?
2. Bir saldırgan, makbuzdaki policy_id alanını, daha izin veren bir politika ile yönetildiğini iddia edecek şekilde değiştirir. İmza orijinal yükü kapsıyordu. Doğrulama sırasında ne olur?
3. Makbuzda neden ham argümanlar ve sonuç yerine tool_args_hash ve result_hash bulunuyor?
4. previous_receipt_hash alanı her makbuzu önceki makbuza bağlar. Bir saldırgan zincirin ortasından sessizce bir makbuzu silerse, ne geçersiz olur?
5. Bir makbuz sorunsuzca doğrulanıyor. Bu, ajan 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:
Ek meydan okuma 1: Makbuz şemasını kendi seçtiğiniz ek bir alanla genişletin (örneğin, izleme için istek kimliği), kanonik imzalama mantığını buna göre güncelleyin ve makbuzun doğrulamada hala tam olarak çalıştığını doğrulayın. Ardından imzalama sonrası alanı değiştirin ve doğrulamanın başarısız olduğunu teyit edin. Bu, kanonik kodlamanın her baytının imzaya nasıl katkıda bulunduğunu anlamanızı sağlar.
Ek meydan okuma 2: İki makbuzunuzun kanonik baytlarını belirleyici bir sırada birleştirip SHA-256 hash’ini alın ve sonuç özeti üçüncü bir makbuza yeni bir alan olarak gömün, sonra onu imzalayın. Üç makbuzun da hâlâ tam olarak doğrulandığını kontrol edin. Bu, bir adımlı kapsama kanıtı oluşturur: üçüncü makbuzu tutan biri, ilk ikisinin imzalandığı zamanda var olduklarını kanıtlayabilir, içeriklerini ifşa etmeden. Seçici açıklama makbuzlarının bu deseni kullandığını unutmayın (Merkle taahhütleri, RFC 6962).
Kriptografik makbuzlar, AI ajanlarına aşağıdaki denetim izini verir:
Bunlar girdi doğrulama, politika uygulama veya kimlik altyapısının yerine geçmez. Bu katmanların temelini oluştururlar. Regüle edilmiş iş yüklerine, çoklu organizasyon uygulamalarına veya gelecekteki denetleyicilerin size güvenemeyeceği herhangi bir ortamda ajanlar dağıtırken, makbuzlar denetim izini dürüst yapmanın yoludur.
En önemli çıkarım: makbuzlar kimin ne zaman ne dediğini kanıtlar. Ne söylendiğinin doğru veya haklı olduğunu kanıtlamaz. Bu ayrımı sıkı tutun. Bu, dürüst bir köken sistemi ile yanıltıcı bir sistem arasındaki farktır.
Bu dersten gerçek ortamda makbuz imzalı ajanlar dağıtmaya geçmeye hazır olduğunuzda:
https://your-org.example.com/.well-known/agent-keys.json.Diğer öğrenenlerle tanışmak, ofis saatlerine katılmak ve AI Ajanları ile ilgili sorularınızı yanıtlamak için Microsoft Foundry Discord’a katılın.
Bu ders tek makbuz imzalama ve hash zincirli sıraları kapsar. Aynı primitifler, yönetişim tutumunuz olgunlaştıkça karşılaşabileceğiniz birkaç daha gelişmiş deseni oluşturur:
authorization_*) ve yürütme sonrası (result_*) olarak bağımsız imzalarla ayrılır; yetkilendirme kararı ve gözlemlenen sonuç farklı aktörler veya zamanlarda üretildiğinde faydalıdır. Bu dersin makbuz formatının üzerine ek olarak eklenir.result_hash içine koyduğunuz baytları mühürler. Gerçek dünya yükleri genellikle tek bir araç çağrısından daha zengindir: karar öncesi muhakeme (model tahmini, düşünülen seçenekler, kanıt ve tamlığı, risk durumu, hesap verebilirlik zinciri, kapı sonucu) tümü bir makbuz tarafından mühürlenebilir. Bu makbuz formatını minimal tutar ve yük şemalarının alan bazında evrilmesine izin verir.signature.alg alanı gerektiğinde ML-DSA-65 (NIST post-kuantum imza standardı) taşıyabilir. İki imzalı geçiş dönemi planlayın.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.