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

کدام سمت با شکست مواجه شد: موتور یا ورودی؟

Which side failed, the engine or the input

  • سطح ۲: میانی
  • سناریوی رخداد
  • ۲۰ دقیقه

وضعیت

تیمی ابزار rea را درون پایپ‌لاین یک ایجنت (agent) قرار داده‌اند که شب‌ها فایل‌های باینری را تحلیل می‌کند. رپر (wrapper) برای مواجهه با شکست‌ها فقط یک قانون دارد: با بروز هر خطایی در فراخوانی، هدف را ببندد، فرایند Java را متوقف کند، هدف را دوباره باز کند و عملیات را تکرار نماید. لاگ ثبت‌شده در طول شب نشان می‌دهد موتور 11 بار راه‌اندازی مجدد شده، پس از هر بار همان خطا تکرار شده و هزینه‌ی وارد کردن مجدد هدف نیز هر بار پرداخت شده است. دو نوع خطا در لاگ دیده می‌شود و رپر با هر دو به یک شیوه برخورد کرده است.

خطای اول از خط فرمان مکی نشئت گرفته که پایپ‌لاین را اجرا می‌کند: بررسی چینش ساختاری (layout inspection) یک آبجکت‌فایل با خروجی 1 خارج شد. خطای دوم از نشست MCP آمده است: دستور analyze_function برای نام رویه‌ای که ایجنت تایپ کرده بود، یک خطا برگرداند. شما گزارش دستورات، هر دو بسته خطای استاندارد (error envelope)، ایندکس نشست و لاگ سرور را در اختیار دارید. مشخص کنید هر شکست ناشی از چه بوده و قانون تکراری را بنویسید که رپر باید بر اساس آن عمل می‌کرد.

نسخه
rea 6.7.0 at 27dc42d with the Ghidra provider
مدل
no model; the fixtures are the ledger binaries built at -O1 and -O2
سخت‌افزار
one aarch64 Mac

شواهد

capability-unavailable.txt
title: the whole envelope of the failed CLI call
source: manuals/reverse-engineering-101/capture/out/04-inspect-binary-layout.json
lang: json
note: Read code, category and retryable before the message.
---
{
  "code": "capability_unavailable",
  "category": "unsupported_provider",
  "message": "The initial real-verified pwntools artifact profile supports Linux x64 only.",
  "retryable": false,
  "remediation": {
    "action": "The initial real-verified pwntools artifact profile supports Linux x64 only."
  },
  "details": {
    "provider_id": "pwntools-elf",
    "operation": "inspect_binary_layout",
    "reason": "The initial real-verified pwntools artifact profile supports Linux x64 only."
  }
}
diagnostics-tail.txt
title: the end of the diagnostics object
source: manuals/reverse-engineering-101/capture/out/10-mcp-13-analyze-function-missing.json
lines: 92-113
lang: json
note: The engine wrote nothing to stdout or stderr, the capture is complete, and the remote code is not_found.
---
          "failure_output": {
            "stdout": {
              "text": "",
              "bytes": 0,
              "retained_bytes": 0
            },
            "stderr": {
              "text": "",
              "bytes": 0,
              "retained_bytes": 0
            },
            "complete": true
          },
          "failure_cause": {
            "name": "GhidraRemoteError",
            "message": "Unknown Ghidra procedure name or address: _nothing",
            "code": "not_found"
          },
          "failure_kind": "remote",
          "failure_message": "Unknown Ghidra procedure name or address: _nothing",
          "remote_code": "not_found",
          "remote_message": "Unknown Ghidra procedure name or address: _nothing"
invalid-request-envelope.txt
title: the decoded error of the MCP call
source: manuals/reverse-engineering-101/capture/out/10-mcp-13-analyze-function-missing.json
lines: 32-49
lang: json
note: Read code, category and retryable, then the one issue in details.
---
  "decoded_text": {
    "error": {
      "code": "invalid_request",
      "category": "invalid_input",
      "message": "Analysis input is invalid. Check the arguments and try again.",
      "retryable": true,
      "remediation": {
        "action": "Correct the listed arguments and retry."
      },
      "details": {
        "operation": "analyze_function",
        "issues": [
          {
            "path": [],
            "reason": "invalid_value",
            "message": "Unknown Ghidra procedure name or address: _nothing"
          }
        ],
layout-call-exit-1.txt
title: the CLI call that exited 1
source: manuals/reverse-engineering-101/capture/out/00-commands.txt
lines: 10-11
lang: console
note: The command, its exit code, its time, and the file it wrote.
---
$ rea inspect-binary-layout fixtures/ledger-x86_64-O1.o --format json
[exit 1] (0.6 s) -> 04-inspect-binary-layout.json
server-log-around-the-error.txt
title: the server log around the failed call
source: manuals/reverse-engineering-101/capture/out/10-mcp-server.log
lines: 10-12
lang: jsonl
note: Two error lines at level 40, one per layer, then the next call completes with status ok.
---
{"level":40,"time":1792316959970,"application":"rea","mode":"mcp","layer":"ghidra-bridge","method":"analyze_function","status":"error","msg":"Ghidra bridge request completed"}
{"level":40,"time":1792316959971,"application":"rea","mode":"mcp","layer":"server","tool":"analyze_function","durationMs":2.73,"status":"error","msg":"MCP tool execution completed"}
{"level":30,"time":1792316960484,"application":"rea","mode":"mcp","layer":"server","tool":"close_binary","durationMs":491.18,"status":"ok","msg":"MCP tool execution completed"}
session-around-the-error.txt
title: three consecutive calls of the MCP session
source: manuals/reverse-engineering-101/capture/out/10-mcp-session.txt
lines: 12-14
lang: text
note: The call before and the call after the error both succeeded on the same open target.
---
12  tools/call analyze_function         ok     -> 10-mcp-12-analyze-function-grade-label-O1.json  (18 ms)
13  tools/call analyze_function         error  -> 10-mcp-13-analyze-function-missing.json  (4 ms)
14  tools/call export_evidence_bundle   ok     -> 10-mcp-14-export-evidence-bundle-O1.json  (18 ms)

سؤال‌ها

  1. هر دو بسته خطای استاندارد پنج فیلد یکسان دارند. پیش از خواندن پیام، کدام دو فیلد مشخص می‌کنند که گام بعدی چیست؟
  2. در خطای اول آمده است که یک پروفایل فقط از Linux x64 پشتیبانی می‌کند. ایراد از کجا بود: میزبان (host)، فایل یا موتور؟ و فراخوانی درست بعدی چیست؟
  3. در خطای دوم مقدار فیلد retryable: true است. اگر فراخوانی با همان آرگومان‌ها تکرار شود چه پاسخی برمی‌گردد و چه چیزی باید تغییر کند؟
  4. شیء عیب‌یابی چگونه به شما نشان می‌دهد که فرایند Ghidra هنگام شکست فراخوانی کاملاً سالم بوده است؟
  5. کدهایی را نام ببرید که راه‌اندازی مجدد موتور، پاسخ درست به آن‌هاست.

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

راه‌حل گام‌به‌گام
  1. ابتدا code ،category و retryable را بخوانید. هر خطای rea حاوی فیلدهای code ،category ،message ،retryable و remediation است. فیلد code تفکیک‌کننده (discriminator) بوده و یکی از 20 حالت ممکن است. فیلد category یکی از 10 دسته‌بندی است و نوع مشکل را مشخص می‌کند. این فلگ مشخص می‌کند که آیا ممکن است همین فراخوانی بعداً موفق شود یا خیر. فیلد message برای انسان نوشته شده است. رپر باید بر اساس دو فیلد اول و این فلگ branch بسازد، نه متن پیام خطا.
  2. بررسی خطای CLI. گزارش دستورات نشان می‌دهد که اجرای inspect-binary-layout روی آبجکت‌فایل، بعد از 0.6 ثانیه با خروجی 1 پایان یافته است. بسته خطای استاندارد دارای کد capability_unavailable، دسته‌ی unsupported_provider و مقدار retryable: false است. بخش جزئیات، نام ارائه‌دهنده را pwntools-elf و عملیات را مشخص کرده است. این ارائه‌دهنده فقط روی یک پلتفرم اجرا می‌شود: Linux x64؛ در حالی که پایپ‌لاین روی مک اجرا می‌شود. موتور اصلاً اجرا نشد. فراخوانی درست بعدی استفاده از یک ارائه‌دهنده‌ی دیگر یا میزبانی دیگر است، و راهنما برای ابزار چینش ساختاری روی این ماشین inspect-macho را به کار می‌برد. هیچ راه‌اندازی مجددی نمی‌تواند ارائه‌دهنده‌ای را که این‌جا اجرا نمی‌شود تغییر دهد.
  3. بررسی خطای MCP. ایندکس نشست نشان می‌دهد فراخوانیِ قبل و فراخوانیِ بعد، هر دو روی همان هدفِ بازشده کامل شده‌اند و فراخوانی ناموفق 4 میلی‌ثانیه زمان برده است. خطای رمزگشایی‌شده کد invalid_request، دسته‌ی invalid_input و retryable: true دارد. تنها مورد ذکرشده در جزئیات این است که نام رویه ناشناخته است. این فلگ یعنی یک فراخوانیِ اصلاح‌شده می‌تواند روی همان اتصال موفق شود. تکرار با همان نام همان خطا را برمی‌گرداند؛ بنابراین آرگومان باید تغییر کند، و list_procedures نام‌های موجود را می‌دهد.
  4. بررسی شیء عیب‌یابی. فیلد failure_output خروجی‌های stdout و stderr را که Ghidra حین درخواست ناموفق نوشته نگه می‌دارد: هر دو خالی‌اند و complete: true ثبت شده است. کد مخزن راه‌دور (remote) برابر not_found است. یک خروجی کامل و خالی به همراه یک کد مخزن راه‌دور نشان می‌دهد که موتور به پرسش پاسخ داده و پاسخ منفی بوده است. لاگ سرور نیز این موضوع را تایید می‌کند: دو خط در سطح 40 ثبت شده، یکی برای لایه‌ی رابط (bridge) و یکی برای لایه‌ی سرور، با مدت زمان 2.73 میلی‌ثانیه، و خط بعدی close_binary با وضعیت ok است. موتور قبل از فراخوانی، حین آن و پس از آن سالم بوده است.
  5. جایگاه درست راه‌اندازی مجدد. راه‌اندازی مجدد پاسخ مناسبی برای خانواده‌ی دیگری از کدهاست: provider_unavailable ،provider_timeout و یک execution_failure که اطلاعات عیب‌یابی آن خروجی ناقص را نشان دهد. در راهنما آمده است که provider_timeout کد مربوط به اولین فراخوانی وابسته به Ghidra است که از مهلت زمانی شروع 330,000 میلی‌ثانیه‌ای عبور می‌کند، و target_unavailable کد مربوط به تمام ابزارهای ارائه‌دهنده پیش از open_binary است. هیچ‌کدام در این دو شکست رخ نداده بودند.
نتیجه

هیچ‌کدام از این دو شکست تقصیر موتور نبود. اولی ارائه‌دهنده‌ای بود که روی میزبان اجرا نمی‌شود؛ غیرقابل‌تکرار که با ابزاری دیگر برطرف می‌شد. دومی به دلیل یک آرگومان اشتباه رخ داد که پس از تغییر آرگومان قابل تکرار بود، و فرایند Ghidra هم بالا ماند و به فراخوانی بعدی در همان نشست پاسخ داد. 11 بار راه‌اندازی مجدد هیچ حاصلی نداشت و هر بار هزینه‌ی یک بار وارد کردن هدف را به دنبال داشت.

رپر اکنون پیش از هر کاری category و retryable را می‌خواند. خطاهای unsupported_provider و unsupported_target مسیر را به ارائه‌دهنده یا میزبان دیگری هدایت کرده و متوقف می‌شوند. خطای invalid_input آرگومان را از روی یک فهرست تصحیح کرده و یک بار دوباره تلاش می‌کند. خطاهای unavailable ،timeout و execution_failure با خروجی ناقص، موتور را با تعیین سقف مشخصی برای تعداد دفعات، دوباره راه‌اندازی می‌کنند. باقی موارد به همراه پیام و راهکار به انسان گزارش می‌شوند. پس از اعمال این تغییرات، شب بعد بدون هیچ راه‌اندازی مجددی سپری شد و هر دو شکست به یک سطر در گزارش تبدیل شدند.

مسیرهای اشتباه رایج
  • «کد خروجی 1 یعنی موتور کرش کرده؛ دوباره راه‌اندازی‌اش کن.» بسته خطای استاندارد می‌گوید unsupported_provider و غیرقابل‌تکرار است. ارائه‌دهنده اصلاً شروع به کار نکرده بود، و راه‌اندازی مجدد هم چیز جدیدی را آغاز نمی‌کند.
  • «چون retryable برابر true است، همان فراخوانی را تکرار کن.» این فلگ می‌گوید فراخوانی می‌تواند بعداً و پس از تغییر ورودی موفق شود. همان نام ناشناخته، دقیقاً همان پاسخ را می‌گیرد.
  • «بررسی متن پیام برای تصمیم‌گیری روی branch.» پیام‌ها برای انسان نوشته شده‌اند و ممکن است بین نسخه‌ها تغییر کنند. کد، دسته‌بندی و فلگ قرارداد اصلی هستند.
  • «هر خطی با سطح 40 در لاگ سرور نشان می‌دهد رابط ناسالم است.» هر دو خط یک درخواست ناموفق را ثبت کرده‌اند که در 2.73 میلی‌ثانیه کامل شده بود، و خط بعدی هم یک فراخوانی موفق را روی همان اتصال ثبت کرده است.
درس کلی

بسته خطای استاندارد پاسخی نوع‌دار (typed) است و سیاست تکراری که نوع آن را نادیده بگیرد، هر شکستی را به پرهزینه‌ترین شکل آن تبدیل می‌کند. تفکیک‌کننده و فلگ retryable را بخوانید، جدولی برای نگاشت دسته‌بندی به اقدام نگه دارید، و قبل از این‌که موتور را دوباره راه‌اندازی کنید، به اطلاعات عیب‌یابی نگاه کنید تا شواهد زنده‌بودن آن را ببینید. ارزان‌ترین راه‌حل برای اکثر شکست‌ها تغییر ورودی است و گران‌ترین آن شروع سرد (cold start)؛ بنابراین سیاست انتخابی باید تفاوت میان این دو را تشخیص دهد.

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

در مرجع خطاهای Reverse Engineering 101 پنج فیلد و 20 کد خطا فهرست شده‌اند؛ در صفحه‌ی پرونده خطای نام ناشناخته و خطوط لاگ آن بررسی شده‌اند؛ در صفحه‌ی سرور rea MCP مهلت زمانی شروع و بازیابی متناسب با timeout آمده است؛ و در درس حالت‌های شکست خطای آبشاری (cascading error) به عنوان حالتی معرفی شده که در آن یک پاسخ نادرست باعث ایجاد فراخوانی‌های بیش‌تر می‌شود.