Surfactant
Update for SecTor 2024
Dokumentasi
Surfaktan dapat digunakan untuk mengumpulkan informasi dari satu set file untuk menghasilkan SBOM, bersama dengan memanipulasi SBOM dan menganalisis informasi di dalamnya. Ini menarik informasi dari jenis file yang diakui (seperti file PE, ELF, atau MSI) yang terkandung dalam struktur direktori yang sesuai dengan paket perangkat lunak yang diekstraksi. Secara default, informasinya adalah metadata "level permukaan" yang terkandung dalam file yang tidak mengharuskan menjalankan file atau dekompilasi.
Untuk kemudahan penggunaan, kami sarankan menggunakan PIPX karena secara transparan menangani membuat dan menggunakan lingkungan virtual Python, yang membantu menghindari konflik ketergantungan dengan aplikasi Python yang terpasang lainnya. Pasang pipx dengan mengikuti instruksi pemasangannya.
pipx install (dengan Python> = 3.8) pipx install surfactantCatatan: Dukungan file Mach-O mengharuskan pemasangan surfaktan dengan dependensi opsional
macho(misalnyapipx install surfactant[macho]).
pipx inject surfactant . Sebagai contoh, ini adalah bagaimana plugin hashing fuzzy dapat diinstal dari repositori git (nama paket PYPI, direktori sumber lokal, atau file roda juga dapat digunakan). pipx inject surfactant git+https://github.com/LLNL/Surfactant#subdirectory=plugins/fuzzyhashesJika karena alasan tertentu mengelola lingkungan virtual secara manual diinginkan, langkah -langkah berikut dapat digunakan sebagai gantinya:
python -m venv venv
source venv/bin/activatepip install pip install surfactantpip install . Sebagai contoh, ini adalah bagaimana plugin hashing fuzzy dapat diinstal dari repositori git (nama paket PYPI, direktori sumber lokal, atau file roda juga dapat digunakan). 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 .Untuk menginstal dependensi opsional yang diperlukan untuk menjalankan pytest dan pra-komit:
pip install -e " .[test,dev] " pip install dengan opsi -e atau --editable juga dapat digunakan untuk menginstal plugin surfaktan untuk pengembangan.
pip install -e plugins/fuzzyhashes Pengaturan surfaktan dapat diubah menggunakan sub -perintah surfactant config , atau dengan mengedit tangan file konfigurasi pengaturan (ini tidak sama dengan file JSON yang digunakan untuk mengonfigurasi pengaturan untuk sampel tertentu yang dijelaskan nanti). Halaman Dokumentasi Pengaturan memiliki daftar opsi yang tersedia yang dibangun-ke dalam surfaktan.
Menggunakan surfactant config sangat mirip dengan penggunaan dasar git config . option yang nilainya diakses akan core di section.option Formulir section Sebagai contoh, opsi core.recorded_institution dapat digunakan untuk mengonfigurasi lembaga yang direkam yang digunakan untuk mengidentifikasi siapa pencipta SBOM yang dihasilkan.
Mengatur opsi ini ke LLNL dapat dilakukan dengan perintah berikut:
surfactant config core.recorded_institution LLNLMendapatkan nilai yang ditetapkan saat ini untuk opsi kemudian akan dilakukan dengan:
surfactant config core.recorded_institution Jika diinginkan, file Konfigurasi Pengaturan juga dapat diedit secara manual. Lokasi file akan tergantung pada platform Anda. Pada platform seperti UNIX (termasuk MacOS), spesifikasi direktori XDG diikuti dan pengaturan akan disimpan dalam ${XDG_CONFIG_HOME}/surfactant/config.toml . Jika variabel lingkungan XDG_CONFIG_HOME tidak diatur, lokasi default ke ~/.config . Di Windows, file disimpan di folder AppData Roaming di %APPDATA%\surfactant\config.toml .
File itu sendiri adalah file TOML, dan untuk contoh plugin yang disebutkan sebelumnya mungkin terlihat seperti ini:
[ core ]
recorded_institution = " LLNL " Untuk menguji surfaktan, Anda akan memerlukan file/folder sampel. Jika Anda tidak memilikinya, Anda dapat mengunduh dan menggunakan file .zip portabel dari https://github.com/sharex/sharex/releases atau file linux .tar.gz dari https://github.com/gmlc-tdc/helics/releases. Atau, Anda dapat memilih sampel dari https://lc.llnl.gov/gitlab/cir-software-assurance/unpacker-t-sbom-test-files
File konfigurasi untuk sampel berisi informasi tentang sampel untuk mengumpulkan informasi dari. Contoh file konfigurasi sampel JSON dapat ditemukan di folder contoh repositori ini.
surfactant dijalankan dari ke folder sampel, tidak dapat menjadi file. Perhatikan bahwa bahkan pada Windows, pemisah gaya / direktori UNIX harus digunakan di jalur.extractPaths . Ini digunakan untuk mengumpulkan metadata tentang sampel keseluruhan dan akan ditambahkan sebagai hubungan "berisi" dengan semua entri perangkat lunak yang ditemukan di berbagai extractPaths .extractPaths akan diinstal dengan benar pada sistem yang sebenarnya yaitu "C:/", "C:/Program Files/", dll. Perhatikan bahwa bahkan pada Windows, pemisah gaya / direktori UNIX harus digunakan di jalur. Jika tidak diberikan maka extractPaths akan digunakan sebagai jalur instalasi.includeAllFiles dan excludeFileExts ditetapkan, ekstensi yang ditentukan di excludeFileExts masih akan dikecualikan. File konfigurasi dasar dapat dengan mudah dibangun menggunakan perintah create-config . Ini akan mengambil jalur sebagai argumen baris perintah dan akan menyimpan file dengan nama default dari Direktori Akhir yang diteruskan ke sana sebagai file JSON. yaitu, /home/user/Desktop/myfolder akan membuat myfolder.json .
$ surfactant create-config [INPUT_PATH]Bendera -output dapat digunakan untuk menentukan nama output konfigurasi. -install-prefix dapat digunakan untuk menentukan awalan instalasi, defaultnya adalah '/'.
$ surfactant create-config [INPUT_PATH] --output new_output.json --install-prefix ' C:/ ' Katakanlah Anda memiliki file .tar.gz yang ingin Anda jalankan surfaktan. Untuk contoh ini, kami akan menggunakan Contoh Rilis Helics .tar.gz. Dalam skenario ini, jalur absolut untuk file ini adalah /home/samples/helics.tar.gz . Setelah mengekstraksi file ini, kami mendapatkan folder helik dengan 4 sub-folder: bin, termasuk, lib64, dan berbagi.
Jika kami hanya ingin memasukkan folder yang berisi file biner untuk dianalisis, konfigurasi kami yang paling mendasar adalah:
[
{
"extractPaths" : [ " /home/samples/helics/bin " , " /home/samples/helics/lib64 " ]
}
]SBOM yang dihasilkan akan disusun seperti ini:
{
"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 "
}
]
} File konfigurasi yang lebih rinci mungkin terlihat seperti contoh di bawah ini. SBOM yang dihasilkan akan memiliki entri perangkat lunak untuk Helics.tar.gz dengan hubungan "berisi" dengan semua binari yang ditemukan di ExtractPaths. Memberikan awalan instalasi / dan ExtractPaths sebagai /home/samples/helics akan memungkinkan surfaktan dengan benar menetapkan jalur instalasi di SBOM untuk binari di subfolder sebagai /bin dan /lib64 .
[
{
"archive" : " /home/samples/helics.tar.gz " ,
"extractPaths" : [ " /home/samples/helics " ],
"installPrefix" : " / "
}
]SBOM yang dihasilkan akan disusun seperti ini:
{
"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 "
}
]
}Jika file Tar.GZ Helics Sample kami dilengkapi dengan file Tar.GZ terkait untuk menginstal modul ekstensi plugin (diekstraksi ke dalam folder Helics_plugin yang berisi subfolder bin dan Lib64), kami dapat menambahkannya ke dalam file konfigurasi juga:
[
{
"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 yang dihasilkan akan disusun seperti ini:
{
"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 "
}
]
}Catatan: Contoh -contoh ini telah disederhanakan untuk menunjukkan perbedaan output berdasarkan konfigurasi.
$ surfactant generate [OPTIONS] CONFIG_FILE SBOM_OUTFILE [INPUT_SBOM] Config_file : (wajib) File konfigurasi yang dibuat sebelumnya yang berisi informasi pada sampel
Output SBOM : (Diperlukan) Nama yang diinginkan dari file output
Input_sbom : (opsional) SBOM dasar, harus digunakan dengan hati -hati karena hubungan dapat kacau ketika file diinstal pada sistem yang berbeda
--SKIP_GATHER : (Opsional) Lewati pengumpulan informasi tentang file dan menambahkan perangkat lunak
--kip_relationships : (Opsional) Lewati penambahan hubungan berdasarkan metadata
--skip_install_path : (opsional) melompati termasuk jalur instal untuk file yang ditemukan. Ini dapat menyebabkan hubungan "menggunakan" juga tidak dihasilkan
---dekorded_institusi : (opsional) Nama lembaga yang mengumpulkan data SBOM (default: llnl)
-output_format : (Opsional) Mengubah format output untuk SBOM (diberikan sebagai nama modul penuh plugin surfaktan yang mengimplementasikan hook write_sbom )
--input_format : (Opsional) Menentukan format input SBOM jika seseorang digunakan (default: cytrics) (diberikan sebagai nama modul penuh plugin surfaktan yang mengimplementasikan kait read_sbom )
--help : (opsional) Tampilkan pesan bantuan dan keluar
Bagian ini berisi daftar entri yang berkaitan dengan setiap bagian perangkat lunak yang ditemukan dalam sampel. Metadata termasuk ukuran file, vendor, versi, dll disertakan dalam bagian ini bersama dengan UUID untuk secara unik mengidentifikasi entri perangkat lunak.
Bagian ini berisi informasi tentang bagaimana masing -masing entri perangkat lunak di bagian sebelumnya ditautkan.
Penggunaan : Jenis hubungan ini berarti bahwa perangkat lunak X menggunakan perangkat lunak y yaitu adalah modul pembantu ke x
Berisi : Jenis hubungan ini berarti bahwa perangkat lunak X berisi perangkat lunak Y (seringkali perangkat lunak X adalah penginstal atau arsip seperti file zip)
Bagian ini berisi informasi tentang pengamatan penting tentang komponen perangkat lunak individu. Ini bisa berupa kerentanan, fitur yang diamati, dll
Sebuah folder yang berisi beberapa file SBOM JSON terpisah dapat digabungkan menggunakan merge_sbom.py dengan perintah seperti yang di bawah ini yang mendapatkan daftar file menggunakan LS, dan kemudian menggunakan XArgs untuk meneruskan daftar file yang dihasilkan ke gabungan_sbom.py sebagai argumen.
ls -d ~/Folder_With_SBOMs/Surfactant-* | xargs -d 'n' surfactant merge --config_file=merge_config.json --sbom_outfile combined_sbom.json
Jika opsi file konfigurasi diberikan, entri sistem tingkat atas akan dibuat bahwa semua entri perangkat lunak lain terikat (secara langsung atau tidak langsung berdasarkan hubungan lain). Menentukan UUID yang kosong akan membuat UUID acak dihasilkan untuk entri sistem baru, jika tidak ia akan menggunakan yang disediakan.
Rincian tentang perintah gabungan dapat ditemukan di halaman Docs di sini.
Dukungan surfaktan menggunakan plugin untuk menambahkan fitur tambahan. Pengguna dapat menginstal plugin dengan surfactant plugin install dan menonaktifkan atau mengaktifkannya dengan surfactant plugin disable dan surfactant plugin enable masing -masing. surfactant plugin install mendeteksi lingkungan virtual aktif dan menjalankan perintah yang sesuai yaitu pipx atau pip . Atau, pengguna dapat secara manual mengelola lingkungan mereka dengan pipx inject surfactant saat menggunakan PIPX atau pip install .
Informasi terperinci tentang opsi konfigurasi untuk sistem plugin dan cara mengembangkan plugin baru dapat ditemukan di sini.
Panduan pengguna lengkap untuk surfaktan tersedia secara online dan di direktori Docs.
Untuk pertanyaan atau dukungan, silakan buat diskusi baru tentang diskusi GitHub, atau buka masalah untuk laporan bug dan permintaan fitur.
Kontribusi dipersilakan. Perbaikan bug atau perubahan kecil lebih disukai melalui permintaan tarik ke repositori GitHub surfaktan. Untuk informasi lebih lanjut tentang berkontribusi, lihat file yang berkontribusi.
Surfaktan dirilis di bawah lisensi MIT. Lihat lisensi dan perhatikan file untuk detailnya. Semua kontribusi baru harus dilakukan di bawah lisensi ini.
SPDX-LICENSE-Identifier: MIT
Llnl-code-850771
