سناریوی رخداد

کارتی که نام محیط عملیاتی را یدک می‌کشید

A card that said production

  • سطح ۳: ارشد
  • سناریوی رخداد
  • ۲۵ دقیقه

وضعیت

یک برنامه‌ریز برنامه‌اش را بر اساس کارت‌های ایجنتی می‌سازد که هنگام راه‌اندازی (startup) واکشی می‌کند. این کارت‌ها از یک پروکسی کش‌کننده که تیم دیگری آن را اداره می‌کند رد می‌شوند، و برنامه‌ریز هر کارت را توصیفی معتبر از کارهایی می‌داند که ایجنت قرار است انجام دهد. یک روز صبح، برنامه‌ریز مرحله‌ی انتشار را به شکل Deploy build 2026.10.06-1 to production محول کرد؛ زیرا نسخه‌ای از کارت ایجنت مستقرکننده (deployer) که در دست داشت، ایجنتی را توصیف می‌کرد که بیلد‌های برچسب‌خورده (tagged builds) را در محیط عملیاتی (production) مستقر می‌کند. اما ایجنت مستقرکننده کار را رد کرد. فرایند انتشار متوقف شد، و مهندس نوبت پاسخگویی (آنکال) فهمید نسخه‌ی روی پروکسی، تنها در یک کلمه با کارتی که خود ایجنت ارائه می‌دهد فرق دارد.

کارت ایجنت مستقرکننده حاوی یک امضاست، اما هیچ‌کس در تیم برنامه‌ریز به آن نگاه هم نکرده بود. بارگذار کارت (card loader) فایل JSON را خواند، فیلدهای ناشناس را کنار گذاشت و برنامه‌ریزی را پیش برد. اکنون کارت منتشرشده، پاسخ خود ایجنت به یک درخواست احراز هویت‌شده برای دریافت کارت، امتناع مدل، و گزارش جعبه‌ابزار از استانداردسازی (canonicalizing)، امضا و اعتبارسنجی کارت، همراه با نتیجه‌ی بررسی نسخه‌ای که در توضیحاتش نام محیط عملیاتی آمده، در اختیارتان قرار دارد.

نسخه
A2A 1.0.1 with the manual's capture kit (the test-runner, code-reviewer and deployer agents)
مدل
no model; the agents are deterministic fixtures
سخت‌افزار
one machine, localhost, no network

شواهد

canonical-and-header.txt
title: the canonical payload and the decoded protected header
source: manuals/a2a-101/capture/out/17-signed-card.txt
lines: 1-5
lang: text
note: Line 2 is the whole card without its signatures, keys sorted, no spaces. Read the description inside it and the alg in the header.
---
# 1. canonical payload (RFC 8785): the card without signatures, keys sorted, no spaces
{"capabilities":{"extendedAgentCard":true,"streaming":true},"defaultInputModes":["text/plain"],"defaultOutputModes":["text/plain","application/json"],"description":"Deploys a tagged build to staging after an operator approves it.","name":"deployer","provider":{"organization":"Platform Team","url":"https://deploy.example.com"},"securityRequirements":[{"schemes":{"bearer":{"list":[]}}}],"securitySchemes":{"bearer":{"httpAuthSecurityScheme":{"description":"A token issued by the platform team.","scheme":"Bearer"}}},"skills":[{"description":"Deploy one tagged build to staging, with operator approval.","examples":["Deploy build 2026.10.06-1 to staging"],"id":"deploy","name":"Deploy a build","tags":["deploy","staging"]}],"supportedInterfaces":[{"protocolBinding":"JSONRPC","protocolVersion":"1.0","url":"http://localhost:41243/a2a/jsonrpc"},{"protocolBinding":"HTTP+JSON","protocolVersion":"1.0","url":"http://localhost:41243/a2a/rest"}],"version":"1.4.1"}

# 2. protected header, decoded
{"alg": "HS256", "typ": "JOSE", "kid": "deployer-key-1"}
rejected-production-deploy.txt
title: what the deployer answers to a production deploy
source: manuals/a2a-101/capture/out/08-rejected.http
lines: 27-54
lang: text
note: Read the state and the agent's message inside it.
---

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "task": {
      "id": "23cf3710-c193-457d-93d1-e93e1c860a53",
      "contextId": "cf08459c-e7bd-4736-92d7-2fe3f6e7a1f6",
      "status": {
        "state": "TASK_STATE_REJECTED",
        "message": {
          "messageId": "12b263fc-78eb-4b49-997f-e495cca7813c",
          "contextId": "cf08459c-e7bd-4736-92d7-2fe3f6e7a1f6",
          "taskId": "23cf3710-c193-457d-93d1-e93e1c860a53",
          "role": "ROLE_AGENT",
          "parts": [
            {
              "text": "Production deploys are outside this agent's policy. Use the release train."
            }
          ]
        },
        "timestamp": "2026-10-06T09:00:01.750Z"
      },
      "history": [
        {
          "messageId": "6018366c-f658-47a7-9ed3-4fe53a096533",
          "contextId": "cf08459c-e7bd-4736-92d7-2fe3f6e7a1f6",
          "taskId": "23cf3710-c193-457d-93d1-e93e1c860a53",
signature-and-two-checks.txt
title: the published signature entry and two verification results
source: manuals/a2a-101/capture/out/17-signed-card.txt
lines: 10-17
lang: text
note: The last two lines are the checks: the card as published, and a copy with one word changed.
---
# 4. the signature entry published in the card
{
  "protected": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpPU0UiLCJraWQiOiJkZXBsb3llci1rZXktMSJ9",
  "signature": "yPk834ji_dOVmxElhzV3yTYBT9NVp8Bx1j5K0LQmOww"
}

# 5. verify the published card: True
# 6. verify after changing the description to name production: False
skills-and-signature.txt
title: the skills and the signature of the published deployer card
source: manuals/a2a-101/capture/out/01-agent-cards.http
lines: 181-200
lang: text
note: Read where the skill says the build goes, then the two fields of the signature entry.
---
  "skills": [
    {
      "id": "deploy",
      "name": "Deploy a build",
      "description": "Deploy one tagged build to staging, with operator approval.",
      "tags": [
        "deploy",
        "staging"
      ],
      "examples": [
        "Deploy build 2026.10.06-1 to staging"
      ]
    }
  ],
  "signatures": [
    {
      "protected": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpPU0UiLCJraWQiOiJkZXBsb3llci1rZXktMSJ9",
      "signature": "yPk834ji_dOVmxElhzV3yTYBT9NVp8Bx1j5K0LQmOww"
    }
  ]
the-agent-when-asked.txt
title: what the deployer itself says to an authenticated caller
source: manuals/a2a-101/capture/out/18-extended-card.http
lines: 40-48
lang: text
note: Compare this description with the one the planner acted on.
---
HTTP/1.1 200 OK
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "name": "deployer",
    "description": "Deploys a tagged build to staging after an operator approves it.",
verify-first.txt
title: when a client verifies, and with which algorithms
source: manuals/a2a-101/sections/2-3-extended-cards-and-signatures.md
lines: 120-120
lang: text
note: One sentence on the order of operations, one on the key, one on the algorithm list.
---
A client should verify at least one signature before it trusts an Agent Card {{spec §8.4.3}}, and never with an expired or revoked key. Give your verifier an explicit list of allowed algorithms, as the reference SDK does, to prevent algorithm confusion attacks {{sdk src/a2a/utils/signing.py}}. [Security requirements](#s-security-requirements) covers card spoofing.
verify-rules.txt
title: the three rules a verifier follows to rebuild the signed bytes
source: manuals/a2a-101/sections/2-3-extended-cards-and-signatures.md
lines: 67-71
lang: text
note: Rule 3 says what the signature cannot cover.
---
Each entry holds a base64url `protected` header and `signature` {{proto AgentCardSignature}}, and a verifier rebuilds the signed bytes from the received card under three rules {{spec §8.4.1}}:

1. **Field presence.** A field marked `REQUIRED` must always be present, even when its value is the default {{spec §8.4.1}}. A field with the `optional` keyword stays whenever it was set, and any other field at its default value is dropped.
2. **RFC 8785.** The JSON Canonicalization Scheme sorts object keys, fixes one form for each value, and removes whitespace {{spec §8.4.1}}.
3. **No signatures.** The `signatures` field must be left out of the signed content, because a signature cannot cover itself {{spec §8.4.1}}.

سؤال‌ها

  1. طبق کارت منتشرشده، ایجنت مستقرکننده چه کاری انجام می‌دهد، و این ایجنت در پاسخ به درخواستی که با یک توکن همراه بود چه گفت؟
  2. امضا چه بخش‌هایی را پوشش می‌دهد و چه بخش‌هایی را نادیده می‌گیرد؟
  3. یکی از بررسی‌ها مقدار True و دیگری False بازگرداند. بین این دو چه چیزی تغییر کرده بود، و چرا یک کلمه اهمیت دارد؟
  4. چرا این جعبه‌ابزار با HS256 امضا می‌کند، و چرا استفاده از آن در یک استقرار واقعی در محیط عملیاتی قابل‌قبول نیست؟
  5. اعتبارسنجی کجای فرایند راه‌اندازیِ برنامه‌ریز جای می‌گیرد، و در صورت رد شدنش چه اتفاقی می‌افتد؟
  6. ایجنت مستقرکننده استقرار در محیط عملیاتی را رد کرد. چرا این امتناع مدل لایه‌ی دفاعی به‌حساب نمی‌آید؟

اول شواهد را بخوانید و به سؤال‌ها جواب بدهید، بعد راه‌حل را باز کنید.

راه‌حل گام‌به‌گام
  1. کارت منتشرشده را بخوانید. مهارت ثبت‌شده Deploy a build است، و در توضیحاتش آمده که یک بیلد برچسب‌خورده را پس از تأیید اپراتور به محیط آزمایشی (staging) می‌فرستد. برچسب‌های آن deploy و staging هستند و مثال آن هم استقرار در محیط آزمایشی را نشان می‌دهد. زیر بخش مهارت‌ها، یک فهرست signatures با یک مدخل قرار دارد: یک هدِ protected و یک signature. کارت گسترش‌یافته (extended card) که فقط در پاسخ به فراخواننده‌ای با توکن حامل (bearer token) برگردانده می‌شود، همین ایجنت را توصیف می‌کند: استقرار در محیط آزمایشی پس از تأیید اپراتور. تنها در نسخه‌ی روی پروکسی بود که نام محیط عملیاتی دیده می‌شد.
  2. بار داده‌ی استانداردشده را بخوانید. این بار داده همان کارت بدون امضاهایش است، با کلیدهای مرتب‌شده و بدون فاصله‌ی خالی، دقیقاً همان‌طور که RFC 8785 تعریف می‌کند. توضیحات داخل آن محیط آزمایشی را مشخص کرده است. هدِ رمزگشایی‌شده شامل alg برابر با HS256، فیلد typ برابر با JOSE و فیلد kid برابر با deployer-key-1 است. ورودیِ امضا از اتصال هدِ base64url و بار داده‌ی base64url با یک نقطه تشکیل می‌شود.
  3. قوانین سه‌گانه را بخوانید. مدل اعتبارسنج این بایت‌ها را از روی کارتی که دریافت کرده دوباره می‌سازد. فیلد الزامی (REQUIRED) همیشه باید وجود داشته باشد، حتی اگر روی مقدار پیش‌فرشش باشد. روش استانداردسازی JSON ترتیب و شکل هر مقدار را ثابت می‌کند. فیلد signatures کنار گذاشته می‌شود، چون امضا نمی‌تواند خودش را پوشش دهد. بنابراین، امضا تمام فیلدهای دیگر، از جمله توضیحات را قفل و معتبر می‌کند.
  4. نتایج دو بررسی را بخوانید. بررسی کارت منتشرشده مقدار True بازمی‌گرداند. اما روی نسخه‌ی دست‌کاری‌شده، که در آن کلمه‌ی staging به production تبدیل شده، بایت‌های استانداردشده فرق دارند و بررسی مقدار False برمی‌گرداند. تغییر یک کلمه بایت‌های امضاشده را تغییر می‌دهد و امضا دیگر مطابقت ندارد. این همان آزمایشی است که برنامه‌ریز هرگز اجرا نکرد.
  5. خط مربوط به الگوریتم را بخوانید. این جعبه‌ابزار با HS256 امضا می‌کند چون کتابخانه‌ی استانداردش فاقد ECDSA است. HS256 از نوع HMAC است؛ بنابراین مدل اعتبارسنج خودش کلید امضا را در اختیار دارد و می‌تواند کارت را امضا کند. کارت‌های واقعی از ES256 یا RS256 استفاده می‌کنند که کلید عمومی آن‌ها در یک JWKS منتشر می‌شود و از طریق kid و jku واکشی می‌گردد یا از یک مخزن معتبر برداشته می‌شود. اعتبارسنجی شش گام الزامی (MUST) دارد، و کلاینت پیش از آنکه به کارتی اعتماد کند، دست‌کم یک امضا را اعتبارسنجی می‌کند؛ این کار هرگز نباید با کلید منقضی‌شده یا باطل‌شده انجام شود و باید بر اساس فهرستی صریح از الگوریتم‌های مجاز صورت گیرد.
  6. پیام امتناع مدل را بخوانید. ایجنت مستقرکننده وضعیت TASK_STATE_REJECTED را برگرداند و گفت استقرار در محیط عملیاتی خلاف سیاست‌هایش است. این سیاست درون خود ایجنت قرار دارد و در این مورد کارساز شد. کارت نشانی رابط وب (URL) ارسالیِ برنامه‌ریز را هم مشخص می‌کند. اگر نسخه‌ای بتواند یک کلمه را تغییر دهد، می‌تواند آن فیلد را نیز عوض کند؛ آن وقت درخواست به سروری می‌رود که مهاجم اداره‌اش می‌کند و هیچ سیاستی هم جلوی هیچ کاری را نمی‌گیرد.
نتیجه

برنامه‌ریز به نسخه‌ی اعتبارسنجی‌نشده‌ی یک سند امضاشده اعتماد کرده بود. اکنون بارگذار کارت، پیش از خواندن هر فیلدی برای برنامه‌ریزی، دست‌کم یک امضا را اعتبارسنجی می‌کند. این بخش بایت‌های استانداردشده را بر اساس قوانین سه‌گانه بازسازی می‌کند، کلید مربوط به kid را از یک مخزن معتبر برمی‌دارد و فقط الگوریتم‌های تعیین‌شده توسط تیم را مجاز می‌داند. کارتی که در بررسی رد شود پذیرفته نخواهد شد و هشداری ایجاد می‌کند، و برنامه‌ریز دیگر به محتوای آن اتکا نمی‌کند. برای یک نشستِ (session) احراز هویت‌شده، برنامه‌ریز کارت عمومی کش‌شده را با کارت گسترش‌یافته‌ای که خود ایجنت برمی‌گرداند جایگزین می‌کند. لاگ‌های جعبه‌ابزار اثبات درستی این سازوکارند: روی بایت‌های منتشرشده خروجی True است، روی همان کارت با تغییر فقط یک کلمه خروجی False می‌شود، و توضیحات خود ایجنت هم با نسخه‌ی منتشرشده همخوانی دارد.

مسیرهای اشتباه رایج
  • «کشِ پروکسی را پین می‌کنیم و جلو می‌رویم.» کارت همچنان اعتبارسنجی نشده است؛ تغییر بعدی هم از همین راه نفوذ خواهد کرد.
  • «توضیحات را با نسخه‌ای که هفته‌ی پیش دیدیم مقایسه می‌کنیم.» فیلد version داخل بار داده‌ی امضاشده قرار دارد، و نسخه‌ی تغییریافته هم آن را حفظ می‌کند. فقط امضاست که فیلدها را به هم پیوند می‌دهد.
  • «با هر الگوریتمی که در هد آمده اعتبارسنجی می‌کنیم.» هد بخشی از ورودی است. به مدل اعتبارسنج فهرستی صریح بدهید تا alg تغییریافته نتواند بررسی ضعیف‌تری را انتخاب کند.
  • «ایجنت مستقرکننده درخواست را رد کرد، پس سیستم امن است.» این امتناع از سوی ایجنت سالم در همان نشانی منتشرشده آمد. کارتی که دست‌کاری شده می‌تواند نشانی را هم تغییر دهد، و آن‌وقت ایجنت سالم اصلاً درخواستی نخواهد دید.
  • «به‌جای آن کارت گسترش‌یافته را واکشی می‌کنیم، چون به توکن نیاز دارد.» کارت گسترش‌یافته کارتی کامل‌تر برای فراخواننده‌ی احراز هویت‌شده است و بدون امضا برمی‌گردد. این کارت فقط زمانی کمک می‌کند که برنامه‌ریز به ایجنت طرف صحبت خود اعتماد داشته باشد، و این امضای کارت عمومی است که چنین اعتمادی را می‌سازد.
درس کلی

هر چیزی که یک ایجنت از شبکه می‌خواند ورودی است، نه حقیقت محض؛ و فراداده‌ای که سایر ایجنت‌ها را توصیف می‌کند، پرنفوذترین ورودی به‌شمار می‌رود. پیش از آنکه بر اساس چنین سندی برنامه‌ریزی کنید، یکپارچگیِ آن را با کلیدی که همراه خود سند منتقل نشده بررسی کنید، و به بررسی‌های مبتنی بر سیاست در مقصد نهایی فقط به چشم لایه‌ی دوم نگاه کنید، نه هرگز لایه‌ی اول.

کجای دوره آموزش داده می‌شود

صفحه‌ی کارت‌های گسترش‌یافته و امضاها در A2A 101 مراحل این امضا و هر دو بررسی را گام‌به‌گام توضیح می‌دهد، صفحه‌ی طرح‌های امنیتی اعتبارنامه‌ها و دامنه‌ی (scope) مجوزها را پوشش می‌دهد، و درس تزریق غیرمستقیم پرامپت تبیین می‌کند که چرا محتوای خوانده‌شده توسط ایجنت در غیاب کاربر، همان سطح حمله‌ای (attack surface) است که فیلترهای ورودی کاربر هرگز به آن دسترسی ندارند.