Surfactant
Update for SecTor 2024
Documentación
El tensioactivo se puede utilizar para recopilar información de un conjunto de archivos para generar un SBOM, junto con la manipulación de SBOMS y analizar la información en ellos. Straata información de los tipos de archivos reconocidos (como PE, ELF o archivos MSI) contenidos dentro de una estructura de directorio correspondiente a un paquete de software extraído. De manera predeterminada, la información son metadatos de "nivel de superficie" contenidos en los archivos que no requieren ejecutar los archivos o la descompilación.
Para facilitar el uso, recomendamos usar PIPX ya que maneja transparentemente la creación y el uso de entornos virtuales de Python, lo que ayuda a evitar conflictos de dependencia con otras aplicaciones de Python instaladas. Instale pipx siguiendo sus instrucciones de instalación.
pipx install (con Python> = 3.8) pipx install surfactantNota: Soporte de archivo MACH-O requiere instalar tensioactivo con las dependencias opcionales
macho(por ejemplo,pipx install surfactant[macho]).
pipx inject surfactant . Como ejemplo, así es como se podría instalar el complemento de hash fuzzy desde un repositorio de git (también se pueden usar nombres de paquetes Pypi, directorios de origen locales o archivos de ruedas). pipx inject surfactant git+https://github.com/LLNL/Surfactant#subdirectory=plugins/fuzzyhashesSi por alguna razón se desea administrar manualmente entornos virtuales, se pueden usar los siguientes pasos: en su lugar:
python -m venv venv
source venv/bin/activatepip install pip install surfactantpip install . Como ejemplo, así es como se podría instalar el complemento de hash fuzzy desde un repositorio de git (también se pueden usar nombres de paquetes Pypi, directorios de origen locales o archivos de ruedas). 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 .Para instalar dependencias opcionales necesarias para ejecutar Pytest y precomisionar:
pip install -e " .[test,dev] " pip install con la opción -e o --editable también se puede usar para instalar complementos de tensioactivos para el desarrollo.
pip install -e plugins/fuzzyhashes Los ajustes de tensioactivo se pueden cambiar utilizando el subcomando surfactant config , o editando a mano el archivo de configuración de configuración (este no es el mismo que el archivo JSON utilizado para configurar la configuración para una muestra particular que se describe más adelante). La página de documentación de configuración tiene una lista de opciones disponibles que están integradas en tensioactivos.
El uso surfactant config es muy similar al uso básico de la git config . La clave al que se accede el valor estará en la section.option del formulario. Donde section típicamente es un nombre o core del complemento, y option es la opción de establecer. Como ejemplo, la opción core.recorded_institution se puede usar para configurar la institución grabada utilizada para identificar quién era el creador de un SBOM generado.
Establecer esta opción en LLNL podría hacerse con el siguiente comando:
surfactant config core.recorded_institution LLNLObtener el valor establecido actualmente para la opción se realizaría con:
surfactant config core.recorded_institution Si lo desea, el archivo de configuración de configuración también se puede editar manualmente. La ubicación del archivo dependerá de su plataforma. En las plataformas de tipo UNIX (incluidos los macOS), se sigue la especificación del directorio XDG y la configuración se almacenará en ${XDG_CONFIG_HOME}/surfactant/config.toml . Si la variable de entorno XDG_CONFIG_HOME no está configurada, la ubicación predetermina a ~/.config . En Windows, el archivo se almacena en la carpeta Roaming AppData en %APPDATA%\surfactant\config.toml .
El archivo en sí es un archivo TOML, y para el complemento de ejemplo mencionado anteriormente puede verse algo así:
[ core ]
recorded_institution = " LLNL " Para probar el tensioactivo, necesitará un archivo/carpeta de muestra. Si no tiene uno a mano, puede descargar y usar el archivo .zip portátil de https://github.com/sharex/sharex/releases o el archivo linux .tar.gz de https://github.com/gmlc-tdc/helics/releases. Alternativamente, puede elegir una muestra de https://lc.llnl.gov/gitlab/cir-software-assurance/unpacker-to-sbom-test-files
Un archivo de configuración para una muestra contiene la información sobre la muestra para recopilar información. Ejemplo Los archivos de configuración de muestra JSON se pueden encontrar en la carpeta de ejemplos de este repositorio.
surfactant se está ejecutando a las carpetas de muestra, no puede ser un archivo. Tenga en cuenta que incluso en Windows, los separadores de estilo UNIX / directorio deben usarse en rutas.extractPaths . Esto se utiliza para recopilar metadatos sobre la muestra general y se agregará como una relación "contiene" con todas las entradas de software que se encuentran en los diversos extractPaths .extractPaths estarían si se instalarían correctamente en un sistema real, es decir, "c:/", "c:/archivos de programa/", etc. Tenga en cuenta que incluso en Windows, se deben usar separadores de estilo UNIX / directorio en la ruta. Si no se da, los extractPaths se utilizarán como rutas de instalación.includeAllFiles como excludeFileExts , las extensiones especificadas en excludeFileExts aún se excluirán. Un archivo de configuración básico se puede construir fácilmente utilizando el comando create-config . Esto tomará una ruta como argumento de línea de comandos y guardará un archivo con el nombre predeterminado del directorio final que se le pasó como un archivo JSON. es decir, /home/user/Desktop/myfolder creará myfolder.json .
$ surfactant create-config [INPUT_PATH]El indicador --output se puede usar para especificar el nombre de salida de configuración. El --install-Prefix se puede usar para especificar el prefijo de instalación, el valor predeterminado es '/'.
$ surfactant create-config [INPUT_PATH] --output new_output.json --install-prefix ' C:/ ' Digamos que tiene un archivo .tar.gz en el que desea ejecutar tensioactivo. Para este ejemplo, utilizaremos el ejemplo de lanzamiento de helics .tar.gz. En este escenario, la ruta absoluta para este archivo es /home/samples/helics.tar.gz . Al extraer este archivo, obtenemos una carpeta de helics con 4 subcarpetas: bin, incluir, lib64 y compartir.
Si queremos incluir solo las carpetas que contienen archivos binarios para analizar, nuestra configuración más básica sería:
[
{
"extractPaths" : [ " /home/samples/helics/bin " , " /home/samples/helics/lib64 " ]
}
]El SBOM resultante estaría estructurado así:
{
"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 "
}
]
} Un archivo de configuración más detallado puede parecerse al siguiente ejemplo. El SBOM resultante tendría una entrada de software para Helics.tar.gz con una relación "contiene" con todos los binarios que se encuentran en los extractPaths. Proporcionar el prefijo de instalación de / y un ExtractPath como /home/samples/helics permitirán tensioactivos asignar correctamente las rutas de instalación en el SBOM para binarios en las subcarpetas AS /bin y /lib64 .
[
{
"archive" : " /home/samples/helics.tar.gz " ,
"extractPaths" : [ " /home/samples/helics " ],
"installPrefix" : " / "
}
]El SBOM resultante estaría estructurado así:
{
"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 "
}
]
}Si nuestros helics de muestra Tar.gz el archivo venía con un archivo tardía relacionado para instalar un módulo de extensión de complemento (extraído en una carpeta Helics_Plugin que contiene subcarpetas Bin y Lib64), también podríamos agregarlo al archivo de configuración:
[
{
"archive" : " /home/samples/helics.tar.gz " ,
"extractPaths" : [ " /home/samples/helics " ],
"installPrefix" : " / "
},
{
"archive" : " /home/samples/helics_plugin.tar.gz " ,
"extractPaths" : [ " /home/samples/helics_plugin " ],
"installPrefix" : " / "
}
]El SBOM resultante estaría estructurado así:
{
"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 "
}
]
}Nota: Estos ejemplos se han simplificado para mostrar diferencias en la salida en función de la configuración.
$ surfactant generate [OPTIONS] CONFIG_FILE SBOM_OUTFILE [INPUT_SBOM] Config_file : (requerido) El archivo de configuración creado anteriormente que contiene la información de la muestra
Salida de SBOM : (requerido) El nombre deseado del archivo de salida
Input_sbom : (opcional) Una base sbom, debe usarse con cuidado ya que las relaciones se pueden desordenar cuando los archivos se instalan en diferentes sistemas
--skip_gather : (opcional) omite la recopilación de información sobre los archivos y agregando el software Entirs
--skip_relationships : (opcional) omite la adición de relaciones basadas en metadatos
--skip_install_path : (opcional) omita una ruta de instalación para los archivos descubiertos. Esto puede causar que las relaciones "usos" tampoco se generen
--secorded_institution : (opcional) El nombre de la institución recopila los datos de SBOM (predeterminado: LLNL)
--output_format : (opcional) Cambia el formato de salida para el SBOM (dado como el nombre del módulo completo de un complemento de tensioactivo que implementa el gancho write_sbom )
--input_format : (opcional) Especifica el formato de la entrada SBOM si se usa uno (predeterminado: Cytrics) (dado como nombre completo del módulo de un complemento de tensioactivo que implementa el gancho read_sbom )
--help : (opcional) Muestre el mensaje de ayuda y la salida
Esta sección contiene una lista de entradas relacionadas con cada pieza de software que se encuentra en la muestra. Los metadatos que incluyen el tamaño del archivo, el proveedor, la versión, etc. se incluyen en esta sección junto con un UUID para identificar de manera única la entrada del software.
Esta sección contiene información sobre cómo están vinculadas cada una de las entradas de software en la sección anterior.
Usos : este tipo de relación significa que el software X usa el software y es decir, es un módulo de ayuda para x
Contiene : este tipo de relación significa que el software X contiene el software Y (a menudo el software X es un instalador o archivo como un archivo zip)
Esta sección contiene información sobre observaciones notables sobre componentes de software individuales. Esto podría ser vulnerabilidades, características observadas, etc.
Una carpeta que contiene múltiples archivos SBOM JSON separados se puede combinar utilizando merge_sbom.py con un comando como el siguiente que obtiene una lista de archivos usando LS, y luego usa XARGS para pasar la lista resultante de archivos a fusion_sbom.py como argumentos.
ls -d ~/Folder_With_SBOMs/Surfactant-* | xargs -d 'n' surfactant merge --config_file=merge_config.json --sbom_outfile combined_sbom.json
Si se ofrece la opción de archivo de configuración, se creará una entrada del sistema de nivel superior para que todas las demás entradas de software estén vinculadas (directa o indirectamente en función de otras relaciones). La especificación de un UUID vacío hará que se genere un UUID aleatorio para la nueva entrada del sistema, de lo contrario usará el proporcionado.
Los detalles sobre el comando de fusión se pueden encontrar en la página de documentos aquí.
Surfactante admite el uso de complementos para agregar características adicionales. Los usuarios pueden instalar complementos con surfactant plugin install y deshabilitarlos o habilitarlos con surfactant plugin disable y surfactant plugin enable , respectivamente. surfactant plugin install detecta el entorno virtual activo y ejecuta el comando apropiado, es decir, pipx o pip . Alternativamente, los usuarios pueden administrar manualmente sus entornos con pipx inject surfactant cuando usan PIPX o pip install .
Se puede encontrar información detallada sobre las opciones de configuración para el sistema de complementos y cómo desarrollar nuevos complementos.
Las guías de usuario completas para tensioactivo están disponibles en línea y en el directorio de documentos.
Para preguntas o apoyo, cree una nueva discusión sobre las discusiones de GitHub o abra un problema para informes de errores y solicitudes de funciones.
Las contribuciones son bienvenidas. Las correcciones de errores o los cambios menores se prefieren mediante una solicitud de extracción al repositorio de tensioactivo GitHub. Para obtener más información sobre la contribución, consulte el archivo contribuyente.
Surfactant se libera bajo la licencia MIT. Consulte la licencia y los archivos de notificación para más detalles. Todas las nuevas contribuciones deben hacerse bajo esta licencia.
Identificador SPDX-license: MIT
LLNL-Code-850771
