Trailmark

قم بتحليل شيفرة المصدر إلى رسوم بيانية قابلة للاستعلام عن الوظائف والكلاسات والاستدعاءات والتعليقات الدلالية لتحليل الأمان.

يستخدم Trailmark tree-sitter لتحليل AST غير مقيد بلغة معينة و rustworkx لاجتياز الرسوم البيانية عالي الأداء. الرؤية طويلة المدى هي دمج هذا الرسم البياني مع اختبار التحوير والتوجيه بالتغطية للعثور على الفجوات بين الافتراضات وتغطية الاختبار التي يمكن الوصول إليها من مدخلات المستخدم.

كيف يعمل

يعمل Trailmark في ثلاث مراحل: parse و index و query.```mermaid flowchart TD A["Source Files"] --> B["tree-sitter Parser"] B --> C["CodeGraph (nodes + edges)"] C --> D["rustworkx GraphStore"] D --> E["QueryEngine"] E --> F["JSON / Summary / Hotspots"]

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

### 1. التحليل

يقوم المحلل اللغوي المخصص بلغة معينة بجولة في الدليل، ويحلل كل ملف إلى شجرة AST من نوع tree-sitter، ويستخرج:

- **العُقد** &mdash; الدوال، الطرق، الصنوف، الهياكل، الواجهات، السمات، التعدادات، الوحدات، النطاقات
- **الحواف** &mdash; الاستدعاءات، الوراثة، التنفيذ، الاحتواء، الاستيرادات
- **البيانات الوصفية** &mdash; التعليقات التوضيحية للنوع، التعقيد الدوري، الفروع، نصوص التوثيق، أنواع الاستثناءات

### اللغات المدعومة

| اللغة | الامتدادات | البنى الرئيسية |
| --- | --- | --- |
| Python | `.py` | الدوال، الصنوف، الطرق |
| JavaScript | `.js`, `.jsx`, `.mjs`, `.cjs` | الدوال، الصنوف، دوال السهم |
| TypeScript | `.ts`, `.tsx` | الدوال، الصنوف، الواجهات، التعدادات |
| PHP | `.php` | الدوال، الصنوف، الواجهات، السمات |
| Ruby | `.rb` | الطرق، الصنوف، الوحدات |
| C | `.c`, `.h` | الدوال، الهياكل، التعدادات |
| C++ | `.cpp`, `.hpp`, `.cc`, `.hh`, `.cxx`, `.hxx` | الدوال، الصنوف، الهياكل، النطاقات |
| C# | `.cs` | الطرق، الصنوف، الواجهات، الهياكل، التعدادات، النطاقات |
| Java | `.java` | الطرق، الصنوف، الواجهات، التعدادات |
| Go | `.go` | الدوال، الطرق، الهياكل، الواجهات |
| Rust | `.rs` | الدوال، الهياكل، السمات، التعدادات، كتل التنفيذ |
| Solidity | `.sol` | العقود، الواجهات، المكتبات، الدوال، المعدلات، الهياكل، التعدادات |
| Cairo | `.cairo` | الدوال، السمات، الهياكل، التعدادات، كتل التنفيذ، عقود StarkNet |
| Circom | `.circom` | القوالب، الدوال، الإشارات، المكونات |
| Haskell | `.hs` | الدوال، أنواع البيانات، صنوف الأنواع، المثيلات |
| Erlang | `.erl` | الدوال، السجلات، السلوكيات، الوحدات |
| Miden Assembly | `.masm` | الإجراءات، نقاط الدخول، الثوابت، الاستدعاءات |
| Swift | `.swift` | الدوال، الصنوف، الهياكل، التعدادات، البروتوكولات، الامتدادات |
| Objective-C | `.m`, `.mm`, `.h` | دوال C، الصنوف، الطرق (تسمية قائمة على المُحدد) |
| Kotlin | `.kt`, `.kts` | الدوال، الصنوف، الواجهات، صنوف البيانات، الكائنات، الطرق |
| Dart | `.dart` | الدوال، الصنوف، الصنوف المجردة، الطرق، المُنشئون |
| Move | `.move` | الوحدات، الدوال، الاستيرادات، الاستدعاءات المباشرة |
| Tact | `.tact` | العقود، الهياكل، المستقبلون، الدوال |
| Func | `.fc`, `.func` | الدوال، التضمينات، الاستدعاءات المباشرة |
| Sway | `.sw` | واجهات ABI، الهياكل، طرق التنفيذ، الدوال |
| Rego | `.rego` | الحزم، الاستيرادات، قواعد السياسة، استدعاءات القاعدة |
| Proto | `.proto` | الخدمات، استدعاءات الإجراءات عن بُعد (RPCs)، الرسائل، الحقول، التعدادات |
| Thrift | `.thrift` | الخدمات، الدوال، الهياكل، الحقول، التعدادات |
| GraphQL | `.graphql`, `.gql` | أنواع الكائنات، العمليات الجذرية، الحقول، التعدادات |
| SQL | `.sql` | المخططات، الجداول، العروض، الدوال، الإجراءات |```mermaid
flowchart TD
    subgraph "Per-File Parsing"
        F["Source file"] --> TS["tree-sitter AST"]
        TS --> EX["Extract nodes"]
        TS --> EC["Extract call edges"]
        TS --> EB["Count branches"]
        TS --> ET["Resolve types"]
    end

    EX --> CG["CodeGraph"]
    EC --> CG
    EB --> CG
    ET --> CG

    classDef src fill:#007bff26,stroke:#007bff,color:#007bff
    classDef parse fill:#28a74526,stroke:#28a745,color:#28a745
    classDef extract fill:#ffc10726,stroke:#e6a817,color:#e6a817
    classDef data fill:#6f42c126,stroke:#6f42c1,color:#6f42c1

    class F src
    class TS parse
    class EX,EC,EB,ET extract
    class CG data

تتبع معرفات العقد النمط module:function أو module:Class أو module:Class.method للبحث غير الملتبس. يقوم تحليل الدليل بحل استدعاءات عبر الملفات البسيطة عندما يوجد تعريف فريد؛ أما الاستدعاءات عبر الملفات الغامضة فتترك عند هدفها الأصلي بأفضل جهد وتُوسم بـ uncertain. توسم ثقة الحافة بأنها certain (استدعاءات مباشرة، self.method()) أو inferred (الوصول إلى السمات على كائنات غير self) أو uncertain (التوزيع الديناميكي أو الحل الغامض).

2. الفهرس

يقوم GraphStore بتحميل CodeGraph في PyDiGraph من rustworkx ويبني تعيينات ثنائية الاتجاه للمعرفات/الفهارس للتنقل السريع.

3. الاستعلام

يوفر QueryEngine واجهة برمجة تطبيقات عالية المستوى فوق الرسم البياني المفهرس:

Method	Description
`callers_of(name)`	المستدعون المباشرون للهدف المسمى
`callees_of(name)`	المستدعى المباشر من المصدر المسمى
`ancestors_of(name)`	كل دالة يمكنها الوصول إلى الهدف بشكل متعدي (شريحة لأعلى)
`reachable_from(name)`	كل دالة يمكن الوصول إليها بشكل متعدي من المصدر
`paths_between(src, dst)`	كل مسارات الاستدعاء البسيطة بين عقدتين
`connect_subgraphs(source, target)`	المسارات التي تربط بين رسمين بيانيين فرعيين مسمى
`entrypoint_paths_to(name)`	المسارات من أي نقطة دخول تم اكتشافها إلى الهدف
`attack_surface()`	نقاط الدخول الموسومة بمستوى الثقة وقيمة الأصول وسمات المحلل عند وجودها
`complexity_hotspots(n)`	الدوال التي يكون تعقيدها الدوري ≥ n
`functions_that_raise(exc)`	الدوال التي تتضمن قائمة الاستثناءات المكتشفة بواسطة المحلل `exc`
`generic_parameters(name)`	معلمات النوع العام المعلنة بواسطة عقدة
`type_references(name)`	مراجع النوع للمعاملات والإرجاع والاستثناءات والحدود العامة
`annotate(name, kind, description, source)`	إضافة تعليق دلالي إلى عقدة
`annotations_of(name, kind=None)`	الحصول على تعليقات لعقدة، مرشحة حسب النوع اختيارياً
`nodes_with_annotation(kind)`	كل عقدة موسومة بنوع التعليق المعطى
`clear_annotations(name, kind=None)`	إزالة التعليقات من عقدة
`diff_against(other)`	الفرق الهيكلي بين رسم هذا المحرك وآخر
`preanalysis()`	تشغيل تمريرات التحليل المسبق المضمنة وتخزين التعليقات/الرسومات الفرعية
`augment_sarif(path)`	دمج نتائج SARIF في الرسم البياني
`augment_weaudit(path)`	دمج نتائج weAudit في الرسم البياني
`augment_binary(path)`	دمج ملف JSON لتحليل ثنائي خارجي
`findings(kind=None)`	إرجاع العقد التي تحمل تعليقات من نوع النتائج
`subgraph(name)`	إرجاع العقد في رسم فرعي مسمى
`subgraph_edges(name)`	إرجاع الحواف المستحثة داخل رسم فرعي مسمى
`subgraph_names()`	سرد كل رسم فرعي مسمى موجود حالياً على الرسم البياني
`summary()`	عدد العقد، عدد الحواف، التبعيات
`to_json()`	تصدير كامل للرسم البياني

نموذج البيانات```mermaid

classDiagram class CodeGraph { language: str root_path: str nodes: dict[str, CodeUnit] edges: list[CodeEdge] annotations: dict[str, list[Annotation]] entrypoints: dict[str, EntrypointTag] dependencies: list[str] add_annotation(node_id, annotation) clear_annotations(node_id, kind=None) merge(other) }

trailmark

الأكثر شعبية

Trailmark

كيف يعمل

2. الفهرس

3. الاستعلام

نموذج البيانات```mermaid