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 и 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 Form.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 файл хранится в папке Roaming AppData At %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-te-files files
Файл конфигурации для образца содержит информацию о примере для сбора информации. Пример файлов конфигурации JSON можно найти в папке примеров этого репозитория.
surfactant запускается в папки образцов, не может быть файлом. Обратите внимание, что даже в Windows разделители стиля Unix / каталог должны использоваться в путях.extractPaths . Это используется для сбора метаданных об общей выборке и будет добавлено в качестве «содержимого» отношения ко всем записям программного обеспечения, найденных в различных extractPaths .extractPaths будут, если они будут правильно установлены в реальной системе, то есть «c:/», «c:/программа файлов/» и т. Д. Обратите внимание, что даже в Windows, разделители стиля Unix / Directory должны использоваться в пути. Если не указано, то extractPaths будут использоваться в качестве путей установки.includeAllFiles , так и excludeFileExts , указанные расширения в excludeFileExts все равно будут исключены. Основной файл конфигурации можно легко создать с помощью команды create-config . Это займет путь в качестве аргумента командной строки и сохранит файл с именем по умолчанию конечного каталога, переданного ему в качестве файла JSON. т.е. /home/user/Desktop/myfolder создаст myfolder.json .
$ surfactant create-config [INPUT_PATH]Флаг -выпуск может использоваться для указания выходного имени конфигурации. --Install-Prefix может использоваться для указания префикса установки, по умолчанию есть '/'.
$ surfactant create-config [INPUT_PATH] --output new_output.json --install-prefix ' C:/ ' Допустим, у вас есть файл .tar.gz, на котором вы хотите запустить поверхностно -активное вещество. Для этого примера мы будем использовать пример версии .tar.gz. В этом сценарии абсолютный путь для этого файла - /home/samples/helics.tar.gz samples/helics.tar.gz. При извлечении этого файла мы получаем папку с вершинами с 4 субсолдерами: bin, включить, Lib64 и Share.
Если мы хотим включить только папки, которые содержат двоичные файлы для анализа, наша основная конфигурация была бы:
[
{
"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 будет иметь запись программного обеспечения для версии. Предоставление префикса установки / и ExtractPaths As /home/samples/helics позволит правильно назначать пути установки в SBOM для двоичных файлов в подпапке, как /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 Hellics 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 : (необязательно) пропускает сбор информации в файлах и добавление программного обеспечения Entires
-skip_relationships : (необязательно) пропускает добавление отношений на основе метаданных
-SKIP_INSTALL_PATH : (Необязательно) пропуски, включая путь установки для обнаруженных файлов. Это может привести к тому, что «используют» отношения, чтобы не быть сгенерировано
-Записан_инстатирование : (необязательно) Имя учреждения, собирающего данные SBOM (по умолчанию: LLNL)
--output_format : (необязательно) Измените выходной формат для SBOM (приведено в виде полного имени модуля плагина поверхностно-активного вещества, реализуя крюк write_sbom )
--input_format : (необязательно) Указывает формат входа SBOM, если используется (по умолчанию: Cytrics) (приведено в качестве полного имени модуля плагина поверхностно-активного вещества, реализуя крюк read_sbom )
-help : (необязательно) Показать помощь справочника и выход
В этом разделе содержится список записей, связанных с каждой частью программного обеспечения, найденного в образце. Метаданные, включая размер файла, поставщик, версию и т. Д. Включены в этот раздел вместе с UUID, чтобы уникально идентифицировать запись программного обеспечения.
Этот раздел содержит информацию о том, как связана каждая из записей программного обеспечения в предыдущем разделе.
Использование : этот тип отношений означает, что программное обеспечение x использует программное обеспечение y y y y - это помощник модуля для x
Содержит : этот тип отношения означает, что программное обеспечение x содержит программное обеспечение y (часто x программное обеспечение является установщиком или архивом, таким как zip -файл)
В этом разделе содержится информация о заметных наблюдениях об отдельных компонентах программного обеспечения. Это могут быть уязвимости, наблюдаемые особенности и т. Д.
Папка, содержащая несколько отдельных файлов SBOM JSON, может быть объединена с использованием merge_sbom.py с такой командой, которая находится ниже, которая получает список файлов с использованием LS, а затем использует XARG для передачи полученного списка файлов для 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 можно найти на странице DOCS здесь.
Поддерживает поверхностно -активное вещество с помощью плагинов для добавления дополнительных функций. Пользователи могут устанавливать плагины с surfactant plugin install и отключением или включением с помощью surfactant plugin disable -активного вещества, а surfactant plugin enable соответственно. surfactant plugin install обнаруживает активную виртуальную среду и запускает соответствующую команду, т. Е. pipx или pip . В качестве альтернативы пользователи могут вручную управлять своими средами с pipx inject surfactant при использовании pip install .
Подробная информация о параметрах конфигурации для системы плагинов и о том, как разработать новые плагины, можно найти здесь.
Полные пользовательские руководства для поверхностно -активного вещества доступны в Интернете и в каталоге DOCS.
Для вопросов или поддержки, пожалуйста, создайте новое обсуждение обсуждений GitHub или откройте проблему для отчетов об ошибках и запросах функций.
Взносы приветствуются. Исправление ошибок или незначительные изменения предпочтительны с помощью запроса на притяжение в репозиторий GitHub. Для получения дополнительной информации о внесении вклад см. Файл.
Серванктактивное вещество выпускается по лицензии MIT. Смотрите файлы лицензии и уведомления для получения подробной информации. Все новые взносы должны быть внесены в соответствии с настоящей лицензией.
SPDX-LICENSE-Идентификатор: MIT
Llnl-Code-850771
