เอกสาร
สารลดแรงตึงผิวสามารถใช้รวบรวมข้อมูลจากชุดไฟล์เพื่อสร้าง 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 และ pre-commit:
pip install -e " .[test,dev] " pip install ด้วยตัวเลือก -e หรือ --editable สามารถใช้ในการติดตั้งปลั๊กอินลดแรงตึงผิวเพื่อการพัฒนา
pip install -e plugins/fuzzyhashes การตั้งค่าสารลดแรงตึงผิวสามารถเปลี่ยนแปลงได้โดยใช้คำสั่งย่อย 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-like (รวมถึง MACOS) ข้อมูลจำเพาะของไดเรกทอรี XDG จะถูกติดตามและการตั้งค่าจะถูกเก็บไว้ใน ${XDG_CONFIG_HOME}/surfactant/config.toml หากไม่ได้ตั้งค่าตัวแปร ~/.config แวดล้อม XDG_CONFIG_HOME บน Windows ไฟล์จะถูกเก็บไว้ในโฟลเดอร์โรมมิ่ง AppData ที่ %APPDATA%\surfactant\config.toml
ไฟล์เองเป็นไฟล์ TOML และสำหรับปลั๊กอินตัวอย่างที่กล่าวถึงก่อนหน้านี้อาจมีลักษณะเช่นนี้:
[ core ]
recorded_institution = " LLNL " ในการทดสอบสารลดแรงตึงผิวคุณจะต้องมีไฟล์ตัวอย่าง/โฟลเดอร์ หากคุณไม่มีอยู่ในมือคุณสามารถดาวน์โหลดและใช้ไฟล์. ZIP แบบพกพาได้จาก https://github.com/sharex/sharex/releases หรือไฟล์ 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:/ไฟล์โปรแกรม / " ฯลฯ โปรดทราบว่าแม้ใน Windows หากไม่ได้รับ extractPaths จะถูกใช้เป็นเส้นทางการติดตั้งincludeAllFiles และ excludeFileExts ส่วนขยายที่ระบุใน excludeFileExts จะยังคงถูกยกเว้น ไฟล์การกำหนดค่าพื้นฐานสามารถสร้างได้อย่างง่ายดายโดยใช้คำสั่ง create-config สิ่งนี้จะใช้เส้นทางเป็นอาร์กิวเมนต์บรรทัดคำสั่งและจะบันทึกไฟล์ด้วยชื่อเริ่มต้นของไดเรกทอรีปลายทางที่ส่งผ่านเป็นไฟล์ JSON เช่น /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 .tar.gz ในสถานการณ์นี้เส้นทางที่แน่นอนสำหรับไฟล์นี้คือ /home/samples/helics.tar.gz เมื่อแยกไฟล์นี้เราจะได้รับโฟลเดอร์ Helics ที่มี 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 ที่ได้จะมีรายการซอฟต์แวร์สำหรับ helics.tar.gz ที่มีความสัมพันธ์ "มี" กับไบนารีทั้งหมดที่พบใน extractaths การจัดเตรียมคำนำหน้าการติดตั้งของ / และ extractpaths เป็น /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 "
}
]
}หากไฟล์ helics helics ของเรามาพร้อมกับไฟล์ 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 เอาต์พุต : (จำเป็น) ชื่อที่ต้องการของไฟล์เอาต์พุต
อินพุต _SBOM : (ไม่บังคับ) SBOM พื้นฐานควรใช้ด้วยความระมัดระวังเนื่องจากความสัมพันธ์อาจเกิดความยุ่งเหยิงเมื่อติดตั้งไฟล์ในระบบที่แตกต่างกัน
-SKIP_GATHER : (ไม่บังคับ) ข้ามการรวบรวมข้อมูลเกี่ยวกับไฟล์และเพิ่มซอฟต์แวร์
-SKIP_RELATIONSHIPS : (ไม่บังคับ) ข้ามการเพิ่มความสัมพันธ์ตามข้อมูลเมตา
-SKIP_INSTALL_PATH : (ไม่บังคับ) ข้ามรวมถึงเส้นทางการติดตั้งสำหรับไฟล์ที่ค้นพบ สิ่งนี้อาจทำให้เกิดความสัมพันธ์ "ใช้" เพื่อไม่ถูกสร้างขึ้น
-บันทึกย่อ _Institution : (ไม่บังคับ) ชื่อของสถาบันที่รวบรวมข้อมูล SBOM (ค่าเริ่มต้น: LLNL)
-OUTPUT_FORMAT : (เสริม) เปลี่ยนรูปแบบเอาต์พุตสำหรับ SBOM (กำหนดเป็นชื่อโมดูลเต็มรูปแบบของปลั๊กอินลดแรงตึงผิวที่ใช้ hook write_sbom )
-input_format : (ไม่บังคับ) ระบุรูปแบบของอินพุต SBOM หากมีการใช้งาน (ค่าเริ่มต้น: Cytrics) (กำหนดเป็นชื่อโมดูลเต็มรูปแบบของปลั๊กอินลดแรงตึงผิวที่ใช้ hook read_sbom )
-Help : (ไม่บังคับ) แสดงข้อความช่วยเหลือและออก
ส่วนนี้มีรายการรายการที่เกี่ยวข้องกับซอฟต์แวร์แต่ละชิ้นที่พบในตัวอย่าง ข้อมูลเมตารวมถึงขนาดไฟล์ผู้ขายเวอร์ชัน ฯลฯ จะรวมอยู่ในส่วนนี้พร้อมกับ UUID เพื่อระบุรายการซอฟต์แวร์ที่ไม่ซ้ำกัน
ส่วนนี้มีข้อมูลเกี่ยวกับวิธีการเชื่อมโยงรายการซอฟต์แวร์แต่ละรายการในส่วนก่อนหน้านี้
ใช้ : ประเภทความสัมพันธ์นี้หมายความว่าซอฟต์แวร์ X ใช้ซอฟต์แวร์ Y IE Y เป็นโมดูลตัวช่วยสำหรับ X
มี : ประเภทความสัมพันธ์นี้หมายความว่าซอฟต์แวร์ X มีซอฟต์แวร์ Y (บ่อยครั้งที่ซอฟต์แวร์ X เป็นตัวติดตั้งหรือเก็บถาวรเช่นไฟล์ zip)
ส่วนนี้มีข้อมูลเกี่ยวกับการสังเกตที่โดดเด่นเกี่ยวกับส่วนประกอบซอฟต์แวร์แต่ละตัว นี่อาจเป็นช่องโหว่คุณสมบัติที่สังเกตได้ ฯลฯ
โฟลเดอร์ที่มีไฟล์ SBOM JSON แยกกันหลายไฟล์สามารถรวมกันได้โดยใช้ merge_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 แบบสุ่มถูกสร้างขึ้นสำหรับรายการระบบใหม่ไม่เช่นนั้นจะใช้รายการที่ให้ไว้
รายละเอียดเกี่ยวกับคำสั่ง Merge สามารถพบได้ในหน้าเอกสารที่นี่
สารลดแรงตึงผิวรองรับการใช้ปลั๊กอินเพื่อเพิ่มคุณสมบัติเพิ่มเติม ผู้ใช้สามารถติดตั้งปลั๊กอินที่มี surfactant plugin install และปิดใช้งานหรือเปิดใช้งานด้วย surfactant plugin disable surfactant plugin enable ได้ตามลำดับ surfactant plugin install จะตรวจจับสภาพแวดล้อมเสมือนจริงที่ใช้งานอยู่และเรียกใช้คำสั่งที่เหมาะสมเช่น pipx หรือ pip อีกทางเลือกหนึ่งผู้ใช้สามารถจัดการสภาพแวดล้อมด้วยตนเองด้วย pipx inject surfactant เมื่อใช้ PIPX หรือ pip install
ข้อมูลรายละเอียดเกี่ยวกับตัวเลือกการกำหนดค่าสำหรับระบบปลั๊กอินและวิธีการพัฒนาปลั๊กอินใหม่สามารถดูได้ที่นี่
คู่มือผู้ใช้เต็มรูปแบบสำหรับสารลดแรงตึงผิวมีให้บริการออนไลน์และในไดเรกทอรี DOCS
สำหรับคำถามหรือการสนับสนุนโปรดสร้างการอภิปรายใหม่เกี่ยวกับการอภิปราย GitHub หรือเปิดปัญหาสำหรับรายงานข้อผิดพลาดและคำขอคุณสมบัติ
ยินดีต้อนรับการมีส่วนร่วม การแก้ไขข้อผิดพลาดหรือการเปลี่ยนแปลงเล็กน้อยเป็นที่ต้องการผ่านคำขอดึงไปยังที่เก็บสารลดแรงตึงผิว GitHub สำหรับข้อมูลเพิ่มเติมเกี่ยวกับการบริจาคโปรดดูไฟล์ที่มีส่วนร่วม
สารลดแรงตึงผิวได้รับการปล่อยตัวภายใต้ใบอนุญาต MIT ดูรายละเอียดใบอนุญาตและประกาศสำหรับรายละเอียด การมีส่วนร่วมใหม่ทั้งหมดจะต้องทำภายใต้ใบอนุญาตนี้
SPDX-license-identifier: MIT
LLNL-Code-850771