Surfactant
Update for SecTor 2024
الوثائق
يمكن استخدام الفاعل بالسطح لجمع المعلومات من مجموعة من الملفات لإنشاء SBOM ، إلى جانب معالجة SBOMs وتحليل المعلومات الموجودة فيها. يقوم بسحب المعلومات من أنواع الملفات المعترف بها (مثل ملفات PE أو ELF أو MSI) الموجودة في بنية الدليل المقابلة لحزمة البرامج المستخرجة. بشكل افتراضي ، تكون المعلومات "على مستوى السطح" الوارد في الملفات التي لا تتطلب تشغيل الملفات أو فك الإلغاء.
لسهولة الاستخدام ، نوصي باستخدام PIPX لأنه يتعامل بشفافية لإنشاء واستخدام البيئات الافتراضية Python ، مما يساعد على تجنب تعارضات التبعية مع تطبيقات Python الأخرى المثبتة. تثبيت pipx باتباع تعليمات التثبيت الخاصة بهم.
pipx install (مع Python> = 3.8) pipx install surfactantملاحظة: يتطلب دعم ملف Mach-O تثبيت السطحي مع التبعيات الاختيارية
macho(مثلpipx install surfactant[macho]).
pipx inject surfactant . على سبيل المثال ، هذه هي الطريقة التي يمكن بها تثبيت البرنامج المساعد الغامض من مستودع GIT (يمكن أيضًا استخدام أسماء حزم PYPI أو أدلة المصدر المحلي أو ملفات العجلات). pipx inject surfactant git+https://github.com/LLNL/Surfactant#subdirectory=plugins/fuzzyhashesإذا كانت الإدارة المطلوبة يدويًا لسبب ما مطلوبًا ، يمكن استخدام الخطوات التالية بدلاً من ذلك:
python -m venv venv
source venv/bin/activatepip install pip install surfactantpip install . على سبيل المثال ، هذه هي الطريقة التي يمكن بها تثبيت البرنامج المساعد الغامض من مستودع GIT (يمكن أيضًا استخدام أسماء حزم PYPI أو أدلة المصدر المحلي أو ملفات العجلات). pip install git+https://github.com/LLNL/Surfactant#subdirectory=plugins/fuzzyhashespython -m venv venv
source venv/bin/activategit clone [email protected]:LLNL/Surfactant.gitpip install -e .لتثبيت التبعيات الاختيارية المطلوبة لتشغيل Pytest و Commits:
pip install -e " .[test,dev] " يمكن أيضًا استخدام pip install باستخدام الخيار -e أو --editable الإضافات السطحية للتطوير.
pip install -e plugins/fuzzyhashes يمكن تغيير إعدادات SurfAntant باستخدام المفوض الفرعي surfactant config ، أو عن طريق تحرير ملف تكوين الإعدادات (هذا ليس هو نفسه ملف JSON المستخدم لتكوين الإعدادات لعينة معينة موصوفة لاحقًا). تحتوي صفحة وثائق الإعدادات على قائمة بالخيارات المتاحة التي تم تضمينها في الفاعل بالسطح.
يشبه استخدام surfactant config إلى حد كبير الاستخدام الأساسي git config . سيكون المفتاح الذي يتم الوصول إلى قيمته في section.option النماذج. اخترق حيث يكون section عادةً اسمًا مكونًا إضافيًا أو core ، option هو خيار تعيينه. على سبيل المثال ، يمكن استخدام خيار core.recorded_institution لتكوين المؤسسة المسجلة المستخدمة لتحديد من كان منشئ SBOM المولد.
يمكن إجراء هذا الخيار إلى LLNL مع الأمر التالي:
surfactant config core.recorded_institution LLNLبعد ذلك ، سيتم الحصول على القيمة المحددة حاليًا للخيار مع:
surfactant config core.recorded_institution إذا رغبت في ذلك ، يمكن أيضًا تحرير ملف تكوين الإعدادات يدويًا. سيعتمد موقع الملف على النظام الأساسي الخاص بك. على منصات شبيهة بـ UNIX (بما في ذلك MACOS) ، يتم اتباع مواصفات دليل XDG وسيتم تخزين الإعدادات في ${XDG_CONFIG_HOME}/surfactant/config.toml . إذا لم يتم تعيين متغير بيئة XDG_CONFIG_HOME ، فإن الموقع افتراضي إلى ~/.config . على Windows ، يتم تخزين الملف في مجلد AppData المتجول في %APPDATA%\surfactant\config.toml .
الملف نفسه عبارة عن ملف TOML ، وللسلع الإضافي المذكور سابقًا قد يبدو مثل هذا:
[ core ]
recorded_institution = " LLNL " من أجل اختبار السطحي ، ستحتاج إلى نموذج/مجلد. إذا لم يكن لديك واحدة في متناول اليد ، فيمكنك تنزيل ملف .zip المحمول من https://github.com/sharex/sharex/release أو ملف linux .tar.gz من https://github.com/gmlc-tdc/helics/releases. بدلاً من ذلك ، يمكنك اختيار عينة من https://lc.llnl.gov/gitlab/cir-software-assurance/unpacker-to-sbom-test-files
يحتوي ملف التكوين لعينة على معلومات حول العينة لجمع المعلومات من. مثال يمكن العثور على ملفات تكوين عينة JSON في مجلد أمثلة من هذا المستودع.
surfactant من مجلدات العينة ، لا يمكن أن يكون ملفًا. لاحظ أنه حتى على Windows ، يجب استخدام فواصل Unix نمط / دليل في المسارات.extractPaths . يتم استخدام هذا لجمع البيانات الوصفية حول العينة الكلية وسيتم إضافتها كعلاقة "تحتوي على" لجميع إدخالات البرامج الموجودة في مختلف extractPaths .extractPaths بشكل صحيح على نظام فعلي ، أي "C:/" ، "C / /Program Files/" ، وما إلى ذلك. إذا لم يتم تقديمها ، فسيتم استخدام extractPaths كمسارات التثبيت.includeAllFiles و excludeFileExts ، فسيظل الإضافات المحددة في excludeFileExts مستبعدة. يمكن بناء ملف التكوين الأساسي بسهولة باستخدام الأمر create-config . سيأخذ هذا مسارًا كوسيطة سطر الأوامر وسيحفظ ملفًا مع الاسم الافتراضي للدليل النهائي الذي تم تمريره إليه كملف JSON. IE ، /home/user/Desktop/myfolder ستقوم بإنشاء myfolder.json .
$ surfactant create-config [INPUT_PATH]يمكن استخدام علامة -Output لتحديد اسم إخراج التكوين. يمكن استخدام-install-prefix لتحديد بادئة التثبيت ، الافتراضي هو '/'.
$ surfactant create-config [INPUT_PATH] --output new_output.json --install-prefix ' C:/ ' دعنا نقول أن لديك ملف .tar.gz الذي تريد تشغيل السطحي عليه. على سبيل المثال ، سنستخدم مثال Helics Release .tar.gz. في هذا السيناريو ، المسار المطلق لهذا الملف هو /home/samples/helics.tar.gz helics.tar.gz. عند استخراج هذا الملف ، نحصل على مجلد هيليكات مع 4 فئة فرعية: bin ، تشمل ، lib64 ، والمشاركة.
إذا أردنا تضمين المجلدات التي تحتوي على ملفات ثنائية فقط لتحليلها ، فسيكون تكويننا الأساسي هو:
[
{
"extractPaths" : [ " /home/samples/helics/bin " , " /home/samples/helics/lib64 " ]
}
]سيتم تنظيم SBOM الناتج مثل هذا:
{
"software" : [
{
"UUID" : " abc1 " ,
"fileName" : [ " helics_binary " ],
"installPath" : [ " /home/samples/helics/bin/helics_binary " ],
"containerPath" : null
},
{
"UUID" : " abc2 " ,
"fileName" : [ " lib1.so " ],
"installPath" : [ " /home/samples/helics/lib64/lib1.so " ],
"containerPath" : null
}
],
"relationships" : [
{
"xUUID" : " abc1 " ,
"yUUID" : " abc2 " ,
"relationship" : " Uses "
}
]
} قد يبدو ملف تكوين أكثر تفصيلاً مثل المثال أدناه. سيكون لـ SBOM الناتج إدخال برنامج لـ The Helics.tar.gz مع علاقة "تحتوي" على جميع الثنائيات الموجودة في المستخلصات. سيسمح توفير بادئة تثبيت / و extractpaths AS /home/samples/helics بتعيين مسارات التثبيت بشكل صحيح في SBOM للثنائيات في المجلدات الفرعية AS /bin و /lib64 .
[
{
"archive" : " /home/samples/helics.tar.gz " ,
"extractPaths" : [ " /home/samples/helics " ],
"installPrefix" : " / "
}
]سيتم تنظيم SBOM الناتج مثل هذا:
{
"software" : [
{
"UUID" : " abc0 " ,
"fileName" : [ " helics.tar.gz " ],
"installPath" : null ,
"containerPath" : null
},
{
"UUID" : " abc1 " ,
"fileName" : [ " helics_binary " ],
"installPath" : [ " /bin/helics_binary " ],
"containerPath" : [ " abc0/bin/helics_binary " ]
},
{
"UUID" : " abc2 " ,
"fileName" : [ " lib1.so " ],
"installPath" : [ " /lib64/lib1.so " ],
"containerPath" : [ " abc0/lib64/lib1.so " ]
}
],
"relationships" : [
{
"xUUID" : " abc0 " ,
"yUUID" : " abc1 " ,
"relationship" : " Contains "
},
{
"xUUID" : " abc0 " ,
"yUUID" : " abc2 " ,
"relationship" : " Contains "
},
{
"xUUID" : " abc1 " ,
"yUUID" : " abc2 " ,
"relationship" : " Uses "
}
]
}إذا كان ملف Sample Helics Tar.gz الخاص بنا يأتي مع ملف tar.gz ذي صلة لتثبيت وحدة تمديد مكون إضافي (تم استخراجها في مجلد Helics_Plugin الذي يحتوي على مجلدات Bin و Lib64) ، فيمكننا إضافة ذلك إلى ملف التكوين أيضًا:
[
{
"archive" : " /home/samples/helics.tar.gz " ,
"extractPaths" : [ " /home/samples/helics " ],
"installPrefix" : " / "
},
{
"archive" : " /home/samples/helics_plugin.tar.gz " ,
"extractPaths" : [ " /home/samples/helics_plugin " ],
"installPrefix" : " / "
}
]سيتم تنظيم SBOM الناتج مثل هذا:
{
"software" : [
{
"UUID" : " abc0 " ,
"fileName" : [ " helics.tar.gz " ],
"installPath" : null ,
"containerPath" : null
},
{
"UUID" : " abc1 " ,
"fileName" : [ " helics_binary " ],
"installPath" : [ " /bin/helics_binary " ],
"containerPath" : [ " abc0/bin/helics_binary " ]
},
{
"UUID" : " abc2 " ,
"fileName" : [ " lib1.so " ],
"installPath" : [ " /lib64/lib1.so " ],
"containerPath" : [ " abc0/lib64/lib1.so " ]
},
{
"UUID" : " abc3 " ,
"fileName" : [ " helics_plugin.tar.gz " ],
"installPath" : null ,
"containerPath" : null
},
{
"UUID" : " abc4 " ,
"fileName" : [ " helics_plugin " ],
"installPath" : [ " /bin/helics_plugin " ],
"containerPath" : [ " abc3/bin/helics_plugin " ]
},
{
"UUID" : " abc5 " ,
"fileName" : [ " lib_plugin.so " ],
"installPath" : [ " /lib64/lib_plugin.so " ],
"containerPath" : [ " abc3/lib64/lib_plugin.so " ]
}
],
"relationships" : [
{
"xUUID" : " abc1 " ,
"yUUID" : " abc2 " ,
"relationship" : " Uses "
},
{
"xUUID" : " abc4 " ,
"yUUID" : " abc5 " ,
"relationship" : " Uses "
},
{
"xUUID" : " abc5 " ,
"yUUID" : " abc2 " ,
"relationship" : " Uses "
},
{
"xUUID" : " abc0 " ,
"yUUID" : " abc1 " ,
"relationship" : " Contains "
},
{
"xUUID" : " abc0 " ,
"yUUID" : " abc2 " ,
"relationship" : " Contains "
},
{
"xUUID" : " abc3 " ,
"yUUID" : " abc4 " ,
"relationship" : " Contains "
},
{
"xUUID" : " abc3 " ,
"yUUID" : " abc5 " ,
"relationship" : " Contains "
}
]
}ملاحظة: تم تبسيط هذه الأمثلة لإظهار الاختلافات في الإخراج بناءً على التكوين.
$ surfactant generate [OPTIONS] CONFIG_FILE SBOM_OUTFILE [INPUT_SBOM] config_file : (مطلوب) ملف التكوين الذي تم إنشاؤه مسبقًا يحتوي على المعلومات الموجودة في العينة
إخراج SBOM : (مطلوب) الاسم المطلوب لملف الإخراج
input_sbom : (اختياري) يجب استخدام SBOM قاعدة ، حيث يمكن إفساد العلاقات عند تثبيت الملفات على أنظمة مختلفة
-skip_gather : (اختياري) يتخطى جمع المعلومات على الملفات وإضافة البرامج
-skip_relationships : (اختياري) يتخطى إضافة العلاقات على أساس البيانات الوصفية
-skip_install_path : (اختياري) يتخطى مسار التثبيت للملفات المكتشفة. قد يسبب هذا أيضًا إنشاء علاقات "الاستخدامات"
--- recorded_institution : (اختياري) اسم المؤسسة التي تجمع بيانات SBOM (الافتراضي: llnl)
-output_format : (اختياري) يغير تنسيق الإخراج لـ SBOM (المعطى كاسم كامل للوحدة النمطية لمكون من سطحي ينفذ خطاف write_sbom )
-input_format : (اختياري) يحدد تنسيق الإدخال SBOM إذا تم استخدام المرء (افتراضي: Cytrics) (المعطى كاسم وحدة كاملة لمكون من سطحي ينفذ خطاف read_sbom )
-help : (اختياري) إظهار رسالة المساعدة والخروج
يحتوي هذا القسم على قائمة بالإدخالات المتعلقة بكل جزء من البرامج الموجودة في العينة. يتم تضمين البيانات الوصفية بما في ذلك حجم الملف ، والبائع ، والنسخة ، وما إلى ذلك في هذا القسم إلى جانب UUID لتحديد إدخال البرنامج بشكل فريد.
يحتوي هذا القسم على معلومات حول كيفية ربط كل من إدخالات البرنامج في القسم السابق.
الاستخدامات : يعني نوع العلاقة هذا أن برنامج X يستخدم برنامج y ، أي أن وحدة مساعد إلى x
يحتوي على : نوع العلاقة هذا يعني أن برنامج X يحتوي على برنامج y (غالبًا ما يكون برنامج X هو مثبت أو أرشيف مثل ملف zip)
يحتوي هذا القسم على معلومات حول الملاحظات البارزة حول مكونات البرامج الفردية. قد يكون هذا نقاط ضعف وميزات ملحوظة وما إلى ذلك
يمكن دمج المجلد الذي يحتوي على عدة ملفات SBOM JSON منفصلة باستخدام marge_sbom.py بأمر مثل هذا أدناه يحصل على قائمة بالملفات باستخدام LS ، ثم يستخدم XARGS لتمرير قائمة الملفات الناتجة إلى merge_sbom.py كوسائط.
ls -d ~/Folder_With_SBOMs/Surfactant-* | xargs -d 'n' surfactant merge --config_file=merge_config.json --sbom_outfile combined_sbom.json
إذا تم إعطاء خيار ملف التكوين ، فسيتم إنشاء إدخال النظام الأعلى على مستوى المستوى ، حيث يتم ربط جميع إدخالات البرامج الأخرى (بشكل مباشر أو غير مباشر بناءً على علاقات أخرى). سيؤدي تحديد UUID فارغًا إلى إنشاء UUID عشوائيًا لإدخال النظام الجديد ، وإلا فإنه سيستخدم النظام المقدم.
يمكن الاطلاع على تفاصيل أمر دمج في صفحة المستندات هنا.
يدعم السطحي باستخدام الإضافات لإضافة ميزات إضافية. يمكن للمستخدمين تثبيت المكونات الإضافية مع surfactant plugin install وتعطيلها أو تمكينها من خلال surfactant plugin disable surfactant plugin enable على التوالي. surfactant plugin install باكتشاف البيئة الافتراضية النشطة ويقوم بتشغيل الأمر المناسب IE pipx أو pip . بدلاً من ذلك ، يمكن للمستخدمين إدارة بيئاتهم يدويًا باستخدام pipx inject surfactant عند استخدام pip install .
يمكن العثور هنا على معلومات مفصلة عن خيارات التكوين لنظام البرنامج المساعد وكيفية تطوير مكونات إضافية جديدة.
تتوفر أدلة المستخدم الكاملة لـ Surfactant عبر الإنترنت وفي دليل المستندات.
للأسئلة أو الدعم ، يرجى إنشاء مناقشة جديدة حول مناقشات GitHub ، أو فتح مشكلة لتقارير الأخطاء وطلبات الميزات.
المساهمات موضع ترحيب. يتم تفضيل إصلاحات الأخطاء أو التغييرات البسيطة عبر طلب سحب إلى مستودع github الفاعل بالسطح. لمزيد من المعلومات حول المساهمة ، راجع الملف المساهم.
يتم إصدار السطحي تحت رخصة معهد ماساتشوستس للتكنولوجيا. راجع ملفات الترخيص وإشعار للحصول على التفاصيل. يجب تقديم جميع المساهمات الجديدة بموجب هذا الترخيص.
spdx-recense-idention: MIT
llnl-code-850771
