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
