datadog static analyzer

DataDog محلل ثابت

نصيحة

تدعم DataDog مشاريع مفتوحة المصدر. تعرف على المزيد على DataDog لمشاريع مفتوحة المصدر.

DataDog-Static-Analyzer هو محرك المحلل الثابت لتحليل DataDog الثابت.

كيفية استخدام أداة التحليل الثابت DataDog

بداية سريعة

1. قم بتنزيل الثنائي من الإصدارات
2. قم بتشغيل المحلل على مستودعك (كما هو موضح أدناه)
3. سيتم تشغيل المحلل مع القواعد الافتراضية المتاحة لغات الدعم

datadog-static-analyzer --directory /path/to/directory --output report.csv --format csv

باستخدام Docker

docker run -it --rm -v /path/to/directory:/data ghcr.io/datadog/datadog-static-analyzer:latest --directory /data --output /data/report.csv --format csv

لمزيد من المعلومات حول حاوية Docker ، راجع الوثائق هنا.

إذا واجهت مشكلة ، فاقرأ الأسئلة التي يتم طرحها بشكل متكرر أولاً ، فقد تحتوي على حل لمشكلتك.

استخدام متقدم

يمكنك اختيار القواعد التي يجب استخدامها لمسح مستودعك عن طريق إنشاء ملف static-analysis.datadog.yml .

أولاً ، تأكد من اتباع الوثائق وإنشاء ملف static-analysis.datadog.yml .

يمكن العثور على جميع القواعد على وثائق DataDog. قد يحتوي static-analysis.datadog.yml

مثال على ملف yaml

 schema-version : v1
rulesets :
  - python-code-style
  - python-best-practices
  - python-inclusive
ignore :
  - tests

تكامل CI/CD

يمكنك استخدامه في خط أنابيب CI/CD باستخدام تكاملنا:

• عمل جيثب
• circleci orb

إذا كنت تستخدمه في خط أنابيب CI/CD الخاص بك ، فيمكنك دمج الأداة مباشرة: راجع وثائق DataDog لمزيد من المعلومات.

منتجات intellij jetbrains

يتيح لك ملحق DataDog Intellij استخدام المحلل الثابت مباشرة من جميع منتجات JetBrains. قم بإنشاء ملف static-analysis.datadog.yml ، وقم بتنزيل الامتداد ويمكنك البدء في استخدامه. يمكنك رؤية أدناه مثال على اقتراح لإضافة مهلة عند جلب البيانات باستخدام Python مع وحدة الطلبات.

مقابل الكود

يتيح لك ملحق DataDog vs Code استخدام المحلل الثابت مباشرة من VS Code. قم بإنشاء ملف static-analysis.datadog.yml ، وقم بتنزيل الامتداد ويمكنك البدء في استخدامه.

قائمة قواعد

عندما تكون على متن منتج DataDog ، يمكنك تحديد مجموعة القواعد التي تريدها/تحتاجها. إذا كنت لا تستخدم DataDog مباشرة ، فهناك قائمة بمجموعات القواعد المستخدمة الشائعة المتوفرة في منتج تحليل DataDog الثابت لكل لغة.

القائمة الكاملة متوفرة في وثائقنا.

قائمة القواعد متوفرة في قواعد sets.md.

تحميل

قم بتنزيل أحدث إصدار لنظامك والهندسة المعمارية من صفحة الإصدار.

للحصول على المحلل الثابت عبر شل:

curl -L -O https://www.github.com/DataDog/datadog-static-analyzer/releases/latest/download/datadog-static-analyzer- < target > .zip

مثال للحصول على x86_64 ثنائي لـ Linux:

curl -L -O https://www.github.com/DataDog/datadog-static-analyzer/releases/latest/download/datadog-static-analyzer-x86_64-unknown-linux-gnu.zip

الاستخدام

datadog-static-analyzer -i < directory > -o < output-file >

لكي تعمل الأداة ، يجب أن يكون لديك ملف <directory>/static-analysis.datadog.yml الذي يحدد تكوين المحلل. سيشير هذا الملف إلى القواعد التي ستستخدمها في مشروعك.

يمكنك الحصول على مزيد من المعلومات حول التكوين على وثائق DataDog.

مستخدمي Mac OS X

لا يمكن تنفيذ الثنائي كما هو. تحتاج إلى الإبلاغ عن الثنائي باعتباره آمنًا لتنفيذه باستخدام الأمر التالي.

xattr -dr com.apple.quarantine datadog-static-analyzer

خيارات

• -f أو --format : تنسيق ملف الإخراج. -f sarif ينتج ملفًا متوافقًا مع SARIF
• -r أو --rules : يوفر ملفًا يحتوي على جميع القواعد (يمكن وضع القواعد في ملف باستخدام datadog-export-rulesets )
• -c أو --cpus : عدد النوى المستخدمة للتحليل (عد حوالي 1 جيجابايت من استخدام ذاكرة الوصول العشوائي لكل نواة)
• -o أو --output : ملف الإخراج
• -p أو --ignore-path : المسار (نمط/غلوب) للتجاهل ؛ يقبل المتعددة
• -x أو --performance-statistics : إظهار إحصائيات الأداء للمحلل
• -g أو- --add-git-info : أضف معلومات متعلقة بـ GIT (SHA ، إلخ) في تقرير SARIF عند استخدام -f sarif
• --fail-on-any-violation : اجعل البرنامج يخرج من رمز خروج غير صفري إذا كان هناك انتهاك واحد على الأقل لشدة معينة.
• -w أو- --diff-aware : تمكين المسح الوعائي في الاختلاف (انظر الملاحظات المخصصة أدناه)

إعدادات

اضبط المتغيرات التالية لتكوين تحليل:

• DD_SITE : معلمة موقع DATADOG المستخدمة لجلب القواعد (قائمة العرض) (الافتراضي: datadoghq.com )

ملف التكوين

يمكن تكوين المحلل الثابت باستخدام ملف static-analysis.datadog.yml . هذا ملف yaml مع الإدخالات التالية:

• rulesets : (مطلوب) قائمة مع جميع القواعد المراد استخدامها لهذا المستودع (انظر وثائق DataDog للحصول على قائمة كاملة). يجب أن تكون عناصر هذه القائمة سلاسل أو خرائط تحتوي على تكوين لمجموعة القواعد (الموضحة أدناه.)
• ignore : (اختياري) قائمة بادئات المسار وأنماط الكرة الأرضية لتجاهلها. لن يتم تحليل الملف الذي يطابق أي من إدخالاته.
• only : (اختياري) قائمة بادئات المسار وأنماط الكرة الأرضية لتحليلها. إذا تم تحديدها only ، فسيتم تحليل الملفات التي تتطابق مع أحد إدخالاتها فقط.
• ignore-gitignore : (اختياري) افتراضيًا ، تتم إضافة أي إدخالات موجودة في ملف .gitignore إلى قائمة ignore . إذا كان خيار ignore-gitignore صحيحًا ، فلا تتم قراءة ملف .gitignore .
• max-file-size-kb : سيتم تجاهل ملفات (اختيارية) أكبر من هذا الحجم ، بالكيلوبايت ،. القيمة الافتراضية 200 كيلو بايت.
• schema-version : (اختياري) إصدار المخطط الذي يتبعه ملف التكوين هذا. في حالة تحديد ، يجب أن يكون v1 .

يجب أن تكون إدخالات قائمة rulesets سلاسل تحتوي على اسم مجموعة القواعد لتمكينها ، أو خريطة تحتوي على التكوين لمجموعة القواعد. تحتوي هذه الخريطة على الحقول التالية:

• يعطي الحقل الأول (المطلوب) اسم مجموعة القواعد كمفتاحها ، بقيمة فارغة.
• ignore : (اختياري) قائمة ببادئ بادئات المسار وأنماط الكرة الأرضية لتجاهلها لهذه القواعد . لن يتم تقييم القواعد في هذه القواعد لأي ملفات تتطابق مع أي من الإدخالات في قائمة ignore .
• only : (اختياري) قائمة ببادئ بادئات المسار وأنماط الكرة الأرضية لتحليلها لهذه القواعد . إذا تم تحديدها only ، فسيتم تقييم القواعد في هذه القواعد فقط للملفات التي تتطابق مع أحد الإدخالات.
• rules : (اختياري) خريطة تكوينات القاعدة. لا يزال يتم تقييم القواعد غير المحددة في هذه الخريطة ، ولكن مع التكوين الافتراضي.

تستخدم الخريطة الموجودة في حقل rules اسم القاعدة كمفتاحها ، والقيم هي خرائط مع الحقول التالية:

• ignore (اختياري) قائمة بادئات المسار وأنماط الكرة الأرضية لتجاهلها لهذه القاعدة . لن يتم تقييم هذه القاعدة لأي ملفات تتطابق مع أي من الإدخالات في قائمة ignore .
• only : (اختياري) قائمة بادئات المسار وأنماط الكرة الأرضية لتحليلها لهذه القاعدة . إذا تم تحديدها only ، فسيتم تقييم هذه القاعدة فقط للملفات التي تتطابق مع أحد الإدخالات.
• severity : (اختياري) إذا تم توفيرها ، تجاوز شدة الانتهاكات التي تنتجها هذه القاعدة. الشدة الصالحة هي ERROR WARNING NOTICE NONE .
• category : (اختياري) إذا تم توفيرها ، تجاوز فئة هذه القاعدة. الفئات الصالحة هي BEST_PRACTICES و CODE_STYLE و ERROR_PRONE و PERFORMANCE و SECURITY .
• arguments : (اختياري) خريطة القيم لحجج القاعدة.

تستخدم الخريطة الموجودة في حقل arguments اسم الوسيطة كمفتاحها ، والقيم هي إما سلاسل أو خرائط:

• إذا كنت ترغب في تعيين قيمة للمستودع بأكمله ، فيمكنك تحديدها كسلسلة ؛
• إذا كنت ترغب في تعيين قيم مختلفة لقطاعات فرعية مختلفة في المستودع ، فيمكنك تحديدها كخريطة من بادئة من الشجرة الفرعية إلى القيمة التي ستحصل عليها الوسيطة ضمن تلك الشجرة الفرعية. انظر المثال لمزيد من التفاصيل.

مثال مشروح لملف التكوين:

 # This is a "v1" configuration file.
schema-version : v1
# The list of rulesets to enable for this repository.
rulesets :
  # Enable the `python-inclusive` ruleset with the default configuration.
  - python-inclusive
  # Enable the `python-best-practices` ruleset with a custom configuration.
  - python-best-practices :
    # Do not apply any of the rules in this ruleset to files that match `src/**/*.generated.py`.
    ignore :
      - src/**/*.generated.py
    rules :
      # Special configuration for the `python-best-practices/no-generic-exception` rule.
      no-generic-exception :
        # Treat violations of this rule as errors (normally "notice").
        severity : ERROR
        # Classify violations of this rule under the "code style" category.
        category : CODE_STYLE
        # Only apply this rule to files under the `src/new-code` subtree.
        only :
          - src/new-code
  # Enable the `python-code-style ruleset` with a custom configuration.
  - python-code-style :
    rules :
      max-function-lines :
        # Set arguments for the `python-code-style/max-function-lines` rule.
        arguments :
          # Set the `max-lines` argument to 150 in the whole repository.
          max-lines : 150
      max-class-lines :
        # Set arguments for the `python-code-style/max-class-lines` rule.
        arguments :
          # Set different values for the `max-lines` argument in different subtrees.
          max-lines :
            # Set the `max-lines` argument to 100 by default
            / : 100
            # Set the `max-lines` argument to 75 under the `src/new-code` subtree.
            src/new-code : 75
# Analyze only files in the `src` and `imported` subtrees.
only :
  - src
  - imported
# Do not analyze any files in the `src/tests` subtree.
ignore :
  - src/tests
# Do not add the content of the `.gitignore` file to the `ignore` list.
ignore-gitignore : true
# Do not analyze files larger than 100 kB.
max-file-size-kb : 100

مثال آخر يوضح كل خيار يتم استخدامه:

 schema-version : v1
rulesets :
  - python-best-practices
  - python-code-style :
    ignore :
      - src/generated
      - src/**/*_test.py
    only :
      - src
      - imported/**/new/**
    rules :
      max-function-lines :
        severity : WARNING
        category : PERFORMANCE
        ignore :
          - src/new-code
          - src/new/*.gen.py
        only :
          - src/new
          - src/**/new-code/**
        arguments :
          max-lines : 150
          min-lines :
            / : 10
            src/new-code : 0
ignore :
  - dist
  - lib/**/*.py
only :
  - src
  - imported/**/*.py
ignore-gitignore : true
max-file-size-kb : 256 

مخطط ملف التكوين

هناك تعريف مخطط JSON للتحليل static-analysis.datadog.yml في دليل schema الفرعي.

يمكنك استخدامه للتحقق من بناء جملة ملف التكوين الخاص بك:

1. تثبيت https://www.npmjs.com/package/pajv ( npm install -g pajv )
2. تنفيذ pajv validate -s schema/schema.json -d path/to/your/static-analysis.datadog.yml

هناك بعض الأمثلة على ملفات التكوين الصالحة وغير الصالحة في schema/examples/valid schema/examples/invalid ، على التوالي. إذا قمت بإجراء تغييرات على مخطط JSON ، فيمكنك اختبارها مقابل أمثلةنا:

1. تثبيت https://www.npmjs.com/package/pajv ( npm install -g pajv )
2. تنفيذ make -C schema

الفرق الوعرة المسح الضوئي

يعد Diff-Awarning Scanning ميزة للمحلول الثابت لمسح الملفات التي تم تغييرها مؤخرًا. تستخدم فحوصات Diff-Aware النتائج السابقة وأضف فقط الانتهاكات من الملفات التي تم تغييرها.

من أجل استخدام المسح الضوئي على دراية Diff ، يجب أن تكون عميل DataDog.

لاستخدام المسح الضوئي الوعرة:

1. قم بإعداد متغير بيئة DD_SITE وفقًا لمركز DataDog Datacenter الذي تستخدمه (https://docs.datadoghq.com/getting_started/site/)
2. قم بإعداد متغيرات البيئة DD_APP_KEY و DD_API_KEY مع تطبيق DATADOG ومفاتيح API
3. قم بتشغيل المحلل الثابت مع الخيار --diff-aware

عند استخدام Diff-Lawner ، سيتصل المحلل الثابت بـ DataDog ويحاول تحليلًا سابقًا لاستخدامه. في حالة حدوث أي مشكلة ولا يمكن استخدام diff-exned ، سيقوم المحلل بإخراج خطأ مثل تلك أدناه ويستمر مع فحص كامل.

يمكنك استخدام الخيار --debug true لاستكشاف الأخطاء وإصلاحها أكثر إذا لزم الأمر.

$ datadog-static-analyzer --directory /path/to/code --output output.sarif --format sarif --diff-aware

...
diff aware not enabled (error when receiving diff-aware data from Datadog with config hash 16163d87d4a1922ab89ec891159446d1ce0fb47f9c1469448bb331b72d19f55c, sha 5509900dc490cedbe2bb64afaf43478e24ad144b), proceeding with full scan.
...

أدوات أخرى

datadog-rouulesets

قواعد التصدير من API إلى ملف

cargo run --bin datadog-export-rulesets -- -r < ruleset > -o < file-to-export > 

أكثر

• كيف يعمل المسح الفكري
• الإبلاغ عن قضية
• owasp القياس

يساهم

راجع الملف المساهمة. md لمزيد من المعلومات وكذلك التطوير.

مزيد من المعلومات

• DataDog تحليل ثابت