Surfactant
Update for SecTor 2024
Dokumentation
Tensid kann verwendet werden, um Informationen aus einer Reihe von Dateien zu sammeln, um ein SBOM zusammen mit der Manipulation von SBOMs und der Analyse der darin enthaltenen Informationen zu sammeln. Es zieht Informationen aus anerkannten Dateitypen (z. B. PE-, ELF- oder MSI -Dateien), die in einer Verzeichnisstruktur enthalten sind, die einem extrahierten Softwarepaket entspricht. Standardmäßig sind die Informationen "Oberflächenebene" -Metadaten, die in den Dateien enthalten sind, bei denen keine Dateien oder Dekompilierung ausgeführt werden müssen.
Für eine einfache Anwendung empfehlen wir die Verwendung von PIPX, da es das Erstellen und Verwenden von virtuellen Python -Umgebungen transparent behandelt, wodurch Abhängigkeitskonflikte mit anderen installierten Python -Apps vermieden werden. Installieren Sie pipx , indem Sie ihren Installationsanweisungen befolgen.
pipx install installieren (mit Python> = 3,8) pipx install surfactantHINWEIS: Mach-O-Dateiunterstützung erfordert das Installieren von Tensid mit den optionalen Abhängigkeiten von
macho(z.pipx install surfactant[macho]).
pipx inject surfactant . Auf diese Weise kann das Fuzzy -Hashing -Plugin aus einem Git -Repository installiert werden (PYPI -Paketnamen, lokale Quellverzeichnisse oder Raddateien können ebenfalls verwendet werden). pipx inject surfactant git+https://github.com/LLNL/Surfactant#subdirectory=plugins/fuzzyhashesWenn aus irgendeinem Grund die manuelle Verwaltung virtueller Umgebungen gewünscht wird, können stattdessen die folgenden Schritte verwendet werden:
python -m venv venv
source venv/bin/activatepip install pip install surfactantpip install . Auf diese Weise kann das Fuzzy -Hashing -Plugin aus einem Git -Repository installiert werden (PYPI -Paketnamen, lokale Quellverzeichnisse oder Raddateien können ebenfalls verwendet werden). 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 .So installieren Sie optionale Abhängigkeiten, die für das Ausführen von PyTest und vor dem Kommunikation erforderlich sind:
pip install -e " .[test,dev] " pip install mit der Option -e oder --editable kann auch zur Installation von Tensid -Plugins für die Entwicklung verwendet werden.
pip install -e plugins/fuzzyhashes Tensideinstellungen können unter Verwendung des surfactant config -Unterbefehls oder der Bearbeitung der Einstellungskonfigurationsdatei geändert werden (dies ist nicht mit der JSON -Datei mit der Konfiguration der Einstellungen für ein bestimmtes Beispiel, das später beschrieben wird). Auf der Seite "Einstellungsdokumentation" enthält eine Liste der verfügbaren Optionen, die integriert sind.
Die Verwendung surfactant config ist der grundlegenden Verwendung von git config sehr ähnlich. Der Schlüssel, auf dessen Wert zugegriffen wird, befindet sich im Formulierungsabschnitt section.option OPTION, wobei section in der Regel ein Plugin -Name oder ein Plugin -Name oder core ist, und option ist die Option zum Festlegen. Beispielsweise kann die Option core.recorded_institution verwendet werden, um die aufgezeichnete Institution zu konfigurieren, mit der der Ersteller eines generierten SBOM verwendet wurde.
Das Einstellen dieser Option in LLNL kann mit dem folgenden Befehl erfolgen:
surfactant config core.recorded_institution LLNLDas Erhalten des aktuell festgelegten Wertes für die Option würde dann mit:
surfactant config core.recorded_institution Falls gewünscht, kann die Einstellungskonfigurationsdatei auch manuell bearbeitet werden. Der Ort der Datei hängt von Ihrer Plattform ab. Auf Unix-ähnlichen Plattformen (einschließlich macOS) wird die XDG-Verzeichnisspezifikation beobachtet und die Einstellungen werden in ${XDG_CONFIG_HOME}/surfactant/config.toml gespeichert. Wenn die Umgebungsvariable XDG_CONFIG_HOME nicht festgelegt ist, wird der Speicherort auf ~/.config standardmäßig festgelegt. Unter Windows wird die Datei im Ordner Roaming AppData unter %APPDATA%\surfactant\config.toml gespeichert.
Die Datei selbst ist eine TOML -Datei, und für das zuvor genannte Beispiel -Plugin kann so etwas so aussehen:
[ core ]
recorded_institution = " LLNL " Um das Tensid zu testen, benötigen Sie eine Beispieldatei/einen Beispiel. Wenn Sie keinen zur Hand haben, können Sie die tragbare .zip-Datei von https://github.com/sharex/sharex/releases oder der linux .tar.gz-Datei von https://github.com/gmlc-tdc/helics/relases verwenden. Alternativ können Sie ein Beispiel von https://lc.llnl.gov/gitlab/cir-software-assurance/unpacker-to--bom-te-te-test-files auswählen
Eine Konfigurationsdatei für ein Beispiel enthält die Informationen zum Beispiel, um Informationen zu sammeln. Beispiel JSON -Beispielkonfigurationsdateien finden Sie im Beispiele -Ordner dieses Repositorys.
surfactant von den Beispielordnern ausgeführt wird, kann keine Datei sein. Beachten Sie, dass selbst unter Windows UNIX -Stil- / Verzeichnis -Separatoren in Pfaden verwendet werden sollten.extractPaths extrahiert wurden. Dies wird verwendet, um Metadaten über die Gesamtstichprobe zu sammeln, und wird als "enthält" Beziehung zu allen Softwareeinträgen hinzugefügt, die in den verschiedenen extractPaths enthalten sind.extractPaths in einem tatsächlichen System korrekt installiert würden, dh "c:/", "c:/Programmdateien/" usw. Beachten Sie, dass auch unter Windows, Unix -Stil- / Verzeichnistrenntrennzeichen im Pfad verwendet werden sollten. Wenn nicht gegeben, werden die extractPaths als Installationspfade verwendet.excludeFileExts weiterhin ausgeschlossen werden, wenn beide includeAllFiles und excludeFileExts festgelegt sind. Eine grundlegende Konfigurationsdatei kann einfach mit dem Befehl create-config erstellt werden. Dies nimmt einen Pfad als Befehlszeilenargument ein und speichert eine Datei mit dem Standardnamen des Endverzeichnisses als JSON -Datei. dh, /home/user/Desktop/myfolder erstellt myfolder.json .
$ surfactant create-config [INPUT_PATH]Das Flag -Ausgangsflag kann verwendet werden, um den Konfigurationsausgabennamen anzugeben. Mit dem-installieren-prefix kann das Installationspräfix angeben, die Standardeinstellung ist '/'.
$ surfactant create-config [INPUT_PATH] --output new_output.json --install-prefix ' C:/ ' Nehmen wir an, Sie haben eine .tar.gz -Datei, auf der Sie Tensid ausführen möchten. In diesem Beispiel werden wir das Helics -Release. Tar.gz Beispiel verwenden. In diesem Szenario ist der absolute Pfad für diese Datei /home/samples/helics.tar.gz . Nachdem wir diese Datei extrahiert haben, erhalten wir einen Helics-Ordner mit 4 Unterordnern: Bin, include, lib64 und Share.
Wenn wir nur die Ordner einbeziehen möchten, die binäre Dateien enthalten, die zu analysieren sind, wäre unsere grundlegendste Konfiguration:
[
{
"extractPaths" : [ " /home/samples/helics/bin " , " /home/samples/helics/lib64 " ]
}
]Das resultierende SBOM wäre so strukturiert:
{
"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 "
}
]
} Eine detailliertere Konfigurationsdatei könnte wie das Beispiel unten aussehen. Der resultierende SBOM hätte einen Softwareeintrag für die Helics.tar.gz mit einer "enthält" Beziehung zu allen Binärdateien, die in den Extraktpfaden gefunden wurden. Durch die Bereitstellung des Installationspräfixes von / und A ExtractPaths as /home/samples/helics können die Tensid die Installationspfade in der SBOM für Binärdateien in den Unterordnern als /bin und /lib64 korrekt zuweisen.
[
{
"archive" : " /home/samples/helics.tar.gz " ,
"extractPaths" : [ " /home/samples/helics " ],
"installPrefix" : " / "
}
]Das resultierende SBOM wäre so strukturiert:
{
"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 "
}
]
}Wenn unsere Beispiel -Helics tar.gz -Datei mit einer zugehörigen Tar.gz -Datei zur Installation eines Plugin -Erweiterungsmoduls (extrahiert in einen Helics_plugin -Ordner extrahiert wird, der Bin- und LIB64 -Unterordner enthält), können wir dies auch in die Konfigurationsdatei aufnehmen:
[
{
"archive" : " /home/samples/helics.tar.gz " ,
"extractPaths" : [ " /home/samples/helics " ],
"installPrefix" : " / "
},
{
"archive" : " /home/samples/helics_plugin.tar.gz " ,
"extractPaths" : [ " /home/samples/helics_plugin " ],
"installPrefix" : " / "
}
]Das resultierende SBOM wäre so strukturiert:
{
"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 "
}
]
}Hinweis: Diese Beispiele wurden vereinfacht, um Unterschiede in der Ausgabe basierend auf der Konfiguration zu zeigen.
$ surfactant generate [OPTIONS] CONFIG_FILE SBOM_OUTFILE [INPUT_SBOM] Config_file : (erforderlich) Die zuvor erstellte Konfigurationsdatei, die die Informationen auf dem Beispiel enthält
SBOM -Ausgabe : (Erforderlich) Der gewünschte Name der Ausgabedatei
Input_sbom : (optional) Ein Basis -SBOM sollte mit Sorgfalt verwendet werden, da die Beziehungen durcheinander gebracht werden können, wenn Dateien auf verschiedenen Systemen installiert werden
--skip_gather : (optional) überspringt das Sammeln von Informationen zu Dateien und füge Software-Vorspeisen hinzu
--skip_relationships : (optional) überspringt das Hinzufügen von Beziehungen basierend auf Metadaten
--skip_install_path : (optional) überspringt einschließlich eines Installationspfads für die entdeckten Dateien. Dies kann dazu führen, dass "Verwendungsbeziehungen" auch nicht generiert werden
-aufgezeichnet .
-Output_Format : (optional) ändert das Ausgabeformat für das SBOM (als Vollmodulname eines Tensid-Plugins, das den write_sbom Hook implementiert)
-Input_Format : (optional) Gibt das Format des Eingabe-SBOM an, wenn einer verwendet wird (Standard: Cytrics) (als vollständiger Modulname eines Tensid-Plugins angegeben, das den read_sbom Hook implementiert)
-HELP : (Optional) Zeigen Sie die Hilfebotschaft und beenden Sie an
Dieser Abschnitt enthält eine Liste von Einträgen, die sich auf jede im Beispiel gefundene Software beziehen. Metadaten einschließlich Dateigröße, Anbieter, Version usw. sind in diesem Abschnitt zusammen mit einem UUID enthalten, um den Softwareeintrag eindeutig zu identifizieren.
Dieser Abschnitt enthält Informationen darüber, wie jede der Softwareeinträge im vorherigen Abschnitt verknüpft ist.
Verwendungen : Dieser Beziehungstyp bedeutet, dass X -Software Y -Software verwendet, dh ein Helfermodul für x ist
Enthält : Dieser Beziehungstyp bedeutet, dass X -Software Y -Software enthält (häufig ist X -Software ein Installationsprogramm oder ein Archiv wie eine ZIP -Datei)
Dieser Abschnitt enthält Informationen zu bemerkenswerten Beobachtungen zu einzelnen Softwarekomponenten. Dies können Schwachstellen, beobachtete Merkmale usw. sein
Ein Ordner, der mehrere separate SBOM -JSON -Dateien enthält, kann mit merge_sbom.py mit einem Befehl kombiniert werden, das unten eine Liste von Dateien mit LS erhält, und verwendet dann XARGs, um die resultierende Liste der Dateien an merge_sbom.py als Argumente zu übergeben.
ls -d ~/Folder_With_SBOMs/Surfactant-* | xargs -d 'n' surfactant merge --config_file=merge_config.json --sbom_outfile combined_sbom.json
Wenn die Option "Konfigurationsdatei" angegeben ist, wird ein Systemeintrag auf höchstem Niveau erstellt, an das alle anderen Softwareeinträge gebunden sind (direkt oder indirekt basierend auf anderen Beziehungen). Wenn Sie eine leere UUID angeben, wird ein zufälliger UUID für den neuen Systemeintrag generiert, andernfalls wird das vorgesehene verwendet.
Details zum Merge -Befehl finden Sie auf der Seite "Docs" hier.
Tensid unterstützt mithilfe von Plugins, um zusätzliche Funktionen hinzuzufügen. Benutzer können Plugins mit surfactant plugin install und deaktivieren oder mit surfactant plugin disable bzw. surfactant plugin enable . surfactant plugin install erkennt die aktive virtuelle Umgebung und führt den entsprechenden Befehl aus, IE pipx oder pip . Alternativ können Benutzer ihre Umgebungen manuell mit pipx inject surfactant verwalten, wenn sie PIPX oder pip install verwenden.
Detaillierte Informationen zu Konfigurationsoptionen für das Plugin -System und die Entwicklung neuer Plugins finden Sie hier.
Vollständige Benutzerführer für Tensid sind online und im DOCS -Verzeichnis verfügbar.
Für Fragen oder Unterstützung erstellen Sie bitte eine neue Diskussion zu Github -Diskussionen oder eröffnen Sie ein Problem für Fehlerberichte und Feature -Anfragen.
Beiträge sind willkommen. Fehlerbehebungen oder geringfügige Änderungen werden über eine Pull -Anforderung an das Tensid -Github -Repository bevorzugt. Weitere Informationen zum Beitrag zum Beitrag finden Sie in der beitragenden Datei.
Tensid wird unter der MIT -Lizenz veröffentlicht. Weitere Informationen finden Sie in der Lizenz- und Notizdateien. Alle neuen Beiträge müssen im Rahmen dieser Lizenz geleistet werden.
SPDX-Lizenz-Identifikator: MIT
LLNL-Code-850771
