Surfactant
Update for SecTor 2024
Documentation
Le tensioactif peut être utilisé pour recueillir des informations à partir d'un ensemble de fichiers pour générer un SBOM, ainsi que la manipulation des SBOM et l'analyse des informations. Il tire les informations des types de fichiers reconnus (tels que les fichiers PE, ELF ou MSI) contenus dans une structure de répertoire correspondant à un progiciel extrait. Par défaut, les informations sont les métadonnées "au niveau de la surface" contenues dans les fichiers qui ne nécessitent pas d'exécuter les fichiers ou la décompilation.
Pour plus de facilité d'utilisation, nous vous recommandons d'utiliser PIPX car il gère de manière transparente la création et l'utilisation d'environnements virtuels Python, ce qui permet d'éviter les conflits de dépendance avec d'autres applications Python installées. Installez pipx en suivant leurs instructions d'installation.
pipx install (avec Python> = 3,8) pipx install surfactantRemarque: La prise en charge du fichier Mach-O nécessite l'installation de surfactant avec les dépendances facultatives
macho(par exemplepipx install surfactant[macho]).
pipx inject surfactant . Par exemple, c'est ainsi que le plugin de hachage flou pourrait être installé à partir d'un référentiel GIT (noms de packages PYPI, répertoires source locaux ou fichiers de roue peut également être utilisé). pipx inject surfactant git+https://github.com/LLNL/Surfactant#subdirectory=plugins/fuzzyhashesSi pour une raison quelconque, la gestion manuelle des environnements virtuels est souhaité, les étapes suivantes peuvent être utilisées à la place:
python -m venv venv
source venv/bin/activatepip install pip install surfactantpip install . Par exemple, c'est ainsi que le plugin de hachage flou pourrait être installé à partir d'un référentiel GIT (noms de packages PYPI, répertoires source locaux ou fichiers de roue peut également être utilisé). 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 .Pour installer des dépendances facultatives requises pour exécuter PyTest et pré-Commit:
pip install -e " .[test,dev] " pip install avec l'option -e ou --editable peut également être utilisée pour installer des plugins de surfactant pour le développement.
pip install -e plugins/fuzzyhashes Les paramètres de surfactant peuvent être modifiés à l'aide de la sous-commande surfactant config , ou en modifiant la main le fichier de configuration des paramètres (ce n'est pas le même que le fichier JSON utilisé pour configurer les paramètres pour un échantillon particulier décrit plus loin). La page de documentation des paramètres propose une liste des options disponibles qui sont des tensioactifs intégrés.
L'utilisation surfactant config est très similaire à l'utilisation de base de git config . La clé dont la valeur est accessible se trouvera dans la section.option du formulaire. Option où section est généralement un nom ou un core de plugin, et option est l'option à définir. À titre d'exemple, l'option core.recorded_institution peut être utilisée pour configurer l'institution enregistrée utilisée pour identifier qui était le créateur d'un SBOM généré.
La définition de cette option sur LLNL pourrait être effectuée avec la commande suivante:
surfactant config core.recorded_institution LLNLL'obtention de la valeur actuellement définie pour l'option serait alors effectuée avec:
surfactant config core.recorded_institution Si vous le souhaitez, le fichier de configuration des paramètres peut également être modifié manuellement. L'emplacement du fichier dépendra de votre plate-forme. Sur les plates-formes de type UNIX (y compris MacOS), la spécification du répertoire XDG est suivie et les paramètres seront stockés dans ${XDG_CONFIG_HOME}/surfactant/config.toml . Si la variable d'environnement XDG_CONFIG_HOME n'est pas définie, l'emplacement par défaut ~/.config . Sur Windows, le fichier est stocké dans le dossier Appdata itinérant à %APPDATA%\surfactant\config.toml .
Le fichier lui-même est un fichier Toml, et pour l'exemple mentionné précédemment peut ressembler à ceci:
[ core ]
recorded_institution = " LLNL " Afin de tester le surfactant, vous aurez besoin d'un exemple de fichier / dossier. Si vous n'en avez pas à portée de main, vous pouvez télécharger et utiliser le fichier .zip portable à partir de https://github.com/sharex/sharex/releases ou du fichier Linux .tar.gz à partir de https://github.com/gmlc-tdc/helics/releases. Alternativement, vous pouvez choisir un échantillon sur https://lc.llnl.gov/gitlab/cir-software-assurance/unpacker-t-sbom-test-files
Un fichier de configuration pour un échantillon contient les informations sur l'échantillon pour collecter des informations. Exemple d'exemples de fichiers de configuration JSON se trouvent dans le dossier Exemples de ce référentiel.
surfactant est exécuté aux dossiers d'échantillons, ne peut pas être un fichier. Notez que même sous Windows, les séparateurs de style / répertoire UNIX doivent être utilisés dans les chemins.extractPaths ont été extraits. Ceci est utilisé pour collecter des métadonnées sur l'échantillon global et sera ajouté en tant que relation "contient" à toutes les entrées logicielles trouvées dans les différents extractPaths .extractPaths seraient s'ils sont installés correctement sur un système réel, c'est-à-dire "C: /", "C: / Program Files /", etc. Notez que même sur Windows, les séparateurs de style / répertoire UNIX doivent être utilisés dans le chemin. Si ce n'est pas donné, les extractPaths seront utilisés comme chemins d'installation.includeAllFiles et excludeFileExts sont définis, les extensions spécifiées dans excludeFileExts seront toujours exclues. Un fichier de configuration de base peut être facilement construit à l'aide de la commande create-config . Cela prendra un chemin comme un argument de ligne de commande et enregistrera un fichier avec le nom par défaut du répertoire final qui lui est passé en tant que fichier JSON. IE, /home/user/Desktop/myfolder créera myfolder.json .
$ surfactant create-config [INPUT_PATH]L'indicateur --Output peut être utilisé pour spécifier le nom de sortie de configuration. Le --install-prefix peut être utilisé pour spécifier le préfixe d'installation, la valeur par défaut est «/».
$ surfactant create-config [INPUT_PATH] --output new_output.json --install-prefix ' C:/ ' Disons que vous avez un fichier .tar.gz sur lequel vous souhaitez exécuter un surfactant. Pour cet exemple, nous utiliserons l'exemple de la version .tar.tar.gz. Dans ce scénario, le chemin absolu de ce fichier est /home/samples/helics.tar.gz . Lors de l'extraction de ce fichier, nous obtenons un dossier Helics avec 4 sous-reprendurs: bac, inclure, lib64 et partager.
Si nous voulons inclure uniquement les dossiers contenant des fichiers binaires à analyser, notre configuration la plus élémentaire serait:
[
{
"extractPaths" : [ " /home/samples/helics/bin " , " /home/samples/helics/lib64 " ]
}
]Le SBOM résultant serait structuré comme ceci:
{
"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 fichier de configuration plus détaillé peut ressembler à l'exemple ci-dessous. Le SBOM résultant aurait une entrée logicielle pour Helics.tar.gz avec une relation "contient" avec tous les binaires trouvés dans les extractpathes. La fourniture du préfixe d'installation de / et un extractpathe AS /home/samples/helics permettra à un surfactant affecter correctement les chemins d'installation dans le SBOM pour les binaires des sous-dossiers AS /bin et /lib64 .
[
{
"archive" : " /home/samples/helics.tar.gz " ,
"extractPaths" : [ " /home/samples/helics " ],
"installPrefix" : " / "
}
]Le SBOM résultant serait structuré comme ceci:
{
"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 notre exemple de fichier Helics Tar.gz est venu avec un fichier Tar.gz connexe pour installer un module d'extension de plugin (extrait dans un dossier Helics_plugin qui contient des sous-dossiers bin et lib64), nous pourrions également l'ajouter dans le fichier de configuration:
[
{
"archive" : " /home/samples/helics.tar.gz " ,
"extractPaths" : [ " /home/samples/helics " ],
"installPrefix" : " / "
},
{
"archive" : " /home/samples/helics_plugin.tar.gz " ,
"extractPaths" : [ " /home/samples/helics_plugin " ],
"installPrefix" : " / "
}
]Le SBOM résultant serait structuré comme ceci:
{
"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 "
}
]
}Remarque: Ces exemples ont été simplifiés pour montrer les différences de sortie en fonction de la configuration.
$ surfactant generate [OPTIONS] CONFIG_FILE SBOM_OUTFILE [INPUT_SBOM] Config_file : (requis) le fichier de configuration créé plus tôt qui contient les informations sur l'échantillon
Sortie SBOM : (requise) Le nom souhaité du fichier de sortie
Input_sbom : (facultatif) Un SBOM de base, doit être utilisé avec soin car les relations peuvent être gâchées lorsque les fichiers sont installés sur différents systèmes
--Skip_gather : (facultatif) saute la collecte d'informations sur les fichiers et l'ajout de logiciels entières
--Skip_relationships : (facultatif) saute l'ajout de relations basées sur les métadonnées
--skip_install_path : (facultatif) sauts, y compris un chemin d'installation pour les fichiers découverts. Cela peut provoquer des relations "utilise" pour ne pas être générée
--Cecord_institution : (facultatif) Le nom de l'institution collectant les données SBOM (par défaut: LLNL)
--output_format : (facultatif) modifie le format de sortie pour le SBOM (donné comme nom de module complet d'un plugin de surfactant implémentant le crochet write_sbom )
- INTUPT_FORMAT : (Facultatif) Spécifie le format du SBOM d'entrée si l'on est utilisé (par défaut: Cytrics) (donné comme nom de module complet d'un plugin de surfactant implémentant le crochet read_sbom )
- help : (facultatif) Afficher le message d'aide et la sortie
Cette section contient une liste des entrées relatives à chaque logiciel trouvé dans l'échantillon. Les métadonnées comprenant la taille du fichier, le fournisseur, la version, etc. sont incluses dans cette section ainsi qu'un UUID pour identifier de manière unique l'entrée du logiciel.
Cette section contient des informations sur la façon dont chacune des entrées du logiciel dans la section précédente est liée.
Utilisations : Ce type de relation signifie que le logiciel X utilise le logiciel Y, c'est-à-dire un module d'assistance à x
Contient : Ce type de relation signifie que le logiciel X contient un logiciel Y (souvent le logiciel X est un installateur ou une archive comme un fichier zip)
Cette section contient des informations sur les observations notables sur les composants logiciels individuels. Cela pourrait être des vulnérabilités, des caractéristiques observées, etc.
Un dossier contenant plusieurs fichiers SBOM JSON distincts peut être combiné à l'aide de Merge_sbom.py avec une commande telle que celle ci-dessous qui obtient une liste de fichiers à l'aide de LS, puis utilise xargs pour passer la liste des fichiers résultante à Merge_sbom.py comme arguments.
ls -d ~/Folder_With_SBOMs/Surfactant-* | xargs -d 'n' surfactant merge --config_file=merge_config.json --sbom_outfile combined_sbom.json
Si l'option de fichier de configuration est donnée, une entrée de système de haut niveau sera créée à laquelle toutes les autres entrées de logiciel sont liées (directement ou indirectement en fonction d'autres relations). La spécification d'un UUID vide fera générer un UUID aléatoire pour la nouvelle entrée du système, sinon il utilisera celui fourni.
Les détails sur la commande Merge peuvent être trouvés dans la page Docs ici.
Le tensioactif prend en charge l'utilisation des plugins pour ajouter des fonctionnalités supplémentaires. Les utilisateurs peuvent installer des plugins avec surfactant plugin install et les désactiver ou leur activer avec surfactant plugin disable et surfactant plugin enable respectivement. surfactant plugin install détecte l'environnement virtuel actif et exécute la commande appropriée, c'est-à-dire pipx ou pip . Alternativement, les utilisateurs peuvent gérer manuellement leurs environnements avec pipx inject surfactant lors de l'utilisation de PIPX ou pip install .
Des informations détaillées sur les options de configuration du système de plugins et comment développer de nouveaux plugins peuvent être trouvées ici.
Les guides d'utilisateur complet pour le tensioactif sont disponibles en ligne et dans le répertoire DOCS.
Pour des questions ou un soutien, veuillez créer une nouvelle discussion sur les discussions GitHub, ou ouvrir un problème pour les rapports de bogues et les demandes de fonctionnalités.
Les contributions sont les bienvenues. Les corrections de bugs ou les modifications mineures sont préférées via une demande de traction vers le référentiel GitHub surfactant. Pour plus d'informations sur la contribution, consultez le fichier contributif.
Le tensioactif est libéré sous la licence du MIT. Consultez la licence et notez les fichiers pour plus de détails. Toutes les nouvelles contributions doivent être faites sous cette licence.
Identificateur de licence SPDX: MIT
LLNL-Code-850771
