Surfactantダウンロード - Surfactantソースコードのダウンロード

ドキュメント

説明

界面活性剤を使用して、SBOMを操作し、その情報を分析するとともに、SBOMを生成するファイルのセットから情報を収集できます。抽出されたソフトウェアパッケージに対応するディレクトリ構造内に含まれる認識されたファイルタイプ（PE、ELF、またはMSIファイルなど）から情報を引き出します。デフォルトでは、情報はファイルに含まれているファイルに含まれる「表面レベル」メタデータです。

インストール

ユーザー向け：

使いやすさのために、PIPXはPython仮想環境の作成と使用を透過的に処理するため、PIPXを使用することをお勧めします。インストール手順に従って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> = 3.8を使用して仮想環境を作成してアクティブ化します[オプションですが、グローバルインストールよりも強くお勧めします]

python -m venv venv
source venv/bin/activate

pip install付きの界面活性剤を取り付けます

pip install surfactant

pip installを使用してプラグインをインストールします。例として、これはファジーハッシュプラグインをGitリポジトリ（Pypiパッケージ名、ローカルソースディレクトリ、またはホイールファイルも使用する方法）からインストールする方法です。

pip install git+https://github.com/LLNL/Surfactant#subdirectory=plugins/fuzzyhashes

開発者向け：

Pythonを使用して仮想環境を作成> = 3.8 [オプションですが、推奨]

python -m venv venv
source venv/bin/activate

クローンSBOM界面活性剤

git clone [email protected]:LLNL/Surfactant.git

編集可能な界面活性剤のインストールを作成します（コードの変更はすぐに有効になります）：

pip 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からポータブル.zipファイルをダウンロードして使用できます。または、https：//lc.llnl.gov/gitlab/cir-software-assurance/unpacker-to-sbom-test-filesからサンプルを選択できます

サンプルの構成ファイルを構築します

サンプルの構成ファイルには、情報を収集するサンプルに関する情報が含まれています。例JSONサンプル構成ファイルは、このリポジトリの例フォルダーにあります。

抽出パス：（必須） surfactantサンプルフォルダーに実行されている現在の作業ディレクトリの位置からの絶対パスまたは相対パスは、ファイルではありません。 Windowsでも、PathsでUNIXスタイル/ディレクトリセパレータを使用する必要があることに注意してください。
アーカイブ：（オプション）zip、exeインストーラー、またはextractPathsのフォルダーが抽出されたその他のアーカイブファイルのファイル名を含むフルパス。これは、全体的なサンプルに関するメタデータを収集するために使用され、さまざまなextractPathsにあるすべてのソフトウェアエントリと「含まれる」関係として追加されます。
InstallPrefix ：（オプション） extractPathsのファイルが実際のシステムに正しくインストールされている場合、つまり "c：/"、 "c：/programファイル/"など。WindowsでもパスでUNIXスタイル/ディレクトリセパレーターを使用する必要があることに注意してください。与えられない場合、 extractPathsインストールパスとして使用されます。
includeallfiles ：（オプション）存在してTrueに設定する場合は、界面活性剤によって認識されているものだけでなく、SBOM内のすべてのファイルを含めます。
includefileexts ：（オプション）界面活性剤によって認識されていなくても、含めるファイル拡張子のリスト。
除外：（オプション）界面活性剤によって認識された場合でも、除外するファイル拡張機能のリスト。 includeAllFilesとexcludeFileExts両方とも設定されている場合、 excludeFileExtsの指定された拡張機能は引き続き除外されることに注意してください。

CONFIGコマンドを作成します

基本的な構成ファイルはcreate-configコマンドを使用して簡単に構築できます。これにより、コマンドライン引数としてパスが表示され、endディレクトリのデフォルト名がJSONファイルとして渡されたファイルが保存されます。 IE、 /home/user/Desktop/myfolder myfolder.jsonを作成します。

$  surfactant create-config [INPUT_PATH]

-outputフラグを使用して、構成出力名を指定できます。 -install-prefixを使用してインストールプレフィックスを指定することができます。デフォルトは「/」です。

$  surfactant create-config [INPUT_PATH] --output new_output.json --install-prefix ' C:/ '

構成ファイルの例

界面活性剤を実行したい.tar.gzファイルがあるとしましょう。この例では、Helicsリリース.tar.gzの例を使用します。このシナリオでは、このファイルの絶対パスは/home/samples/helics.tar.gzです。このファイルを抽出すると、4つのサブフォルダー、bin、include、lib64、およびshareを備えたヘリックフォルダーを取得します。

例1：単純な構成ファイル

分析するバイナリファイルを含むフォルダーのみを含めたい場合、最も基本的な構成は次のとおりです。

[
  {
    "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 "
    }
  ]
}

例2：詳細な構成ファイル

より詳細な構成ファイルは、以下の例のように見えるかもしれません。結果のSBOMには、抽出物内で見つかったすべてのバイナリと「含まれる」関係を持つHelics.tar.gzのソフトウェアエントリがあります。 /および抽出物のインストールプレフィックスを/home/samples/helicsの抽出物を提供すると/lib64界面活性剤が界面活性剤を正しく割り当てることができます/bin

[
  {
    "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 "
    }
  ]
}

例3：関連するバイナリの追加

サンプルヘリックス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 ：（必須）サンプルの情報を含む以前に作成されたconfigファイル
SBOM出力：（必須）出力ファイルの目的の名前
input_sbom ：（オプション）ベースSBOMは、異なるシステムにファイルがインストールされている場合に関係を台無しにする可能性があるため、注意して使用する必要があります
-SKIP_GATHER ：（オプション）ファイル上の情報の収集をスキップし、ソフトウェア全体を追加する
-SKIP_RELATIONSHITS ：（オプション）メタデータに基づいて関係の追加をスキップします
-SKIP_INSTALL_PATH ：（オプション）発見されたファイルのインストールパスを含むスキップ。これにより、関係を「使用」することも生成されない可能性があります
-recorded_institution ：（オプション）SBOMデータを収集する機関の名前（デフォルト：LLNL）
-OUTPUT_FORMAT ：（オプション）SBOMの出力形式を変更します（ write_sbomフックを実装する界面活性剤プラグインの完全なモジュール名として与えられます）
- input_format ：（オプション）入力SBOMの形式を指定している場合（デフォルト：cytrics）（ read_sbomフックを実装する界面活性剤プラグインの完全なモジュール名として与えられます）
- ヘルプ：（オプション）ヘルプメッセージと出口を表示します

SBOM出力の理解

ソフトウェア

このセクションには、サンプルにあるソフトウェアの各部分に関連するエントリのリストが含まれています。ファイルサイズ、ベンダー、バージョンなどを含むメタデータは、ソフトウェアエントリを一意に識別するためにUUIDとともにこのセクションに含まれています。

関係

このセクションには、前のセクションの各ソフトウェアエントリがリンクされている方法に関する情報が含まれています。

使用：この関係タイプは、xソフトウェアがyソフトウェアを使用することを意味します。つまり、xへのヘルパーモジュールです
含まれる：この関係タイプは、XソフトウェアにYソフトウェアが含まれることを意味します（多くの場合、Xソフトウェアはzipファイルなどのインストーラーまたはアーカイブです）

観察：

このセクションには、個々のソフトウェアコンポーネントに関する顕著な観察に関する情報が含まれています。これは、脆弱性、観察された機能などです

SBOMのマージ

複数の個別のSBOM JSONファイルを含むフォルダーは、merge_sbom.pyを使用してLSを使用してファイルのリストを取得し、xargsを使用して結果のファイルのリストを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アクティブな仮想環境を検出し、適切なコマンドIE pipxまたはpipを実行します。または、PIPXまたはpip installを使用する場合、ユーザーはpipx inject surfactantを使用して環境を手動で管理できます。

プラグインシステムの構成オプションと新しいプラグインを開発する方法の詳細については、こちらをご覧ください。