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

inspector-sbomgen Lua プラグインの API リファレンスを完了します。プラグインの記述に関するガイドについては、「」を参照してくださいプラグイン開発者ガイド。テストについては、「」を参照してくださいプラグインテストガイド。

概要

ランタイム提供のすべての関数は、グローバルsbomgenテーブル (ファイル I/O、正規表現、ログ記録、定数など) を介してアクセスされます。さらに、各プラグインは、プラグインライフサイクルの定義されたポイントで を呼び出す、最上位のグローバル関数 (discover、collectget_scanner_name、、 subscribe_to_eventなど) の小さなセットを定義します。これらについては、「」を参照してくださいプラグインライフサイクルグローバル。

*_test.lua ファイル内では、sbomgen はテスト作成者が discovery→collection パイプラインを駆動し、アサーションを実行できるようにするtestingグローバルをさらに公開します。「API のテスト」を参照してください。

サンドボックスの制限

プラグインは、標準ライブラリへのアクセスが制限されたサンドボックス化された Lua VM で実行されます。次の Lua 標準ライブラリモジュールを使用できます。

モジュール	Notes (メモ)
base	コア関数 (print、type、tostring、、tonumber、pairsipairs、pcall、、error、 select unpack rawget rawsetなど）。dofile、loadfile、、 loadstringは削除されます。
string	完全な文字列操作 (string.match、string.find、string.format、 string.gsubなど)
table	完全なテーブル操作 (table.insert、table.remove、table.sort、 table.concatなど)
math	完全な数学ライブラリ (math.floor、math.max、 math.minなど)
package	require() は使用できますが、プラグイン独自のディレクトリツリー内のモジュールに制限されます。親ディレクトリトラバーサル (require("../shared")) はブロックされます。 package.cpath と package.pathはクリアされます。

以下の標準ライブラリモジュールは、セキュリティと安定性のために明示的に許可されていません。

モジュール	理由
io	ファイルシステムへの直接アクセスはブロックされます。すべてのファイルオペレーションは、アーティファクトタイプ (ディレクトリ、コンテナ、ボリュームなど) 間で一貫した動作を実現するために、アーティファクトインターフェイスをルーティングする sbomgen.*関数を経由する必要があります。
os	システムレベルのオペレーション (os.execute、os.remove、os.rename、 os.getenvなど) は、プラグインがホストシステムを変更できないようにブロックされます。
debug	デバッグライブラリは、Lua VM 内部の検査や変更を防ぐためにブロックされます。
coroutine	コルーチンはロードされません。

これらのモジュールは VM の許可リストに含まれておらず、プラグインからはアクセスできません。

注記

重要: すべてのファイル I/O は sbomgen.*関数 (、、 などsbomgen.get_file_list) sbomgen.read_file sbomgen.open_fileを経由する必要があります。io.open または直接ファイルシステムにアクセスすると、ランタイムエラーが発生します。sbomgen API は、プラグインがアーティファクト抽象化レイヤーとやり取りすることを確保します。これにより、ディレクトリ、コンテナイメージ、アーカイブ、またはボリュームをスキャンする場合でも一貫した動作が提供されます。

プラグインライフサイクルグローバル

プラグインは、特定の最上位グローバル関数を定義する という名前init.luaの Lua ファイルです。これらのグローバルはsbomgenテーブルにはありません。プラグインが sbomgen を呼び出すために定義する関数です。有効なグローバルのセットは、検出プラグインとコレクションプラグインで異なります。以下の関数ごとに、プラグインがそれを省略すると、表に示されているデフォルトが使用されます。

検出プラグイン

関数	配列	必須	デフォルト (省略した場合)	説明
discover()	0	あり	—	このプラグインが見つけたファイルを返します。パス文字列のシーケンシャルテーブル (単一イベントモード) または値がパスのテーブルであるイベント名文字列 (複数イベントモード) でキー指定されたテーブルを返します。
get_event_name()	0	いいえ	"lua:{platform}/{category}/{ecosystem}"	ファイルが公開されるイベント名を返します。すべての検出プラグインで一意である必要があります。
get_scanner_name()	0	いいえ	エコシステムディレクトリ名	スキャナーの表示名を返します。すべての検出プラグインで一意である必要があります。
get_scanner_description()	0	いいえ	"Lua discovery plugin: {ecosystem}"	人間が読める説明を返します。
get_scanner_groups()	0	いいえ	カテゴリディレクトリから派生 (デベロッパーガイドを参照)	スキャナーグループ文字列のテーブルを返します。sbomgen.groups.* 定数を使用します。
get_localhost_scan_paths()	0	いいえ	—	localhost アーティファクトのスキャン時に含めるファイル/ディレクトリパスのテーブルを返します。localhost スキャンについてのみ相談されます。

コレクションプラグイン

関数	配列	必須	デフォルト (省略した場合)	説明
collect(file_path)	1	あり	—	サブスクライブされたイベントに発行されたファイルごとに 1 回呼び出されます。ファイルを解析し、 を介して検出結果を出力しますsbomgen.push_package()。何も返しません。
subscribe_to_event()	0	いいえ	"lua:{platform}/{category}/{ecosystem}"	このコレクターがサブスクライブするイベント名を返します。対応する検出プラグインの と一致する必要がありますget_event_name()。
get_collector_name()	0	いいえ	エコシステムディレクトリ名	コレクターの表示名を返します。すべてのコレクションプラグインで一意である必要があります。
get_collector_description()	0	いいえ	"" (空)	人間が読める説明を返します。

ファイル I/O

すべてのファイルオペレーションは sbomgen.* API を経由する必要があります。Lua のioライブラリを介したファイルシステムへの直接アクセスは利用できません (「」を参照サンドボックスの制限)。sbomgen ファイル I/O 関数はアーティファクトインターフェイスを介してルーティングされるため、ディスク上のディレクトリ、コンテナイメージ、圧縮アーカイブ、マウントされたボリュームのいずれをスキャンしても、プラグインは同じように動作します。

sbomgen.get_file_list()

アーティファクト内のすべてのファイルパスを文字列のテーブルとして返します。

• 戻り値: {string, ...} — 絶対ファイルパス文字列のテーブル

• パフォーマンス: この関数は、アーティファクト内のすべてのファイルパスを Lua VM に Lua 文字列としてコピーします。大規模なアーティファクト (300K 以上のファイルを含む localhost スキャンなど) では、これだけでも数秒かかります。Lua で返されたテーブルを で反復すると、オーバーヘッドstring.match()がさらに増加します。フルスキャンには 15 秒以上かかる場合があります。アーティファクト内のファイルが多いほど、プラグインの速度が遅くなります。

注記

可能な限り、これらのターゲットを絞った代替手段を優先します。

関数	次の場合に使用します。
sbomgen.find_files_by_name()	一致する正確なファイル名 (例: 、"curl") がわかっている (例: "requirements.txt")
sbomgen.find_files_by_name_icase()	上記と同じですが、大文字と小文字は区別されません
sbomgen.find_files_by_suffix()	パスサフィックス (例: "/pom.properties"、"curlver.h") を一致させる必要があります
sbomgen.find_files_by_path_regex()	フルパス正規表現マッチングが必要です
sbomgen.glob_find_files()	glob 形式のベースネームマッチングが必要です

これらの関数は Lua VM の外部でマッチングを実行し、マッチングされたパスのみを返し、300K-fileアーティファクトでも 1 ミリ秒未満で完了します。一致するロジックを上記のいずれでも表現できないget_file_list()場合にのみ使用します。

-- AVOID in discovery plugins when possible:
local files = sbomgen.get_file_list()
for _, f in ipairs(files) do
    if string.match(f, "pattern$") then ... end
end

-- PREFER:
local matches = sbomgen.find_files_by_name({"target-file.txt"})

sbomgen.read_file(path)

ファイルの内容全体を読み取り、文字列として返します。

• 戻り値: string, err

• 失敗の場合: nil, error_string

local content, err = sbomgen.read_file("/app/package.json")
if err then
    sbomgen.log_error("read failed: " .. err)
    return
end

sbomgen.open_file(path)

読み取りをストリーミングするためのファイルを開きます。FileHandle オブジェクトを返します。これは、コンテンツをメモリにロードすることが実用的でない大きなファイルに使用します。

• 戻り値: FileHandle, err

local fh, err = sbomgen.open_file(path)
if err then return end
local line = fh:read_line()
while line do
    -- process line
    line = fh:read_line()
end
fh:close()

sbomgen.glob_find_files(pattern)

Go glob filepath.Match パターンに一致するファイルを返します。パターンはベースファイル名と照合されます。

• 戻り値: {string, ...}, err

local files, err = sbomgen.glob_find_files("*.txt")

フルパスパターンマッチングstring.matchには、 sbomgen.get_file_list()で を使用します。

sbomgen.find_files_by_name(names)

ベース名 (最後のパスコンポーネント) が指定された名前の 1 つと正確に一致するファイルを返します。反復と比較は Go で行われ、Lua sbomgen.get_file_list()で反復するよりも大幅に高速になります。

• パラメータ: names — 文字列のテーブル (一致するベース名)

• 戻り値: {string, ...} — 一致するファイルパス (エラータプルなし)

local curl_bins = sbomgen.find_files_by_name({"curl", "curl.exe"})
local headers = sbomgen.find_files_by_name({"curlver.h"})

sbomgen.find_files_by_name_icase(names)

ベース名が指定された名前のいずれかと一致するファイルを返します。大文字と小文字は無視されます。たとえば、 は VERSION、Version、および "version"に一致しますversion。と同様にfind_files_by_name、マッチングは Lua VM の外部で行われます。

• パラメータ: names — 文字列のテーブル (一致するベース名、大文字と小文字を区別しない)

• 戻り値: {string, ...} — 一致するファイルパス (エラータプルなし)

local version_files = sbomgen.find_files_by_name_icase({"version"})
local war_files = sbomgen.find_files_by_name_icase({"jenkins.war"})

sbomgen.find_files_by_suffix(suffixes)

完全 (forward-slash-normalizedパスが指定されたサフィックスのいずれかで終わるファイルを返します。と同様にfind_files_by_name、マッチングは Lua VM の外部で行われます。

• パラメータ: suffixes — 文字列のテーブル (一致するパスサフィックス)

• 戻り値: {string, ...} — 一致するファイルパス (エラータプルなし)

local pom_files = sbomgen.find_files_by_suffix({"/pom.properties"})
local release_headers = sbomgen.find_files_by_suffix({"ap_release.h", "opensslv.h"})

sbomgen.find_files_by_path_regex(patterns)

forward-slash-normalizedパスが指定された Go (RE2) 正規表現パターンのいずれかと一致するファイルを返します。マッチングは Lua VM の外部で行われるため、大規模なファイルリストでも効率的です。

• パラメータ: patterns — Go 正規表現文字列のテーブル

• 戻り値: {string, ...} — 一致するファイルパス (エラータプルなし)

• レイズ: パターンのコンパイルに失敗した場合の Lua エラー

local configs = sbomgen.find_files_by_path_regex({"/etc/.*\\.conf$", "/opt/.*/config\\.json$"})

パフォーマンス: find_files_by_* と の比較 get_file_list

検出プラグインの場合は、Lua での反復find_files_by_path_regexよりも find_files_by_name、find_files_by_suffix、または を優先get_file_list()します。300K個のファイルを含む localhost スキャンでは、 を使用して Lua でファイルリストを反復処理するには約 15 秒string.match()かかりますが、 は 1 ミリ秒未満でfind_files_by_name完了します。違いは、すべてのファイルパスを Lua VM に文字列としてget_file_list()コピーし、Lua はループとパターンの一致をそれぞれの文字列として解釈することです。find_files_by_* 関数は Lua VM の外部でマッチングを実行し、マッチングされたパスのみを返し、コピーとパスごとの解釈オーバーヘッドの両方を回避します。

ベースネーム、サフィックス、正規表現の一致として表現できないカスタム一致ロジックが必要なget_file_list()場合にのみ使用します。

sbomgen.read_dir(path)

ディレクトリ内のエントリを一覧表示します。

• 戻り値: {{name, is_dir}, ...}, err

local entries, err = sbomgen.read_dir("/app/node_modules")
if err then return end
for _, e in ipairs(entries) do
    if e.is_dir then
        sbomgen.log_debug("directory: " .. e.name)
    end
end

sbomgen.file_stat(path)

ファイルに関するメタデータを返します。

• 戻り値: {is_regular, is_dir, size}, err

local info, err = sbomgen.file_stat(path)
if err then return end
if info.is_regular and info.size > 0 then
    -- process file
end

sbomgen.read_zip_entry(path, entry_path)

ZIP、JAR、または WAR アーカイブから 1 つのエントリを読み取ります。

• 戻り値: string, err

local manifest, err = sbomgen.read_zip_entry(
    "/app/lib/example.jar",
    "META-INF/MANIFEST.MF"
)

sbomgen.search_binary(path, regex)

ファイルを ELF、PE、または Mach-O バイナリとして解析し、Go 正規表現一致のデフォルトの定数/変数セクションを検索します。

• 戻り値: string|nil, err — 一致した文字列、または一致しない場合は nil

local version, err = sbomgen.search_binary(path, "Version:\\s+([\\d.]+)")
if version then
    sbomgen.log_info("found version: " .. version)
end

sbomgen.search_binary_all(path, regex [, n])

ファイルを ELF、PE、または Mach-O バイナリとして解析し、デフォルトの定数/変数セクションからすべての一意の最初のキャプチャグループの一致を返します。を渡nして結果を制限します。

• 戻り値: {string, ...}|nil, err — 一致した文字列のテーブル、または一致がない場合は nil

local versions, err = sbomgen.search_binary_all(path, "version[= ]+([\\d.]+)", 5)
if versions then
    for _, v in ipairs(versions) do
        sbomgen.log_info("found: " .. v)
    end
end

sbomgen.search_binary_raw(path, regex)

バイナリファイル全体を検索して、特定のセクションに限定されず、最初の正規表現一致を検索します。セクションベースの検索 (search_binary) が不十分な場合に使用します。たとえば、バージョン文字列が標準以外のセクションにある場合などです。

• 戻り値: string|nil, err — 一致した文字列、または一致しない場合は nil

local version, err = sbomgen.search_binary_raw(path, "ProductVersion[\\x00\\s]+([\\d.]+)")

FileHandle メソッド

FileHandle オブジェクトは によって返されますsbomgen.open_file()。

fh:read_line()

次の行を読み取ります (改行文字なし）。EOF nilで を返します。

• 戻り値: string|nil, err

fh:read(n)

最大nバイトまで読み取ります。EOF nilで を返します。

• 戻り値: string|nil, err

fh:close()

ファイルハンドルを閉じます。完了したら、必ずハンドルを閉じます。

バイナリユーティリティ

sbomgen.sha256(path)

ファイルの内容の 16 進エンコードされた SHA-256 ハッシュを返します。

• 戻り値: string, err

local hash, err = sbomgen.sha256("/app/bin/server")
if hash then
    sbomgen.log_info("SHA-256: " .. hash)
end

sbomgen.contains_bytes(path, patterns)

ファイルに指定された各バイトパターンが含まれているかどうかを確認します。入力パターンと同じ順序でブール値のテーブルを返します。

• 戻り値: {bool, ...}, err

local results, err = sbomgen.contains_bytes(path, {
    "\xff Go buildinf:",   -- Go build identifier
    "/rustc/",             -- Rust build identifier
})
if results then
    local is_go = results[1]
    local is_rust = results[2]
end

sbomgen.get_pe_version_info(path)

バイナリファイルから Windows PE バージョンリソースを解析します。バージョンフィールドを含むテーブルを返します。ファイルが PE バイナリnil, errでないか、バージョンリソースがない場合は を返します。

• 戻り値: {product_version, file_version, string_table}, err

フィールドproduct_versionと file_versionフィールドは、 という形式の PE FixedFileInfo構造から取得されます"major.minor.build.revision"。string_table フィールドは、ロケールコード (例: "040904B0"米国英語 Unicode) でキーが設定されたネストされたテーブルです。各ロケールは、PE StringFileInfo (ProductVersion、ProductNameFileDescription、 など) から描画された名前と値のペアのテーブルにマッピングされます。PE バイナリは、1 つ以上のロケールを公開する場合があります。

local info, err = sbomgen.get_pe_version_info(file_path)
if err then return end

-- Fixed version fields (always flat)
local product_ver = info.product_version  -- e.g. "25.1.0.0"
local file_ver    = info.file_version     -- e.g. "25.1.0.0"

-- String table — iterate locales, or address a known locale by key
for locale, fields in pairs(info.string_table or {}) do
    sbomgen.log_info(string.format("%s ProductName=%s", locale, fields.ProductName or ""))
end

-- US English Unicode is the most common locale for PE files
local us = (info.string_table or {})["040904B0"]
if us then
    local display_ver = us.ProductVersion  -- e.g. "25.01"
    local name        = us.ProductName     -- e.g. "7-Zip"
end

sbomgen.parse_product_version(path)

PE バイナリの FixedFileInfo から製品バージョン文字列のみを返すコンビニエンスラッパー。の呼び出しget_pe_version_info(path)と読み取りに相当しますproduct_version。

• 戻り値: string, err

local version, err = sbomgen.parse_product_version(file_path)
if version then
    sbomgen.log_info("product version: " .. version)
end

sbomgen.parse_file_version(path)

PE バイナリの FixedFileInfo からファイルバージョン文字列のみを返す便利なラッパー。の呼び出しget_pe_version_info(path)と読み取りに相当しますfile_version。

• 戻り値: string, err

local version, err = sbomgen.parse_file_version(file_path)
if version then
    sbomgen.log_info("file version: " .. version)
end

パッケージ出力

sbomgen.push_package(pkg)

パッケージの検出結果を SBOM にプッシュします。コレクションプラグインでのみ使用できます。

このpkgテーブルでは、次のフィールドがサポートされています。

フィールド	タイプ	必須	説明
name	文字列	はい	パッケージ名
version	string	いいえ	解決済みバージョン文字列
namespace	string	いいえ	PURL 名前空間 (例: 、"curl""wordpress/plugin")
purl_type	string	はい	PURL タイプ (例: 、"pypi"、"npm"、"cargo""deb"、"generic")
component_type	string	はい	CycloneDX コンポーネントタイプ。sbomgen.component_types.*定数を使用する (例: sbomgen.component_types.LIBRARY)
qualifiers	テーブル	いいえ	キーと値のペアとしての PURL 修飾子 (パッケージ URL に表示されます)
properties	テーブル	いいえ	キーと値のペアとしての CycloneDX コンポーネントプロパティ (「」を参照CycloneDX プロパティ)
children	テーブル	いいえ	ネストされた子パッケージ。それぞれが と同じシェイプです pkg (必須フィールドは再帰的に検証されます）。

sbomgen.push_package({
    name = "requests",
    version = "2.28.1",
    purl_type = "pypi",
    component_type = sbomgen.component_types.LIBRARY,
    qualifiers = { example_qualifier = "example_qualifier_value" },
    properties = {
        -- Use your own namespace; amazon:inspector:* is reserved for Amazon Inspector.
        ["acme:example:extra_field"] = "example_value",
    },
})

CycloneDX プロパティ

CycloneDX プロパティは、SBOM のコンポーネントにアタッチされたキーと値のメタデータです。これらは PURL 修飾子とは異なります。

• qualifiers — PURL 修飾子。これらはパッケージ URL 文字列の一部になります (例: pkg:deb/debian/curl@7.88.1?arch=amd64)。一部の PURL 修飾子は Amazon Inspector に意味的意味を持ち、脆弱性の識別に影響します。「パッケージ URL とは」を参照してください。 for Inspector のタイプごとの規則。

• properties — CycloneDX コンポーネントのプロパティ。これらは SBOM のcomponents[].properties配列に表示され、コンポーネントの識別方法は変更されません。

予約済み名前空間

CycloneDX プロパティ名前空間の amazon:inspector:*ファミリーは、Amazon Inspector 用に予約されています。

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

• amazon:inspector:sbom_scanner:* — Amazon Inspector スキャン API によって使用されます。

プラグイン定義のプロパティでは、これらの名前空間を使用しないでください。予約された名前空間に書き込むと、Inspector が依存する値にシャドウや競合が発生し、結果として生じる SBOM が脆弱性の特定中に誤って解釈される可能性があります。予約キーの完全なリストについては、Amazon Inspector での CycloneDX 名前空間の使用」を参照してください。

キー命名規則

に渡されたプロパティキーsbomgen.push_package()は、次のように処理されます。

入力キー	SBOM で生成されるキー	カスタムプラグインに推奨されますか?
を含む : (例: acme:my_plugin:field)	逐語的に使用	はい — プラグイン定義のすべてのプロパティを独自の名前空間に配置します
いいえ : (例: field)	への自動プレフィックス付き amazon:inspector:sbom_generator:field	いいえ — リザーブド名前空間に書き込まれます

定義するプロパティキーには、必ず少なくとも 1 つのコロンを含めます。組織またはプラグインに固有の名前空間を使用します (例: acme:python-pip:*)。

properties = {
    -- Custom namespace — safe to use (recommended)
    ["acme:python-pip:manifest_path"] = file_path,
    ["acme:python-pip:pinned"]        = "true",

    -- Fully-qualified key outside amazon:inspector:* — also fine
    ["my:custom:namespace:key"] = "value",

    -- No colon: avoid — ends up as "amazon:inspector:sbom_generator:custom_field"
    -- custom_field = "value",
}

sbomgen によって設定されたプロパティ

Sbomgen は、出力するすべてのコンポーネントに独自のプロパティをアタッチできます。これらの値は予約済みamazon:inspector:sbom_generator:*名前空間から取得されるため、プラグインで生成しないでください。観察されたランタイム動作:

• source_path は常に sbomgen によって追加されます。

• source_file_scanner と source_package_collectorは、 --enable-debug-props が有効になっている場合に追加されます。

予約キーの完全な分類は、Amazon Inspector ユーザーガイド: Amazon Inspector での CycloneDX 名前空間の使用」で管理されています Amazon Inspector。

プロパティ定数

組み込みプロパティキー定数は、 経由で使用できますsbomgen.properties。以下のすべての定数は、予約されたamazon:inspector:sbom_generator:*名前空間内のキーに解決されます。これらの定数は、sbomgen の組み込みスキャナーが一貫したプロパティキーを出力するように存在します。これらはカスタムプラグインの拡張ポイントではありません。カスタムプラグインで使用すると、Inspector が依存する値をシャドウできる予約済み名前空間に書き込まれます。上記の 予約済み名前空間 を参照してください。

カスタムプラグインの作成者は、これらの定数を再利用するのではなく、独自の名前空間 ( などacme:my_plugin:*) でプロパティを定義する必要があります。

定数	解決された値
sbomgen.properties.NAMESPACE	amazon:inspector:sbom_generator:
sbomgen.properties.VENDOR	amazon:inspector:sbom_generator:vendor
sbomgen.properties.FILE_SIZE_BYTES	amazon:inspector:sbom_generator:file_size_bytes
sbomgen.properties.KERNEL_COMPONENT	amazon:inspector:sbom_generator:kernel_component
sbomgen.properties.RUNNING_KERNEL	amazon:inspector:sbom_generator:running_kernel
sbomgen.properties.UNRESOLVED_VERSION	amazon:inspector:sbom_generator:unresolved_version
sbomgen.properties.TRANSITIVE_DEPENDENCY	amazon:inspector:sbom_generator:experimental:transitive_dependency
sbomgen.properties.GO_REPLACE_DIRECTIVE	amazon:inspector:sbom_generator:replaced_by
sbomgen.properties.DUPLICATE_PACKAGE	amazon:inspector:sbom_generator:is_duplicate_package
sbomgen.properties.DUPLICATE_PURL	amazon:inspector:sbom_generator:duplicate_purl
sbomgen.properties.DOCKERFILE_CHECK	amazon:inspector:sbom_generator:dockerfile_finding
sbomgen.properties.CERTIFICATE_FINDING	amazon:inspector:sbom_generator:certificate_finding
sbomgen.properties.CERTIFICATE_SUBJECT_NAME	amazon:inspector:sbom_generator:certificate:subject_name
sbomgen.properties.CERTIFICATE_ISSUER_NAME	amazon:inspector:sbom_generator:certificate:issuer_name
sbomgen.properties.CERTIFICATE_SIGNATURE_ALGORITHM	amazon:inspector:sbom_generator:certificate:signature_algorithm
sbomgen.properties.CERTIFICATE_NOT_VALID_BEFORE	amazon:inspector:sbom_generator:certificate:not_valid_before
sbomgen.properties.CERTIFICATE_NOT_VALID_AFTER	amazon:inspector:sbom_generator:certificate:not_valid_after
sbomgen.properties.WINDOWS_REGISTRY_KEY	amazon:inspector:sbom_generator:registry_key
sbomgen.properties.SUBSCRIPTION_ENABLED	amazon:inspector:sbom_generator:subscription:enabled
sbomgen.properties.SUBSCRIPTION_NAME	amazon:inspector:sbom_generator:subscription:name
sbomgen.properties.SUBSCRIPTION_LOCKED_VERSION	amazon:inspector:sbom_generator:subscription:locked_version
sbomgen.properties.OPENSSL_FULL_VERSION	amazon:inspector:sbom_generator:openssl:full_version
sbomgen.properties.HARDENED_IMAGE_VENDOR	amazon:inspector:sbom_generator:hardened_image:vendor

スキャナーグループ

検出プラグインは、 を介してスキャナーグループを宣言する必要がありますget_scanner_groups()。グループはスキャナーを分類し、ユーザーがカテゴリを選択的に有効または無効にできるようにします。定数は 経由で使用できますsbomgen.groups。

定数	値	説明
sbomgen.groups.OS	"os"	OS パッケージマネージャー (dpkg、rpm など)
sbomgen.groups.PROGRAMMING_LANGUAGE	"programming-language-packages"	言語パッケージマネージャー (pip、npm、maven など)
sbomgen.groups.BINARY	"binary"	コンパイルされたバイナリ分析 (Go、Rust)
sbomgen.groups.PACKAGE_COLLECTOR	"pkg-scanner"	一般的なパッケージコレクション
sbomgen.groups.EXTRA_ECOSYSTEMS	"extra-ecosystems"	追加のエコシステム (curl、nginx など)
sbomgen.groups.CERTIFICATE	"certificate"	証明書スキャン
sbomgen.groups.CUSTOM	"custom"	経由でロードされたすべてのカスタムプラグインに自動的に追加 --plugin-dir
sbomgen.groups.MACHINE_LEARNING	"machine-learning"	機械学習モデルの検出

例:

function get_scanner_groups()
    return {sbomgen.groups.PROGRAMMING_LANGUAGE, sbomgen.groups.PACKAGE_COLLECTOR}
end

コンポーネントタイプの定数

の component_typeフィールドは、CycloneDX 1.5 コンポーネントタイプのいずれかpush_package()である必要があります。定数は 経由で使用できますsbomgen.component_types。

定数	値
sbomgen.component_types.APPLICATION	"application"
sbomgen.component_types.FRAMEWORK	"framework"
sbomgen.component_types.LIBRARY	"library"
sbomgen.component_types.CONTAINER	"container"
sbomgen.component_types.PLATFORM	"platform"
sbomgen.component_types.OPERATING_SYSTEM	"operating-system"
sbomgen.component_types.DEVICE	"device"
sbomgen.component_types.DEVICE_DRIVER	"device-driver"
sbomgen.component_types.FIRMWARE	"firmware"
sbomgen.component_types.FILE	"file"
sbomgen.component_types.MACHINE_LEARNING_MODEL	"machine-learning-model"
sbomgen.component_types.DATA	"data"

例:

sbomgen.push_package({
    name = "requests",
    version = "2.28.1",
    purl_type = "pypi",
    component_type = sbomgen.component_types.LIBRARY,
})

プラットフォーム定数

と を比較するための定数sbomgen.get_platform()。経由で利用可能sbomgen.platform:

定数	値
sbomgen.platform.LINUX	"linux"
sbomgen.platform.WINDOWS	"windows"
sbomgen.platform.DARWIN	"darwin"

例:

if sbomgen.get_platform() == sbomgen.platform.WINDOWS then
    -- Windows-specific logic
end

アーティファクト情報

sbomgen.get_platform()

ランタイムプラットフォーム文字列 (、、 など"darwin") "linux" "windows"を返します。

sbomgen.get_artifact_type()

スキャンされるアーティファクトのタイプ (例: 、"archive") "directory"を返します。

sbomgen.should_collect_licenses()

ユーザーが 経由でライセンスコレクションを有効にtrueした場合、 を返します--collect-licenses。

sbomgen.get_env_vars()

アーティファクトから環境変数を{key, value}エントリのテーブルとして返します。

local env_vars = sbomgen.get_env_vars()
for _, env in ipairs(env_vars) do
    if env.key == "NODE_ENV" then
        sbomgen.log_info("Node environment: " .. env.value)
    end
end

sbomgen.get_system_drive()

アーティファクトの環境からシステムドライブ文字 ( など"C:") を返します。SystemDrive 環境変数を読み取り、設定"C:"されていない場合はデフォルトで になります。これは と同等の Lua ですstrutils.GetSystemDriverLetter()。

local drive = sbomgen.get_system_drive()
local program_files = drive .. "/Program Files/"

システム情報

これらの関数は、アーティファクトのオペレーティングシステムとハードウェアに関するメタデータを返します。情報が利用できない場合 (OS メタデータなしでディレクトリをスキャンする場合など）、値は空の文字列になることがあります。

関数	戻り値
sbomgen.get_os_name()	OS 名 (例: 、"Ubuntu""Alpine Linux")
sbomgen.get_os_version()	OS バージョン (例: 、"22.04""3.18")
sbomgen.get_os_codename()	OS コード名 (例: 、"jammy""bookworm")
sbomgen.get_os_id()	OS 識別子 (例: 、"ubuntu""alpine")
sbomgen.get_kernel_name()	カーネル名 (例: "Linux")
sbomgen.get_kernel_version()	カーネルバージョン文字列
sbomgen.get_cpu_arch()	CPU アーキテクチャ (例: 、"x86_64""aarch64")
sbomgen.get_hostname()	システムのホスト名

正規表現

Lua の組み込みパターンには、代替 (|)、量子範囲 ({n,})、先読みなどの機能がありません。このギャップを埋めるために、sbomgen は Go のregexpパッケージを直接公開します。これらの関数は、Lua パターンではなく Go 正規表現構文 (RE2) を使用します。

sbomgen.regex_find(str, pattern)

Go 正規表現パターンの最初の一致を返します。一致しないnil場合は を返します。

• 戻り値: string|nil, err

local version = sbomgen.regex_find(content, "\\d+\\.\\d+\\.\\d+")

sbomgen.regex_match(str, pattern)

最初の一致からキャプチャグループを返します。インデックス 1 は完全一致、2 以上はキャプチャグループです。

• 戻り値: {string, ...}|nil, err

local groups = sbomgen.regex_match(content, "(MySQL|MariaDB) (\\d+)\\.(\\d+)\\.(\\d+)")
if groups then
    local db_type = groups[2]   -- "MySQL" or "MariaDB"
    local major   = groups[3]
end

sbomgen.regex_find_all(str, pattern [, n])

重複しないすべての一致を返します。を渡nして結果を制限します (デフォルト: すべて）。

• 戻り値: {string, ...}|nil, err

local versions = sbomgen.regex_find_all(content, "\\d+\\.\\d+\\.\\d+")

sbomgen.regex_replace(str, pattern, replacement)

すべての一致を置き換えます。置換文字列は$1、キャプチャグループの参照に $2、 などを使用できます。

• 戻り値: string, err

local cleaned = sbomgen.regex_replace(raw_version, "(1[6-9]\\d{8,}|buildkitsandbox.*)$", "")

正規表現パターンと Lua パターンを使用するタイミング

Lua の組み込み string.match/string.find はシンプルなパターンに使用します。高速で、バックスラッシュをエスケープする必要はありません。必要に応じて を使用しますsbomgen.regex_*。

• 代替: (foo|bar)

• 量子範囲: \d{8,}

• Lua パターンでは表現できない複雑な文字クラス

構造化解析

Sbomgen は、構造化テキスト形式を直接 Lua テーブルにデコードするための軽量ヘルパーを公開します。

sbomgen.json_decode(str)

JSON 文字列を Lua テーブルに解析します。

• 戻り値: table|nil, err

local doc, err = sbomgen.json_decode('{"name":"requests","version":"2.28.1"}')
if err then return end
sbomgen.log_info(doc.name)

sbomgen.xml_decode(str)

XML 文字列を Lua テーブルに解析します。

• 戻り値: table|nil, err

XML 値は、次の形状を使用します。

• _name — 要素名

• _attr — 属性テーブル、存在する場合

• _text — テキストコンテンツがある場合はトリミング

• 数値インデックス 1..n — 子要素

local doc, err = sbomgen.xml_decode('<package id="Newtonsoft.Json" version="13.0.3" />')
if err then return end
sbomgen.log_info(doc._attr.id)

Windows レジストリ

これらの関数は、Windows レジストリへの読み取り専用アクセスを提供します。Windows 以外のアーティファクトでは、 はエラーregistry_open_keyを返します。レジストリアクセサーは初回使用時に遅延的に初期化され、ライブ Windows API アクセス (Windows でのローカルホストスキャン) とファイルベースの REGF ハイブ解析 (コンテナ/ボリュームスキャン) の両方をサポートします。

sbomgen.registry_open_key(path)

レジストリキーを開きます。で閉じる必要があるキーハンドルを返しますregistry_close。

• 戻り値: key, err

local key, err = sbomgen.registry_open_key("SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Uninstall\\7-Zip")
if err then return end
-- use key...
sbomgen.registry_close(key)

sbomgen.registry_get_string(key, value_name)

開いているレジストリキーから文字列値を読み取ります。

• 戻り値: string, err

local version, err = sbomgen.registry_get_string(key, "DisplayVersion")

sbomgen.registry_get_integer(key, value_name)

開いているレジストリキーから整数値を読み取ります。

• 戻り値: number, err

sbomgen.registry_get_strings(key, value_name)

開いているレジストリキーからマルチ文字列 (REG_MULTI_SZ) 値を読み取ります。文字列のテーブルを返します。

• 戻り値: {string, ...}, err

local paths, err = sbomgen.registry_get_strings(key, "DependsOnService")
if paths then
    for _, p in ipairs(paths) do
        sbomgen.log_info("depends on: " .. p)
    end
end

sbomgen.registry_get_subkeys(key)

開いているレジストリキーの下にすべてのサブキー名を返します。

• 戻り値: {string, ...}, err

local subkeys, err = sbomgen.registry_get_subkeys(key)
for _, name in ipairs(subkeys) do
    local subkey, err = sbomgen.registry_open_key(parent_path .. "\\" .. name)
    -- ...
end

sbomgen.registry_close(key)

レジストリキーハンドルを閉じます。キーハンドルもガベージコレクターによって自動的に閉じられますが、明示的に閉じることをお勧めします。

ログ記録

ログメッセージは sbomgen のコンソール出力に書き込まれます。プラグインによって出力されるすべてのメッセージには、プラグインのソースラベルとエコシステムのプレフィックスが自動的に付けられます。次に例を示します。

[custom:python-pip] Parsing requirements.txt

log_info、log_warn、 log_errorは常に出力します。 は、 で sbomgen が呼び出された場合にのみlog_debug出力します--verbose。

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

フォーマットされたメッセージstring.formatに を使用します。

sbomgen.log_info(string.format("found %d packages in %s", count, file_path))

関数のデバッグ

sbomgen.breakpoint(message)

stderr messageに出力し、ユーザーが Enter を押すまで実行をブロックします。message を省略すると、 はデフォルトのメッセージを出力します。

プラグインのキーポイントにブレークポイントを配置し、 で実行して周囲のログ出力を表示--verboseすることで、これを粗デバッガーとして使用します。

sbomgen.log_info("state: " .. some_variable)
sbomgen.breakpoint("paused after state dump — press Enter to continue")

API のテスト

グローバルtestingテーブルの下にある関数は、 によってロードされたプラグインテストファイル (*_test.lua) 内でのみ使用できますinspector-sbomgen plugin test。検出プラグインまたはコレクションプラグインでは実行時に使用できません。完全な sbomgen.* API はテストファイル内でも使用できますが、アーティファクトを必要とするsbomgen.*関数 ( などsbomgen.read_file()) は、スキャン内から呼び出されたときにのみ意味のある結果を生成します。説明ガイドについては、「」を参照してくださいプラグインテストガイド。

スキャン関数

各スキャン関数は、特定の種類のアーティファクトを作成し、それに対して現在のプラグインの検出→収集パイプラインを実行し、結果を返します。path 引数は、テストファイルの ディレクトリに関連して解決されます。

関数	アーティファクトの種類
testing.scan_directory(path)	ディレクトリ
testing.scan_archive(path)	ディレクトリ ( のエイリアスscan_directory)
testing.scan_localhost(path)	Localhost
testing.scan_binary(path)	バイナリ
testing.scan_volume(path)	Volume
testing.scan_container(path)	コンテナ

6 つすべての は、以下のシェイプの結果テーブルを返します。

結果シェイプ

各検出結果テーブルは、以下に示すフィールドのみを射影します。特に、 namespaceと purl_typeは個別に射影されません。これらは完全なpurl文字列に組み込まれます。

local result = testing.scan_directory("_testdata/example")
-- result.findings                        -- array of finding tables
-- result.findings[i].name                -- string
-- result.findings[i].version             -- string
-- result.findings[i].component_type      -- string
-- result.findings[i].purl                -- string (the full Package URL, or "" if none)
-- result.findings[i].properties          -- table<string, string>
-- result.findings[i].children            -- array of finding tables (same shape, recursive)

アサーション

関数	署名	説明
testing.assert_equals	(expected: any, actual: any, message?: string)	の場合、失敗しますtostring(expected) ~= tostring(actual)。
testing.assert_not_equals	(expected: any, actual: any, message?: string)	の場合、失敗しますtostring(expected) == tostring(actual)。
testing.assert_true	(value: any, message?: string)	value が falseまたは の場合、失敗しますnil。
testing.assert_false	(value: any, message?: string)	value が falseではなく、 でない場合、失敗しますnil。
testing.assert_nil	(value: any, message?: string)	value が でない場合、失敗しますnil。
testing.assert_not_nil	(value: any, message?: string)	が の場合、失敗valueしますnil。
testing.assert_contains	(haystack: string, needle: string, message?: string)	に needle (部分文字列一致) が含まれていない場合haystack、失敗します。
testing.assert_matches	(str: string, pattern: string, message?: string)	str が指定された Go (RE2) 正規表現と一致しない場合、失敗します。
testing.assert_length	(tbl: table, expected: integer, message?: string)	が と等しくない場合#tbl、失敗しますexpected。

コントロールフロー

関数	署名	説明
testing.fail	(message: string)	指定されたメッセージで現在のテストをすぐに失敗させます。
testing.skip	(message: string)	現在のテストをスキップします。結果はスキップ済みとして報告され、失敗は報告されません。

検出のテスト

ファイルマッチングtest_で名前が で始まるグローバル Lua 関数*_test.luaは、テストとして扱われます。テストファイルは、通常の{phase}/{platform}/{category}/{ecosystem}/深さinit.luaの の横に配置する必要があります。修正データはテストファイル_testdata/の横にある にあります。ランナーはテストファイルを検索する_testdata/ときに に降順しません。

エラー処理

失敗する可能性がある 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 は警告をログに記録し、次のファイルまたはプラグインに進みます。他のプラグインは影響を受けません。