Surfactant
Update for SecTor 2024
文件
表面活性劑可用於從一組文件中收集信息，以生成SBOM，並操縱SBOM並分析其中的信息。它從與提取的軟件包相對應的目錄結構中包含的識別文件類型（例如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] "帶有-e或--editable選項的pip install也可以用於安裝表面活性劑插件進行開發。
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的平台（包括MACOS）上，遵循XDG目錄規範，設置將存儲在${XDG_CONFIG_HOME}/surfactant/config.toml中。如果未設置XDG_CONFIG_HOME環境變量，則位置默認為~/.config 。在Windows上，該文件存儲在%APPDATA%\surfactant\config.toml的漫遊appdata文件夾中。
該文件本身是一個TOML文件，對於前面提到的示例插件可能看起來像這樣：
[ core ]
recorded_institution = " LLNL " 為了測試表面活性劑，您將需要一個示例文件/文件夾。如果您沒有手頭，則可以從https://github.com/sharex/sharex/releases或linux .tar.gz文件下載並使用Portable .zip文件，從https://github.com/gmlc.com/gmlc-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/”等。請注意，即使在Windows，Unix樣式/目錄分離器中，也應在路徑中使用。如果沒有給出，則extractPaths將用作安裝路徑。includeAllFiles和excludeFileExts ，則仍將排除excludeFileExts中指定的擴展名。 可以使用create-config命令輕鬆構建基本的配置文件。這將以命令行參數為路徑，並保存一個文件，其中包含端目錄的默認名稱作為JSON文件傳遞給該文件。即/home/user/Desktop/myfolder將創建myfolder.json 。
$ surfactant create-config [INPUT_PATH]- 輸出標誌可用於指定配置輸出名稱。 - 安裝式預訂可用於指定安裝前綴，默認值為'/'。
$ surfactant create-config [INPUT_PATH] --output new_output.json --install-prefix ' C:/ ' 可以說，您有一個要運行表面活性劑的.tar.gz文件。在此示例中，我們將使用Helics Release .tar.gz示例。在這種情況下，此文件的絕對路徑是/home/samples/helics.tar.gz 。提取此文件後，我們將獲得一個帶有4個子文件夾的螺旋文件夾：bin，include，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的軟件條目，並具有與Extractpath中發現的所有二進製文件的“包含”關係。提供/和提取路徑的安裝前綴為/home/samples/helics將允許表面活性劑正確分配SBOM中的SBOM中的安裝路徑，以示為子文件夾中的二進製文件AS /bin and /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 tar.gz文件帶有相關的tar.gz文件以安裝插件擴展模塊（提取到包含bin和lib64子文件夾的Helics_plugin文件夾中），我們也可以將其添加到配置文件中：
[
{
"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）
-unput_format ：（可選）更改SBOM的輸出格式（以實現write_sbom Hook的表面活性劑插件的完整模塊名稱給出）
-Input_format ：（可選）指定輸入SBOM的格式（如果使用）（默認：cantrics）（以表面活性劑插件的完整模塊為單位，則實現了read_sbom Hook）
- 支持：（可選）顯示幫助消息和退出
本節包含與示例中發現的每個軟件有關的條目列表。本節中包含包括文件大小，供應商，版本等（包括文件大小，供應商，版本等）的元數據，以及唯一標識軟件條目的UUID。
本節包含有關上一節中每個軟件條目的鏈接方式的信息。
用途：此關係類型意味著X軟件使用Y軟件，即是X的助手模塊
包含：此關係類型意味著X軟件包含Y軟件（通常X軟件是安裝程序或檔案，例如zip文件）
本節包含有關有關單個軟件組件的顯著觀察的信息。這可能是漏洞，觀察到的功能等
可以使用Merge_sbom.py與一個命令將包含多個單獨的SBOM JSON文件的文件夾組合在一起，以下一個使用LS獲取文件列表，然後使用XARGS將結果列表傳遞給Merge_sbom.py as aS grimuments。
ls -d ~/Folder_With_SBOMs/Surfactant-* | xargs -d 'n' surfactant merge --config_file=merge_config.json --sbom_outfile combined_sbom.json
如果給出了配置文件選項，則將創建一個頂級系統條目，即所有其他軟件條目都與（直接或間接基於其他關係）。指定一個空的UUID將使隨機的UUID為新系統條目生成，否則將使用提供的uuid。
有關合併命令的詳細信息可以在此處的“文檔”頁面中找到。
表面活性劑支持使用插件添加其他功能。用戶可以通過surfactant plugin install並禁用或通過surfactant plugin disable和surfactant plugin enable插件。 surfactant plugin install可檢測活動的虛擬環境並運行適當的命令IE pipx或pip 。另外，使用PIPX或pip install時，用戶可以用pipx inject surfactant手動管理其環境。
可以在此處找到有關插件系統配置選項以及如何開發新插件的詳細信息。
表面活性劑的完整用戶指南可在線和文檔目錄中獲得。
有關問題或支持，請在GitHub討論上進行新的討論，或為錯誤報告和功能請求打開問題。
歡迎捐款。通過向表面活性劑GitHub存儲庫的拉請請求優選錯誤修復或較小的更改。有關貢獻的更多信息，請參見貢獻文件。
表面活性劑是根據MIT許可發布的。有關詳細信息，請參見許可證和通知文件。所有新捐款必鬚根據本許可做出。
SPDX-LICENSE-IDIFIER：麻省理工學院
llnl-Code-850771
