View a markdown version of this page

プラグイン開発者ガイド - Amazon Inspector
概要クイックスタート: 新しいプラグインの作成IDE セットアッププラグインディレクトリ構造検出プラグインコレクションプラグインプラグインの実行使用可能なスキャナーの一覧表示スキャナーの選択プラグイン衝突ルールデバッグAPI リファレンスエラー処理サンドボックスの制限プラグイン間でのコードの共有

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

プラグイン開発者ガイド

このガイドでは、カスタム Lua プラグインを使用して Amazon Inspector SBOM Generator (inspector-sbomgen) を拡張する方法について説明します。プラグインを使用すると、sbomgen のソースコードを変更したり、再コンパイルしたりすることなく、新しいパッケージエコシステムのサポートを追加できます。

関数カタログの詳細については、「」を参照してくださいプラグイン API リファレンス。テストの記述に関するガイダンスについては、「」を参照してくださいプラグインテストガイド。

概要

Sbomgen プラグインは Lua で記述され、2 ステップのパイプラインに従います。

  • 検出 — アーティファクトのファイルリストをスキャンし、エコシステムに関連するファイルをレポートします。

  • コレクション — 検出された各ファイルを解析し、パッケージの検出結果を SBOM にプッシュします。

プラグインイベントモデル

検出プラグインには、パッケージメタデータを含むファイルがインベントリのアーティファクトで検出されたことをコレクションプラグインに伝える方法が必要です。このデータ共有を容易にするために、検出プラグインはイベント名を定義し、ファイルパスのリストを返します。コレクションプラグインは、そのイベントをサブスクライブし、一致する各ファイルパスを受け取ります。この解析からファイル検出を分離 — 1 つの検出プラグインで複数のコレクターをフィードできます (ファンアウトパターン）。ただし、各検出プラグインには一意のイベント名が必要であり、各コレクションプラグインには一意のコレクター名が必要です。詳細については、「プラグイン衝突ルール」を参照してください。

開発者はこれをオブザーバー設計パターンとして認識する場合があります。

この設計により、単一の検出プラグインが複数の独立した分析をパフォーマンスの高い方法でトリガーできます。たとえば、1 つの検出プラグインがアーティファクトrequirements.txt内のすべての を見つけ、フィードできます。

  • 各行を SBOM 検出結果 () に解析するパッケージコレクターname==version。

  • API キーまたはトークンを含む行を誤ってバージョンとしてピン留めするシークレットコレクター。

  • ピン留めされていないまたはワイルドカードバージョンの指定子をレポートするポリシーコレクター。

各コレクターは、アーティファクトのファイルシステムを再歩行することなく、同じファイルリストに対して個別に実行されます。これにより、プラグインの作成者は、対応する検出プラグインを変更することなく、既存のイベントをサブスクライブする新しいコレクションプラグインを追加することもできます。

クイックスタート: 新しいプラグインの作成

新しいプラグインを作成する最も簡単な方法は、組み込みの足場コマンドを使用することです。

inspector-sbomgen plugin new

コマンドは、プラグイン名とプロジェクトディレクトリの入力を求めます。Enter キーを押すと、括弧で囲まれたデフォルトが受け入れられます。

Plugin name (identifies the software ecosystem your plugin will inventory, e.g. debian-dpkg, rhel-rpm, python-pip, cmake) [my-custom-ecosystem]: cmake
Project directory [my-sbomgen-plugins]:

引数を直接渡すこともできます。

inspector-sbomgen plugin new --name cmake --path /tmp/custom-plugins

実例から始める

独自のロジックを記述する前にプラグインを試す場合は、 --with-exampleフラグを使用して新しいプラグインを作成します。

inspector-sbomgen plugin new --with-example

これにより、サンプルロックファイルパーサー、テストデータ、および合格テストを含む完全に機能するプラグインプロジェクトが生成されます。サンプルプラグインは、example.lockファイルを検出し、name==versionエントリを解析して、パッケージを SBOM にプッシュします。テストをすぐに実行してプラグインシステムが動作していることを確認し、実際のエコシステムをターゲットにするようにコードを変更することができます。

すべてのオプションのオーバーライド関数 (get_scanner_name、get_event_name、、get_scanner_groupsマルチイベント検出など) を含む高度なスキャフォールドの場合、 --with-overridesフラグを使用します (詳細については後で説明します）。

inspector-sbomgen plugin new --with-overrides

プラグインの完了

スキャフォールド後、生成されたプラグインファイルには、エコシステム固有のロジックを追加する場所を示すTODOマーカーが含まれています。これらのマーカーを使用して、足場を動作するプラグインに変換します。

  • すべてのTODOマーカーを実際の値に置き換える

  • ターゲットファイルと一致するdiscover()ように のファイルパターンを更新する

  • に解析ロジックを実装collect()し、パッケージごとに sbomgen.push_package()を呼び出す

プラグインをテストする

プラグインをテストする方法は 2 つあります。

1. 組み込みテストハーネス — 開発中にプラグインロジックを検証inspector-sbomgen plugin testするために使用します。これにより、実際のアーティファクトをスキャンせずにinit_test.luaテストファイルが実行されます。

inspector-sbomgen plugin test --path ./my-plugins

テストファイルの書き込みと testing.* API プラグインテストガイド の使用の詳細については、「」を参照してください。

2。End-to-endスキャン — 標準の sbomgen コマンドを使用してプラグインを呼び出し、実際のアーティファクトに対して機能することを確認します。このアプローチでは、プラグインがターゲットとするファイル ( requirements.txtまたは同等のディレクトリなど) を含むアーティファクトと、プラグインディレクトリへのパスの両方を指定する必要があります。

inspector-sbomgen directory \
    --path /path/to/test/dir \
    --plugin-dir ./my-plugins \
    --disable-native-scanners \
    -o sbom.json

--disable-native-scanners フラグにより、Lua プラグインのみが実行されるため、組み込み (ネイティブ) スキャナーからの出力なしで簡単にテストできます。

IDE セットアップ

Sbomgen は、VS Code の sbomgen.* API 全体のコード補完、型チェック、インラインドキュメントを提供します。

Lua Language Server を使用した VS コード

  • Lua 拡張機能のインストール: sumneko.lua

  • プラグインプロジェクトで任意の.luaファイルを開く

これで完了です。plugin new コマンドは、Lua Language Server によって自動的に検出library/sbomgen.luaされる .vscode/settings.jsonと を生成します。すぐに以下が取得されます。

  • すべてのsbomgen.*関数のコード補完

  • タイプのパラメータヒント

  • ホバードキュメント

  • タイプチェック

プラグインディレクトリ構造

Sbomgen 検出プラグインとコレクションプラグインは、次のディレクトリ構造に従う必要があります。

{plugin-dir}/
├── discovery/
│   └── {platform}/
│       └── {category}/
│           └── {ecosystem}/
│               └── init.lua          # REQUIRED entrypoint
└── collection/
    └── {platform}/
        └── {category}/
            └── {ecosystem}/
                └── init.lua          # REQUIRED entrypoint

これらのディレクトリ名には意味があります。sbomgen はそれらを使用して、スキャナー名、イベント名、スキャナーグループ、プラットフォームフィルタリングなど、プラグインのデフォルトメタデータを取得します。これにより、開発者が書き込む必要があるボイラープレートの量が減少します。正しい値を選択すると、プラグインが sbomgen のスキャナー選択および実行モデルと適切に統合されます。

以下のセクションでは、セマンティックの意味と規則に関するガイダンスを提供しながら、ディレクトリ構造について詳しく説明します。

プラットフォーム

プラットフォームディレクトリは、プラグインを実行するオペレーティングシステムを制御します。

値 どのようなときに使うか
cross-platform プラグインは任意の OS (ほとんどのプラグイン) で動作します。
linux Linux 固有の検出ロジック
windows Windows 固有の検出ロジック
macos macOS 固有の検出ロジック

Category

カテゴリディレクトリは、プラグインに割り当てられたデフォルトのスキャナーグループを決定します。これにより、プラグインがデフォルトで実行されるか、明示的なオプトインを必要とするかが制御されます。グループが実行に与える影響スキャナーの選択については、「」を参照してください。

値 デフォルトグループ どのようなときに使うか
proglang programming-language-packages, pkg-scanner プログラミング言語パッケージ (pip、npm、maven など)
os os, pkg-scanner OS パッケージマネージャー (dpkg、rpm、apk など)
extra-ecosystems extra-ecosystems, pkg-scanner アプリケーションとランタイム (nginx、curl、wordpress など)

上記のいずれとも一致しないカテゴリ名を使用する場合、カテゴリ名自体がグループとして使用されます。

エコシステム

特定のパッケージエコシステムの名前 (例: 、python-pip、python-poetrydebian-dpkg、curl)。ハイフン名は一般的な規則ですが、厳密な要件ではありません。

スキャナー名とコレクター名は、エコシステムディレクトリ名から直接取得されます。

イベント名のペアリング

同じディレクトリパスにある検出プラグインとコレクションプラグインは自動的にペアリングされます。たとえば、 の検出プラグインは、 とdiscovery/cross-platform/proglang/python-pip/自動的にペアになりますcollection/cross-platform/proglang/python-pip/。

これを上書きするには、プラグインsubscribe_to_event()で get_event_name()と を定義します。

検出プラグイン

検出プラグインには discover()関数のみが必要です。他のすべての関数はオプションです。デフォルトはディレクトリパスから算出されます。

ほとんどの検出プラグインは、Python requirements.txtpip、package.jsonnpm、Rust 貨物など、名前またはパスが特定のエコシステムを識別するファイルを見つけることによって機能Cargo.lockします。sbomgen.find_files_by_* 関数は Lua VM の外部でこのマッチングを実行するため、Lua で完全なファイルリストを繰り返すよりも大幅に高速になります。

-- REQUIRED: Scans the artifact and returns a table of file paths.
function discover()
    return sbomgen.find_files_by_name({"requirements.txt"})
end

discover() は、文字列の Lua テーブル (配列) を返す必要があります。ファイルが見つからない場合は、空のテーブル を返します{}。

一般的な検出パターン

目標 推奨関数
1 つ以上の正確なファイル名と一致する sbomgen.find_files_by_name({names})
大文字と小文字を区別せずにファイル名を一致させる sbomgen.find_files_by_name_icase({names})
パスサフィックスで一致 (例: /pom.properties) sbomgen.find_files_by_suffix({suffixes})
フルパス正規表現で一致 sbomgen.find_files_by_path_regex({patterns})
Glob スタイルのベースネーム一致 (例: *.lock) sbomgen.glob_find_files(pattern)

ロジックでサフィックスと一致するファイルを保持し、ビルド出力ディレクトリを除外するなど、ポストフィルタリングが必要な場合は、find_files_by_*呼び出しを Lua ループと組み合わせます。

function discover()
    local found = {}
    for _, f in ipairs(sbomgen.find_files_by_suffix({".conda-meta.json"})) do
        if not f:match("[/\\]%.cache[/\\]") then
            table.insert(found, f)
        end
    end
    return found
end

他のマッチャーが適合しない限り、検出sbomgen.get_file_list()は避けてください。Lua VM へのすべてのパスをコピーし、大きなアーティファクトで数秒かかることがあります。詳細については、プラグイン API リファレンス「」を参照してください。

マルチイベント検出

デフォルトでは、 によって返されるすべてのファイルは 1 つのイベント ( から) に発行discover()されますget_event_name()。スキャナーが異なるファイルを異なるコレクターにルーティングする必要がある場合は、代わりにキー付きテーブルを返します。

function discover()
    return {
        EventNameFoundCurl = sbomgen.find_files_by_name({"curl", "curl.exe"}),
        EventNameFoundLibcurl = sbomgen.find_files_by_name({"curlver.h"}),
    }
end

が文字列キーを含むテーブルをdiscover()返すと、各キーは個別のイベント名として扱われ、その値 (ファイルパスのテーブル) がそのイベントに発行されます。コレクションプラグインは、通常subscribe_to_event()どおり を介して特定のイベントをサブスクライブします。

これは下位互換性があります。シーケンシャルテーブルを返すことは、{"file1", "file2"}引き続き単一イベントモードとして機能します。検出は自動です。文字列キーを持つテーブルはマルチイベントで、整数キー (または空) のみを持つテーブルは単一イベントです。

マルチイベントを使用する場合、 get_event_name()は発行には使用されません (イベント名は返されたテーブルキーから取得されます）。ただし、衝突検出のためにプラグインのロード中に呼び出されるため、一意の値を返すか、デフォルトを使用するには省略する必要があります。

オプションの検出関数

これらすべてには、ディレクトリパスから派生した正常なデフォルトがあります。上書きする必要がある場合にのみ定義します。

関数 デフォルト 次の場合に上書きします。
get_scanner_name() {ecosystem} (例: python-pip) カスタムスキャナー名が必要
get_scanner_description() "Lua discovery plugin: {ecosystem}" カスタム説明が必要
get_scanner_groups() カテゴリディレクトリから派生 非標準グループが必要です
get_event_name() ディレクトリパスから派生 カスタムイベントルーティングが必要です
get_localhost_scan_paths() なし プラグインには、スキャン中にlocalhostスキャンされた特定のパスが必要です

Localhost スキャンパス

sbomgen はlocalhostスキャンを実行すると、ユーザー指定のディレクトリとスキャナーによって宣言されたデフォルトパスをウォークします。デフォルトでは、Lua 検出プラグインはパスを提供しないため、ユーザー指定のディレクトリ外のファイルはファイルリストに表示されません。

localhost walker に含めるディレクトリまたはファイルパスを返get_localhost_scan_paths()すように を定義します。

function get_localhost_scan_paths()
    return {
        "/usr/bin",
        "/usr/local/bin",
    }
end

返されたパスは、localhostスキャン中にのみウォーカーのスキャンリストに追加されます。container、directory、または archiveスキャンには影響しません。

プラットフォーム固有のスキャンパス

Windows、macOS、Linux のさまざまな場所にファイルが存在する場合は、 でブランチsbomgen.get_platform()し、ホストに適切なパスを返します。

function get_localhost_scan_paths()
    local platform = sbomgen.get_platform()

    if platform == sbomgen.platform.WINDOWS then
        local drive = sbomgen.get_system_drive()
        return {
            drive .. "/Program Files/MyApp/myapp.exe",
            drive .. "/Program Files (x86)/MyApp/myapp.exe",
        }
    end

    if platform == sbomgen.platform.DARWIN then
        return {"/Applications/MyApp.app/Contents/MacOS/myapp"}
    end

    -- Linux
    return {
        "/usr/bin/myapp",
        "/usr/local/bin/myapp",
    }
end

Windows sbomgen.get_system_drive()では、 を使用して、ハードコーディングではなくシステムドライブ文字 ( など"C:") を解決します。LOCALAPPDATA や などの環境変数から派生したパスの場合PROGRAMFILES、値を反復処理sbomgen.get_env_vars()してキーで検索します。詳細については、プラグイン API リファレンス「」を参照してください。

コレクションプラグイン

コレクションプラグインには collect()関数のみが必要です。他のすべての関数はオプションです。

collect(file_path) は、ペアになった検出プラグインによって検出されたファイルごとに 1 回呼び出されます。一般的なパターンは次のとおりです。

  • (メモリにロードされた小さなファイルsbomgen.read_file()の場合) または sbomgen.open_file() (line-by-lineファイルの場合) を使用してファイルの内容を読み込みます。

  • 内容を解析する — sbomgen.json_decode() 単純なマニフェスト、JSON、sbomgen.xml_decode()XML、またはコンパイルされたバイナリsbomgen.search_binary()の文字列マッチング。

  • パッケージのメタデータsbomgen.push_package()を使用して を呼び出して、検出された各パッケージを発行します。

-- REQUIRED: Called once per discovered file.
-- Parse the file and call sbomgen.push_package() for each package found.
function collect(file_path)
    local content, err = sbomgen.read_file(file_path)
    if err or not content then return end

    for line in content:gmatch("[^\r\n]+") do
        local name, version = line:match("^([%w%-%_%.]+)==(.+)$")
        if name and version then
            sbomgen.push_package({
                name = name,
                version = version,
                purl_type = "pypi",
                component_type = sbomgen.component_types.LIBRARY,
            })
        end
    end
end

collect() は値を返しません。すべてのpush_package()呼び出しには、name、purl_type、および が必要ですcomponent_type。サポートされているすべてのフィールドプラグイン API リファレンスについては、「」を参照してください。

コンポーネントへのメタデータのアタッチ

Sbomgen では、PURL 修飾子と CycloneDX プロパティの 2 つの方法でメタデータをパッケージコンポーネントにアタッチできます。これらはさまざまな目的を果たし、それらの選択は、Amazon Inspector が結果の SBOM の脆弱性を特定する方法に影響します。

メカニズム 表示される場所 に を使用する
qualifiers パッケージ URL 内 (例: pkg:deb/debian/curl@7.88.1?arch=amd64) パッケージの ID の一部であるデータ
properties SBOM の components[].properties配列 パッケージの識別方法を変更しない説明メタデータ

推奨事項: カスタムメタデータには CycloneDX プロパティ (独自の名前空間の下) を優先します。プロパティはコンポーネントの ID を変更しないため、Amazon Inspector の脆弱性識別には影響しません。エコシステムの PURL タイプに必要な場合は、PURL 修飾子を予約します。

PURL 修飾子

一部の PURL 修飾子は Amazon Inspector にとって意味的意味を持ち、脆弱性の特定に影響を与えます。たとえば、debコンポーネントでは Inspector は archや などの修飾子を使用して正しい脆弱性フィードdistroを選択します。コンパイルされたバイナリのgenericコンポーネントでは、 go_toolchain や などの修飾子を使用して、使用されるツールチェーンrust_toolchainを識別します。Inspector の修飾子を設定しても認識されないか、予期される修飾子を省略すると、脆弱性が見逃されたり、誤って帰属されたりする可能性があります。

「パッケージ URL とは」を参照してください。 Inspector が PURL タイプごとに認識する修飾子規則については、「Amazon Inspector ユーザーガイド」の「」を参照してください。

の qualifiersテーブルを使用して修飾子を設定しますsbomgen.push_package()。

sbomgen.push_package({
    name = "curl",
    version = "7.88.1",
    purl_type = "deb",
    namespace = "debian",
    component_type = sbomgen.component_types.LIBRARY,
    qualifiers = {
        arch = "amd64",
        distro = "debian-12",
    },
})

修飾子は、PURL タイプに対する Inspector の期待と一致する場合にのみ設定します。パッケージのアイデンティティに含まれていないメタデータを記録する必要がある場合は、代わりに CycloneDX プロパティを使用します。

CycloneDX プロパティ

CycloneDX プロパティは、SBOM のcomponents[].properties配列に表示されるキーと値の注釈です。識別方法に影響を与えずにコンポーネントを記述するため、プラグイン定義メタデータの安全な選択肢です。

amazon:inspector:*名前空間は Amazon Inspector 用に予約されています。具体的には次のとおりです。

  • amazon:inspector:sbom_generator:* — sbomgen とその組み込みスキャナー用に予約されています。

  • amazon:inspector:sbom_scanner:* — Amazon Inspector スキャン API 用に予約されています。

プラグインの作成者は、これらの予約済み名前空間内でキーを出力しないでください。書き込むと Inspector の動作が妨げられ、上書きされる可能性があります。予約キーの完全なリストについては、Amazon Inspector での CycloneDX 名前空間の使用」を参照してください。

プロパティを定義するときは、独自の名前空間 (通常は組織またはプラグイン識別子) を使用します。

sbomgen.push_package({
    name = "requests",
    version = "2.28.1",
    purl_type = "pypi",
    component_type = sbomgen.component_types.LIBRARY,
    properties = {
        ["acme:python:manifest_path"] = file_path,
        ["acme:python:pinned"] = "true",
        ["acme:python:source"] = "requirements.txt",
    },
})

キー命名規則

プロパティキーは、次のように sbomgen によって処理されます。

  • コロンを含むキーは、SBOM で逐語的に使用されます。名前空間を制御するために、キーには必ず少なくとも 1 つのコロンを含めてください。

  • コロンを含まないキーには、自動的に というプレフィックスが付けられ、予約された Inspector 名前空間内にamazon:inspector:sbom_generator:配置されます。カスタムプロパティでは、このシェイプは避けてください。

properties = {
    ["acme:my_plugin:detected_via"] = "lockfile",  -- used as-is (recommended)
    detected_via                   = "lockfile",  -- becomes "amazon:inspector:sbom_generator:detected_via" (avoid)
}

sbomgen.properties.* 定数は、公式スキャナーが予約された名前空間内で一貫したキーを出力するように存在します。これらはカスタムプラグインの拡張ポイントではなく、代わりに独自の名前空間を使用します。

子コンポーネントのプロパティと修飾子

ネストは独立したコンポーネントchildrenです。各子には独自の テーブルpropertiesと qualifiersテーブルがあります。親に設定されたメタデータは子には伝達されません。値を必要とする各子に明示的に値を設定します。

オプションのコレクション関数

関数 デフォルト 次の場合に上書きします。
get_collector_name() {ecosystem} (例: python-pip) カスタムコレクター名が必要
get_collector_description() 空の文字列 説明が必要です
subscribe_to_event() ディレクトリパスから派生 カスタムイベントルーティングが必要です

プラグインの実行

プラグインがパッケージメタデータを生成するには、sbomgen に、プラグインがターゲットとするファイル (、、requirements.txtpackage.jsonまたは同等のパッケージマニフェストファイルを含むディレクトリなど) を含むアーティファクトをスキャンする必要があります。

基本的な使用法

inspector-sbomgen <artifact type> <arguments> --plugin-dir /path/to/plugins

例: 

inspector-sbomgen directory --path /target -o /tmp/sbom.json --plugin-dir /path/to/plugins

ネイティブスキャナーを無効にした場合 (Lua のみモード)

inspector-sbomgen directory --path /target --plugin-dir /path/to/plugins --disable-native-scanners -o sbom.json

詳細なログ記録を使用する

inspector-sbomgen directory --path /target --plugin-dir /path/to/plugins --verbose -o sbom.json

使用可能なスキャナーの一覧表示

を使用してlist-scanners、sbomgen で使用できるすべてのスキャナーを表示します。これには、組み込みのネイティブスキャナー、sbomgen にバンドルされた公式 Lua プラグイン、 を介して提供したカスタム Lua プラグインが含まれます--plugin-dir。

inspector-sbomgen list-scanners --plugin-dir /path/to/plugins
┌─────────────────────┬────────┬───────────────────────────────┬─────────────────────────────┐
│    SCANNER NAME     │ SOURCE │            GROUPS             │         DESCRIPTION         │
├─────────────────────┼────────┼───────────────────────────────┼─────────────────────────────┤
│ curl                │ custom │ extra-ecosystems              │ Discovers curl version      │
│                     │        │ pkg-scanner                   │ header files (curlver.h)    │
├─────────────────────┼────────┼───────────────────────────────┼─────────────────────────────┤
│ python-requirements │ custom │ pkg-scanner                   │ Discovers requirements*.txt │
│                     │        │ programming-language-packages │ files for Python pip        │
│                     │        │                               │ packages                    │
└─────────────────────┴────────┴───────────────────────────────┴─────────────────────────────┘

SOURCE 列には、各スキャナーの出所が表示されます。

ソース 意味
native sbomgen にバンドルされた組み込みスキャナー
official sbomgen にバンドルされた Lua プラグイン
custom 経由でロードされるユーザー提供の Lua プラグイン --plugin-dir

list-scanners なしで実行すると、 スキャナーnativeと officialスキャナーの両方が--plugin-dir引き続き含まれます。これらは常に使用できます。--plugin-dir フラグは、customスキャナーをリストに追加します。

ネイティブスキャナーのない Lua スキャナーのみを一覧表示するには: 

inspector-sbomgen list-scanners --plugin-dir /path/to/plugins --disable-native-scanners

スキャナーの選択

Lua 検出プラグインは、組み込みのネイティブスキャナーと同じスキャナー選択モデルに参加します。デフォルトでは、sbomgen は、 グループがアーティファクトタイプのデフォルトのスキャナーグループと一致するすべてのスキャナーを実行します。これを 3 つのフラグで上書きできます。

特定のスキャナーのみを実行する

名前付きスキャナーのみを実行する--scannersには、 を使用します。他のすべてのスキャナーは除外されます。

inspector-sbomgen directory --path /target \
    --plugin-dir /path/to/plugins \
    --scanners python-requirements \
    -o sbom.json

これにより、python-requirementsスキャナーのみが実行されます。複数のスキャナー名をカンマで区切って渡すか、スキャナーグループ名 ( などprogramming-language-packages) を渡して、そのグループに属するすべてのスキャナーを有効にすることができます。

特定のスキャナーを除外する

他のすべてを実行中に名前付きスキャナーを除外--skip-scannersするには、 を使用します。

inspector-sbomgen directory --path /target \
    --plugin-dir /path/to/plugins \
    --skip-scanners python-poetry \
    -o sbom.json

これにより、 を除くすべてのデフォルトスキャナーが実行されますpython-poetry。と同様に--scanners、このフラグはグループ名も受け入れるため、 を渡すと、そのグループ内のすべてのスキャナー--skip-scanners programming-language-packagesが無効になります。

注記

--scanners と --skip-scannersは相互に排他的です。両方を渡すとエラーが発生します。

デフォルト以外のグループからスキャナーを追加する

デフォルトのスキャナーセットは、スキャンされるアーティファクトタイプによって異なります (グループが選択に与える影響以下の のマトリックスを参照）。グループがアーティファクトタイプのデフォルトセットに含まれていないスキャナーは、オプトインしない限り実行されません。--additional-scanners を使用して、スキャナーを置き換えずにデフォルトセットに追加します。

inspector-sbomgen directory --path /target \
    --plugin-dir /path/to/plugins \
    --additional-scanners my-extra-scanner \
    -o sbom.json

これにより、アーティファクトタイプのすべてのデフォルトスキャナーと が実行されますmy-extra-scanner。フラグは、置き換えるのではなく、スキャナー名またはグループ名、デフォルトセットのスタックのカンマ区切りリストを受け入れます。を使用してlist-scanners、スキャナーが属するグループを確認します。

グループが選択に与える影響

検出プラグインの get_scanner_groups()関数は、スキャナーが属するグループを決定します。スキャナーがデフォルトで実行されるかどうかは、そのグループとスキャンされるアーティファクトタイプの両方によって異なります。以下のマトリックスは、各アーティファクトタイプのデフォルトのスキャナーセットに含まれるグループを示しています。

[Group] (グループ) directory / archive container localhost volume binary
os — ✓ ✓ ✓ —
programming-language-packages ✓ ✓ ✓ ✓ —
binary ✓ ✓ — — ✓
extra-ecosystems — ✓ ✓ ✓ —
dockerfile ✓ ✓ — — —
custom ✓ ✓ ✓ ✓ ✓
certificate — — — — —
machine-learning — — — — —
pkg-scanner — — — — —

✓ は、そのグループ内のすべてのスキャナーがそのアーティファクトタイプに対してデフォルトで実行されることを意味します。— は、 グループがデフォルトセットに含まれていないため、そのスキャナーは --scannersまたは を介して明示的に選択された場合にのみ実行されます--additional-scanners。

注目すべき詳細:

  • custom は常にデフォルトのセットにあります。 を介してロードされたカスタムプラグインは customグループ--plugin-dirを自動的に受信するため、アーティファクトタイプに関係なくデフォルトで実行されます。

  • extra-ecosystems は、container、、localhostおよび volumeスキャンではデフォルトですが、directory、archive、または binaryスキャンではデフォルトではありません。これらのタイプを含めるには--additional-scanners、 (名前またはextra-ecosystemsグループで) 渡す必要があります。

  • pkg-scanner は情報です。スキャナーを に表示するパッケージコレクターとしてマークしますがlist-scanners、それ自体ではスキャナーが実行されません。で実行グループ ( などprogramming-language-packages) とペアリングしますget_scanner_groups()。

たとえば、 が返すプラグイン{sbomgen.groups.EXTRA_ECOSYSTEMS, sbomgen.groups.PACKAGE_COLLECTOR}は、コンテナ、localhost、ボリュームスキャンでデフォルトで実行されますが、ディレクトリ、アーカイブ、バイナリスキャンでは --additional-scanners (または --scanners) が必要です。

プラグイン衝突ルール

Sbomgen は、ロードされたすべてのプラグインに一意のメタデータを適用して、サイレント上書きを防ぎ、SBOM の整合性を確保します。衝突が検出されると、後のプラグインはスキップされ、警告がログに記録されます。

チェック対象

メタデータ スコープ 衝突時
検出イベント名 (get_event_name) すべての検出プラグイン 2 番目のプラグインがスキップされました
スキャナー名 (get_scanner_name) すべての検出プラグイン 2 番目のプラグインがスキップされました
コレクター名 (get_collector_name) すべてのコレクションプラグイン 2 番目のプラグインがスキップされました

許可される内容

複数のコレクションプラグインは、 を介して同じイベントにサブスクライブできますsubscribe_to_event()。これは意図したファンアウトパターンです。1 つの検出プラグインは、それぞれが異なることを行う複数のコレクターにフィードできます (たとえば、1 つはパッケージを抽出し、もう 1 つはシークレットを検出します）。

衝突の回避

2 つのプラグインが同じスキャナー名、イベント名、またはコレクター名を使用している場合、ロードされた 2 番目のプラグインはスキップされます。衝突を解決するには、プラグインで適切なオーバーライド関数 (get_scanner_name()、、または ) を定義してget_event_name()、競合するメタデータの名前を変更しますget_collector_name()。

衝突警告の例

[custom:python-pip] SKIPPED: discovery event name "EventNameFoundPythonRequirements"
is already registered by [official:python-pip]. Each discovery plugin must have a
unique event name. Rename get_event_name() in your plugin to use a unique name.

警告は、スキップされたプラグイン、衝突したプラグイン、その名前をすでに所有しているプラグイン、変更する関数を示します。

デバッグ

コンソールのログ記録

プラグインは、次の関数を使用して sbomgen のコンソール出力にメッセージを送信できます。

関数 [レベル] デフォルトでは表示されますか?
sbomgen.log_debug(message) DEBUG いいえ — 必須 --verbose
sbomgen.log_info(message) 情報 はい
sbomgen.log_warn(message) WARN はい
sbomgen.log_error(message) エラー はい

プラグインからのすべてのログ出力には、プラグインのソースとパス (例: [custom:python-pip]) が自動的にプレフィックス付けされるため、異なるプラグインからのメッセージは簡単に区別できます。log_info、log_warn、および log_errorは常に出力します。sbomgen が で呼び出された場合にのみlog_debug出力されます--verbose。

function discover()
    sbomgen.log_info("starting discovery")
    local files = sbomgen.find_files_by_name({"requirements.txt"})
    sbomgen.log_debug(string.format("matched %d files", #files))
    if #files == 0 then
        sbomgen.log_warn("no requirements.txt files found")
    end
    return files
end

ブレークポイント

Enter を押すまでプラグインの実行を一時停止してブロックsbomgen.breakpoint()するには、 を使用します。これは粗デバッガーとして機能します。ログステートメントと組み合わせて、特定の時点で状態を検査します。

function discover()
    local files = sbomgen.find_files_by_name({"requirements.txt"})

    sbomgen.log_info(string.format("about to inspect %d files", #files))
    sbomgen.breakpoint("before file inspection — press Enter to continue")

    local found = {}
    for _, f in ipairs(files) do
        if not f:match("[/\\]tests[/\\]") then
            table.insert(found, f)
        end
    end

    sbomgen.log_info(string.format("kept %d files after filtering", #found))
    sbomgen.breakpoint("after filtering — press Enter to continue")

    return found
end

ブレークポイントメッセージが stderr に出力されます。Enter を押すまで実行が一時停止し、ログ出力を確認する時間を確保します。

一般的な問題

症状 原因 修正
プラグインがロードされていません init.lua がみつかりません エントリポイントが正しいディレクトリ深度に存在することを確認する
「必要な関数の欠落」 関数名のタイプミス get_scanner_name、get_scanner_description、、get_scanner_groups、、discover、get_event_name、collect、 get_localhost_scan_paths get_collector_namesubscribe_to_eventが定義されていることを確認します。
コレクションプラグインが呼び出されない イベント名の不一致 検証get_event_name()して同じ文字列をsubscribe_to_event()返す
SBOM にパッケージがない push_package 呼び出されていないか、必須フィールドがありません name、purl_type、 component_typeがすべてのpush_package呼び出し (子を含む) で設定されていることを確認します。sbomgen.component_types.* 定数を使用します。
プラグインのランタイムエラー 実行中の Lua エラー エラーの詳細を含む警告メッセージの sbomgen 出力を確認する
「SKIPPED: discovery event name ... is already registered」 別のプラグインが同じイベント名を使用する 名前get_event_name()を一意の値に変更する
「SKIPPED: スキャナー名 ... は既に登録されています」 別のプラグインが同じスキャナー名を使用する 名前get_scanner_name()を一意の値に変更する
「SKIPPED: collector name ... is already registered」 別のプラグインが同じコレクター名を使用する 名前get_collector_name()を一意の値に変更する

API リファレンス

完全な関数カタログは、コンパニオンドキュメントに保持されます。

→ プラグイン API リファレンス

API リファレンスは、すべてのsbomgen.*関数 (ファイル I/O、バイナリユーティリティ、パッケージ出力、regex、構造化解析、Windows レジストリ、ログ記録、デバッグ）、テストファイルで使用できる testing.* API、すべての組み込み定数 (properties、groups、platform)component_types、プラグインライフサイクルグローバルを対象としています。

エラー処理

失敗する可能性がある API 関数は、 の 2 つの値を返しますvalue, err。成功すると、 errは になりますnil。失敗した場合、最初の値は nilで、 errはエラー文字列です。

local content, err = sbomgen.read_file(path)
if err then
    sbomgen.log_error("failed to read " .. path .. ": " .. err)
    return
end
-- content is safe to use here

プラグインが未処理の Lua エラーを発生させた場合、sbomgen は警告をログに記録し、次のファイルまたはプラグインに進みます。他のプラグインは影響を受けません。

サンドボックスの制限

プラグインは、標準ライブラリへのアクセスが制限されたサンドボックス化された Lua VM で実行されます。

[Library] (ライブラリ) 使用可能 Notes (メモ)
base ✓ dofile、loadfile、 loadstringが削除されます
string ✓ 完全な文字列操作
table ✓ 完全なテーブル操作
math ✓ 完全な数学ライブラリ
package ✓ require() プラグインディレクトリに制限
io ✗ 代わりに sbomgen.* I/O 関数を使用する
os ✗ セキュリティのためにブロック
debug ✗ VM イントロスペクションを防ぐためにブロック
coroutine ✗ ロードされていません

io.open または を介したファイルシステムへの直接アクセスos.executeは利用できません。すべてのファイルオペレーションは sbomgen API を経由する必要があります。これにより、アーティファクトタイプ間で一貫した動作が保証され、プラグインがアーティファクト外のファイルにアクセスできなくなります。

require() は、プラグイン独自のディレクトリツリー内からのみモジュールをロードできます。などの親ディレクトリトラバーサルrequire("../shared")はブロックされます。

プラグイン間でのコードの共有

を使用してrequire()、プラグインの ディレクトリ内からヘルパーモジュールをロードできます。

my-ecosystem/
├── init.lua
└── helpers.lua
-- helpers.lua
local M = {}
function M.parse_version(s)
    return string.match(s, "(%d+%.%d+%.%d+)")
end
return M
-- init.lua
local helpers = require("helpers")

function subscribe_to_event() return "MyEvent" end

function collect(file_path)
    local content, err = sbomgen.read_file(file_path)
    if err then return end
    local version = helpers.parse_version(content)
    -- ...
end

を使用したサブディレクトリもサポートinit.luaされています。

my-ecosystem/
├── init.lua
└── parsers/
    └── init.lua
local parsers = require("parsers")

require() はプラグインの ディレクトリに制限されています。他のプラグインまたはシステムパスからモジュールをロードすることはできません。サードパーティーの Lua ライブラリ (LuaRocks など) はサポートされていません。プラグインディレクトリ内のローカルヘルパーモジュールのみをロードできます。