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

لیست خالی که ایجنت آن را «هیچ» خواند

An empty list that an agent read as none

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

وضعیت

یک ایجنت کدنویسی در حال بررسی فایل اجرایی ledger-arm64-O1 برای معماری arm64 از طریق سرور rea MCP است که ارائه‌دهنده‌ی (provider) Ghidra در پشت آن قرار دارد. وظیفه‌ی ایجنت، بازبینی امنیتیِ عمل تقسیم در تابع _percent_change است. ایجنت ابزار analyze_function را یک بار صدا می‌زند و در گزارش خود می‌نویسد: «این تابع، یک تابع برگ (leaf) است. هیچ تابعی را صدا نمی‌زند، بنابراین عمل تقسیم نمی‌تواند به یک کال‌بک یا کنترل‌کننده (handler) برسد.» یکی از بازبین‌ها می‌پرسد این جمله از کجا آمده است. ایجنت به یک خط از پرونده (dossier) اشاره می‌کند؛ آرایه‌ی callees که خالی است.

بازبین این خط را به‌عنوان اثبات (proof) نمی‌پذیرد و از شما می‌خواهد مشخص کنید که پرونده دقیقاً چه چیزی را اثبات می‌کند و چه چیزی را اثبات نمی‌کند. شما این پرونده، سطر مربوط به همین رکورد در خلاصه‌ی بسته (bundle summary)، و مستنداتی را که هر دو را شرح می‌دهند در اختیار دارید. گزارش باید ظرف یک ساعت آینده تحویل داده شود و جمله‌ی مربوط به تابع برگ، همان پایه‌ای است که ادامه‌ی کل بازبینی روی آن بنا شده است.

نسخه
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

شواهد

bundle-summary-head.txt
title: the head of the bundle summary
source: manuals/reverse-engineering-101/capture/out/11-inspect-evidence-bundle-O1.json
lines: 1-6
lang: json
note: Eight records and zero unknown revisions, because no unknown was recorded before the export.
---
{
  "kind": "evidence-bundle-summary",
  "filters": {},
  "total_retained_records": 8,
  "matching_records": 8,
  "unknown_revisions": 0,
the-assembly-facet.txt
title: the assembly facet of the same dossier
source: manuals/reverse-engineering-101/capture/out/10-mcp-09-analyze-function-percent-change-O1.json
lines: 1017-1024
lang: json
note: Six instructions. Count the ones that transfer control to another function.
---
          "assembly": [
            "0x100000500: cbz w0, 0x100000514",
            "0x100000504: sub w8, w1, w0",
            "0x100000508: mov w9, #0x64",
            "0x10000050c: mul w8, w8, w9",
            "0x100000510: sdiv w0, w8, w0",
            "0x100000514: ret"
          ],
the-callees-line.txt
title: the callees facet of the _percent_change dossier
source: manuals/reverse-engineering-101/capture/out/10-mcp-09-analyze-function-percent-change-O1.json
lines: 1052-1053
lang: json
note: The array that the agent read as proof. The incoming references start on the next line.
---
          "callees": [],
          "incoming_references": [
the-coverage-block.txt
title: the relationship_coverage block at the end of the record
source: manuals/reverse-engineering-101/capture/out/10-mcp-09-analyze-function-percent-change-O1.json
lines: 1899-1905
lang: json
note: Read the status, then the diagnostic sentence that says what complete covers.
---
        "relationship_coverage": {
          "status": "complete",
          "diagnostics": [
            "Only resolved Ghidra call references are returned; unresolved computed or indirect calls remain unknown, while function classifications distinguish thunks and externals."
          ]
        },
        "locations": [],
the-limitations.txt
title: the ten limitations of the record
source: manuals/reverse-engineering-101/capture/out/10-mcp-09-analyze-function-percent-change-O1.json
lines: 1887-1897
lang: json
note: The seventh string names the flows that the callees facet cannot hold.
---
        "limitations": [
          "The session serves operations only after Ghidra reports default auto-analysis complete; incomplete analysis does not expose partial results.",
          "The imported Program and temporary project are ephemeral and deleted on close. Annotation operations edit session database metadata; original executable bytes are never written.",
          "Cancelling an active Ghidra request terminates its ephemeral database and discards session annotations. The selected target remains open; the next provider query imports the original artifact again.",
          "Default-space addresses use lowercase 0x-prefixed hexadecimal; other address spaces use <percent-encoded-space>:0x<hex>.",
          "References cover the complete Ghidra function-body AddressSet and exact entry. Dossier incoming edges omit sources owned by that function; procedure_references also retains those internal edges.",
          "The dossier combines Ghidra FunctionManager, Listing, ReferenceManager, BasicBlockModel, and decompiler observations; provider-specific pseudocode and assembly are not cross-provider text invariants.",
          "Resolved reference metadata identifies computed, indirect, external, call, jump, and data edges; unresolved targetless flows remain unknown, and function classifications distinguish thunks and externals.",
          "Synthetic Ghidra entry-point references without actionable memory sources are omitted.",
          "The Java bridge serializes one function request per Program and lets each decompilation run until it completes or the caller cancels.",
          "macOS sessions require a matching executable Ghidra native decompiler; REA checks for it but does not build native components or change Gatekeeper quarantine state."
unresolved-calls.txt
title: the unresolved_calls facet of the same dossier
source: manuals/reverse-engineering-101/capture/out/10-mcp-09-analyze-function-percent-change-O1.json
lines: 1244-1245
lang: json
note: Also empty. Read it together with the coverage block before you decide what empty means.
---
          "unresolved_calls": [],
          "referenced_strings": [],
value-flow-counts.txt
title: the _percent_change row of the bundle summary
source: manuals/reverse-engineering-101/capture/out/11-inspect-evidence-bundle-O1.json
lines: 237-255
lang: json
note: The value_flow object gives counts with a truncated flag, which the callees array does not.
---
      "operation": "analyze_function",
      "confidence": "observed",
      "authority": "shipped-artifact",
      "analysis_profile_digest": "3fc72c9b4b78498fb992b938f8f3389dc670244a293c1d40abf5e1d10162ed3b",
      "retention": "complete-record",
      "limitation_count": 10,
      "native_dossier": {
        "available": true,
        "procedure_address": "0x100000500",
        "procedure_name": "_percent_change",
        "value_flow": {
          "status": "observed",
          "truncated": false,
          "omitted_operations_lower_bound": 0,
          "known_omitted_inputs": 0,
          "known_omitted_edges": 0
        }
      }
    }

سؤال‌ها

  1. آرایه‌ی callees خالی است. دو وضعیت متفاوت در دنیای واقعی را نام ببرید که دقیقاً به تولید همین خط منجر می‌شوند.
  2. کدام فیلد در رکورد مشخص می‌کند که مجموعه‌ی callees تا چه حد کامل است، و مقدار آن چه مواردی را پوشش می‌دهد؟
  3. فهرست محدودیت‌ها طولانی است. کدام مورد، آرایه‌ی callees را مقید (qualify) می‌کند، و این موضوع چگونه جمله‌ی داخل گزارش را تغییر می‌دهد؟
  4. خلاصه‌ی بسته برای جریان مقدار (value flow) تعداد را گزارش می‌کند. چرا rea در آنجا پای یک عدد صفر می‌ایستد، اما در پرونده پای خالی بودن آرایه نمی‌ایستد؟
  5. چه شاهدی در همین رکورد مشخص می‌کند که آیا تابع فراخوانی انجام می‌دهد یا خیر؟ جمله‌ای را بنویسید که گزارش باید به جای جمله‌ی فعلی داشته باشد.
  6. اگر هیچ جنبه‌ای (facet) تکلیف مسئله را روشن نمی‌کرد، چه چیزی را ثبت می‌کردید، و چه چیزی پرونده‌ی آن را می‌بست؟

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

راه‌حل گام‌به‌گام
  1. آرایه را از ادعا جدا کنید. خالی بودن آرایه‌ی callees می‌گوید ارائه‌دهنده هیچ ارجاع فراخوانیِ برطرف‌شده‌ای (resolved call reference) برنگردانده است. این آرایه نمی‌گوید که هیچ فراخوانی‌ای وجود ندارد. دو وضعیتی که به تولید همین خط منجر می‌شوند عبارت‌اند از: تابعی بدون هیچ فراخوانی، و تابعی که Ghidra نتوانسته مقصد فراخوانی‌های آن را مشخص و برطرف کند. ایجنت بدون بررسی بیشتر، یکی از این دو وضعیت را انتخاب کرده است.
  2. لیست خالیِ دوم را بخوانید. unresolved_calls نیز خالی است. این موضوع یک حالت را حذف می‌کند: Ghidra هیچ محل فراخوانی‌ای با مقصد نامشخص ندیده است. اما این مورد، جریان‌های محاسبه‌شده یا غیرمستقیمی را که اصلاً به ارجاع تبدیل نشده‌اند، نفی نمی‌کند.
  3. بخش پوشش را بخوانید. مقدار relationship_coverage.status برابر complete است، و پیام تشخیصی آن می‌گوید فقط ارجاعات فراخوانیِ حل‌شده‌ی Ghidra برگردانده شده‌اند و فراخوانی‌های محاسبه‌شده یا غیرمستقیمِ برطرف‌نشده، همچنان نامشخص می‌مانند. کلمه‌ی Complete به این معنی است که rea کل مجموعه‌ی برطرف‌شده را بدون محدودیت در خواندن برگردانده است. این یک ادعا درباره‌ی میزان خواندنِ ارائه‌دهنده است، نه درباره‌ی رفتار برنامه در زمان اجرا.
  4. محدودیتِ مرتبط را پیدا کنید. هفتمین رشته از ده رشته‌ی موجود می‌گوید متادیتای ارجاعات برطرف‌شده، یال‌هایی را مشخص می‌کند که Ghidra یافته است، و جریان‌های حل‌نشده‌ی بدون مقصد همچنان نامشخص باقی می‌مانند. خودِ رکورد به شما می‌گوید که آرایه‌های خالی‌اش را چطور بخوانید. قاعده‌ی مستندات هم همین است: نبودِ پوشش به معنای ناشناخته بودن است، نه وجود نداشتن.
  5. آن را با شمارشی که حامل اظهارنظر صریح است مقایسه کنید. خلاصه‌ی بسته شیء value_flow را برای همین رکورد نشان می‌دهد: مقدار truncated برابر false است و عملیات، ورودی‌ها و یال‌های نادیده‌گرفته‌شده همگی 0 هستند. این صفرها همراه با پرچمی آمده‌اند که می‌گوید هیچ‌چیز کوتاه (truncate) نشده است. آرایه‌ی callees چنین پرچمی ندارد. یک عدد صفر به همراه اعلام وضعیت کوتاه‌سازی (truncation)، یک شمارش قطعی است. اما یک لیست خالی بدون چنین اعلامی، صرفاً یک مشاهده (observation) است مبنی بر این که چیزی دیده نشده است.
  6. شمارنده‌های ناشناخته‌ها را بخوانید. در هدِ خلاصه آمده است که مقدار unknown_revisions برابر 0 است. این عدد یعنی هنگام خروجی گرفتن از بسته، هیچ مجهولی ثبت نشده بود. معنایش این نیست که فرایند بررسی هیچ سؤال بی‌پاسخی ندارد.
  7. از جنبه‌ی مشاهده‌شده استفاده کنید. جنبه‌ی اسمبلی (assembly facet) شامل شش دستورالعمل است: یک مقایسه و انشعاب در صورت صفر بودن (compare and branch on zero)، یک تفریق، یک جابه‌جایی مقدار ثابت، یک ضرب، یک تقسیم علامت‌دار و یک بازگشت. هیچ‌کدام از آن‌ها کنترل را به تابع دیگری منتقل نمی‌کنند. این اسمبلی همان متن فهرستی (Listing text) است که Ghidra مشاهده کرده و دقیقاً همان شاهدی است که ادعای برگ بودنِ تابع به آن نیاز دارد. آرایه‌ی callees خط اشتباهی برای استناد به یک جمله‌ی درست بود.
نتیجه

ادعای مطرح‌شده در گزارش درست بود، اما شواهدِ زیربنای آن اشتباه بود. جمله‌ی اصلاح‌شده به این صورت است: «کد اسمبلی _percent_change دارای شش دستورالعمل و فاقد دستور فراخوانی است؛ پرونده هیچ callee برطرف‌شده‌ای را با پوشش کامل روی ارجاعات برطرف‌شده گزارش نمی‌کند، و رکورد تصریح می‌کند که جریان‌های حل‌نشده و بدون مقصد، ناشناخته باقی می‌مانند.» گزارش به جنبه‌ی اسمبلی، بخش پوشش و محدودیت‌ها استناد می‌کند و آرایه‌ی callees را فقط به‌عنوان یک مشاهده‌ی ثانویه نقل می‌کند.

تیم همچنین نحوه‌ی نوشتن ایجنت را تغییر می‌دهد. اکنون قاعده‌ای در دستورالعمل‌های آن وجود دارد که می‌گوید یک لیست خالی همیشه به‌صورت «موردی مشاهده نشد» به همراه وضعیت پوشش در کنار آن گزارش شود، و هرگز از کلمه‌ی مطلق «هیچ» استفاده نشود. هرگاه هیچ جنبه‌ی مشاهده‌شده‌ای پاسخ قطعی به یک سؤال ندهد، ایجنت تابع record_unknown را با خود سؤال، مرجعی که می‌تواند پرونده‌ی آن را ببندد و یک آزمون ارزیابی (probe) پیشنهادی صدا می‌زند. برای سؤالی از جنس فراخوانی، این به معنای مرجعیت shipped-artifact و سطح اطمینان observed خواهد بود که از کد اسمبلی یا ثبت فرایند (process capture) به دست می‌آید؛ درست همان‌طور که مجهولاتِ ایجادشده توسط compare_functions پیش از این مطالبه می‌کردند.

مسیرهای اشتباه رایج
  • «آرایه‌ی callees خالی است و پوشش کامل است، بنابراین اثبات می‌شود که تابع اصلاً هیچ‌چیز را صدا نمی‌زند.» کلمه‌ی Complete ارجاعات برطرف‌شده‌ای را پوشش می‌دهد که Ghidra برگردانده است. محدودیت‌های خودِ رکورد می‌گویند که جریان‌های حل‌نشده‌ی بدون مقصد، ناشناخته باقی می‌مانند.
  • «یک مجهول باقی‌مانده ثبت کنید و گزارش را با سؤال باز تحویل دهید.» در همان رکورد، یک جنبه‌ی مشاهده‌شده وجود دارد که پاسخ سؤال را می‌دهد. پیش از ثبت یک مجهول، تمام جنبه‌ها را بررسی کنید.
  • «خلاصه‌ی بسته می‌گوید صفر مجهول وجود دارد، پس هیچ سؤال بازی وجود ندارد.» این شمارنده مواردی را گزارش می‌دهد که ثبت شده‌اند؛ نمی‌تواند سؤالاتی را بشمارد که هنوز هیچ‌کس آن‌ها را ننوشته است.
  • «به شبه‌کد اعتماد کنید؛ آن هم هیچ فراخوانی تابعی را نشان نمی‌دهد.» شبه‌کد در واقع خوانش دیکامپایلر با تایپ‌هایی با درجه‌ی اطمینان پایین است، همان‌طور که مستندات این تابع نیز این موضوع را نشان می‌دهد. به دستورالعمل‌ها استناد کنید، نه به خوانش دیکامپایلر از آن‌ها.
درس کلی

یک لیست در نتیجه‌ی ابزار، ادعایی درباره‌ی دیده‌های آن ابزار است، نه درباره‌ی آنچه واقعاً وجود دارد. پیش از اینکه یک لیست خالی را به «هیچ» تبدیل کنید، فیلدی را بیابید که میزان پوشش آن لیست را مشخص می‌کند و محدودیتی را پیدا کنید که آن را مقید می‌سازد؛ همچنین شمارشی را که همراه با پرچم کوتاه‌سازی است، به آرایه‌ای که هیچ پرچمی ندارد ترجیح دهید. وقتی یک جنبه حاصل تفسیر است، به دنبال جنبه‌ای بگردید که مشاهده‌ی مستقیم همان موضوع باشد و به آن استناد کنید. اگر هیچ مشاهده‌ای پاسخ قطعی نداد، سؤال را همراه با شواهدی که می‌تواند پرونده‌ی آن را ببندد ثبت کنید.

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

صفحه‌ی پوشش در مهندسی معکوس 101 همین خطوط را بررسی می‌کند، صفحه‌ی پرونده شانزده جنبه را فهرست کرده و شش دستورالعمل را نشان می‌دهد، درس حالت‌های شکست (failure modes) ادعایی را که فراتر از شواهدش می‌رود توهم ایجنت می‌نامد، و درس 35 دفتر مجهولات را در Python می‌سازد.