
trailmark v0.5.0
بناء والاستعلام عن تمثيل قاعدة بيانات رسومية لشفرة المصدر
Trailmark
يقوم Trailmark بتحليل الشيفرة المصدرية إلى رسم بياني من الدوال والأنواع والاستدعاءات والعلاقات الأخرى، ثم يتيح لك طرح أسئلة بنيوية حوله:
- ما نقاط الدخول التي يمكنها الوصول إلى هذه الدالة، وعلى أي مسارات استدعاء؟
- ما الذي تغيّر في سطح الهجوم بين إيداعين (commit)؟
- ما الدوال التي تكتب في متغير التخزين هذا في Solidity؟
- أين توقف تحليل الاستدعاءات، بحيث تكون نتائج إمكانية الوصول غير مكتملة؟
يحلّل اللغات المدعومة عبر tree-sitter، ويخزّن الرسم البياني في rustworkx، ويعرضه عبر أداة سطر أوامر وواجهة برمجة تطبيقات Python. صُمّم Trailmark لمراجعة الأمان: تسجّل كل حافة ما إذا كانت قد جاءت مباشرة من الصياغة النحوية أو من استدلال استكشافي، وتبقى الاستدعاءات التي تعذّر تحليلها في الرسم البياني.
الرؤية طويلة المدى هي دمج هذا الرسم البياني مع اختبار الطفرات (mutation testing) والتشويش الموجّه بالتغطية (coverage-guided fuzzing) لتحديد الفجوات بين الافتراضات وتغطية الاختبارات التي يمكن الوصول إليها من مدخلات المستخدم.
الميزات
- مخططات الشيفرة. الدوال والطرق والأصناف والبنى والسمات والعقود والوحدات، مترابطة عبر الاستدعاءات والوراثة والاحتواء واستخدام الأنواع. يدمج
--language autoكل لغة مدعومة في شجرة واحدة ضمن مخطط واحد. - سطح الهجوم. كشف نقاط الدخول الواعي بإطار العمل (Flask، FastAPI، Spring، ASP.NET Core، actix-web، NestJS، تسجيلات Elysia HTTP، ظهور Solidity، وغيرها)، كل منها موسوم بمستوى ثقة وقيمة أصل. تجاوز الكشف أو وسّعه باستخدام
.trailmark/entrypoints.toml. - أدلة نقاط الدخول. افحص المراجع القابلة للاستدعاء والتعريفية، وأجسام الملفات القابلة للتنفيذ، والمرشحين غير المحلولين مع مصدر المنشأ. تبقى المراجع منفصلة عن التنفيذ. اختر جذور مصدر إضافية باستثناءات صريحة.
- قابلية الوصول. المستدعون والمستدعَون المباشرون، والشرائح العابرة، ومسارات الاستدعاء المحدودة من نقاط الدخول إلى هدف ما.
- الفروقات البنيوية. قارن بين مجلدين أو مرجعي git وأبلغ عن التعريفات المضافة أو المحذوفة، وتغييرات التوقيع والنوع، وتغييرات ثقة حواف الاستدعاء، ونقاط الدخول.
- المخططات. مخططات استدعاء Mermaid، والتسلسلات الهرمية للأصناف، وتبعيات الوحدات، وعروض الاحتواء، وخرائط التعقيد، وتدفقات نقاط الدخول إلى الهدف.
- النتائج على المخطط. استورد نتائج SARIF وweAudit، وأرفق تعليقاتك التوضيحية الخاصة، وشغّل تمريرات التحليل المسبق (نطاق التأثير، حدود الامتيازات، التلوث الخشن) التي تخزّن نتائجها كتعليقات توضيحية ومخططات فرعية مسماة.
- الفجوات المرئية. تصبح الاستدعاءات التي يتعذر حلها عُقدًا وكيلة بدلًا من أن تختفي، ويحصيها
trailmark analyze --resolution. - أدلة الاستثناءات. افحص عبارات throw وrethrow والمعالجات وصيغة التنظيف الموجودة في المصدر باستخدام
exception_events()؛ تبقى المعاملات المطروحة المجهولة مرئية. راجع نموذج المخطط لتغطية الواجهات الأمامية وحدود أدلة هذه الصيغة. - روابط لا يستطيع Trailmark رؤيتها. صرّح بحواف RPC وFFI والعمليات الفرعية في
.trailmark/links.toml، أو استورد مخطط استدعاء أنتجته أداة تحليل ثنائي. - أدلة الثنائيات المترجمة. افحص صراحةً صور ELF وMach-O وPE المرتبطة، واربط دوال المصدر وأسطره بالنطاقات المترجمة، واستعد استدعاءات الثنائي ونقل الذيول المستنتج، واستعلم عن تفكيك محدود عبر 15 حالة معمارية/نمط. يشمل تعيينات الشيفرة المجردة، والشرائح الشاملة، والرفاق المحليين للتصحيح المُتحقَّق منهم، والأسماء المستعارة المطوية، ومدخلات الاستيراد المسماة. راجع أدلة الثنائيات للحزمة الاختيارية
trailmark[binary]ومتطلبات أدوات المضيف. - الوصول إلى تخزين Solidity. حواف
readsوwritesبين الدوال ومتغيرات حالة العقد التي تلمسها.
التثبيت
uv tool install trailmark # the CLI
uv add trailmark # the library, in a uv-managed project
يتطلب Python ≥ 3.12. تختبر CI Python من 3.12 حتى 3.15.
مع Nix، يشغّل nix run github:trailofbits/trailmark واجهة سطر الأوامر مباشرةً.
يتتبّع هذا الملف التمهيدي والأدلة الفرع main. تسرد
سجل التغييرات
ما يتضمنه كل إصدار منشور، وتذكر أدلة واجهة سطر الأوامر وواجهة Python البرمجية
الإصدار الذي أضاف كل ميزة أحدث.
تُنزَّل معظم القواعد النحوية وتُخزَّن مؤقتًا عند أول استخدام. تُجمَّع القواعد النحوية المضمّنة عند أول استخدام، وهو ما يتطلب مترجم C. راجع التثبيت للأجهزة غير المتصلة بالإنترنت، والوكلاء الذين يفحصون TLS، والبناء من نسخة مستخرجة.
لمدمجي المهارات: راجع توافق v0.7 للتحقق من المخطط والهوية والحالة وإمكانية الوصول.
البدء السريع
# Node and edge counts for a Python project (Python is the default language)
trailmark analyze --summary path/to/project
# The same summary as JSON, including source-file counts per language (v0.7+)
trailmark analyze --summary --json --language auto path/to/project
# Full JSON graph of every supported language in the tree
trailmark analyze --language auto path/to/project > graph.json
# Detected entrypoints with trust level and asset value
trailmark entrypoints --language auto path/to/project
# How the attack surface changed between two git refs
trailmark diff --repo . main HEAD
# Mermaid call graph around one function
trailmark diagram -t path/to/project -T call-graph -f handle_request
# How many call sites could not be resolved, grouped by callee name
trailmark analyze --language rust --resolution path/to/project
يَرفُض تحليل الدليل الجذور المفقودة وملفات المصدر التي لا تُطابق أي شيء. يتضمّن الملخّص اللغات المختارة وأعداد الملفات التي تم فحصها؛ استخدم --allow-empty لإدخال فارغ مقصود.
يتضمّن Graph JSON إصدار Trailmark المُصدِّر وإصدار مخطط التصدير (v0.7+)؛ قارن اللقطات المبنية باستخدام إصدار Trailmark واللغات نفسها.
الأسئلة نفسها من Python:
from trailmark.query.api import QueryEngine
engine = QueryEngine.from_directory("path/to/project", language="auto")
engine.attack_surface() # entrypoints and their trust levels
engine.callers_of("verify_signature") # direct callers
engine.ancestors_of("verify_signature") # everything that can reach it
engine.entrypoint_paths_to("verify_signature")
engine.complexity_hotspots(10) # cyclomatic complexity >= 10
الأسماء يمكن أن تكون مجردة (verify_signature)، أو مؤهلة (Auth.verify)، أو معرّفات عقد كاملة (auth:Auth.verify). نتائج الاستعلام عبارة عن قواميس وقوائم عادية تُسلسَل مباشرةً إلى JSON.
كيف يعمل
flowchart LR
A["Source files"] --> B["tree-sitter parsers"]
B --> C["CodeGraph"]
C --> D["GraphStore (rustworkx)"]
D --> E["QueryEngine"]
E --> F["CLI / Python API"]
classDef src fill:#007bff26,stroke:#007bff,color:#007bff
classDef parse fill:#28a74526,stroke:#28a745,color:#28a745
classDef data fill:#6f42c126,stroke:#6f42c1,color:#6f42c1
classDef query fill:#ffc10726,stroke:#e6a817,color:#e6a817
class A src
class B parse
class C,D data
class E,F query